modeldict 0.5.0

----------------
Modeldict
----------------

Modeldict包含一组由持久数据存储（Redis、Django模型等）支持的字典类，适用于分布式使用。字典值在字典实例中本地缓存，并且仅在数据存储中的值发生变化时与它们的持久数据存储同步。

用法
-----

Modeldict包含各种由持久数据存储支持的类似字典的对象。所有字典类都位于“modeldict”包中。目前，Modeldict提供以下字典

1. ``modeldict.redis.RedisDict`` - 由Redis支持。
2. ``modeldict.models.ModelDict`` - 由数据库对象（可能是Django模型）支持。
3. ``modeldict.zookeeper.ZookeeperDict`` - 由Zookeeper支持。

每个字典类都有一个不同的``__init__``方法，它接受不同的参数，因此请查阅它们的文档以获取具体的用法细节。

一旦您有一个modeldict实例，就可以像使用普通字典一样使用它：

from modeldict import RedisDict
from redis import Redis

# 构造一个新的RedisDict对象
设置 = RedisDict('settings', Redis())

# 分配和从字典中检索值
settings['foo'] = 'bar'
settings['foo']
>>> 'bar'

# 分配和检索另一个值
settings['buzz'] = 'foogle'
settings['buzz']
>>> 'foogle'

# 删除一个值，访问将引发 KeyError
del settings['foo']
settings['foo']
>>> KeyError

所有字典类型都会在它们持久化数据存储中序列化它们的对象，因此任何可序列化的对象都可以保存到这些存储中。

关于持久性、一致性和内存缓存的相关说明
-----------------------------

在 Modeldict 字典类（即 ``RedisDict``）上几乎调用的所有方法都被代理到内部字典对象，该对象作为字典值的缓存。只有当持久存储中存储的值实际发生变化时，此缓存才会更新为最新的值。

为了检查持久存储中的数据是否已更改，每个 modeldict 后端都需要提供一个快速的 ``last_updated()`` 方法，该方法可以快速告诉字典上次任何值在持久存储中更新的时间。例如，``ModelDict`` 构造函数需要传入一个作为参数的 ``cache`` 对象，该对象提供了维护 ``last_updated`` 状态的缓存行接口方法的实现。memcache 客户端是此对象的良好候选。

默认情况下，所有 Modeldict 类在所有写入操作（插入、更新和删除）以及字典上的任何读取操作之前都会与其持久数据存储同步。这种模式以读取速度为代价提供了 *高读取一致性*。您可以保证对您的字典的任何读取操作（即 ``settings['cool_feature']``）都将始终使用最新的数据。如果您创建对象后，持久数据存储的另一个消费者已修改该存储中的值，您将能够立即通过字典实例读取新数据。

手动控制持久存储同步
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

如上所述，在每次读取字典数据之前与持久存储同步的缺点是它会降低您的读取性能。如果您从字典中读取 100 个键，这意味着 100 次检查 ```last_updated()``` 的访问。即使在像 memecache 这样快速的数据存储中，这也会很快累加起来。

因此，您可能希望不使用字典的每次读取之前与持久存储同步，而是手动控制该同步。要这样做，请在构造字典时传递 ``autosync=False``，例如：

from modeldict import RedisDict
from redis import Redis

# 构造一个不同步读取的新 RedisDict 对象
settings = RedisDict('settings', Redis(), autosync=False)

这会导致字典以以下方式表现

1. 正常情况下，字典在实例化时从持久数据存储初始化。
2. 写入操作（包括插入和更新）以及字典中值的删除将仍然在每次操作发生时自动与数据存储同步。
3. 任何时间从字典中读取，都*只使用当前在内部缓存中的数据*。字典*不会在读取之前尝试与其持久数据存储同步*。
4. 要强制字典尝试与其持久数据存储同步，您可以在字典上调用 ``sync()`` 方法。与 ``autosync`` 为假时一样，如果 ``last_update`` 表明没有更改，则字典将跳过从持久存储更新。

手动同步的一个良好用例是读取密集型的 Web 应用程序，其中您使用 modeldict 进行设置配置。实际上很少请求会*更改*字典内容 - 大多数只是从字典中读取。在这种情况下，您可能在用户 Web 请求的开始时调用 ``sync()``，以确保字典是最新的，但在请求过程中不调用，以便尽可能快地将响应推送给用户。

与 Django 的集成
------------------------

如果您想将字典值存储在Django应用程序的数据库中，应使用``modeldict.models.modelDict``类。此类接受一个模型管理器的实例，以及``key_col``和``value_col``参数，这些参数可用于告诉``ModelDict``在对象上使用哪些列来存储数据。

也许使用``autosync=False``（参见上面的“手动控制持久存储同步”）来构造您的字典，并在每次请求之前手动调用``sync()``会更有利。这可以通过``request_started``信号最简单地实现：

django.core.signals.request_started.connect(settings.sync)

创建您自己的持久字典
---------------------------------

创建您自己的持久字典很简单。您只需要继承``modeldict.base.PersistedDict``并实现以下所需接口方法。

1. ``persist(key, value)`` - 在``key``处将``value``持久化到您的数据存储。
2. ``depersist(key)`` - 从您的数据存储中删除``key``处的值。
3. ``persistents()`` - 返回一个包含所有键的``key=val``字典。
4. ``last_updated()`` - 表示您的数据存储中的数据最后更新的一个可比较值。

您还可以实现一些可选的字典方法，当在字典上调用实际的非下划线版本时，``modeldict.base.PersistedDict``将调用这些方法。

1. ``_pop(key[,default])`` - 如果``key``在字典中，则移除它并返回其值，否则返回``default``。如果没有提供``default``并且``key``不在字典中，则引发``KeyError``。
2. ``_setdefault(key[,default])`` - 如果键在字典中，则返回其值。如果没有，则插入键并使用``default``值，并返回``default``。``default``的默认值为``None``。