django-redis中⽂⽂档Andrey Antukh, 4.7.0
翻译:
1. 介绍
django-redis 基于 BSD 许可, 是⼀个使 Django ⽀持 Redis cache/session 后端的全功能组件.
1.1 为何要⽤ django-redis ?
因为:
持续更新
本地化的 redis-py URL 符号连接字符串
可扩展客户端
可扩展解析器
python中文文档可扩展序列器
默认客户端主/从⽀持
完善的测试
已在⼀些项⽬的⽣产环境中作为 cache 和 session 使⽤
⽀持永不超时设置
原⽣进⼊ redis 客户端/连接池⽀持
⾼可配置 ( 例如仿真缓存的异常⾏为 )
默认⽀持 unix 套接字
⽀持 Python 2.7, 3.4, 3.5 以及 3.6
1.2 可⽤的 django-redis 版本
稳定版本: 4.7.0
稳定版本: 3.8.4
1.3 我该使⽤哪个版本
版本号像 3.6, 3.7 … 等的是主要发⾏版本, 会包含向后不兼容的内容. 跟多信息请在升级前阅读升级⽇志.版本号像 3.7.0, 3.7.1… 等的是⼩更新或者 bug 修复版本, ⼀般只会包含 bug 修复, 没有功能更新.
1.4 依赖
1.4.1 Django 版本⽀持
django-redis 3.8.x ⽀持 django 1.4, 1.5, 1.6, 1.7 (或许会有 1.8)
django-redis 4.4.x ⽀持 django 1.6, 1.7, 1.8, 1.9 和 1.10
1.4.2 Redis Server ⽀持
⽀持 redis-server 2.6.x 或更⾼
⽀持 redis-server 2.8.x 或更⾼
1.4.3 其他依赖
所有版本的 django-redis 基于 redis-py >= 2.10.0.
2. ⽤户指南
2.1 安装
安装 django-redis 最简单的⽅法就是⽤ pip :
pip install django-redis
2.2 作为 cache backend 使⽤配置
为了使⽤ django-redis , 你应该将你的 django cache setting 改成这样:
为了更好的互操作性并使连接字符串更加 “标准”, 从 3.8.0 开始 django-redis 使⽤ redis-py native url notation 作为连接字符串.
URL 格式举例
redis://[:password]@localhost:6379/0
rediss://[:pa
sword]@localhost:6379/0
unix://[:password]@/path/to/socket.sock?db=0
⽀持三种 URL scheme :
redis://: 普通的 TCP 套接字连接
rediss://: SSL 包裹的 TCP 套接字连接
unix://: Unix 域套接字连接
指定数据库数字的⽅法:
db 查询参数, 例如: redis://localhost?db=0
如果使⽤ redis:// scheme, 可以直接将数字写在路径中, 例如: redis://localhost/0
在某些环境下连接密码放在 url 是不安全的, 这时你可以忽略密码或者使⽤⽅便的 OPTIONS 设置:
CACHES = {
"default": {
"BACKEND": "django_redis.cache.RedisCache",
"LOCATION": "redis://127.0.0.1:6379/1",
"OPTIONS": {
"CLIENT_CLASS": "django_redis.client.DefaultClient",
"PASSWORD": "mysecret"
}
}
}
注意, 这样配置不会覆盖 uri 中的密码, 所以如果你已经在 uri 中设置了密码, 此设置将被忽略.
2.3 作为 session backend 使⽤配置
Django 默认可以使⽤任何 cache backend 作为 session backend, 将 django-redis 作为 session 储存后端不⽤安装任何额外的 backend SESSION_ENGINE = "ib.sessions.backends.cache"
SESSION_CACHE_ALIAS = "default"
2.4 使⽤ django-redis 进⾏测试
django-redis ⽀持定制基于 Redis 的客户端 ( 参考[可扩展 redis 客户端][] ) 可以⽤来测试, 例如: 替换默认的客户端为 fakerdis () 或者mockredis (). 这样做可以不⽤依赖真的 redis server 做集成测试.
使⽤ fakeredis 举例:
import fakeredis
CACHES = {
"default": {
"OPTIONS": {
"REDIS_CLIENT_CLASS": "fakeredis.FakeStrictRedis",
}
}
}
如果在测试完毕后想清理所有数据, 在你的 TestCase 中加⼊如下代码:
def tearDown(self):
from django_redis import get_redis_connection
get_redis_connection("default").flushall()
3. 进阶使⽤
3.1 Pickle 版本
django-redis 使⽤ pickle 序列化⼏乎所有数据.
默认使⽤最新的 pickle. 如果你想设置其他版本, 使⽤ PICKLE_VERSION 参数:
CACHES = {
"default": {
# ...
"OPTIONS": {
"PICKLE_VERSION": -1 # Use the latest protocol version
}
}
}
3.2 套接字超时
套接字超时设置使⽤ SOCKET_TIMEOUT 和 SOCKET_CONNECT_TIMEOUT 参数:
CACHES = {
"default": {
# ...
"OPTIONS": {
"SOCKET_CONNECT_TIMEOUT": 5, # in seconds
"SOCKET_TIMEOUT": 5, # in seconds
}
}
}
SOCKET_CONNECT_TIMEOUT : socket 建⽴连接超时设置
SOCKET_TIMEOUT : 连接建⽴后的读写操作超时设置
3.3 压缩⽀持
django-redis ⽀持压缩, 但默认是关闭的. 你可以激活它:
CACHES = {
"default": {
# ...
"OPTIONS": {
"COMPRESSOR": "django_redispressors.zlib.ZlibCompressor",
}
}
}
使⽤ lzma 压缩的例⼦:
import lzma
CACHES = {
"default": {
# ...
"OPTIONS": {
"COMPRESSOR": "django_redispressors.lzma.LzmaCompressor",
}
}
}
3.4 memcached 异常⾏为
在某些情况下, redis 只作为缓存使⽤, 当它关闭时如果你不希望触发异常. 这是 memcached backend 的默认⾏为, 你可以使⽤ django-redis 模拟这种情况.
为了设置这种类似memcached 的⾏为 ( 忽略连接异常 ), 使⽤ IGNORE_EXCEPTIONS 参数:
CACHES = {
"default": {
# ...
"OPTIONS": {
"IGNORE_EXCEPTIONS": True,
}
}
}
Also, you can apply the same settings to all configured caches, you can set the global flag in your settings:
当然，你也可以给所有缓存配置相同的忽略⾏为:
DJANGO_REDIS_IGNORE_EXCEPTIONS = True
3.5 ⽇志忽略异常
当使⽤ IGNORE_EXCEPTIONS 或者 DJANGO_REDIS_IGNORE_EXCEPTIONS 参数忽略异常时, 你也许会⽤到
DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS 参数来配置⽇志异常:
DJANGO_REDIS_LOGGER = 'some.specified.logger'
如果你想设置指定的 logger 输出异常, 只需要设置全局变量 DJANGO_REDIS_LOGGER 为 logger 的名称或其路径即可. 如果没有 logger 被设置并且 DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS=True 时此参数将取 name :
DJANGO_REDIS_LOGGER = 'some.specified.logger'
3.6 永不超时设置
django-redis comes with infinite timeouts support out of the box. And it behaves in same way as django backend contract specifies:
django-redis ⽀持永不超时设置. 其表现和 django backend 指定的相同:
timeout=0 ⽴即过期
timeout=None 永不超时
cache.set("key", "value", timeout=None)
3.7 通过值 (value) 获取 ttl (time to live)
With redis, you can access to ttl of any stored key, for it, django-redis exposes ttl function.
It returns:
在 redis 中, 你可以获取任何 key 的 ttl, django-redis 也⽀持获取 ttl 的函数:
它返回:
0 key 不存在 (或已过期).
None key 存在但没有设置过期.
ttl 任何有超时设置的 key 的超时值.
以 keys 搜索过期:
>>> ache import cache
>>> cache.set("foo", "value", timeout=25)
>>> l("foo")
25
>>> l("not-existent")
3.8 expire & persist
除了简单的 ttl 查询, 你可以使⽤ persist 或者 expire ⽅法让⼀个值永久存在或者指定⼀个新的过期时间:
使⽤ persist 的例⼦:
>>> cache.set("foo", "bar", timeout=22)
>>> l("foo")
22
>>> cache.persist("foo")
>>> l("foo")
None
使⽤ expire 的例⼦:
>>> cache.set("foo", "bar", timeout=22)
>>> pire("foo", timeout=5)
>>> l("foo")
5
3.9 locks
django-redis ⽀持 redis 分布式锁. 锁的线程接⼝是相同的, 因此你可以使⽤它作为替代.
使⽤ python 上下⽂管理器分配锁的例⼦:
with cache.lock("somekey"):
do_some_thing()
3.10 扫描 & 删除键 (keys)
django-redis ⽀持使⽤全局通配符的⽅式来检索或者删除键.
使⽤通配符搜索的例⼦
>>> ache import cache
>>> cache.keys("foo_*")
["foo_1", "foo_2"]
这个简单的写法将返回所有匹配的值, 但在拥有很⼤数据量的数据库中这样做并不合适. 在 redis 的 server side cursors 2.8 版及以上, 你可以使⽤iter_keys取代keys⽅法, iter_keys将返回匹配值的迭代器, 你可以使⽤迭代器⾼效的进⾏遍历.
使⽤ server side cursors 搜索
>>> ache import cache
>>> cache.iter_keys("foo_*")
<generator object algo at 0x7ffa9c2713a8>
>>> next(cache.iter_keys("foo_*"))
"foo_1"
如果要删除键, 使⽤delete_pattern⽅法, 它和keys⽅法⼀样也⽀持全局通配符, 此函数将会返回删掉的键的数量
使⽤ delete_pattern 的例⼦
>>> ache import cache
>>> cache.delete_pattern("foo_*")
3.11 Redis 本地命令
django-redis 有限制的⽀持⼀些 Redis 原⼦操作, 例如SETNX和INCR命令.
你可以在 set() ⽅法中加上nx参数使⽤来使⽤SETNX命令
例⼦:
>>> ache import cache
>>> cache.set("key", "value1", nx=True)
True
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论