Fixed #20892 -- Allowed configuring memcached client using OPTIONS.

Previously, the MemcachedCache backend ignored `OPTIONS` and
PyLibMCCache used them to set pylibmc behaviors. Both backends now
pass `OPTIONS` as keyword arguments to the client constructors.

3 files changed, 53 insertions, 3 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 7aa58e4ee7..b983ae1ace 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -27,6 +27,9 @@ details on these changes.
 
 * ``django.utils.translation.string_concat()`` will be removed.
 
+* ``django.core.cache.backends.memcached.PyLibMCCache`` will no longer support
+  passing ``pylibmc`` behavior settings as top-level attributes of ``OPTIONS``.
+
 .. _deprecation-removed-in-2.0:
 
 2.0
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index 3953ba917c..d6a59c8ab9 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -168,7 +168,10 @@ Minor features
 Cache
 ~~~~~
 
-* ...
+* Memcached backends now pass the contents of :setting:`OPTIONS <CACHES-OPTIONS>`
+  as keyword arguments to the client constructors, allowing for more advanced
+  control of client behavior. See the :ref:`cache arguments <cache_arguments>`
+  documentation for examples.
 
 CSRF
 ~~~~
@@ -490,3 +493,7 @@ Miscellaneous
 * ``django.utils.translation.string_concat()`` is deprecated in
   favor of :func:`django.utils.text.format_lazy`. ``string_concat(*strings)``
   can be replaced by ``format_lazy('{}' * len(strings), *strings)``.
+
+* For the ``PyLibMCCache`` cache backend, passing ``pylibmc`` behavior settings
+  as top-level attributes of ``OPTIONS`` is deprecated. Set them under a
+  ``behaviors`` key within ``OPTIONS`` instead.
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 50b4be95b9..1730ef6294 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -403,6 +403,10 @@ behavior. These arguments are provided as additional keys in the
     On some backends (``database`` in particular) this makes culling *much*
     faster at the expense of more cache misses.
 
+  Memcached backends pass the contents of :setting:`OPTIONS <CACHES-OPTIONS>`
+  as keyword arguments to the client constructors, allowing for more advanced
+  control of client behavior. For example usage, see below.
+
 * :setting:`KEY_PREFIX <CACHES-KEY_PREFIX>`: A string that will be
   automatically included (prepended by default) to all cache keys
   used by the Django server.
@@ -437,8 +441,44 @@ of 60 seconds, and a maximum capacity of 1000 items::
         }
     }
 
-Invalid arguments are silently ignored, as are invalid values of known
-arguments.
+Here's an example configuration for a ``python-memcached`` based backend with
+an object size limit of 2MB::
+
+    CACHES = {
+        'default': {
+            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
+            'LOCATION': '127.0.0.1:11211',
+            'OPTIONS': {
+                'server_max_value_length': 1024 * 1024 * 2,
+            }
+        }
+    }
+
+Here's an example configuration for a ``pylibmc`` based backend that enables
+the binary protocol, SASL authentication, and the ``ketama`` behavior mode::
+
+    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,
+                }
+            }
+        }
+    }
+
+.. versionchanged:: 1.11
+
+    Memcached backends can now be configured using ``OPTIONS``.
+
+    In older versions, you could pass ``pylibmc`` behavior settings directly
+    inside ``OPTIONS``. This is deprecated in favor of setting them under a
+    ``behaviors`` key within ``OPTIONS`` instead.
 
 .. _the-per-site-cache: