nimax 1.0.0__tar.gz

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

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: false
+      - run: uv run --extra dev ruff check .
+      - run: uv run --extra dev ruff format --check .
+
+  typecheck:
+    name: Type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: false
+      - run: uv run --extra dev ty check src/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: false
+      - run: uv run --extra dev pytest --cov=nimax --cov-report=xml
+      - uses: codecov/codecov-action@v6
+        if: matrix.python-version == '3.14'
+        with:
+          files: coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}

nimax-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: false
+      - run: uv build
+      - uses: actions/upload-artifact@v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

nimax-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.idea/
+.ruff_cache/
+.code-graph/
+.coverage
+coverage.xml
+uv.lock

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

@@ -0,0 +1,37 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --extra dev ruff format
+        language: system
+        types: [python]
+
+      - id: ruff-check
+        name: ruff check --fix
+        entry: uv run --extra dev ruff check --fix --exit-non-zero-on-fix
+        language: system
+        types: [python]
+
+      - id: ruff-format-post
+        name: ruff format (post-fix)
+        entry: uv run --extra dev ruff format
+        language: system
+        types: [python]
+
+      - id: ty
+        name: ty check
+        entry: uv run --extra dev ty check src/
+        language: system
+        pass_filenames: false
+        types: [python]
+
+  - repo: https://github.com/hukkin/mdformat
+    rev: 0.7.22
+    hooks:
+      - id: mdformat
+
+  - repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
+    hooks:
+      - id: taplo-format

nimax-1.0.0/.taplo.toml

@@ -0,0 +1,3 @@
+[formatting]
+array_trailing_comma = true
+array_auto_collapse = false

