django-redis 文档翻译

时间  2019-11-08
标签 django redis 文档 翻译 栏目 Python 繁體版
原文   原文链接

一. 文档管理

当咱们须要翻译文档时首先要考虑的是文档的托管，本身作是一种办法，但使用服务提供商的服务可让咱们更专一的进行文档翻译而不用关心其余操做。html

好比我在打算翻译 django redis 文档时先考虑本身搭，后来想到以前本身读过的不少文档都托管在 readthedocs 上，因而就决定使用它啦。python

使用方式很简单，首先，咱们须要使用文档生成工具生成文档，我这里使用的是 sphinx，安装方式很简单：git

  1. pip install sphinx

而后新建一个目录存放文档，在此目录下输入：github

  1. sphinx-quickstart

一路回车肯定便可，一个简单的文档管理目录就生成好啦，而后咱们在 idex.rst 中进行书写即。redis

conf.py 中是一些输出的配置，这里咱们打算在 readthedocs 托管文档，因此就用 readthedocs 的主题，首先安装主题：数据库

  1. pip install sphinx_rtd_theme

而后在 conf.py 中更改主题配置：django

  1. html_theme = 'sphinx_rtd_theme'

此时咱们就能够开始写文章啦，写完后，在当前目录下执行：json

  1. make html

就能够看到生成的 html 效果啦。 到这里若是是打算本身托管，咱们能够将生成的 html 放到本身服务器或者 github pages。 而我打算用 readthedocs 的服务，因此此时首先要把当前目录的内容都上传到 github。后端

上传后在相应的仓库内选择 settings－> Integrations & services －> add service, 而后搜索 readthedocs 添加便可。缓存

而后登录readthedocs，注册帐号绑定 github，选择相应仓库，生成文档便可～

这是笔者生成的文档： django-redis 中文文档

二. 翻译

django-redis 中文文档

Andrey Antukh, niwi@niwi.be 4.7.0

翻译: RaPoSpectre

1. 介绍

django-redis 基于 BSD 许可, 是一个使 Django 支持 Redis cache/session 后端的全功能组件.

1.1 为什么要用 django-redis ?

由于:

  • 持续更新
  • 本地化的 redis-py URL 符号链接字符串
  • 可扩展客户端
  • 可扩展解析器
  • 可扩展序列器
  • 默认客户端主/从支持
  • 完善的测试
  • 已在一些项目的生产环境中做为 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 支持

  • django-redis 3.x.y 支持 redis-server 2.6.x 或更高
  • django-redis 4.x.y 支持 redis-server 2.8.x 或更高

1.4.3 其余依赖

全部版本的 django-redis 基于 redis-py >= 2.10.0.

2. 用户指南

2.1 安装

安装 django-redis 最简单的方法就是用 pip :

  1. pip install django-redis

2.2 做为 cache backend 使用配置

为了使用 django-redis , 你应该将你的 django cache setting 改为这样:

  1. CACHES = {
  2. "default": {
  3. "BACKEND": "django_redis.cache.RedisCache",
  4. "LOCATION": "redis://127.0.0.1:6379/1",
  5. "OPTIONS": {
  6. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  7. }
  8. }
  9. }

为了更好的互操做性并使链接字符串更加 “标准”, 从 3.8.0 开始 django-redis 使用 redis-py native url notation 做为链接字符串.

URL 格式举例

  1. redis://[:password]@localhost:6379/0
  2. rediss://[:password]@localhost:6379/0
  3. 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 设置:

  1. CACHES = {
  2. "default": {
  3. "BACKEND": "django_redis.cache.RedisCache",
  4. "LOCATION": "redis://127.0.0.1:6379/1",
  5. "OPTIONS": {
  6. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  7. "PASSWORD": "mysecret"
  8. }
  9. }
  10. }

注意, 这样配置不会覆盖 uri 中的密码, 因此若是你已经在 uri 中设置了密码, 此设置将被忽略.

2.3 做为 session backend 使用配置

Django 默承认以使用任何 cache backend 做为 session backend, 将 django-redis 做为 session 储存后端不用安装任何额外的 backend

  1. SESSION_ENGINE = "django.contrib.sessions.backends.cache"
  2. SESSION_CACHE_ALIAS = "default"

2.4 使用 django-redis 进行测试

