Metadata-Version: 2.4
Name: core-redis
Version: 1.0.0
Summary: This project/library contains common elements related to Redis integration...
Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
Maintainer: Alejandro Cora González
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/bytecode-solutions/core/core-redis
Project-URL: Repository, https://gitlab.com/bytecode-solutions/core/core-redis
Project-URL: Documentation, https://core-redis.readthedocs.io/en/latest/
Project-URL: Issues, https://gitlab.com/bytecode-solutions/core/core-redis/-/issues
Project-URL: Changelog, https://gitlab.com/bytecode-solutions/core/core-redis/-/blob/master/CHANGELOG.md
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: core-mixins>=3.1.2
Requires-Dist: redis>=4.0.0
Provides-Extra: dev
Requires-Dist: core-dev-tools>=1.2.1; extra == "dev"
Requires-Dist: core-tests>=2.0.5; extra == "dev"
Dynamic: license-file

core-redis
===============================================================================

This project/library contains common elements related to Redis integration.

===============================================================================

.. image:: https://img.shields.io/pypi/pyversions/core-redis.svg
    :target: https://pypi.org/project/core-redis/
    :alt: Python Versions

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-redis/-/blob/main/LICENSE
    :alt: License

.. image:: https://gitlab.com/bytecode-solutions/core/core-redis/badges/release/pipeline.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-redis/-/pipelines
    :alt: Pipeline Status

.. image:: https://readthedocs.org/projects/core-redis/badge/?version=latest
    :target: https://readthedocs.org/projects/core-redis/
    :alt: Docs Status

.. image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security

|


Installation
===============================================================================

.. code-block:: bash

    pip install core-redis
    uv pip install core-redis  # or using UV


Features
===============================================================================

- ``RedisClient``: thin connection wrapper that decouples the ecosystem from
  the underlying ``redis`` library.
- ``cache_redis_based``: write-through caching decorator backed by Redis (L2)
  with an in-memory LRU as L1.


RedisClient
===============================================================================

``RedisClient`` abstracts the ``redis`` library so the rest of the ecosystem
never imports it directly. The connection is created lazily on first use and
is thread-safe.

.. code-block:: python

    from core_redis import RedisClient

    client = RedisClient(host="localhost", port=6379, db=0)

    client.set("key", b"value", ex=60)        # store with 60 s TTL
    data  = client.get("key")                 # b"value" or None
    count = client.delete("key")              # 1
    n     = client.exists("key", "other")     # 0–N
    alive = client.ping()                     # True

Additional keyword arguments are forwarded verbatim to ``redis.Redis``
(e.g. ``ssl=True``, ``socket_timeout=5``).


cache_redis_based
===============================================================================

Write-through caching decorator: L1 is a bounded in-memory LRU; L2 is Redis.
TTL is handled natively by Redis (``SET … EX``), so no background threads or
manual expiry are needed.

.. code-block:: python

    from core_redis.decorators import cache_redis_based

    @cache_redis_based(
        key_prefix="myapp/",
        ttl=3600,
        redis_kwargs={"host": "localhost", "port": 6379},
    )
    def fetch_reference_data(dataset: str) -> dict:
        ...


Local Redis with Docker
===============================================================================

Start a Redis server on the default port:

.. code-block:: bash

    docker run -d --name redis-local -p 6379:6379 redis:latest

Stop and remove it when done:

.. code-block:: bash

    docker stop redis-local && docker rm redis-local


Setting Up for Development
===============================================================================

.. code-block:: bash

    pip install --upgrade pip
    pip install virtualenv
    virtualenv --python=python3.12 .venv
    source .venv/bin/activate
    pip install -e ".[dev]"


Running Tests
===============================================================================

.. code-block:: shell

    python manager.py run-tests                                          # unit tests
    python manager.py run-tests --test-type integration
    python manager.py run-coverage                                       # unit + coverage

Functional tests require a running Redis server (see `Local Redis with Docker`_):

.. code-block:: shell

    # defaults: REDIS_HOST=localhost REDIS_PORT=6379 REDIS_DB=15
    python manager.py run-tests --test-type functional --pattern "*.py"


Contributing
===============================================================================

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass: ``python manager.py run-tests``
5. Run linting: ``pylint core_redis``
6. Run security checks: ``bandit -r core_redis``
7. Submit a pull request


License
===============================================================================

This project is licensed under the MIT License. See the LICENSE file for details.


Links
===============================================================================

* **Documentation:** https://core-redis.readthedocs.io/en/latest/
* **Repository:** https://gitlab.com/bytecode-solutions/core/core-redis
* **Issues:** https://gitlab.com/bytecode-solutions/core/core-redis/-/issues
* **Changelog:** https://gitlab.com/bytecode-solutions/core/core-redis/-/blob/master/CHANGELOG.md
* **PyPI:** https://pypi.org/project/core-redis/


Support
===============================================================================

For questions or support, please open an issue on GitLab or contact the maintainers.


Authors
===============================================================================

* **Alejandro Cora González** - *Initial work* - alek.cora.glez@gmail.com