nimax-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Logan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nimax-1.0.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: nimax
+Version: 1.0.0
+Summary: Record and replay niquests HTTP and WebSocket interactions in pytest
+Project-URL: Homepage, https://github.com/adamlogan73/nimax
+Project-URL: Repository, https://github.com/adamlogan73/nimax
+Project-URL: Bug Tracker, https://github.com/adamlogan73/nimax/issues
+Author-email: Adam Logan <adamlogan73@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Adam Logan
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cassette,http,niquests,pytest,testing,vcr,websocket
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: niquests>=3
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: niquests[ws]>=3; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6; extra == 'dev'
+Requires-Dist: pytest>=9; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: ty>=0; extra == 'dev'
+Requires-Dist: websockets>=13; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nimax
+
+[![CI](https://github.com/adamlogan73/nimax/actions/workflows/ci.yml/badge.svg)](https://github.com/adamlogan73/nimax/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/adamlogan73/nimax/graph/badge.svg)](https://codecov.io/gh/adamlogan73/nimax)
+[![PyPI](https://img.shields.io/pypi/v/nimax)](https://pypi.org/project/nimax/)
+
+Record and replay [niquests](https://github.com/jawah/niquests) HTTP and WebSocket interactions in pytest.
+
+nimax is a VCR-style cassette library built natively for niquests — supporting lazy responses, multiplexed connections, `AsyncSession`, and WebSockets. It is to niquests what [betamax](https://github.com/betamax/betamax) is to requests.
+
+## Installation
+
+```bash
+pip install nimax
+```
+
+## Quick start
+
+### Automatic fixture
+
+nimax registers a `nimax_session` pytest fixture automatically. Use it instead of `niquests.Session()` in your tests:
+
+```python
+def test_my_api(nimax_session):
+    resp = nimax_session.get("https://api.example.com/users")
+    assert resp.status_code == 200
+```
+
+On the first run nimax records the real HTTP response to a cassette file under `cassettes/<test_module>/<test_name>.json`. Subsequent runs replay from the cassette — no network required.
+
+### Async sessions
+
+```python
+import pytest
+import niquests
+
+async def test_async(nimax_session):
+    async with niquests.AsyncSession() as session:
+        with NimaxRecorder(session).use_cassette("my_cassette.json"):
+            resp = await session.get("https://api.example.com/data")
+            assert resp.status_code == 200
+```
+
+### Programmatic API
+
+```python
+import niquests
+from nimax import NimaxRecorder, RecordMode
+
+def test_programmatic(tmp_path):
+    session = niquests.Session()
+    cassette_path = tmp_path / "my_cassette.json"
+    with NimaxRecorder(session).use_cassette(cassette_path, record_mode=RecordMode.ONCE):
+        resp = session.get("https://api.example.com/users")
+        assert resp.status_code == 200
+```
+
+## Record modes
+
+| Mode | Behaviour |
+|---|---|
+| `once` | Record on first run, replay on subsequent runs (default) |
+| `none` | Never record — raise an error if no matching interaction exists |
+| `new_episodes` | Replay existing interactions; record any unmatched requests |
+| `all` | Always record, overwriting the cassette each run |
+
+## Placeholders
+
+Scrub sensitive values (tokens, API keys) from cassettes before they are written:
+
+```python
+from nimax import Placeholder
+
+recorder = NimaxRecorder(session, placeholders=[
+    Placeholder(placeholder="<AUTH_TOKEN>", replace="Bearer secret123"),
+])
+```
+
+## Custom matchers and serializers
+
+```python
+from nimax import BaseMatcher, NimaxRecorder
+
+class BodyMatcher(BaseMatcher):
+    name = "body"
+
+    def match(self, recorded: dict, live: object) -> bool:
+        return recorded.get("body") == live.body  # type: ignore[union-attr]
+
+NimaxRecorder.register_matcher(BodyMatcher)
+```
+
+YAML cassettes are supported out of the box — use a `.yaml` extension for the cassette path.
+
+## Requirements
+
+- Python ≥ 3.11
+- niquests ≥ 3
+- pytest ≥ 8
+- PyYAML ≥ 6
+
+## License
+
+MIT

nimax-1.0.0/README.md

@@ -0,0 +1,104 @@
+# nimax
+
+[![CI](https://github.com/adamlogan73/nimax/actions/workflows/ci.yml/badge.svg)](https://github.com/adamlogan73/nimax/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/adamlogan73/nimax/graph/badge.svg)](https://codecov.io/gh/adamlogan73/nimax)
+[![PyPI](https://img.shields.io/pypi/v/nimax)](https://pypi.org/project/nimax/)
+
+Record and replay [niquests](https://github.com/jawah/niquests) HTTP and WebSocket interactions in pytest.
+
+nimax is a VCR-style cassette library built natively for niquests — supporting lazy responses, multiplexed connections, `AsyncSession`, and WebSockets. It is to niquests what [betamax](https://github.com/betamax/betamax) is to requests.
+
+## Installation
+
+```bash
+pip install nimax
+```
+
+## Quick start
+
+### Automatic fixture
+
+nimax registers a `nimax_session` pytest fixture automatically. Use it instead of `niquests.Session()` in your tests:
+
+```python
+def test_my_api(nimax_session):
+    resp = nimax_session.get("https://api.example.com/users")
+    assert resp.status_code == 200
+```
+
+On the first run nimax records the real HTTP response to a cassette file under `cassettes/<test_module>/<test_name>.json`. Subsequent runs replay from the cassette — no network required.
+
+### Async sessions
+
+```python
+import pytest
+import niquests
+
+async def test_async(nimax_session):
+    async with niquests.AsyncSession() as session:
+        with NimaxRecorder(session).use_cassette("my_cassette.json"):
+            resp = await session.get("https://api.example.com/data")
+            assert resp.status_code == 200
+```
+
+### Programmatic API
+
+```python
+import niquests
+from nimax import NimaxRecorder, RecordMode
+
+def test_programmatic(tmp_path):
+    session = niquests.Session()
+    cassette_path = tmp_path / "my_cassette.json"
+    with NimaxRecorder(session).use_cassette(cassette_path, record_mode=RecordMode.ONCE):
+        resp = session.get("https://api.example.com/users")
+        assert resp.status_code == 200
+```
+
+## Record modes
+
+| Mode | Behaviour |
+|---|---|
+| `once` | Record on first run, replay on subsequent runs (default) |
+| `none` | Never record — raise an error if no matching interaction exists |
+| `new_episodes` | Replay existing interactions; record any unmatched requests |
+| `all` | Always record, overwriting the cassette each run |
+
+## Placeholders
+
+Scrub sensitive values (tokens, API keys) from cassettes before they are written:
+
+```python
+from nimax import Placeholder
+
+recorder = NimaxRecorder(session, placeholders=[
+    Placeholder(placeholder="<AUTH_TOKEN>", replace="Bearer secret123"),
+])
+```
+
+## Custom matchers and serializers
+
+```python
+from nimax import BaseMatcher, NimaxRecorder
+
+class BodyMatcher(BaseMatcher):
+    name = "body"
+
+    def match(self, recorded: dict, live: object) -> bool:
+        return recorded.get("body") == live.body  # type: ignore[union-attr]
+
+NimaxRecorder.register_matcher(BodyMatcher)
+```
+
+YAML cassettes are supported out of the box — use a `.yaml` extension for the cassette path.
+
+## Requirements
+
+- Python ≥ 3.11
+- niquests ≥ 3
+- pytest ≥ 8
+- PyYAML ≥ 6
+
+## License
+
+MIT

nimax-1.0.0/conftest.py

@@ -0,0 +1 @@
+pytest_plugins = ["pytester"]

nimax-1.0.0/pyproject.toml

@@ -0,0 +1,110 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[project]
+name = "nimax"
+version = "1.0.0"
+description = "Record and replay niquests HTTP and WebSocket interactions in pytest"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Adam Logan", email = "adamlogan73@gmail.com" }]
+keywords = [
+  "pytest",
+  "niquests",
+  "vcr",
+  "cassette",
+  "http",
+  "websocket",
+  "testing",
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Framework :: Pytest",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Testing",
+]
+requires-python = ">=3.11"
+dependencies = [
+  "niquests>=3",
+  "PyYAML>=6",
+]
+
+[project.urls]
+Homepage = "https://github.com/adamlogan73/nimax"
+Repository = "https://github.com/adamlogan73/nimax"
+"Bug Tracker" = "https://github.com/adamlogan73/nimax/issues"
+
+[project.optional-dependencies]
+dev = [
+  "niquests[ws]>=3",
+  "websockets>=13",
+  "ruff>=0.9",
+  "ty>=0",
+  "pytest>=9",
+  "pytest-asyncio>=0.24",
+  "pytest-cov>=6",
+]
+
+[project.entry-points.pytest11]
+nimax = "nimax.plugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nimax"]
+
+# ── pytest ────────────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+pythonpath = ["."]
+
+# ── ruff ──────────────────────────────────────────────────────────────────────
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  # Formatter conflicts
+  "ISC001", # single-line-implicit-string-concatenation
+  "D",
+  "ANN401", # Any annotations are legitimate for niquests internals
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+  "S101",     # assert OK in tests
+  "SLF001",   # private member access OK in tests
+  "ARG001",   # unused function args (fixtures)
+  "ARG002",   # unused method args (fixtures)
+  "PLR2004",  # magic values OK in tests
+  "PLC0415",  # conditional imports OK in tests (optional deps)
+  "ASYNC110", # asyncio.sleep polling OK for cross-thread shutdown coordination
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["nimax"]
+
+# ── coverage ──────────────────────────────────────────────────────────────────
+
+[tool.coverage.run]
+source = ["nimax"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+
+# ── ty ────────────────────────────────────────────────────────────────────────
+
+[tool.ty.environment]
+python-version = "3.11"

nimax-1.0.0/src/nimax/__init__.py

@@ -0,0 +1,19 @@
+"""nimax: record and replay niquests HTTP/WebSocket interactions in pytest."""
+
+from ._adapter import NimaxRecorder
+from ._cassette import Cassette
+from ._matchers import BaseMatcher
+from ._placeholders import Placeholder
+from ._record_mode import RecordMode
+from ._serializers import BaseSerializer, JSONSerializer, YAMLSerializer
+
+__all__ = [
+    "BaseMatcher",
+    "BaseSerializer",
+    "Cassette",
+    "JSONSerializer",
+    "NimaxRecorder",
+    "Placeholder",
+    "RecordMode",
+    "YAMLSerializer",
+]

nimax-1.0.0/src/nimax/_adapter.py

@@ -0,0 +1,94 @@
+"""NimaxRecorder: programmatic API for wrapping a session with a cassette."""
+
+from __future__ import annotations
+
+import contextlib
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar
+
+from ._cassette import DEFAULT_MATCH_ON, Cassette
+from ._matchers import BUILTIN_MATCHERS, BaseMatcher
+from ._record_mode import RecordMode
+from ._serializers import BUILTIN_SERIALIZERS, BaseSerializer, JSONSerializer
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Iterable
+
+    import niquests
+
+    from ._placeholders import Placeholder
+
+
+class NimaxRecorder:
+    """Wraps a niquests session to provide cassette recording and replay.
+
+    Usage::
+
+        recorder = NimaxRecorder(session)
+        with recorder.use_cassette("my_test") as cassette:
+            resp = session.get("https://example.com")
+
+    The recorder patches ``niquests.Session.send`` and
+    ``niquests.AsyncSession.send`` class-wide for the duration of the context,
+    so any sessions created inside the block are also intercepted.
+
+    Custom matchers and serializers can be registered at the class level::
+
+        NimaxRecorder.register_matcher(MyMatcher)
+        NimaxRecorder.register_serializer(MySerializer)
+    """
+
+    _matchers: ClassVar[dict[str, type[BaseMatcher]]] = dict(BUILTIN_MATCHERS)
+    _serializers: ClassVar[dict[str, type[BaseSerializer]]] = dict(BUILTIN_SERIALIZERS)
+
+    def __init__(self, session: niquests.Session | niquests.AsyncSession) -> None:
+        self._session = session
+
+    @classmethod
+    def register_matcher(cls, matcher: type[BaseMatcher]) -> None:
+        """Register a custom matcher, making it available by name."""
+        cls._matchers[matcher.name] = matcher
+
+    @classmethod
+    def register_serializer(cls, serializer: type[BaseSerializer]) -> None:
+        """Register a custom serializer, making it available by extension."""
+        cls._serializers[serializer.extension] = serializer
+
+    @contextlib.contextmanager
+    def use_cassette(  # noqa: PLR0913
+        self,
+        name: str,
+        *,
+        cassette_dir: Path | str = "cassettes",
+        record_mode: RecordMode = RecordMode.ONCE,
+        match_on: Iterable[str] = DEFAULT_MATCH_ON,
+        serializer: BaseSerializer | None = None,
+        placeholders: list[Placeholder] | None = None,
+    ) -> Generator[Cassette, None, None]:
+        """Context manager that activates a named cassette for the session.
+
+        :param name:         Cassette name (used as the filename stem).
+        :param cassette_dir: Directory to store cassette files.
+        :param record_mode:  When to record vs replay.
+        :param match_on:     Iterable of matcher names.
+        :param serializer:   Explicit serializer (defaults to JSON).
+        :param placeholders: Sensitive values to redact in the cassette.
+        """
+        resolved_serializer = serializer or JSONSerializer()
+        path = Path(cassette_dir) / f"{name}.{resolved_serializer.extension}"
+        cassette = Cassette(
+            path=path,
+            record_mode=record_mode,
+            match_on=frozenset(match_on),
+            serializer=resolved_serializer,
+            placeholders=placeholders,
+            matcher_registry=type(self)._matchers,  # noqa: SLF001
+            serializer_registry=type(self)._serializers,  # noqa: SLF001
+        )
+        with cassette:
+            yield cassette
+
+    # Convenience: expose session on the recorder for use inside the context
+    @property
+    def session(self) -> niquests.Session | niquests.AsyncSession:
+        return self._session