mkdocs.yml

site_name: python-wrap
site_description: Everyday Python decorators that just work. Retry, cache, time out, rate limit and more. Typed, async-aware, zero dependencies.
site_author: Mahmoud Ahmed
site_url: https://pythonwrap.readthedocs.io/
repo_url: https://github.com/LitePy/PythonWrap
repo_name: LitePy/PythonWrap
edit_uri: edit/main/docs/
copyright: Copyright © 2026 Mahmoud Ahmed · MIT licence

strict: true
validation:
  links:
    anchors: warn

theme:
  name: material
  logo: assets/logo-mark.svg
  favicon: assets/logo-mark.svg
  icon:
    repo: fontawesome/brands/github
  font:
    text: Inter
    code: JetBrains Mono
  palette:
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-night
        name: Follow the system
  features:
    - navigation.instant
    - navigation.instant.progress
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - navigation.footer
    - navigation.indexes
    - toc.follow
    - search.suggest
    - search.highlight
    - search.share
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
    - content.action.edit

extra_css:
  - stylesheets/extra.css

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/LitePy/PythonWrap
    - icon: fontawesome/brands/python
      link: https://pypi.org/project/python-wrap/

plugins:
  - search
  - redirects:
      redirect_maps:
        choosing.md: get-started/choosing.md
        async.md: get-started/async-and-methods.md
        stacking.md: get-started/stacking.md
        testing.md: testing/index.md
        performance.md: project/performance.md
        limitations.md: project/limitations.md
        migration.md: project/migration.md
        changelog.md: project/changelog.md
        guides/resilience.md: features/resilience/index.md
        guides/policies.md: features/resilience/policies.md
        guides/configuration.md: features/configuration.md
        guides/caching.md: features/caching/index.md
        guides/batching.md: features/caching/batching.md
        guides/concurrency.md: features/concurrency/index.md
        guides/async-toolkit.md: features/concurrency/async-helpers.md
        guides/observability.md: features/observability/index.md
        guides/metrics.md: features/observability/metrics.md
        guides/validation.md: features/correctness/validation.md
        guides/state.md: features/correctness/state.md
        guides/devtools.md: features/devtools.md
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          options:
            docstring_style: google
            show_signature_annotations: true
            separate_signature: true
            members_order: source
            show_root_heading: true
            show_root_full_path: false
            show_source: false
            heading_level: 2
            merge_init_into_class: true

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.snippets:
      base_path: [.]
      check_paths: true
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

