Skip to content

1.8.0

Latest

Choose a tag to compare

@github-actions github-actions released this 18 Nov 22:12
· 1 commit to master since this release
1.8.0

This release is mostly about keys and correctness. pylibmc now checks every key itself, as the memcached protocol says it should, so a stray space or newline can no longer corrupt a connection or inject a command. Booleans come back as booleans, numbers that do not fit are refused instead of wrapping around, and the Linux wheels can log in with SASL. New are master keys, exists(), incr and decr with an initial value, and more behaviors and exception classes. pylibmc now needs Python 3.11 or later. Read the changes that can break existing code before upgrading.

Changes that can break existing code

  • pylibmc needs CPython 3.11 or later, or PyPy 3.11: Python 3.8 to 3.10 and PyPy 3.9 and 3.10 have reached end of life. pip on an older Python keeps installing pylibmc 1.7.x; pin pylibmc<1.8 if your environment resolves packages some other way. Building from source needs libmemcached 1.0.18 or later, the oldest version that was ever tested (the documentation said 1.0.8); an older one stops the build with an error (#362). The wheels are not affected.
  • With the text protocol (the default), a key that contains whitespace or a control character (the bytes 0x00 to 0x20 and 0x7f) raises ValueError in every method, before anything is sent (#351). Such keys used to reach the server: a space or a newline made later replies go to the wrong call on the same client, \r\n could inject commands such as flush_all, and some calls quietly reported a miss. This is the memcached protocol's rule, and the one python-memcached enforces. UTF-8 and other non-ASCII bytes are still fine, as is any byte with binary=True; hash or percent-encode keys that break the rule. The verify_keys behavior is therefore ignored: setting it emits a DeprecationWarning, and get_behaviors() no longer lists it.
  • True and False come back as booleans, not as 1 and 0 (#245). They are stored as the integer with an extra flag (bit 31), so older pylibmc and python-memcached still read the integer. Booleans stored by earlier versions still read back as integers, and a stored bool that the server changes with incr, decr, append or prepend reads back as the number it now is.
  • Numbers that do not fit are refused instead of silently wrapping around. An expiry time that is negative or does not fit in 32 bits raises ValueError in every method that takes one (#202); the text protocol used to expire such a key at once and the binary protocol to store it forever. A cas token outside 64 bits raises OverflowError, as do a too large min_compress_len, delta of incr_multi and decr_multi, and flags of deserialize; negative values of those raise ValueError (#357).
  • A udp: client is write-only: libmemcached sends without reading replies. incr, decr, incr_multi, cas and exists on such a client now raise NotSupportedError instead of returning made-up values, as reads already did, and the other writes return True, which means "sent" (#377).
  • SocketCreateError is now called ErrorReply: it has always meant that the server answered ERROR, not a socket failure. The old name is the very same class, so catching it keeps working, but using it emits a DeprecationWarning. Errors that used to be a plain pylibmc.Error now have subclasses of their own (see below), which matters only to code that checks type(exc) is pylibmc.Error.

New

  • Every data method takes a keyword-only master_key= argument (#53, #176). When given, it is hashed instead of the key to pick the server, so related keys can live on one server and a get_multi of them reaches only that server. Pass the same master key to read, change and delete an item as to write it. See the "Master keys" section of the docs.
  • Client.exists(key, master_key=None) tells whether a key is stored without transferring the value (#378). It is not free: libmemcached asks with an add of an empty item that expires at once, so on a full cache a miss can evict another item. key in client therefore keeps using get.
  • incr and decr take initial= and expire=, which create a missing key with that value in one round trip instead of a racy add followed by incr (#379). This needs binary=True; a text-protocol client raises NotSupportedError. A key created this way holds plain digits, so get returns bytes. delta may now be up to 2**32 - 1.
  • cas takes min_compress_len and compress_level and compresses like set, and cas tokens of 2**63 and above work (#285).
  • New behaviors tcp_keepidle, randomize_replica_read and server_timeout_limit, and the murmur3 hash, which needs libmemcached 1.1 or later (the wheels have it) (#380).
  • New exception classes, all subclasses of pylibmc.Error: AuthFailure (SASL login refused), AuthProblem (the login could not be attempted), InvalidArguments, ServerAllocationError (the server is out of memory), InProgress and SystemCallError (#381).

Fixes

  • SASL logins work with the Linux wheels on Debian, Ubuntu and other systems where they failed with "no mechanism available" (#289). The wheels ship the PLAIN, LOGIN, CRAM-MD5, DIGEST-MD5 and SCRAM-SHA-1 plugins and point only their own copy of libsasl2 at them, so other SASL users in the process are not affected. A SASL_PATH you set is used instead. For Kerberos (GSSAPI), set SASL_PATH to your system's plugin directory.
  • Reference leaks: incr_multi and decr_multi leaked every key on every call, delete_multi leaked a key whenever a delete failed, and get, gets, get_multi and delete_multi leaked rejected keys.
  • key_prefix in the *_multi methods no longer cuts a key short at a NUL byte, which with binary=True stored keys under the wrong name.
  • get_behaviors() no longer raises KeyError for a hash or distribution pylibmc has no name for; it returns the number, and setting a number works.
  • Client.clone() raises MemoryError instead of returning an unusable client.
  • For packagers: the test suite again runs against a memcached at any address given by MEMCACHED_HOST and MEMCACHED_PORT, as in 1.6.3 (#376).

Build and platforms

  • Python 3.15 is supported.
  • Wheels are provided for PyPy 3.11 on both PyPy 7.3 (pypy311_pp73) and PyPy 8.0 (pypy311_pp80).
  • The extension's leftover code for Python 2 and Pythons older than 3.11 is gone. The only difference you could notice is that it imports pickle directly instead of first trying a module called cPickle.

Documentation

  • The pickle_protocol behavior suggests pinning the protocol when more than one Python version shares a cache, and the pooling example no longer uses xrange.

Thanks to Tim Graham for dropping the end-of-life Pythons, restoring the commented-out doctests and much other cleanup, and to @mxamin, whose testing and review of the release candidates found problems that were fixed before 1.8.0.

Install with pip install -U pylibmc. Full change log: https://github.com/lericson/pylibmc/blob/master/docs/changelog.rst