pyproject.toml

[project]
name = "fastapi-cachex"
version = "0.3.8"
description = "A caching library for FastAPI with support for Cache-Control, ETag, and multiple backends."
readme = "README.md"
requires-python = ">=3.10"
license = "Apache-2.0"
license-files = ["LICENSE"]
authors = [
    { name = "allen0099", email = "s96016641@gmail.com" }
]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "Programming Language :: Python",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Programming Language :: Python :: 3 :: Only",
    "Framework :: FastAPI",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
    "Typing :: Typed",
]
keywords = ["fastapi", "cache", "etag", "cache-control", "redis", "memcached", "in-memory"]
# Floors are checked by the `lowest` tox env (`uv_resolution = lowest-direct`).
dependencies = [
    "fastapi>=0.133.0",
    "itsdangerous>=1.1.0",
    "pydantic>=2.7.0",
    # Imported directly; `starlette.middleware.sessions.Session` is new in 1.0.
    "starlette>=1.0.0",
]

[project.urls]
Homepage = "https://github.com/allen0099/FastAPI-CacheX"
Repository = "https://github.com/allen0099/FastAPI-CacheX.git"
Issues = "https://github.com/allen0099/FastAPI-CacheX/issues"
Documentation = "https://fastapi-cachex.readthedocs.io/"

[dependency-groups]
dev = [
    "coverage>=7.8.0",
    "httpx2>=2.13.1",
    "mypy>=1.15.0",
    "orjson>=3.10.16",
    "pre-commit>=4.2.0",
    "PyJWT>=2.9.0",
    "pymemcache>=4.0.0",
    "pytest>=8.3.5",
    "pytest-asyncio>=0.26.0",
    "pytest-cov>=6.1.0",
    "redis[hiredis]>=5.3.0",
    "ruff>=0.11.2",
    "tox>=4.25.0",
    "tox-uv>=1.29.0",
    "ty>=0.0.1a34",
    "types-orjson>=3.6.2",
    "types-redis>=4.6.0.20241004",
]
docs = [
    # Pre-1.0: upgrades are deliberate, not automatic.
    "zensical>=0.0.65,<0.1",
    "mkdocstrings-python>=2.0",
    "markdown-callouts>=0.4",
]

[project.optional-dependencies]
memcached = ["pymemcache>=4.0.0"]
# Deprecated alias of `memcached`, removed in 0.4.0 (#202).
memcache = ["pymemcache>=4.0.0"]
redis = ["redis[hiredis]>=5.3.0", "orjson>=3.4.7"]
jwt = ["PyJWT>=2.9.0"]

[build-system]
requires = ["uv_build>=0.12,<0.13"]
build-backend = "uv_build"

[tool.uv.build-backend]
module-root = ""
include = ["fastapi_cachex/py.typed"]

[tool.pytest.ini_options]
pythonpath = [
    "."
]
testpaths = ["tests"]
addopts = ["--strict-markers"]
xfail_strict = true
# Every async test and fixture runs on pytest-asyncio; no per-test marker.
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"
# An unexpected warning fails the test. A test that expects one asserts it
# with pytest.warns or opts out with a narrow filterwarnings mark.
filterwarnings = [
    "error",
    # starlette 1.0.0 (our floor, run by the `lowest` tox env) imports
    # TestClient through an alias that newer anyio deprecates. Later starlette
    # releases no longer use it; nothing in this package or its tests does.
    "ignore:The anyio.abc.BlockingPortal alias is deprecated:DeprecationWarning",
]

[tool.ruff.lint]
ignore = [
    "E501",
    "ANN401",
    "COM812", # redundant rule, use formatter to fix
    "FBT001", "FBT002", # Boolean arguments are part of Cache-Control API design
    "C901", # allow slightly complex session flow
    "CPY001", # no copyright header convention in this project (stabilized in ruff 0.16)
]
preview = true
explicit-preview-rules = true
extend-select = ['ALL']

[tool.ruff.lint.flake8-bugbear]
# FastAPI dependency markers are meant to be called in argument defaults.
extend-immutable-calls = ["fastapi.Depends"]

[tool.ruff.lint.isort]
force-single-line = true

[tool.ruff.lint.pyupgrade]
# Preserve types, even if a file imports `from __future__ import annotations`.
keep-runtime-typing = true

[tool.ruff.lint.per-file-ignores]
"scripts/**" = ["INP001"]  # Standalone tooling, not an importable package
"examples/**" = [
    "INP001",  # Standalone apps, run by path; not an importable package
    "S106",  # token_format="jwt" is not a password
]
"tests/**" = [
    "D",
    "S101",
    "S105",
    "S106",
    "ARG",
    "ANN",
    "B011",
    "BLE",
    "PLR",
    "SLF",
    "PLC0415",  # Import in functions is intentional for test setup
    "PT031"  # Single statement in pytest.warns is acceptable
]
"fastapi_cachex/cache.py" = [
    "PLR0913", "PLR0915", "PLR0911", "PLR0912", # Many arguments/statements/returns/branches needed for flexible caching logic
    "S101", # Internal invariant guard, not a validation shortcut
]
"fastapi_cachex/backends/memcached.py" = ["PLC0415"]  # Optional dependency
# PLR0917: these constructors take many positional options; making them
# keyword-only would break the public API.
"fastapi_cachex/backends/redis.py" = ["PLR0913", "PLR0917", "PLC0415"]  # Optional dependency, Redis config
"fastapi_cachex/lock.py" = ["PLR0913", "PLR0917"]  # Configurable lock parameters
"fastapi_cachex/session/manager.py" = [
    "PLR0915", # Session/security validation branches needed
    "S105", # token_format = "simple" / "jwt" is not a password
]

[tool.ruff.format]
docstring-code-format = true

[tool.ty.src]
exclude = [
    "./.serena/",
]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.coverage.run]
source = ["fastapi_cachex", "scripts"]
omit = ["tests/*"]
branch = true

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "if TYPE_CHECKING:",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
    # Anchored: a bare "pass" or "..." would also exclude any line (and the
    # block it opens) containing "password", "bypass" or "Field(...".
    "^\\s*pass\\s*(#.*)?$",
    "^\\s*\\.\\.\\.\\s*(#.*)?$",
]
fail_under = 90
show_missing = true

[tool.mypy]
python_version = "3.10"
plugins = [
    "pydantic.mypy"
]
warn_redundant_casts = true
warn_unused_ignores = true
disallow_any_generics = true
check_untyped_defs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
disallow_untyped_decorators = true
no_implicit_optional = true
warn_return_any = true
warn_unreachable = true
strict_optional = true
strict_equality = true

[[tool.mypy.overrides]]
module = ["tests.*"]
disallow_untyped_defs = false
disallow_incomplete_defs = false

[[tool.mypy.overrides]]
module = ["pymemcache.*"]
ignore_missing_imports = true