interlock-cb 1.0.0__tar.gz

interlock_cb-1.0.0/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "worktree": {
+    "bgIsolation": "none"
+  }
+}

interlock_cb-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Report incorrect behaviour
+title: ''
+labels: bug
+assignees: ''
+---
+
+**What happened**
+A clear description of the bug.
+
+**Expected behaviour**
+What you expected instead.
+
+**Minimal reproduction**
+```python
+# the smallest snippet that triggers the issue
+```
+
+**Environment**
+- interlock version:
+- Python version:
+- OS:
+- Extras in use (otel / httpx2):
+
+**Additional context**
+Anything else that helps — config used, traceback, etc.

interlock_cb-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/bagowix/interlock/security/advisories/new
+    about: Please report security issues privately, not as public issues.

interlock_cb-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Problem**
+What are you trying to do that interlock makes hard or impossible today?
+
+**Proposed solution**
+What you'd like to see. API sketches welcome.
+
+**Alternatives considered**
+Other approaches you weighed.
+
+**Scope check**
+interlock v1 is deliberately a focused circuit breaker (see `planning/PLAN.md`).
+Does this fit the v1 core, or a later milestone (timeout/retry/pipeline,
+distributed state, more integrations)?

interlock_cb-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Summary
+
+<!-- What does this change and why? -->
+
+## Checklist
+
+- [ ] Tests added or updated (suite stays at 100% coverage)
+- [ ] `uv run ruff format --check` and `uv run ruff check` pass
+- [ ] `uv run mypy` and `uv run pyright` pass
+- [ ] Docs updated (`docs/`) for user-facing changes
+- [ ] `CHANGELOG.md` `[Unreleased]` updated
+- [ ] Commits follow Conventional Commits
+
+## Related issues
+
+<!-- e.g. Closes #123 -->

interlock_cb-1.0.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"
+
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore"

interlock_cb-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Ruff format
+        run: uv run ruff format --check
+
+      - name: Ruff lint
+        run: uv run ruff check
+
+      - name: Mypy
+        run: uv run mypy --num-workers 2
+
+      - name: Pyright
+        run: uv run pyright
+
+      - name: Tests
+        run: uv run pytest --cov

interlock_cb-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Build site
+        run: uv run zensical build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

interlock_cb-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Tests
+        run: uv run pytest
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

interlock_cb-1.0.0/.gitignore

@@ -0,0 +1,39 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.idea/
+.vscode/
+.vim/
+
+.venv/
+venv/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.pytype/
+*.pyc
+.env
+.local/
+
+.DS_Store
+.python-version
+.ruff_cache
+*.npy
+script.py
+requests.http
+
+tmp/
+*egg-info/
+reports/
+scratch/
+
+# Zensical docs build output
+site/

interlock_cb-1.0.0/.hypothesis/.gitignore

@@ -0,0 +1,9 @@
+# This .gitignore file was automatically created by Hypothesis. Hypothesis gitignores
+# .hypothesis by default, because we generally recommend that .hypothesis not be checked
+# into version control.
+#
+# If you *would* like to check .hypothesis into version control, you should delete this
+# file. Hypothesis will not re-create this .gitignore unless .hypothesis is deleted (and
+# if it does, that's a bug - please report it!)
+
+*

interlock_cb-1.0.0/.hypothesis/constants/06a4b260de5060ee

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/config.py
+# hypothesis_version: 6.155.7
+
+[0.0, 0.5, 1.0, 60.0, 100, 'Config']

interlock_cb-1.0.0/.hypothesis/constants/089c843b9bbadf6f

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/httpx2.py
+# hypothesis_version: 6.155.7
+
+['HttpStatusClassifier', 'Response']

interlock_cb-1.0.0/.hypothesis/constants/0ded8d2e102de102

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/errors.py
+# hypothesis_version: 6.155.7
+
+['CallTimeoutError', 'CircuitOpenError', 'InterlockError']