django-redis 支持定制基于 Redis 的客户端 ( 参考 可扩展 redis 客户端 ) 能够用来测试, 例如: 替换默认的客户端为 fakerdis (https://github.com/jamesls/fakeredis) 或者 mockredis (https://github.com/locationlabs/mockredis). 这样作能够不用依赖真的 redis server 作集成测试.

使用 fakeredis 举例:

  1. import fakeredis
  2. CACHES = {
  3. "default": {
  4. "OPTIONS": {
  5. "REDIS_CLIENT_CLASS": "fakeredis.FakeStrictRedis",
  6. }
  7. }
  8. }

若是在测试完毕后想清理全部数据, 在你的 TestCase 中加入以下代码:

  1. def tearDown(self):
  2. from django_redis import get_redis_connection
  3. get_redis_connection("default").flushall()

3. 进阶使用

3.1 Pickle 版本

django-redis 使用 pickle 序列化几乎全部数据.

默认使用最新的 pickle. 若是你想设置其余版本, 使用 PICKLE_VERSION 参数:

  1. CACHES = {
  2. "default": {
  3. # ...
  4. "OPTIONS": {
  5. "PICKLE_VERSION": -1 # Use the latest protocol version
  6. }
  7. }
  8. }

3.2 套接字超时

套接字超时设置使用 SOCKET_TIMEOUT 和 SOCKET_CONNECT_TIMEOUT 参数:

  1. CACHES = {
  2. "default": {
  3. # ...
  4. "OPTIONS": {
  5. "SOCKET_CONNECT_TIMEOUT": 5, # in seconds
  6. "SOCKET_TIMEOUT": 5, # in seconds
  7. }
  8. }
  9. }

SOCKET_CONNECT_TIMEOUT : socket 创建链接超时设置

SOCKET_TIMEOUT : 链接创建后的读写操做超时设置

3.3 压缩支持

django-redis 支持压缩, 但默认是关闭的. 你能够激活它:

  1. CACHES = {
  2. "default": {
  3. # ...
  4. "OPTIONS": {
  5. "COMPRESSOR": "django_redis.compressors.zlib.ZlibCompressor",
  6. }
  7. }
  8. }

使用 lzma 压缩的例子:

  1. import lzma
  3. CACHES = {
  4. "default": {
  5. # ...
  6. "OPTIONS": {
  7. "COMPRESSOR": "django_redis.compressors.lzma.LzmaCompressor",
  8. }
  9. }
  10. }

3.4 memcached 异常行为

在某些状况下, redis 只做为缓存使用, 当它关闭时若是你不但愿触发异常. 这是 memcached backend 的默认行为, 你可使用 django-redis 模拟这种状况.

为了设置这种相似memcached 的行为 ( 忽略链接异常 ), 使用 IGNORE_EXCEPTIONS 参数:

  1. CACHES = {
  2. "default": {
  3. # ...
  4. "OPTIONS": {
  5. "IGNORE_EXCEPTIONS": True,
  6. }
  7. }
  8. }

Also, you can apply the same settings to all configured caches, you can set the global flag in your settings:

固然,你也能够给全部缓存配置相同的忽略行为:

  1. DJANGO_REDIS_IGNORE_EXCEPTIONS = True

3.5 日志忽略异常

当使用 IGNORE_EXCEPTIONS 或者 DJANGO_REDIS_IGNORE_EXCEPTIONS 参数忽略异常时, 你也许会用到 DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS 参数来配置日志异常:

  1. DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS = True

若是你想设置指定的 logger 输出异常, 只须要设置全局变量 DJANGO_REDIS_LOGGER 为 logger 的名称或其路径便可. 若是没有 logger 被设置而且 DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS=True 时此参数将取 name :

  1. 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 永不超时
  1. 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 搜索过时:

  1. >>> from django.core.cache import cache
  2. >>> cache.set("foo", "value", timeout=25)
  3. >>> cache.ttl("foo")
  4. 25
  5. >>> cache.ttl("not-existent")
  6. 0

3.8 expire & persist

除了简单的 ttl 查询, 你可使用 persist 或者 expire 方法让一个值永久存在或者指定一个新的过时时间:

使用 persist 的例子:

  1. >>> cache.set("foo", "bar", timeout=22)
  2. >>> cache.ttl("foo")
  3. 22
  4. >>> cache.persist("foo")
  5. >>> cache.ttl("foo")
  6. None

使用 expire 的例子:

  1. >>> cache.set("foo", "bar", timeout=22)
  2. >>> cache.expire("foo", timeout=5)
  3. >>> cache.ttl("foo")
  4. 5

3.9 locks

django-redis 支持 redis 分布式锁. 锁的线程接口是相同的, 所以你可使用它做为替代.

使用 python 上下文管理器分配锁的例子:

  1. with cache.lock("somekey"):
  2. do_some_thing()

3.10 扫描 & 删除键 (keys)

django-redis 支持使用全局通配符的方式来检索或者删除键.

使用通配符搜索的例子

  1. >>> from django.core.cache import cache
  2. >>> cache.keys("foo_*")
  3. ["foo_1", "foo_2"]

这个简单的写法将返回全部匹配的值, 但在拥有很大数据量的数据库中这样作并不合适. 在 redis 的 server side cursors 2.8 版及以上, 你可使用 iter_keys 取代 keys 方法, iter_keys 将返回匹配值的迭代器, 你可使用迭代器高效的进行遍历.

使用 server side cursors 搜索

  1. >>> from django.core.cache import cache
  2. >>> cache.iter_keys("foo_*")
  3. <generator object algo at 0x7ffa9c2713a8>
  4. >>> next(cache.iter_keys("foo_*"))
  5. "foo_1"

若是要删除键, 使用 delete_pattern 方法, 它和 keys 方法同样也支持全局通配符, 此函数将会返回删掉的键的数量

使用 delete_pattern 的例子

  1. >>> from django.core.cache import cache
  2. >>> cache.delete_pattern("foo_*")

3.11 Redis 本地命令

django-redis 有限制的支持一些 Redis 原子操做, 例如 SETNX 和 INCR 命令.

你能够在 set() 方法中加上 nx 参数使用来使用 SETNX 命令

例子:

  1. >>> from django.core.cache import cache
  2. >>> cache.set("key", "value1", nx=True)
  3. True
  4. >>> cache.set("key", "value2", nx=True)
  5. False
  6. >>> cache.get("key")
  7. "value1"

当值 (value) 有合适的键 (key) 时, incr 和 decr 也可使用 Redis 原子操做

3.12 原生客户端使用

在某些状况下你的应用须要进入原生 Redis 客户端使用一些 django cache 接口没有暴露出来的进阶特性. 为了不储存新的原生链接所产生的另外一份设置, django-redis 提供了方法 get_redis_connection(alias) 使你得到可重用的链接字符串.

  1. >>> from django_redis import get_redis_connection
  2. >>> con = get_redis_connection("default")
  3. >>> con
  4. <redis.client.StrictRedis object at 0x2dc4510>

警告 不是全部的扩展客户端都支持这个特性.

3.13 链接池

django-redis 使用 redis-py 的链接池接口, 并提供了简单的配置方式. 除此以外, 你能够为 backend 定制化链接池的产生.

redis-py 默认不会关闭链接, 尽量重用链接

3.13.1 配置默认链接池

配置默认链接池很简单, 你只须要在 CACHES 中使用 CONNECTION_POOL_KWARGS 设置链接池的最大链接数量便可:

  1. CACHES = {
  2. "default": {
  3. "BACKEND": "django_redis.cache.RedisCache",
  4. ...
  5. "OPTIONS": {
  6. "CONNECTION_POOL_KWARGS": {"max_connections": 100}
  7. }
  8. }
  9. }

你能够得知链接池已经打开多少链接:

  1. from django.core.cache import get_cache
  2. from django_redis import get_redis_connection
  4. r = get_redis_connection("default") # Use the name you have defined for Redis in settings.CACHES
  5. connection_pool = r.connection_pool
  6. print("Created connections so far: %d" % connection_pool._created_connections)

3.13.2 使用你本身的链接池子类

有时你想使用本身的链接池子类. django-redis 提供了 CONNECTION_POOL_CLASS 来配置链接池子类

myproj/mypool.py

  1. from redis.connection import ConnectionPool
  3. class MyOwnPool(ConnectionPool):
  4. # Just doing nothing, only for example purpose
  5. pass

setting.py

  1. # Omitting all backend declaration boilerplate code.
  3. "OPTIONS": {
  4. "CONNECTION_POOL_CLASS": "myproj.mypool.MyOwnPool",
  5. }

3.13.3 定制化的 connection factory

若是以前的方法都不合适, 你能够定制 django-redis 的 connection factory 过程甚至彻底重写.

django-redis 默认使用Django setting 中 DJANGO_REDIS_CONNECTION_FACTORY 参数指定的 django_redis.pool.ConnectionFactory 类产生链接.

ConnectionFactory 类的部分接口

  1. # Note: Using Python 3 notation for code documentation ;)
  3. class ConnectionFactory(object):
  4. def get_connection_pool(self, params:dict):
  5. # Given connection parameters in the `params` argument,
  6. # return new connection pool.
  7. # It should be overwritten if you want do something
  8. # before/after creating the connection pool, or return your
  9. # own connection pool.
  10. pass
  12. def get_connection(self, params:dict):
  13. # Given connection parameters in the `params` argument,
  14. # return a new connection.
  15. # It should be overwritten if you want to do something
  16. # before/after creating a new connection.
  17. # The default implementation uses `get_connection_pool`
  18. # to obtain a pool and create a new connection in the
  19. # newly obtained pool.
  20. pass
  22. def get_or_create_connection_pool(self, params:dict):
  23. # This is a high layer on top of `get_connection_pool` for
  24. # implementing a cache of created connection pools.
  25. # It should be overwritten if you want change the default
  26. # behavior.
  27. pass
  29. def make_connection_params(self, url:str) -> dict:
  30. # The responsibility of this method is to convert basic connection
  31. # parameters and other settings to fully connection pool ready
  32. # connection parameters.
  33. pass
  35. def connect(self, url:str):
  36. # This is really a public API and entry point for this
  37. # factory class. This encapsulates the main logic of creating
  38. # the previously mentioned `params` using `make_connection_params`
  39. # and creating a new connection using the `get_connection` method.
  40. pass

3.14 可扩展解析器

redis-py (django-redis 使用的 Redis 客户端) 支持的纯净 Python Redis 解析器能够知足大部分普通任务, 但若是你想要性能更好, 可使用 hiredis

hiredis 是一个用 C 写的 Redis 客户端, 而且他的解析器能够用在 django-redis 中:

  1. "OPTIONS": {
  2. "PARSER_CLASS": "redis.connection.HiredisParser",
  3. }

3.15 可扩展客户端

django_redis 设计的很是灵活和可配置。它提供了可扩展的后端，拥有易扩展的特性.

3.15.1 默认客户端

咱们已经说明了默认客户端几乎全部的特色, 但有一个例外: 默认客户端支持主从配置.

若是须要主从设置, 你须要更改 LOCATION 参数:

  1. "LOCATION": [
  2. "redis://127.0.0.1:6379/1",
  3. "redis://127.0.0.1:6378/1",
  4. ]

第一个字段表明 master 服务器, 第二个字段表明 slave 服务器.

警告 主从设置没有在生产环境中通过大量测试

3.15.2 分片客户端

此可扩展客户端实现了客户端分片, 它几乎继承了默认客户端的所有功能. 若是须要使用, 请将配置改为这样:

  1. CACHES = {
  2. "default": {
  3. "BACKEND": "django_redis.cache.RedisCache",
  4. "LOCATION": [
  5. "redis://127.0.0.1:6379/1",
  6. "redis://127.0.0.1:6379/2",
  7. ],
  8. "OPTIONS": {
  9. "CLIENT_CLASS": "django_redis.client.ShardClient",
  10. }
  11. }
  12. }

警告 分片客户端仍处于试验阶段, 请在生产环境中谨慎使用

3.15.3 集群客户端

咱们同时也在尝试解决惊群问题, 更多信息请阅读Wikipedia

和上文讲的同样, 客户端基本继承了默认客户端全部功能, 增长额外的方法以获取/设置键 (keys)

设置举例

  1. CACHES = {
  2. "default": {
  3. "BACKEND": "django_redis.cache.RedisCache",
  4. "LOCATION": "redis://127.0.0.1:6379/1",
  5. "OPTIONS": {
  6. "CLIENT_CLASS": "django_redis.client.HerdClient",
  7. }
  8. }
  9. }

一些其余的设置:

  • CACHE_HERD_TIMEOUT: 设置集群超时 (默认值为: 60s)

3.16 可扩展序列器

客户端在将数据发给服务器以前先会序列化数据. django-redis 默认使用 Python pickle 序列化数据.

若是须要使用 json 序列化数据, 使用 JSONSerializer

设置举例

  1. CACHES = {
  2. "default": {
  3. "BACKEND": "django_redis.cache.RedisCache",
  4. "LOCATION": "redis://127.0.0.1:6379/1",
  5. "OPTIONS": {
  6. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  7. "SERIALIZER": "django_redis.serializers.json.JSONSerializer",
  8. }
  9. }
  10. }

使用 MsgPack http://msgpack.org/ 进行序列化 (须要 msgpack-python 库支持)

设置举例

  1. CACHES = {
  2. "default": {
  3. "BACKEND": "django_redis.cache.RedisCache",
  4. "LOCATION": "redis://127.0.0.1:6379/1",
  5. "OPTIONS": {
  6. "CLIENT_CLASS": "django_redis.client.DefaultClient",
  7. "SERIALIZER": "django_redis.serializers.msgpack.MSGPackSerializer",
  8. }
  9. }
  10. }

3.17 可扩展 Redis 客户端

django-redis 默认使用 redis.client.StrictClient 做为 Redis 客户端, 你可使用其余客户端替代, 好比以前在讲测试时咱们用 fakeredis 代替真实客户端.

使用 REDIS_CLIENT_CLASS in the CACHES 来配置你的客户端, 使用 REDIS_CLIENT_KWARGS 提供配置客户端的参数 (可选).

设置举例

  1. CACHES = {
  2. "default": {
  3. "OPTIONS": {
  4. "REDIS_CLIENT_CLASS": "my.module.ClientClass",
  5. "REDIS_CLIENT_KWARGS": {"some_setting": True},
  6. }
  7. }
  8. }
相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程