Система кэширования Django

Memcached

Memcached — это кэш-сервер, полностью работающий в памяти, первоначально разработанный для обработки больших нагрузок на LiveJournal.com, а затем выпущенный компанией Danga Interactive с открытым исходным кодом. Он используется такими сайтами, как Facebook и Wikipedia, для уменьшения доступа к базе данных и существенного повышения производительности сайта.

Memcached работает как демон и получает выделенный объем оперативной памяти. Всё, что он делает, это предоставляет быстрый интерфейс для добавления, получения и удаления данных в кэше. Все данные хранятся непосредственно в памяти, поэтому нет накладных расходов на использование базы данных или файловой системы.

После установки самого Memcached вам потребуется установить привязку к Memcached. Есть несколько доступных Python-привязок к Memcached; две поддерживаемые Django — pylibmc и pymemcache.

Для использования Memcached с Django:

• Установите BACKEND на django.core.cache.backends.memcached.PyMemcacheCache или django.core.cache.backends.memcached.PyLibMCCache (в зависимости от выбранной вами привязки к memcached)
• Установите LOCATION на ip:port значения, где ip — IP-адрес демона Memcached, а port — порт, на котором работает Memcached, или на unix:path значение, где path — путь к файлу сокета Unix Memcached.

В этом примере Memcached работает на локальном хосте (127.0.0.1) на порту 11211, используя привязку pymemcache:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": "127.0.0.1:11211",
    }
}

В этом примере Memcached доступен через локальный файл сокета Unix /tmp/memcached.sock, используя привязку pymemcache:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": "unix:/tmp/memcached.sock",
    }
}

Отличной особенностью Memcached является его способность к совместному использованию кэша на нескольких серверах. Это означает, что вы можете запускать демоны Memcached на нескольких машинах, и программа будет рассматривать группу машин как один кэш, без необходимости дублировать значения кэша на каждой машине. Для использования этой функции включите все адреса серверов в LOCATION в виде строки, разделенной точкой с запятой или запятой, или в виде списка.

В этом примере кэш совместно используется между экземплярами Memcached, работающими по IP-адресам 172.19.26.240 и 172.19.26.242, оба на порту 11211:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": [
            "172.19.26.240:11211",
            "172.19.26.242:11211",
        ],
    }
}

В следующем примере кэш совместно используется между экземплярами Memcached, работающими по IP-адресам 172.19.26.240 (порт 11211), 172.19.26.242 (порт 11212) и 172.19.26.244 (порт 11213):

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": [
            "172.19.26.240:11211",
            "172.19.26.242:11212",
            "172.19.26.244:11213",
        ],
    }
}

По умолчанию бэкенд PyMemcacheCache устанавливает следующие параметры (вы можете переопределить их в OPTIONS):

"OPTIONS": {
    "allow_unicode_keys": True,
    "default_noreply": False,
    "serde": pymemcache.serde.pickle_serde,
}

Последний момент о Memcached заключается в том, что кэширование в памяти имеет недостаток: поскольку кэшированные данные хранятся в памяти, данные будут потеряны при сбое сервера. Очевидно, что память не предназначена для постоянного хранения данных, поэтому не полагайтесь на кэширование в памяти как на единственное хранилище данных. Без сомнения, ни один из бэкэндов кэширования Django не должен использоваться для постоянного хранения — все они предназначены для кэширования, а не хранения — но мы указываем на это здесь, потому что кэширование в памяти особенно временное.

Redis

Redis — это база данных в оперативной памяти, которая может использоваться для кэширования. Для начала вам понадобится работающий Redis-сервер, либо локально, либо на удаленной машине.

После настройки Redis-сервера вам потребуется установить Python-привязки к Redis. redis-py — это привязка, поддерживаемая Django по умолчанию. Также рекомендуется установить пакет hiredis-py.

Для использования Redis в качестве бэкенда кэширования с Django:

• Установите BACKEND на django.core.cache.backends.redis.RedisCache.
• Установите LOCATION на URL, указывающий на ваш экземпляр Redis, используя соответствующий протокол. См. документацию redis-py для подробностей доступных схем.

Например, если Redis работает на локальном хосте (127.0.0.1) на порту 6379:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379",
    }
}

Часто Redis-серверы защищены аутентификацией. Чтобы указать имя пользователя и пароль, добавьте их в LOCATION вместе с URL:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://username:password@127.0.0.1:6379",
    }
}

Если у вас настроены несколько Redis-серверов в режиме репликации, вы можете указать серверы либо в виде строки, разделенной точкой с запятой или запятой, либо в виде списка. При использовании нескольких серверов операции записи выполняются на первом сервере (лидер). Операции чтения выполняются на других серверах (реплики), выбранных случайным образом:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": [
            "redis://127.0.0.1:6379",  # leader
            "redis://127.0.0.1:6378",  # read-replica 1
            "redis://127.0.0.1:6377",  # read-replica 2
        ],
    }
}

Кэширование в базе данных

Django может хранить свои кэшированные данные в вашей базе данных. Это работает лучше всего, если у вас быстрый и хорошо индексированный сервер базы данных.

Для использования таблицы базы данных в качестве бэкенда кэширования:

• Установите BACKEND на django.core.cache.backends.db.DatabaseCache
• Установите LOCATION на tablename, имя таблицы базы данных. Это имя может быть любым, пока это допустимое имя таблицы, которое еще не используется в вашей базе данных.

В этом примере имя таблицы кэша — my_cache_table:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.db.DatabaseCache",
        "LOCATION": "my_cache_table",
    }
}

В отличие от других бэкэндов кэширования, кэш базы данных не поддерживает автоматическое удаление истекших записей на уровне базы данных. Вместо этого истекшие записи кэша удаляются каждый раз, когда вызывается add(), set() или touch().

python manage.py createcachetable

class CacheRouter:
    """A router to control all database cache operations"""

    def db_for_read(self, model, **hints):
        "All cache read operations go to the replica"
        if model._meta.app_label == "django_cache":
            return "cache_replica"
        return None

    def db_for_write(self, model, **hints):
        "All cache write operations go to primary"
        if model._meta.app_label == "django_cache":
            return "cache_primary"
        return None

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        "Only install the cache model on primary"
        if app_label == "django_cache":
            return db == "cache_primary"
        return None

Кэширование на файловой системе

Файловый бэкенд сериализует и хранит каждое значение кеша в отдельном файле. Чтобы использовать этот бэкенд, установите BACKEND на "django.core.cache.backends.filebased.FileBasedCache" и LOCATION на подходящую директорию. Например, чтобы хранить кэшированные данные в /var/tmp/django_cache, используйте такое значение:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": "/var/tmp/django_cache",
    }
}

Если вы работаете в Windows, укажите букву диска в начале пути, как показано ниже:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": "c:/foo/bar",
    }
}

Путь к директории должен быть абсолютным — то есть начинаться с корня файловой системы. Не имеет значения, ставите ли вы слеш в конце настройки.

Убедитесь, что директория, указанная в этой настройке, существует, доступна для чтения и записи, или что она может быть создана системным пользователем, под которым работает ваш веб-сервер. Продолжая предыдущий пример, если ваш сервер работает как пользователь apache, убедитесь, что директория /var/tmp/django_cache существует и доступна для чтения и записи пользователем apache, или что она может быть создана пользователем apache.

Кэширование в оперативной памяти

Это кеш по умолчанию, если в файле настроек не указан другой. Если вам нужны преимущества скорости кэширования в оперативной памяти, но у вас нет возможности запускать Memcached, рассмотрите кэширование в локальной памяти. Этот кеш относится к процессу (см. ниже) и потокобезопасен. Чтобы его использовать, установите BACKEND на "django.core.cache.backends.locmem.LocMemCache". Например:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
        "LOCATION": "unique-snowflake",
    }
}

Кэш LOCATION используется для идентификации отдельных хранилищ памяти. Если у вас только один locmem кеш, вы можете опустить LOCATION; однако, если у вас более одного кеша локальной памяти, вам необходимо назначить имя хотя бы одному из них, чтобы они оставались отдельными.

Кеш использует стратегию удаления наименее используемых элементов (LRU).

Обратите внимание, что каждый процесс будет иметь свою собственную частную экземпляр кеша, что означает невозможность кэширования между процессами. Это также означает, что кеш локальной памяти не является особенно эффективным с точки зрения использования памяти, поэтому, вероятно, не является хорошим выбором для рабочей среды. Он удобен для разработки.

Кэширование «фиктивными данными» (для разработки)