interlock_cb-1.0.0/.hypothesis/constants/0e433060b82d8622

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/protocols.py
+# hypothesis_version: 6.155.7
+
+['Clock', 'EventListener', 'FailureClassifier', 'SlidingWindow', 'Storage']

interlock_cb-1.0.0/.hypothesis/constants/19a9ca7724cb2cc3

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/window.py
+# hypothesis_version: 6.155.7
+
+[0.0, 'WindowSnapshot', 'WindowType']

interlock_cb-1.0.0/.hypothesis/constants/206bebd6662412a7

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/_state_machine.py
+# hypothesis_version: 6.155.7
+
+[0.0, 'StateMachine']

interlock_cb-1.0.0/.hypothesis/constants/426ccac79ef394c0

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/_windows.py
+# hypothesis_version: 6.155.7
+
+['build_window']

interlock_cb-1.0.0/.hypothesis/constants/5090f2d8008d86a7

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/otel.py
+# hypothesis_version: 6.155.7
+
+['OTelEventListener', 'breaker', 'from', 'interlock', 'interlock.reset', 'outcome', 's', 'to']

interlock_cb-1.0.0/.hypothesis/constants/53bef2a567a6bbac

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/breaker.py
+# hypothesis_version: 6.155.7
+
+['AsyncCallable[P, R]', 'CircuitBreaker', 'SyncCallable[P, R]']

interlock_cb-1.0.0/.hypothesis/constants/653425710aa90c9c

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/_typing.py
+# hypothesis_version: 6.155.7
+
+['AsyncCallable', 'Call', 'P', 'R', 'SyncCallable']

interlock_cb-1.0.0/.hypothesis/constants/656cbb32ddaa52e9

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/_engine.py
+# hypothesis_version: 6.155.7
+
+['AsyncCallable[P, R]', 'Engine', 'SyncCallable[P, R]']

interlock_cb-1.0.0/.hypothesis/constants/67b0a8ccf18bf5d2

@@ -0,0 +1,4 @@
+# file: /usr/lib/python3.12/sitecustomize.py
+# hypothesis_version: 6.155.7
+
+[]

interlock_cb-1.0.0/.hypothesis/constants/6c2108f77b1357cf

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/listeners.py
+# hypothesis_version: 6.155.7
+
+['LoggingEventListener', 'circuit %r: reset', 'interlock']

interlock_cb-1.0.0/.hypothesis/constants/6dbf5957cd1b3627

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/_clock.py
+# hypothesis_version: 6.155.7
+
+['SystemClock']

interlock_cb-1.0.0/.hypothesis/constants/6f2e032b5988ca14

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/_classify.py
+# hypothesis_version: 6.155.7
+
+[]

interlock_cb-1.0.0/.hypothesis/constants/8341443ac143cf7e

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/version.py
+# hypothesis_version: 6.155.7
+
+['1.0.0', 'VERSION']

interlock_cb-1.0.0/.hypothesis/constants/9c26eabcd1227abe

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/.venv/bin/pytest
+# hypothesis_version: 6.155.7
+
+['-script.pyw', '.exe', '__main__']

interlock_cb-1.0.0/.hypothesis/constants/ad8f434ace58570d

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/timeout.py
+# hypothesis_version: 6.155.7
+
+['timeout']

interlock_cb-1.0.0/.hypothesis/constants/c357a4ad29caa583

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/state.py
+# hypothesis_version: 6.155.7
+
+['State']

interlock_cb-1.0.0/.hypothesis/constants/d56313e8a47d81c2

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/_detect.py
+# hypothesis_version: 6.155.7
+
+['__call__', 'is_async_callable']

interlock_cb-1.0.0/.hypothesis/constants/d5a94da48926492c

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/__init__.py
+# hypothesis_version: 6.155.7
+
+['AsyncCallable', 'Call', 'CallTimeoutError', 'CircuitBreaker', 'CircuitOpenError', 'Clock', 'Config', 'EventListener', 'FailureClassifier', 'InterlockError', 'LoggingEventListener', 'Outcome', 'Registry', 'SlidingWindow', 'State', 'Storage', 'SyncCallable', 'VERSION', 'WindowSnapshot', 'WindowType', '__version__', 'timeout']

