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
          - 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
      - Caching and batching:
          - features/caching/index.md
          - Memoize: features/caching/memoize.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
          - Async helpers: features/concurrency/async-helpers.md
          - Run in a thread: features/concurrency/run-in-thread.md
          - Periodic tasks: features/concurrency/periodic.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
      - Correctness:
          - features/correctness/index.md
          - Validation: features/correctness/validation.md
          - State and transactions: features/correctness/state.md
      - Developer tools: features/devtools.md
      - Configuration: features/configuration.md
  - Testing: testing/index.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
  - 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
      - Caching and batching:
          - Caching: api/caching.md
          - Batching: api/batching.md
      - Concurrency and limits:
          - Concurrency: api/concurrency.md
          - Async helpers: api/aio.md
          - Bulkhead: api/bulkhead.md
          - Periodic: api/periodic.md
      - Observability:
          - Logging and audit: api/logs.md
          - Timing and profiling: api/timing.md
          - Metrics: api/metrics.md
          - Events: api/events.md
      - Correctness:
          - Validation: api/validation.md
          - State: api/state.md
      - Configuration: api/config.md
      - Developer tools: api/devtools.md
      - Testing helpers: api/testing.md
      - Errors: api/errors.md
  - Project:
      - Performance: project/performance.md
      - Limitations: project/limitations.md
      - Migrating to 0.2: project/migration.md
      - Changelog: project/changelog.md