Наконец, Django поставляется с «фиктивным» кешем, который на самом деле не кэширует — он просто реализует интерфейс кеша без выполнения каких-либо действий.

Это полезно, если у вас есть сайт в рабочей среде, который использует мощные механизмы кэширования в различных местах, но среда разработки/тестирования, где вы не хотите кэшировать и не хотите изменять свой код для обработки последнего случая. Чтобы активировать кэширование «фиктивными данными», установите BACKEND следующим образом:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.dummy.DummyCache",
    }
}

Использование пользовательского бэкенда кеша

Хотя Django предоставляет поддержку нескольких бэкендов кеша «из коробки», иногда может потребоваться использовать настраиваемый бэкенд кеша. Чтобы использовать внешний бэкенд кеша с Django, используйте путь импорта Python в качестве BACKEND параметра настройки CACHES, как показано ниже:

CACHES = {
    "default": {
        "BACKEND": "path.to.backend",
    }
}

Если вы создаёте собственный бэкенд, вы можете использовать стандартные бэкенды кеша в качестве эталонных реализаций. Вы найдёте код в каталоге django/core/cache/backends/ исходного кода Django.

Примечание: без действительно веской причины, такой как хостинг, который не поддерживает их, вы должны придерживаться бэкендов кеша, включённых в Django. Они хорошо протестированы и хорошо документированы.

Аргументы кэша

Каждый бэкенд кеша может принимать дополнительные аргументы для управления поведением кэширования. Эти аргументы предоставляются как дополнительные ключи в настройке CACHES. Допустимые аргументы следующие:

• TIMEOUT: Значение таймаута по умолчанию в секундах для кеша. Этот аргумент по умолчанию равен 300 секундам (5 минут). Вы можете установить TIMEOUT на None, чтобы по умолчанию ключи кеша никогда не истекали. Значение 0 заставляет ключи немедленно истекать (эффективно «не кэшировать»).

• OPTIONS: Любые параметры, которые необходимо передать бэкенду кеша. Список допустимых параметров будет различаться в зависимости от каждого бэкенда, и бэкенды кеша, основанные на сторонней библиотеке, будут передавать свои параметры непосредственно базовой библиотеке кеша.

  Бэкенды кеша, которые реализуют свою собственную стратегию удаления (т. е., бэкенды locmem, filesystem и database), будут учитывать следующие параметры:

  • MAX_ENTRIES: Максимальное количество элементов, разрешённых в кэше, прежде чем старые значения будут удалены. Этот аргумент по умолчанию равен 300.

  • CULL_FREQUENCY: Доля элементов, которые удаляются, когда достигается MAX_ENTRIES. Фактическое соотношение составляет 1 / CULL_FREQUENCY, поэтому установите CULL_FREQUENCY на 2, чтобы удалять половину элементов, когда достигается MAX_ENTRIES. Этот аргумент должен быть целым числом и по умолчанию равен 3.

    Значение 0 для CULL_FREQUENCY означает, что весь кеш будет очищен, когда достигается MAX_ENTRIES. В некоторых бэкендах (database, в частности) это делает удаление намного быстрее за счет большего количества промахов кеша.

  Бэкенды Memcached и Redis передают содержимое OPTIONS в качестве ключевых аргументов конструкторам клиента, что позволяет более точно контролировать поведение клиента. Пример использования показан ниже.

• KEY_PREFIX: Строка, которая будет автоматически включена (представлена по умолчанию) во все ключи кеша, используемые сервером Django.

  Дополнительную информацию см. в документации по кэшу.

• VERSION: Номер версии по умолчанию для ключей кеша, сгенерированных сервером Django.

  Дополнительную информацию см. в документации по кэшу.

• KEY_FUNCTION: Строка, содержащая путь с точками к функции, которая определяет, как составить префикс, версию и ключ в окончательный ключ кеша.

  Дополнительную информацию см. в документации по кэшу.

В этом примере файловый бэкенд настраивается с таймаутом 60 секунд и максимальной ёмкостью 1000 элементов:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": "/var/tmp/django_cache",
        "TIMEOUT": 60,
        "OPTIONS": {"MAX_ENTRIES": 1000},
    }
}

Вот пример конфигурации для бэкенда, основанного на pylibmc, который включает двоичный протокол, аутентификацию SASL и режим работы ketama:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyLibMCCache",
        "LOCATION": "127.0.0.1:11211",
        "OPTIONS": {
            "binary": True,
            "username": "user",
            "password": "pass",
            "behaviors": {
                "ketama": True,
            },
        },
    }
}