interlock_cb-1.0.0/.hypothesis/constants/fadb156b26650b6f

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/registry.py
+# hypothesis_version: 6.155.7
+
+['Registry']

interlock_cb-1.0.0/.hypothesis/constants/ffd8d4d32246fbfc

@@ -0,0 +1,4 @@
+# file: /home/runner/work/interlock/interlock/interlock/outcome.py
+# hypothesis_version: 6.155.7
+
+['Outcome']

interlock_cb-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,64 @@
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+
+default_stages: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.18
+    hooks:
+      - id: ruff-format
+      - id: ruff-check
+        name: ruff-check
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-docstring-first
+        exclude: ^interlock/version\.py$
+      - id: check-ast
+      - id: check-toml
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+      - id: detect-private-key
+      - id: no-commit-to-branch
+        args: [ --branch, main ]
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy --num-workers 2
+        language: system
+        types: [python]
+        pass_filenames: false
+        args: [--config-file=./pyproject.toml]
+
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+
+  - repo: https://github.com/jackdewinter/pymarkdown
+    rev: v0.9.38
+    hooks:
+      - id: pymarkdown
+        name: pymarkdown
+        files: \.md$
+        pass_filenames: true
+        exclude: (CHANGELOG\.md|^\.github/)
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.4.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args: []

interlock_cb-1.0.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-06-27
+
+### Added
+
+- Core state machine: `CLOSED` / `OPEN` / `HALF_OPEN` plus the operator
+  overrides `FORCED_OPEN`, `DISABLED` and `METRICS_ONLY` (shadow mode).
+- Sliding windows behind a `SlidingWindow` protocol, with count-based and
+  time-based implementations selected via `Config.window_type`.
+- Failure-rate trigger with `failure_rate_threshold` and
+  `minimum_number_of_calls`, and **slow-call detection** via
+  `slow_call_duration_threshold` and `slow_call_rate_threshold`.
+- Lazy `OPEN → HALF_OPEN` transition with a probe limit and a concurrency cap.
+- Single public `CircuitBreaker` for sync and async, usable as a decorator, a
+  sync/async context manager, and `breaker.call(fn, ...)`. Decorators preserve
+  the signature and sync/async nature via `ParamSpec` + `@overload`.
+- Manual control: `reset()`, `force_open()`, `disable()`, `metrics_only()`.
+- `Registry` of named breakers with a shared default config and per-name
+  overrides.
+- Immutable `Config` (frozen dataclass) with eager validation.
+- `FailureClassifier` protocol with a default policy (any raised exception is a
+  failure); classification by result is supported by custom classifiers.
+- `CircuitOpenError` carrying the breaker name, an estimated `retry_after`, and
+  the last recorded failure.
+- Async-first `timeout` primitive that turns a hang into `CallTimeoutError`.
+- Observability: `EventListener` protocol, a zero-dependency
+  `LoggingEventListener`, and an `OTelEventListener` (extra `interlock-cb[otel]`).
+- httpx2 transport integration (extra `interlock-cb[httpx2]`):
+  `CircuitBreakerTransport` and `AsyncCircuitBreakerTransport` apply a breaker
+  per host, with an `HttpStatusClassifier` treating `429, 500, 502, 503, 504`
+  and transport exceptions as failures.
+- `InterlockDeprecationWarning` (subclasses `UserWarning`, visible by default).
+- `py.typed`; strict mypy and pyright; 100% test coverage.
+
+[Unreleased]: https://github.com/bagowix/interlock/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/bagowix/interlock/releases/tag/v1.0.0

interlock_cb-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,65 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**galushko355@gmail.com**. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+[homepage]: https://www.contributor-covenant.org