<commit_before>django-redis documentation
==========================
<NAME>, <<EMAIL>>
4.0.0
:toc: left
:numbered:
:source-highlighter: pygments
:pygments-style: friendly


Introduction
------------

_django-redis_ is a xref:license[BSD Licensed], full featured Redis cache/session backend for Django.


Why use django-redis?
~~~~~~~~~~~~~~~~~~~~~

Because:

- In active development.
- Uses native redis-py url notation connection strings.
- Pluggable clients.
- Pluggable parsers.
- Pluggable serializers.
- Master-Slave support in the default client.
- Complete battery of tests.
- Used in production in several projects as cache and session storage.
- Supports infinite timeouts.
- Facilities for raw access to Redis client/connection pool.
- Highly configurable (can emulate memcached exception behavior, for example).
- Unix sockets supported by default.
- With support for python 2.7, 3.3 and 3.4



Supported django-redis versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Development version: *4.0.0*
- Supported stable version: *3.8.4*


How version number is handled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Versions like _3.6_, _3.7_, ... are considered major releases
and can contain some backward incompatibilities. For more information
is very recommended see the changelog before update.

Versions like _3.7.0_, _3.7.1_, ... are considered minor or bug
fix releases and are should contain only bug fixes. No new features.


Requirements
~~~~~~~~~~~~

Django version support
^^^^^^^^^^^^^^^^^^^^^^

- *django-redis 3.8.x* will maintain support for django 1.4, 1.5, 1.6, 1.7 (and maybe 1.8)
- *django-redis 4.0.0* will maintain support for django 1.6, 1.7 and 1.8


Redis Server Support
^^^^^^^^^^^^^^^^^^^^

- *django-redis 3.8.x* will maintain support for redis-server 2.6.x and upper.
- *django-redis 4.0.0* will maintain support for redis-server 2.8.x and upper.


Other requirements
^^^^^^^^^^^^^^^^^^

All supported versions of *django-redis* depends on `redis-py >= 2.10.0`.


User guide
----------

Installation
~~~~~~~~~~~~

The simplest way to use *django-redis* in your project is to install it with *pip*:

[source,text]
----
pip install django-redis
----

Configure as cache backend
~~~~~~~~~~~~~~~~~~~~~~~~~~

To start using *django-redis*, you should change your Django cache settings to something like this:

[source, python]
----
CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
        }
    }
}
----

django-redis, since 3.8.0, it starts using redis-py native url notation for connection strings,
that allows better interoperability and have a connection string in more "standard" way.

.This is a examples of url format
----
redis://[:password]@localhost:6379/0
rediss://[:password]@localhost:6379/0
unix://[:password]@/path/to/socket.sock?db=0
----

Three URL schemes are supported:

- `redis://`: creates a normal TCP socket connection
- `rediss://`: creates a SSL wrapped TCP socket connection
- `unix://` creates a Unix Domain Socket connection

There are several ways to specify a database number:

- A `db` querystring option, e.g. redis://localhost?db=0
- If using the redis:// scheme, the path argument of the url, e.g. `redis://localhost/0`


NOTE: if you are coming fron django-redis < 3.8.x, you are probably using redis_cache. Since
django-redis 3.8.x, `redis_cache` module is deprecated in favor to `django_redis`. The
`redis_cache` module will be removed in 3.9.x versions.




Configure as session backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Django can by default use any cache backend as session backend and you benefit from that by using
*django-redis* as backend for session storage without installing any additional backends:

[source, python]
----
SESSION_ENGINE = "django.contrib.sessions.backends.cache"
SESSION_CACHE_ALIAS = "default"<commit_msg>Update documentation.<commit_after>django-redis documentation
==========================
<NAME>, <<EMAIL>>
4.1.0
:toc: left
:numbered:
:source-highlighter: pygments
:pygments-style: friendly


Introduction
------------

_django-redis_ is a xref:license[BSD Licensed], full featured Redis cache/session backend for Django.


Why use django-redis?
~~~~~~~~~~~~~~~~~~~~~

Because:

- In active development.
- Uses native redis-py url notation connection strings.
- Pluggable clients.
- Pluggable parsers.
- Pluggable serializers.
- Master-Slave support in the default client.
- Complete battery of tests.
- Used in production in several projects as cache and session storage.
- Supports infinite timeouts.
- Facilities for raw access to Redis client/connection pool.
- Highly configurable (can emulate memcached exception behavior, for example).
- Unix sockets supported by default.
- With support for python 2.7, 3.3 and 3.4



Supported django-redis versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Supported stable version: *4.1.0*
- Supported stable version: *3.8.4*


How version number is handled
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Versions like _3.6_, _3.7_, ... are considered major releases
and can contain some backward incompatibilities. For more information
is very recommended see the changelog before update.

Versions like _3.7.0_, _3.7.1_, ... are considered minor or bug
fix releases and are should contain only bug fixes. No new features.


Requirements
~~~~~~~~~~~~

Django version support
^^^^^^^^^^^^^^^^^^^^^^

- *django-redis 3.8.x* will maintain support for django 1.4, 1.5, 1.6, 1.7 (and maybe 1.8)
- *django-redis 4.1.0* will maintain support for django 1.6, 1.7 and 1.8


Redis Server Support
^^^^^^^^^^^^^^^^^^^^

- *django-redis 3.x.y* will maintain support for redis-server 2.6.x and upper.
- *django-redis 4.x.y* will maintain support for redis-server 2.8.x and upper.


Other requirements
^^^^^^^^^^^^^^^^^^

All supported versions of *django-redis* depends on `redis-py >= 2.10.0`.


User guide
----------

Installation
~~~~~~~~~~~~

The simplest way to use *django-redis* in your project is to install it with *pip*:

[source,text]
----
pip install django-redis
----

Configure as cache backend
~~~~~~~~~~~~~~~~~~~~~~~~~~

To start using *django-redis*, you should change your Django cache settings to something like this:

[source, python]
----
CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
        }
    }
}
----

django-redis, since 3.8.0, it starts using redis-py native url notation for connection strings,
that allows better interoperability and have a connection string in more "standard" way.

.This is a examples of url format
----
redis://[:password]@localhost:6379/0
rediss://[:password]@localhost:6379/0
unix://[:password]@/path/to/socket.sock?db=0
----

Three URL schemes are supported:

- `redis://`: creates a normal TCP socket connection
- `rediss://`: creates a SSL wrapped TCP socket connection
- `unix://` creates a Unix Domain Socket connection

There are several ways to specify a database number:

- A `db` querystring option, e.g. redis://localhost?db=0
- If using the redis:// scheme, the path argument of the url, e.g. `redis://localhost/0`


NOTE: if you are coming fron django-redis < 3.8.x, you are probably using redis_cache. Since
django-redis 3.8.x, `redis_cache` module is deprecated in favor to `django_redis`. The
`redis_cache` module will be removed in 3.9.x versions.



Configure as session backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Django can by default use any cache backend as session backend and you benefit from that by using
*django-redis* as backend for session storage without installing any additional backends:

[source, python]
----
SESSION_ENGINE = "django.contrib.sessions.backends.cache"
SESSION_CACHE_ALIAS = "default"
{'fraction_non_alphanumeric': 0.16240506329113924, 'fraction_numerical': 0.02291139240506329, 'mean_word_length': 3.856177012907191, 'pattern_counts': {'":': 10, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4691480', 'n_tokens_mistral': 2479, 'n_tokens_neox': 2333, 'n_words': 877}