Вот пример конфигурации для бэкенда, основанного на pymemcache, который включает пул клиентов (что может улучшить производительность за счет поддержания подключений клиентов), обрабатывает ошибки memcache/сети как промахи кеша и устанавливает флаг TCP_NODELAY на сокете подключения:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": "127.0.0.1:11211",
        "OPTIONS": {
            "no_delay": True,
            "ignore_exc": True,
            "max_pool_size": 4,
            "use_pooling": True,
        },
    }
}

Вот пример конфигурации для бэкенда, основанного на redis, который выбирает базу данных 10 (по умолчанию Redis поставляется с 16 логическими базами данных) и устанавливает пользовательский класс пула подключений (redis.ConnectionPool используется по умолчанию):

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379",
        "OPTIONS": {
            "db": "10",
            "pool_class": "redis.BlockingConnectionPool",
        },
    }
}

Указание кэша на уровне представления в URLconf

В примерах в предыдущем разделе жестко задано, что представление кэшируется, потому что cache_page изменяет функцию my_view на месте. Этот подход связывает ваше представление с системой кэширования, что не является идеальным по нескольким причинам. Например, вы можете захотеть повторно использовать функции представлений на другом сайте без кэширования или распределить представления по людям, которые могут их использовать без кэширования. Решением этих проблем является указание кэша на уровне представления в URLconf, а не рядом с самими функциями представлений.

Вы можете сделать это, обернув функцию представления с помощью cache_page, когда вы ссылаетесь на нее в URLconf. Вот старый URLconf из предыдущего примера:

urlpatterns = [
    path("foo/<int:code>/", my_view),
]

Вот то же самое, с my_view, обернутым в cache_page:

from django.views.decorators.cache import cache_page

urlpatterns = [
    path("foo/<int:code>/", cache_page(60 * 15)(my_view)),
]

Доступ к кэшу

django.core.cache.caches

Вы можете получить доступ к кэшам, настроенным в настройке CACHES, через объект, подобный словарю: django.core.cache.caches. Повторные запросы к одному и тому же псевдониму в одном и том же потоке вернут один и тот же объект.

>>> from django.core.cache import caches
>>> cache1 = caches["myalias"]
>>> cache2 = caches["myalias"]
>>> cache1 is cache2
True

Если указанного ключа не существует, будет поднято исключение InvalidCacheBackendError.

Для обеспечения потокобезопасности для каждого потока будет возвращен другой экземпляр бэкенда кэша.

django.core.cache.cache

В качестве сокращения, кеш по умолчанию доступен как django.core.cache.cache:

>>> from django.core.cache import cache

Этот объект эквивалентен caches['default'].

Основные методы

Основные методы:

cache.set(key, value, timeout=DEFAULT_TIMEOUT, version=None)

>>> cache.set("my_key", "hello, world!", 30)

cache.get(key, default=None, version=None)

>>> cache.get("my_key")
'hello, world!'

key должен быть str, а value может быть любым объектом Python, который можно закодировать с помощью протокола pickle.

Аргумент timeout является необязательным и по умолчанию равен аргументу timeout соответствующего бэкенда в настройке CACHES (описано выше). Это количество секунд, в течение которого значение должно храниться в кэше. Передача значения None для timeout сохранит значение в кэше навсегда. Значение timeout равное 0 не сохранит значение в кэше.

Если объект отсутствует в кэше, cache.get() возвращает None:

>>> # Wait 30 seconds for 'my_key' to expire...
>>> cache.get("my_key")
None

Если вам нужно определить, существует ли объект в кэше, и вы сохранили литеральное значение None, используйте специальный объект в качестве значения по умолчанию:

>>> sentinel = object()
>>> cache.get("my_key", sentinel) is sentinel
False
>>> # Wait 30 seconds for 'my_key' to expire...
>>> cache.get("my_key", sentinel) is sentinel
True

cache.get() может принимать аргумент default. Это определяет, какое значение должно быть возвращено, если объект отсутствует в кэше:

>>> cache.get("my_key", "has expired")
'has expired'

cache.add(key, value, timeout=DEFAULT_TIMEOUT, version=None)

Для добавления ключа только если он еще не существует, используйте метод add(). Он принимает те же параметры, что и set(), но не пытается обновить кэш, если указанный ключ уже существует:

