Metadata-Version: 2.4
Name: python-binary-memcached
Version: 0.33.0
Summary: A pure python module to access memcached via its binary protocol with SASL auth support
Author-email: Jayson Reis <santosdosreis@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/jaysonsantos/python-binary-memcached
Project-URL: Repository, https://github.com/jaysonsantos/python-binary-memcached
Project-URL: Documentation, https://python-binary-memcached.readthedocs.org
Project-URL: Changelog, https://github.com/jaysonsantos/python-binary-memcached/blob/main/CHANGELOG.md
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: uhashring
Dynamic: license-file

Introduction to bmemcached
==========================

A pure python module (thread safe) to access memcached via it's binary with SASL auth support.

The main purpose of this module it to be able to communicate with memcached using binary protocol and support authentication, so it can work with Heroku for example.

Latest compiled docs on Read The Docs `here <https://python-binary-memcached.readthedocs.org>`_.

Installing
----------
Use pip or easy_install.

.. code-block:: bash

    pip install python-binary-memcached

Using
-----

.. code-block:: python

    import bmemcached
    client = bmemcached.Client(('127.0.0.1:11211', ), 'user',
                                'password')
    client.set('key', 'value')
    print(client.get('key'))


Using it with distributed keys

.. code-block:: python

    import bmemcached
    client = bmemcached.DistributedClient(
        ('127.0.0.1:11211', ), 'user', 'password'
    )
    client.set('key', 'value')
    print(client.get('key'))

Using it with raw data

By default, the client keeps the type of each value in the memcached flags field.
Some applications already use the flags field for their own data, and a default
client then fails to read their keys. Set ``raw_data=True`` to read and write
those keys.

.. code-block:: python

    import bmemcached
    client = bmemcached.Client(('127.0.0.1:11211', ), raw_data=True)
    client.set('key', b'value')
    print(client.get('key'))  # b'value'

In raw data mode:

- A read returns the stored ``bytes`` value. The client ignores the flags field.
- A write accepts only ``bytes`` values. Other types raise ``TypeError``.
- The client does not compress values. The default ``compress_level=-1`` means
  no compression, and a ``compress_level`` greater than 0 raises
  ``MemcachedException``.

``DistributedClient`` accepts the same ``raw_data`` argument.

.. warning::

    A write in raw data mode sets the flags field of the key to 0. This
    overwrites the flags that another application set on the key.

Testing
-------

``python-binary-memcached`` unit tests are found in the ``test/`` directory
and are designed to be run using `pytest`_. `pytest`_ will discover the tests
automatically, so all you have to do is:

.. code-block:: console

    $ pytest
    ...
    170 passed in 4.43 seconds

This runs the tests with the default Python interpreter.

You can also verify that the tests pass on other supported Python interpreters.
For this we use ``tox``, which will automatically create a ``virtualenv`` for
each supported Python version and run the tests. For example:

.. code-block:: console

    $ tox
    ...
    py310: commands succeeded
    py311: commands succeeded
    py312: commands succeeded
    ERROR:  py313: InterpreterNotFound: python3.13
    py314: commands succeeded

You may not have all the required Python versions installed, in which case you
will see one or more ``InterpreterNotFound`` errors.

Using with Django
-----------------
If you want to use it with Django, go to `django-bmemcached <https://github.com/jaysonsantos/django-bmemcached>`_ to get a Django backend.

Tests Status
------------
.. image:: https://github.com/jaysonsantos/python-binary-memcached/actions/workflows/tests-and-lint.yml/badge.svg?branch=main
    :target: https://github.com/jaysonsantos/python-binary-memcached/actions/workflows/tests-and-lint.yml

.. _`pytest`: https://pypi.org/project/pytest/
.. _`tox`: https://pypi.org/project/tox/
