Repository navigation
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.8if 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
0x00to0x20and0x7f) raisesValueErrorin 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\ncould inject commands such asflush_all, and some calls quietly reported a miss. This is the memcached protocol's rule, and the onepython-memcachedenforces. UTF-8 and other non-ASCII bytes are still fine, as is any byte withbinary=True; hash or percent-encode keys that break the rule. Theverify_keysbehavior is therefore ignored: setting it emits aDeprecationWarning, andget_behaviors()no longer lists it. TrueandFalsecome back as booleans, not as1and0(#245). They are stored as the integer with an extra flag (bit 31), so older pylibmc andpython-memcachedstill read the integer. Booleans stored by earlier versions still read back as integers, and a stored bool that the server changes withincr,decr,appendorprependreads 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
ValueErrorin 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. Acastoken outside 64 bits raisesOverflowError, as do a too largemin_compress_len,deltaofincr_multianddecr_multi, andflagsofdeserialize; negative values of those raiseValueError(#357). - A
udp:client is write-only: libmemcached sends without reading replies.incr,decr,incr_multi,casandexistson such a client now raiseNotSupportedErrorinstead of returning made-up values, as reads already did, and the other writes returnTrue, which means "sent" (#377). SocketCreateErroris now calledErrorReply: it has always meant that the server answeredERROR, not a socket failure. The old name is the very same class, so catching it keeps working, but using it emits aDeprecationWarning. Errors that used to be a plainpylibmc.Errornow have subclasses of their own (see below), which matters only to code that checkstype(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 aget_multiof 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 anaddof an empty item that expires at once, so on a full cache a miss can evict another item.key in clienttherefore keeps usingget.incranddecrtakeinitial=andexpire=, which create a missing key with that value in one round trip instead of a racyaddfollowed byincr(#379). This needsbinary=True; a text-protocol client raisesNotSupportedError. A key created this way holds plain digits, sogetreturnsbytes.deltamay now be up to2**32 - 1.castakesmin_compress_lenandcompress_leveland compresses likeset, and cas tokens of2**63and above work (#285).- New behaviors
tcp_keepidle,randomize_replica_readandserver_timeout_limit, and themurmur3hash, 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),InProgressandSystemCallError(#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-MD5andSCRAM-SHA-1plugins and point only their own copy of libsasl2 at them, so other SASL users in the process are not affected. ASASL_PATHyou set is used instead. For Kerberos (GSSAPI), setSASL_PATHto your system's plugin directory. - Reference leaks:
incr_multianddecr_multileaked every key on every call,delete_multileaked a key whenever a delete failed, andget,gets,get_multianddelete_multileaked rejected keys. key_prefixin the*_multimethods no longer cuts a key short at a NUL byte, which withbinary=Truestored keys under the wrong name.get_behaviors()no longer raisesKeyErrorfor a hash or distribution pylibmc has no name for; it returns the number, and setting a number works.Client.clone()raisesMemoryErrorinstead of returning an unusable client.- For packagers: the test suite again runs against a memcached at any address given by
MEMCACHED_HOSTandMEMCACHED_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
pickledirectly instead of first trying a module calledcPickle.
Documentation
- The
pickle_protocolbehavior suggests pinning the protocol when more than one Python version shares a cache, and the pooling example no longer usesxrange.
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