nav:
  - Home: index.md
  - Get started:
      - get-started/index.md
      - Installation: get-started/installation.md
      - Quickstart: get-started/quickstart.md
      - Choose a decorator: get-started/choosing.md
      - Async and methods: get-started/async-and-methods.md
      - Stacking decorators: get-started/stacking.md
      - Errors: get-started/errors.md
  - Features:
      - features/index.md
      - Resilience:
          - features/resilience/index.md
          - Retry: features/resilience/retry.md
          - HTTP clients: features/resilience/http-clients.md
          - Circuit breaker: features/resilience/circuit-breaker.md
          - Timeout and deadline: features/resilience/timeout.md
          - Fallback and suppress: features/resilience/fallback.md
          - Hedged requests: features/resilience/hedge.md
          - Policies: features/resilience/policies.md
          - Named policies and predicates: features/resilience/named-policies.md
          - Presets and the policy doctor: features/resilience/presets-and-doctor.md
          - Circuit breakers across processes: features/resilience/multi-process-breakers.md
      - Caching and batching:
          - features/caching/index.md
          - Memoize: features/caching/memoize.md
          - Shared stores and credentials: features/caching/stores-and-credentials.md
          - Async cache stores: features/caching/async-stores.md
          - Once: features/caching/once.md
          - Cached property: features/caching/cached-property.md
          - Singleflight: features/caching/singleflight.md
          - Batching: features/caching/batching.md
      - Concurrency and limits:
          - features/concurrency/index.md
          - Rate limits: features/concurrency/rate-limits.md
          - Throttle and debounce: features/concurrency/throttle-debounce.md
          - Bulkheads: features/concurrency/bulkheads.md
          - Adaptive limits: features/concurrency/adaptive-limits.md
          - Graceful shutdown: features/concurrency/graceful-shutdown.md
          - Async helpers: features/concurrency/async-helpers.md
          - Run in a thread: features/concurrency/run-in-thread.md
          - Periodic tasks: features/concurrency/periodic.md
          - Leases and idempotency: features/concurrency/leases-and-idempotency.md
          - Shared limits and quotas: features/concurrency/shared-limits.md
          - Buffered writes: features/concurrency/buffered-writes.md
          - Migrating a lock helper: features/concurrency/lock-compat.md
      - Observability:
          - features/observability/index.md
          - Logging: features/observability/logging.md
          - Audit: features/observability/audit.md
          - Timing and profiling: features/observability/timing.md
          - Metrics and events: features/observability/metrics.md
          - Exporters: features/observability/exporters.md
          - Live dashboard: features/observability/dashboard.md
          - Circuit breaker alerts: features/observability/alerts.md
          - Context, telemetry and health: features/observability/production.md
      - Correctness:
          - features/correctness/index.md
          - Validation: features/correctness/validation.md
          - State and transactions: features/correctness/state.md
          - Batch processing: features/correctness/batch-processing.md
      - Developer tools: features/devtools.md
      - Configuration: features/configuration.md
      - Dynamic switches: features/switches.md
      - Web helpers: features/web-helpers.md
  - Testing:
      - testing/index.md
      - Chaos and fault injection: testing/chaos.md
  - Cookbook:
      - cookbook/index.md
      - Resilient HTTP client: cookbook/resilient-http-client.md
      - Async crawler and bulk fetch: cookbook/async-crawler.md
      - FastAPI: cookbook/fastapi.md
      - Django: cookbook/django.md
      - CLI tools and scripts: cookbook/cli-and-scripts.md
      - DataLoader-style batching: cookbook/dataloader-batching.md
      - Testing your code: cookbook/testing-your-code.md
      - Observability: cookbook/observability.md
      - Framework integrations: cookbook/framework-integrations.md
      - Existing FastAPI application: cookbook/existing-fastapi-app.md
  - API reference:
      - api/index.md
      - Resilience:
          - Retry and fallback: api/retry.md
          - Circuit breaker: api/circuit.md
          - Deadline: api/deadline.md
          - Hedging: api/hedging.md
          - Policies: api/policy.md
          - Named registry: api/policies.md
          - Presets: api/presets.md
          - Doctor: api/doctor.md
          - Predicates: api/predicates.md
          - HTTP clients: api/http.md
      - Caching and batching:
          - Caching: api/caching.md
          - Batching: api/batching.md
          - Redis stores: api/stores.md
          - Async cache: api/async_cache.md
          - Expiring credentials: api/credentials.md
          - Buffered writers: api/buffering.md
          - Batch processing: api/processing.md
      - Concurrency and limits:
          - Concurrency: api/concurrency.md
          - Async helpers: api/aio.md
          - Bulkhead: api/bulkhead.md
          - Adaptive limits: api/adaptive.md
          - Graceful shutdown: api/lifecycle.md
          - Periodic: api/periodic.md
          - Coordination: api/coordination.md
          - Idempotency: api/idempotency.md
          - Quotas and shared windows: api/quotas.md
          - Shared backends: api/shared.md
          - Single-host backends: api/local_state.md
          - Lock helper compatibility: api/compat.md
      - Observability:
          - Logging and audit: api/logs.md
          - Timing and profiling: api/timing.md
          - Metrics: api/metrics.md
          - Events: api/events.md
          - Redaction: api/redaction.md
          - OpenTelemetry adapter: api/observability.md
          - Health registry: api/health.md
          - Exporters: api/exporters.md
          - Dashboard: api/dashboard.md
          - Alerts: api/alerts.md
          - Slow calls: api/slow.md
      - Correctness:
          - Validation: api/validation.md
          - State: api/state.md
      - Configuration: api/config.md
      - Developer tools: api/devtools.md
      - Switches: api/switches.md
      - Framework adapters:
          - Flask: api/flask.md
          - FastAPI and ASGI: api/fastapi.md
          - Django: api/django.md
          - Celery: api/celery.md
          - Web helpers: api/web.md
      - Testing helpers: api/testing.md
      - Chaos: api/chaos.md
      - Migration tool: api/migrate.md
      - Errors: api/errors.md
  - Project:
      - Performance: project/performance.md
      - Limitations: project/limitations.md
      - Migrating to 0.2: project/migration.md
      - Migrating to 0.3: project/migration-0.3.md
      - API stability: project/stability.md
      - Operations runbook: project/operations.md
      - Threat model: project/threat-model.md
      - Production pilot: project/pilot.md
      - Migrating from tenacity: project/migrating-from-tenacity.md
      - Migrating from pybreaker: project/migrating-from-pybreaker.md
      - Migrating from limits: project/migrating-from-limits.md
      - The migration tool: project/migrate-tool.md
      - Changelog: project/changelog.md