DOCSEARCHbyAlgolia
Submit Docs

cacheout

repository·master·Indexed 19 days ago

https://github.com/dgilland/cacheout

A thread-safe, in-memory caching library for Python (>= 3.6) supporting multiple eviction policies including FIFO and LFU. It features memoization via decorators, bulk operations (get_many, set_many, add_many, delete_many), TTL expiration, and lifecycle callbacks for monitoring cache events.

Tokens
8.7K
Snippets
43
Records
49
Agent score
65%

What's inside cacheout

  1. Understand cacheout versioning and API stability

    master

    The project follows Semantic Versioning (SemVer). Backwards compatibility is only guaranteed for the public API, which consists of objects imported directly into the cacheout module.

    To ensure your integration does not break during MINOR version updates, you should only import and use objects from the main cacheout module. Objects located in other parts of the library (internal modules or sub-packages) may undergo breaking changes even in minor releases.

  3. Guidelines for submitting a Pull Request

    master

    Before submitting a pull request to cacheout, ensure it adheres to the following requirements:

    • Include Tests: Every pull request must include corresponding tests for the changes made.
    • Cross-Version Compatibility: The changes must work correctly across all Python versions supported by the project.

  4. Autoformat code with invoke

    master

    Use the invoke CLI to automatically format the codebase. You can run all formatters at once or target specific tools like black, isort, or docformatter individually.

    # Run all autoformatters
inv fmt

# Run individual formatters
inv black
inv isort
inv docformatter

  6. Set up cacheout for local development

    master

    To contribute to cacheout, follow these steps to set up your local development environment:

    1. Fork and Clone: Fork the repository on GitHub and clone your fork locally.
    2. Environment Setup: Create a virtual environment and install the required dependencies using requirements.txt.
    3. Branching: Create a new branch for your specific bugfix or feature.
    4. Formatting: Use the inv fmt command to autoformat your code according to project standards.
    5. Testing: Run tox to ensure your changes pass all unit tests across all supported Python versions.
    6. Documentation: Add your name to AUTHORS.rst.
    7. Submission: Commit your changes, push to your fork, and submit a pull request via GitHub.
    # Clone your fork
git clone git@github.com:your_username_here/cacheout.git

# Install dependencies
cd cacheout
pip install -r requirements.txt

# Create a development branch
git checkout -b name-of-your-bugfix-or-feature

# Autoformat code
inv fmt

# Run tests across all supported Python versions
tox

# Commit and push
git add .
git commit -m "<Detailed description of your changes>"
git push origin name-of-your-bugfix-or-feature-branch

  7. Lint the codebase with invoke

    master

    Use the invoke CLI to run linters and type checkers. You can run the full linting suite or target specific tools like flake8, pylint, or mypy individually.

    # Run all linters
inv lint

# Run individual linters
inv flake8
inv pylint
inv mypy

  8. How to report bugs or submit feedback

    master

    Bugs and feature proposals should be submitted via GitHub issues at https://github.com/dgilland/cacheout.

    When reporting a bug, include:

    • Your operating system name and version.
    • Details about your local setup relevant to troubleshooting.
    • Detailed, reproducible steps to trigger the bug.

    When proposing a feature:

    • Provide a detailed explanation of how the feature would work.
    • Keep the proposed scope as narrow as possible to facilitate implementation.

  9. Run tests with invoke or tox

    master

    You can run tests using invoke for local execution or tox to run tests across all supported Python versions (provided those versions are available on your PATH).

    Using invoke

    • inv unit: Runs all unit tests.
    • inv test: Runs unit tests and builds.
    # Run unit tests
inv unit

# Run unit tests and builds
inv test

# Run tests on all supported Python versions
tox

  10. Build and release the package

    master

    Use invoke to manage package distributions and releases.

    • inv build: Builds the package, outputting source and binary distributions to the dist/ directory.
    • inv release: Releases a new version of the package to PyPI.
    # Build the package
inv build

# Release to PyPI
inv release

  11. Initialize a Cache object

    master

    Create a new Cache instance. By default, it has a maxsize of 256, TTL expiration disabled, and returns None for missing keys. You can customize these settings during initialization.

    Supported replacement policies include:

    • FIFO (First In, First Out)
    • LIFO (Last In, First Out)
    • LRU (Least Recently Used)
    • MRU (Most Recently Used)
    • LFU (Least Frequently Used)
    • RR (Random Replacement)
    from cacheout import Cache
import time

# Default cache
cache = Cache()

# Customized cache
# Note: ttl is in seconds if timer is time.time
cache = Cache(maxsize=256, ttl=0, timer=time.time, default=None)

  12. Manage documentation with invoke

    master

    Use invoke to build or serve the project documentation.

    • inv docs: Builds the documentation, outputting files to docs/_build/.
    • inv docs -s|--server: Serves the documentation over HTTP.

    Serving options

    • -b|--bind <address>: Specify the bind address (default: 127.0.0.1).
    • -p|--port <port>: Specify the port (default: 8000).
    # Build docs
inv docs

# Serve docs on default (127.0.0.1:8000)
inv docs -s

# Serve docs on specific port
inv docs -s -p 8080

# Serve docs on specific bind address and port
inv docs -s -b 0.0.0.0 -p 8080