>>> cache.set("add_key", "Initial value")
>>> cache.add("add_key", "New value")
>>> cache.get("add_key")
'Initial value'

Если вам нужно узнать, хранил ли add() значение в кэше, вы можете проверить возвращаемое значение. Оно вернет True, если значение было сохранено, и False в противном случае.

cache.get_or_set(key, default, timeout=DEFAULT_TIMEOUT, version=None)

Если вы хотите получить значение ключа или установить значение, если ключ отсутствует в кэше, есть метод get_or_set(). Он принимает те же параметры, что и get(), но значение по умолчанию устанавливается как новое значение кэша для этого ключа, а не возвращается:

>>> cache.get("my_new_key")  # returns None
>>> cache.get_or_set("my_new_key", "my new value", 100)
'my new value'

Вы также можете передать любой вызываемый объект в качестве значения по умолчанию:

>>> import datetime
>>> cache.get_or_set("some-timestamp-key", datetime.datetime.now)
datetime.datetime(2014, 12, 11, 0, 15, 49, 457920)

cache.get_many(keys, version=None)

Также существует интерфейс get_many(), который обращается к кэшу только один раз. get_many() возвращает словарь со всеми запрошенными ключами, которые фактически существуют в кэше (и не истекли):

>>> cache.set("a", 1)
>>> cache.set("b", 2)
>>> cache.set("c", 3)
>>> cache.get_many(["a", "b", "c"])
{'a': 1, 'b': 2, 'c': 3}

cache.set_many(dict, timeout)

Для более эффективного задания нескольких значений используйте set_many(), чтобы передать словарь пар ключ-значение:

>>> cache.set_many({"a": 1, "b": 2, "c": 3})
>>> cache.get_many(["a", "b", "c"])
{'a': 1, 'b': 2, 'c': 3}

Как и cache.set(), set_many() принимает необязательный параметр timeout.

В поддерживаемых бэкендах (memcached) set_many() возвращает список ключей, которые не удалось вставить.

cache.delete(key, version=None)

Вы можете явно удалить ключи с помощью delete(), чтобы очистить кэш для определенного объекта:

>>> cache.delete("a")
True

delete() возвращает True, если ключ был успешно удален, и False в противном случае.

cache.delete_many(keys, version=None)

Если вы хотите очистить сразу несколько ключей, delete_many() может принимать список ключей для очистки:

>>> cache.delete_many(["a", "b", "c"])

cache.clear()

Наконец, если вы хотите удалить все ключи из кэша, используйте cache.clear(). Будьте осторожны; clear() удалит все из кэша, а не только ключи, заданные вашим приложением:

>>> cache.clear()

cache.touch(key, timeout=DEFAULT_TIMEOUT, version=None)

cache.touch() устанавливает новое время истечения срока действия для ключа. Например, чтобы обновить ключ, чтобы он истек через 10 секунд:

>>> cache.touch("a", 10)
True

Как и другие методы, аргумент timeout является необязательным и по умолчанию равен параметру TIMEOUT соответствующего бэкенда в настройке CACHES.

touch() возвращает True, если ключ был успешно обновлён, и False в противном случае.

cache.incr(key, delta=1, version=None)

cache.decr(key, delta=1, version=None)

Вы также можете увеличить или уменьшить значение ключа, который уже существует, используя методы incr() или decr() соответственно. По умолчанию существующее значение кэша будет увеличено или уменьшено на 1. Другие значения для увеличения/уменьшения можно указать, передав аргумент вызову увеличения/уменьшения. ValueError будет поднят, если вы попытаетесь увеличить или уменьшить несуществующий ключ кэша:

>>> cache.set("num", 1)
>>> cache.incr("num")
2
>>> cache.incr("num", 10)
12
>>> cache.decr("num")
11
>>> cache.decr("num", 5)
6

cache.close()

Вы можете закрыть подключение к кэшу с помощью close(), если это реализовано бэкендом кэша.

>>> cache.close()

Префикс ключей кэша

Если вы используете один экземпляр кэша на нескольких серверах или в производственной и тестовой средах, данные, кэшированные одним сервером, могут быть использованы другим. Если формат кэшированных данных отличается между серверами, это может привести к проблемам, которые сложно диагностировать.

Чтобы предотвратить это, Django предоставляет возможность префикса всех ключей кэша, используемых сервером. Когда конкретный ключ кэша сохраняется или извлекается, Django автоматически добавляет префикс к ключу кэша, используя значение настройки кэша KEY_PREFIX.

Обеспечивая, что у каждого экземпляра Django разный KEY_PREFIX, вы можете гарантировать, что не возникнет коллизий в значениях кэша.

Версионирование кэша

При изменении кода, использующего кэшированные значения, может потребоваться очистка всех существующих кэшированных значений. Наиболее простой способ сделать это — очистить весь кэш, но это может привести к потере валидных и полезных значений кэша.

Django предоставляет лучший способ для этого. Система кэширования Django имеет системный идентификатор версии, задаваемый с помощью настройки кэша VERSION. Значение этой настройки автоматически объединяется с префиксом кэша и предоставленным пользователем ключом кэша, чтобы получить окончательный ключ кэша.

По умолчанию любой запрос к ключу автоматически включает версию системного ключа кэша. Однако все базовые функции кэширования принимают аргумент version, поэтому вы можете указать конкретную версию ключа кэша для установки или получения. Например:

>>> # Set version 2 of a cache key
>>> cache.set("my_key", "hello world!", version=2)
>>> # Get the default version (assuming version=1)
>>> cache.get("my_key")
None
>>> # Get version 2 of the same key
>>> cache.get("my_key", version=2)
'hello world!'

Версия конкретного ключа может быть увеличена или уменьшена с помощью методов incr_version() и decr_version(). Это позволяет увеличивать/уменьшать версию конкретных ключей, не затрагивая другие. Продолжая наш предыдущий пример:

>>> # Increment the version of 'my_key'
>>> cache.incr_version("my_key")
>>> # The default version still isn't available
>>> cache.get("my_key")
None
# Version 2 isn't available, either
>>> cache.get("my_key", version=2)
None
>>> # But version 3 *is* available
>>> cache.get("my_key", version=3)
'hello world!'

Преобразование ключей кеша

Как описано в предыдущих двух разделах, ключ кеша, предоставленный пользователем, не используется дословно — он комбинируется с префиксом кеша и версией ключа для получения окончательного ключа кеша. По умолчанию три части соединяются двоеточием, чтобы получить конечную строку:

def make_key(key, key_prefix, version):
    return "%s:%s:%s" % (key_prefix, version, key)

Если вы хотите объединить части по-другому или применить другое преобразование к окончательному ключу (например, вычислить хэш-сумму частей ключа), вы можете предоставить пользовательскую функцию ключа.

Настройка кеша KEY_FUNCTION указывает путь к функции, соответствующей прототипу make_key() выше. Если она указана, эта пользовательская функция ключа будет использоваться вместо функции объединения ключей по умолчанию.

Предупреждения о ключах кеша

Memcached, наиболее часто используемый кэш-бекенд в рабочей среде, не позволяет ключам кеша иметь длину более 250 символов или содержать пробелы или управляющие символы, и использование таких ключей вызовет исключение. Чтобы поощрить переносимость кода кэша и свести к минимуму неприятные сюрпризы, другие встроенные кэш-бекенды выдают предупреждение (django.core.cache.backends.base.CacheKeyWarning), если используется ключ, который вызовет ошибку в memcached.

Если вы используете бекенд рабочей среды, который может принимать более широкий спектр ключей (пользовательский бекенд или один из встроенных бекендов, не являющихся memcached), и хотите использовать этот более широкий спектр без предупреждений, вы можете отключить CacheKeyWarning с помощью этого кода в модуле management одного из ваших INSTALLED_APPS:

import warnings

from django.core.cache import CacheKeyWarning

warnings.simplefilter("ignore", CacheKeyWarning)

Если вы хотите вместо этого предоставить пользовательскую логику валидации ключей для одного из встроенных бекендов, вы можете унаследовать его, переопределить только метод validate_key и следовать инструкциям по использованию пользовательского кэш-бекенда. Например, чтобы сделать это для бекенда locmem, поместите этот код в модуль:

from django.core.cache.backends.locmem import LocMemCache


class CustomLocMemCache(LocMemCache):
    def validate_key(self, key):
        """Custom validation, raising exceptions or warnings as needed."""
        ...

…и используйте путь к этому классу в Python в части BACKEND вашей настройки CACHES.