Andriy Kornatskyy avatar Andriy Kornatskyy committed ba90603

Added Key Encoding section to documentation.

Comments (0)

Files changed (1)

doc/userguide.rst

 :py:class:`~wheezy.caching.pools.Pooled` serves context manager purpose,
 effectively acquiring and returning item to the pool.
 
+Key Encoding
+------------
+
+`Memcached`_ has some restrictions concerning keys used. Text protocol requires
+a valid key contain only ASCII characters except space (0x20), carriage
+return (0x0d), line feed (0x0a) since these characters are meaningful in
+text protocol. Key length is restricted to 250.
+
+* :py:meth:`~wheezy.caching.encoding.string_encode` - encodes ``key`` with
+  UTF-8 encoding.
+* :py:meth:`~wheezy.caching.encoding.base64_encode` - encodes ``key`` with
+  base64 encoding.
+* :py:meth:`~wheezy.caching.encoding.hash_encode` - encodes ``key`` with
+  given hash function. See list of available hashes in ``hashlib`` module
+  from Python Statndard Library. Additional algorithms may also be available
+  depending upon the OpenSSL library that Python uses on your platform.
+
+There is general purpose function:
+
+* :py:meth:`~wheezy.caching.encoding.encode_keys` - encodes all keys in mapping
+  with ``key_encode`` callable. Returns a tuple of: *key mapping*
+  (encoded key => key) and *value mapping* (encoded key => value).
+
+You can specify key encoding function by passing ``key_encode`` argument to
+*memcache* and/or *pylibmc* cache factory.
+
 CacheDependency
 ---------------
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.