rest-api-mocker 0.1.0__tar.gz

rest_api_mocker-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - name: Ruff (lint)
+        run: ruff check src tests
+      - name: Ruff (format)
+        run: ruff format --check src tests
+      - name: Mypy
+        run: mypy src
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[test]"
+      - name: Pytest
+        run: pytest
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - name: Build distribution
+        run: python -m build
+      - name: Check distribution
+        run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

rest_api_mocker-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+# Publishes when you cut a GitHub Release. Uses PyPI Trusted Publishing
+# (OIDC) — no API tokens or secrets to manage. See README for the one-time
+# PyPI setup this requires.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

rest_api_mocker-0.1.0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

rest_api_mocker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 julien lopez
+
+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.

rest_api_mocker-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: rest-api-mocker
+Version: 0.1.0
+Summary: A small Python wrapper for RestApiMocker.
+Project-URL: Homepage, https://github.com/julienlopez/RestApiMockerPythonAPI
+Project-URL: Repository, https://github.com/julienlopez/RestApiMockerPythonAPI
+Author-email: Julien Lopez <julien.lopez51@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 julien lopez
+        
+        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: api,http,mock,rest,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing :: Mocking
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.20
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: responses>=0.23; extra == 'test'
+Description-Content-Type: text/markdown
+
+# rest-api-mocker
+
+A small Python wrapper for [RestApiMocker](https://github.com/julienlopez/RestApiMockerPythonAPI).
+
+## Installation
+
+```bash
+pip install rest-api-mocker
+```
+
+Until it's published, install from a checkout:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Usage
+
+```python
+from rest_api_mocker import RestApiMocker
+
+mocker = RestApiMocker("http://localhost", 8080)
+mocker.add_mock(
+    method="GET",
+    path_pattern="/users/.*",
+    status=200,
+    body={"id": 1, "name": "Ada"},
+)
+```
+
+`RestApiMocker` can also be used as a context manager so the underlying HTTP
+session is closed for you:
+
+```python
+with RestApiMocker("http://localhost", 8080) as mocker:
+    mocker.add_mock("GET", "/health", 200, {"ok": True})
+```
+
+### API
+
+The client mirrors the server's `/internal` control plane:
+
+| Method | Description |
+| --- | --- |
+| `add_mock(method, path_pattern, status, body, conditions=None)` | Register a mock response. |
+| `get_mocks() -> list[MockConfig]` | List all configured mocks. |
+| `delete_mock(index)` | Delete a mock by its 0-based index. |
+| `delete_all_mocks()` | Delete every configured mock. |
+| `delete_mocks_by_pattern(path_pattern)` | Delete all mocks matching a path pattern. |
+| `get_config() -> ServerConfig` | Get the server's public/private ports. |
+| `get_history() -> list[RequestRecord]` | Get the recorded request history. |
+
+```python
+mocker.add_mock("GET", "/users/.*", 200, {"id": 1})
+
+config = mocker.get_config()          # ServerConfig(public_port=9090, private_port=80)
+mocks = mocker.get_mocks()            # [MockConfig(...)]
+history = mocker.get_history()        # [RequestRecord(method=..., path=..., timestamp=...)]
+
+mocker.delete_mocks_by_pattern("/users/.*")
+mocker.delete_all_mocks()
+```
+
+The `MockConfig`, `ServerConfig` and `RequestRecord` dataclasses are importable
+from the top-level package.
+
+### Errors
+
+A non-success response from the mocker server raises `MockRequestError`
+(a subclass of `RestApiMockerError`):
+
+```python
+from rest_api_mocker import MockRequestError
+
+try:
+    mocker.add_mock("GET", "/x", 200, {})
+except MockRequestError as exc:
+    print(exc.status_code, exc.response_text)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest             # tests
+ruff check .       # lint
+ruff format .      # format
+mypy src           # type-check
+```
+
+CI (`.github/workflows/ci.yml`) runs the tests on Python 3.8–3.13 plus lint,
+format, and type checks on every push and pull request.
+
+## Releasing to PyPI
+
+Publishing is automated by `.github/workflows/publish.yml`, which runs when you
+publish a GitHub Release. It uses PyPI **Trusted Publishing** (OIDC), so there
+are no API tokens or secrets to store.
+
+One-time setup:
+
+1. Create an account at <https://pypi.org/account/register/>.
+2. On PyPI, go to your account → *Publishing* → *Add a pending publisher* and
+   register this repository as a trusted publisher:
+   - PyPI Project Name: `rest-api-mocker`
+   - Owner / Repository: your GitHub `owner` / `RestApiMockerPythonAPI`
+   - Workflow name: `publish.yml`
+   - Environment name: `pypi`
+3. (Recommended) In the GitHub repo settings, create an Environment named
+   `pypi` to gate releases.
+
+To cut a release:
+
+1. Bump `version` in `pyproject.toml` (and `__version__` in
+   `src/rest_api_mocker/__init__.py`).
+2. Tag and push, then publish a GitHub Release for that tag. The workflow
+   builds the package and uploads it to PyPI.
+
+> Tip: to rehearse without affecting the real index, register the same trusted
+> publisher on <https://test.pypi.org> and point the publish step at it with
+> `with: { repository-url: https://test.pypi.org/legacy/ }`.

rest_api_mocker-0.1.0/README.md

@@ -0,0 +1,121 @@
+# rest-api-mocker
+
+A small Python wrapper for [RestApiMocker](https://github.com/julienlopez/RestApiMockerPythonAPI).
+
+## Installation
+
+```bash
+pip install rest-api-mocker
+```
+
+Until it's published, install from a checkout:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Usage
+
+```python
+from rest_api_mocker import RestApiMocker
+
+mocker = RestApiMocker("http://localhost", 8080)
+mocker.add_mock(
+    method="GET",
+    path_pattern="/users/.*",
+    status=200,
+    body={"id": 1, "name": "Ada"},
+)
+```
+
+`RestApiMocker` can also be used as a context manager so the underlying HTTP
+session is closed for you:
+
+```python
+with RestApiMocker("http://localhost", 8080) as mocker:
+    mocker.add_mock("GET", "/health", 200, {"ok": True})
+```
+
+### API
+
+The client mirrors the server's `/internal` control plane:
+
+| Method | Description |
+| --- | --- |
+| `add_mock(method, path_pattern, status, body, conditions=None)` | Register a mock response. |
+| `get_mocks() -> list[MockConfig]` | List all configured mocks. |
+| `delete_mock(index)` | Delete a mock by its 0-based index. |
+| `delete_all_mocks()` | Delete every configured mock. |
+| `delete_mocks_by_pattern(path_pattern)` | Delete all mocks matching a path pattern. |
+| `get_config() -> ServerConfig` | Get the server's public/private ports. |
+| `get_history() -> list[RequestRecord]` | Get the recorded request history. |
+
+```python
+mocker.add_mock("GET", "/users/.*", 200, {"id": 1})
+
+config = mocker.get_config()          # ServerConfig(public_port=9090, private_port=80)
+mocks = mocker.get_mocks()            # [MockConfig(...)]
+history = mocker.get_history()        # [RequestRecord(method=..., path=..., timestamp=...)]
+
+mocker.delete_mocks_by_pattern("/users/.*")
+mocker.delete_all_mocks()
+```
+
+The `MockConfig`, `ServerConfig` and `RequestRecord` dataclasses are importable
+from the top-level package.
+
+### Errors
+
+A non-success response from the mocker server raises `MockRequestError`
+(a subclass of `RestApiMockerError`):
+
+```python
+from rest_api_mocker import MockRequestError
+
+try:
+    mocker.add_mock("GET", "/x", 200, {})
+except MockRequestError as exc:
+    print(exc.status_code, exc.response_text)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest             # tests
+ruff check .       # lint
+ruff format .      # format
+mypy src           # type-check
+```
+
+CI (`.github/workflows/ci.yml`) runs the tests on Python 3.8–3.13 plus lint,
+format, and type checks on every push and pull request.
+
+## Releasing to PyPI
+
+Publishing is automated by `.github/workflows/publish.yml`, which runs when you
+publish a GitHub Release. It uses PyPI **Trusted Publishing** (OIDC), so there
+are no API tokens or secrets to store.
+
+One-time setup:
+
+1. Create an account at <https://pypi.org/account/register/>.
+2. On PyPI, go to your account → *Publishing* → *Add a pending publisher* and
+   register this repository as a trusted publisher:
+   - PyPI Project Name: `rest-api-mocker`
+   - Owner / Repository: your GitHub `owner` / `RestApiMockerPythonAPI`
+   - Workflow name: `publish.yml`
+   - Environment name: `pypi`
+3. (Recommended) In the GitHub repo settings, create an Environment named
+   `pypi` to gate releases.
+
+To cut a release:
+
+1. Bump `version` in `pyproject.toml` (and `__version__` in
+   `src/rest_api_mocker/__init__.py`).
+2. Tag and push, then publish a GitHub Release for that tag. The workflow
+   builds the package and uploads it to PyPI.
+
+> Tip: to rehearse without affecting the real index, register the same trusted
+> publisher on <https://test.pypi.org> and point the publish step at it with
+> `with: { repository-url: https://test.pypi.org/legacy/ }`.

rest_api_mocker-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rest-api-mocker"
+version = "0.1.0"
+description = "A small Python wrapper for RestApiMocker."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { file = "LICENSE" }
+authors = [{ name = "Julien Lopez", email = "julien.lopez51@gmail.com" }]
+keywords = ["mock", "rest", "api", "testing", "http"]
+dependencies = ["requests>=2.20"]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing :: Mocking",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "responses>=0.23"]
+dev = [
+    "pytest>=7",
+    "responses>=0.23",
+    "ruff>=0.4",
+    "mypy>=1.8",
+    "types-requests",
+]
+
+[project.urls]
+Homepage = "https://github.com/julienlopez/RestApiMockerPythonAPI"
+Repository = "https://github.com/julienlopez/RestApiMockerPythonAPI"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rest_api_mocker"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py38"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true

rest_api_mocker-0.1.0/src/rest_api_mocker/__init__.py

@@ -0,0 +1,17 @@
+"""rest_api_mocker — a small Python wrapper for RestApiMocker."""
+
+from __future__ import annotations
+
+from .client import RestApiMocker
+from .exceptions import MockRequestError, RestApiMockerError
+from .models import MockConfig, RequestRecord, ServerConfig
+
+__all__ = [
+    "RestApiMocker",
+    "RestApiMockerError",
+    "MockRequestError",
+    "ServerConfig",
+    "RequestRecord",
+    "MockConfig",
+]
+__version__ = "0.1.0"

rest_api_mocker-0.1.0/src/rest_api_mocker/client.py

@@ -0,0 +1,164 @@
+"""Client for talking to a RestApiMocker server."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Sequence
+
+import requests
+
+from .exceptions import MockRequestError
+from .models import MockConfig, RequestRecord, ServerConfig
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class RestApiMocker:
+    """A thin wrapper around the RestApiMocker HTTP control API.
+
+    All methods talk to the server's ``/internal`` control plane.
+
+    Example:
+        >>> mocker = RestApiMocker("http://localhost", 8080)
+        >>> mocker.add_mock(
+        ...     method="GET",
+        ...     path_pattern="/users/.*",
+        ...     status=200,
+        ...     body={"id": 1, "name": "Ada"},
+        ... )
+    """
+
+    def __init__(
+        self,
+        url: str,
+        port: int,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: requests.Session | None = None,
+    ) -> None:
+        """Create a client.
+
+        Args:
+            url: Base URL of the mocker server, e.g. ``"http://localhost"``.
+            port: Port the mocker server's internal API listens on.
+            timeout: Per-request timeout in seconds.
+            session: Optional pre-configured :class:`requests.Session`. When
+                omitted, a new session is created and owned by this instance.
+        """
+        self.url = url.rstrip("/")
+        self.port = port
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self._owns_session = session is None
+
+    @property
+    def base_url(self) -> str:
+        """The fully-qualified base URL, including port."""
+        return f"{self.url}:{self.port}"
+
+    # -- low-level helpers ------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> requests.Response:
+        """Send a request to ``/internal`` and raise on a non-success status.
+
+        Raises:
+            MockRequestError: If the server returns a 4xx/5xx response.
+        """
+        response = self._session.request(
+            method,
+            f"{self.base_url}/internal{path}",
+            timeout=self.timeout,
+            **kwargs,
+        )
+        if not response.ok:
+            raise MockRequestError(response.status_code, response.text)
+        return response
+
+    # -- mocks ------------------------------------------------------------
+
+    def add_mock(
+        self,
+        method: str,
+        path_pattern: str,
+        status: int,
+        body: Any,
+        conditions: Sequence[dict[str, Any]] | None = None,
+    ) -> None:
+        """Register a mock response on the server (``POST /internal/mock``).
+
+        Args:
+            method: HTTP method to match, e.g. ``"GET"``.
+            path_pattern: Path (or pattern) the mock should match.
+            status: HTTP status code the mock should return.
+            body: Response body. Serialized to a JSON string before sending.
+            conditions: Optional list of matching conditions.
+
+        Raises:
+            MockRequestError: If the server returns a non-success response.
+        """
+        mock_definition = {
+            "method": method,
+            "path_pattern": path_pattern,
+            "status": status,
+            "body": json.dumps(body),
+            "conditions": list(conditions) if conditions is not None else [],
+        }
+        self._request("POST", "/mock", json=mock_definition)
+
+    def get_mocks(self) -> list[MockConfig]:
+        """Return all configured mocks (``GET /internal/mocks``)."""
+        response = self._request("GET", "/mocks")
+        return [MockConfig.from_dict(item) for item in response.json()]
+
+    def delete_mock(self, index: int) -> None:
+        """Delete a mock by its 0-based index (``DELETE /internal/mock/<index>``).
+
+        Raises:
+            MockRequestError: If the index is out of range (404) or the request
+                otherwise fails.
+        """
+        self._request("DELETE", f"/mock/{index}")
+
+    def delete_all_mocks(self) -> None:
+        """Delete every configured mock (``DELETE /internal/mocks``)."""
+        self._request("DELETE", "/mocks")
+
+    def delete_mocks_by_pattern(self, path_pattern: str) -> None:
+        """Delete all mocks whose path pattern matches ``path_pattern``.
+
+        Maps to ``DELETE /internal/mocks/by-pattern?path_pattern=...``.
+
+        Raises:
+            MockRequestError: If no mock matches the pattern (404) or the
+                request otherwise fails.
+        """
+        self._request(
+            "DELETE",
+            "/mocks/by-pattern",
+            params={"path_pattern": path_pattern},
+        )
+
+    # -- introspection ----------------------------------------------------
+
+    def get_config(self) -> ServerConfig:
+        """Return the server's port configuration (``GET /internal/config``)."""
+        response = self._request("GET", "/config")
+        return ServerConfig.from_dict(response.json())
+
+    def get_history(self) -> list[RequestRecord]:
+        """Return the recorded request history (``GET /internal/history``)."""
+        response = self._request("GET", "/history")
+        return [RequestRecord.from_dict(item) for item in response.json()]
+
+    # -- lifecycle --------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying session, if this instance owns it."""
+        if self._owns_session:
+            self._session.close()
+
+    def __enter__(self) -> RestApiMocker:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()

rest_api_mocker-0.1.0/src/rest_api_mocker/exceptions.py

@@ -0,0 +1,21 @@
+"""Exceptions raised by :mod:`rest_api_mocker`."""
+
+from __future__ import annotations
+
+
+class RestApiMockerError(Exception):
+    """Base class for all errors raised by this library."""
+
+
+class MockRequestError(RestApiMockerError):
+    """Raised when the mocker server returns a non-success response.
+
+    Attributes:
+        status_code: HTTP status code returned by the server.
+        response_text: Raw response body returned by the server.
+    """
+
+    def __init__(self, status_code: int, response_text: str) -> None:
+        self.status_code = status_code
+        self.response_text = response_text
+        super().__init__(f"Mocker server returned {status_code}: {response_text}")

rest_api_mocker-0.1.0/src/rest_api_mocker/models.py

@@ -0,0 +1,66 @@
+"""Dataclasses mirroring the RestApiMocker server's JSON types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ServerConfig:
+    """Server configuration, as returned by ``GET /internal/config``."""
+
+    public_port: int
+    private_port: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ServerConfig:
+        return cls(
+            public_port=data["public_port"],
+            private_port=data["private_port"],
+        )
+
+
+@dataclass
+class RequestRecord:
+    """A single request recorded by the public server.
+
+    Returned by ``GET /internal/history``.
+    """
+
+    method: str
+    path: str
+    timestamp: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RequestRecord:
+        return cls(
+            method=data["method"],
+            path=data["path"],
+            timestamp=data["timestamp"],
+        )
+
+
+@dataclass
+class MockConfig:
+    """A configured mock response.
+
+    Returned by ``GET /internal/mocks``. Note that ``body`` is the JSON string
+    the server stores, not a decoded object.
+    """
+
+    method: str
+    path_pattern: str
+    status: int
+    body: str
+    conditions: list[Any] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> MockConfig:
+        return cls(
+            method=data["method"],
+            path_pattern=data["path_pattern"],
+            status=data["status"],
+            body=data.get("body", ""),
+            conditions=list(data.get("conditions") or []),
+        )

rest_api_mocker-0.1.0/tests/test_client.py

@@ -0,0 +1,180 @@
+import json
+
+import pytest
+import responses
+
+from rest_api_mocker import (
+    MockConfig,
+    MockRequestError,
+    RequestRecord,
+    RestApiMocker,
+    ServerConfig,
+)
+
+BASE = "http://localhost:8080/internal"
+
+
+def make_mocker():
+    return RestApiMocker("http://localhost", 8080)
+
+
+@responses.activate
+def test_add_mock_posts_expected_payload():
+    responses.add(responses.POST, f"{BASE}/mock", status=200)
+
+    make_mocker().add_mock(
+        method="GET",
+        path_pattern="/users/.*",
+        status=200,
+        body={"id": 1, "name": "Ada"},
+    )
+
+    assert len(responses.calls) == 1
+    sent = json.loads(responses.calls[0].request.body)
+    assert sent == {
+        "method": "GET",
+        "path_pattern": "/users/.*",
+        "status": 200,
+        "body": json.dumps({"id": 1, "name": "Ada"}),
+        "conditions": [],
+    }
+
+
+@responses.activate
+def test_add_mock_raises_on_non_200():
+    responses.add(responses.POST, f"{BASE}/mock", status=500, body="boom")
+
+    with pytest.raises(MockRequestError) as exc_info:
+        make_mocker().add_mock("GET", "/x", 200, {})
+
+    assert exc_info.value.status_code == 500
+    assert exc_info.value.response_text == "boom"
+
+
+def test_base_url_strips_trailing_slash():
+    mocker = RestApiMocker("http://localhost/", 8080)
+    assert mocker.base_url == "http://localhost:8080"
+
+
+@responses.activate
+def test_conditions_default_is_not_shared():
+    responses.add(responses.POST, f"{BASE}/mock", status=200)
+    mocker = make_mocker()
+
+    mocker.add_mock("GET", "/a", 200, {})
+    mocker.add_mock("GET", "/b", 200, {})
+
+    first = json.loads(responses.calls[0].request.body)["conditions"]
+    second = json.loads(responses.calls[1].request.body)["conditions"]
+    assert first == [] and second == []
+
+
+@responses.activate
+def test_get_config():
+    responses.add(
+        responses.GET,
+        f"{BASE}/config",
+        json={"public_port": 9090, "private_port": 80},
+        status=200,
+    )
+
+    config = make_mocker().get_config()
+    assert config == ServerConfig(public_port=9090, private_port=80)
+
+
+@responses.activate
+def test_get_history():
+    responses.add(
+        responses.GET,
+        f"{BASE}/history",
+        json=[{"method": "GET", "path": "/users/1", "timestamp": 1700000000}],
+        status=200,
+    )
+
+    history = make_mocker().get_history()
+    assert history == [
+        RequestRecord(method="GET", path="/users/1", timestamp=1700000000)
+    ]
+
+
+@responses.activate
+def test_get_mocks():
+    responses.add(
+        responses.GET,
+        f"{BASE}/mocks",
+        json=[
+            {
+                "method": "GET",
+                "path_pattern": "/users/.*",
+                "status": 200,
+                "body": "{}",
+                "conditions": [],
+            }
+        ],
+        status=200,
+    )
+
+    mocks = make_mocker().get_mocks()
+    assert mocks == [
+        MockConfig(
+            method="GET",
+            path_pattern="/users/.*",
+            status=200,
+            body="{}",
+            conditions=[],
+        )
+    ]
+
+
+@responses.activate
+def test_delete_mock_by_index():
+    responses.add(responses.DELETE, f"{BASE}/mock/0", status=200, body="Mock deleted")
+
+    make_mocker().delete_mock(0)
+    assert responses.calls[0].request.url == f"{BASE}/mock/0"
+
+
+@responses.activate
+def test_delete_mock_out_of_range_raises():
+    responses.add(responses.DELETE, f"{BASE}/mock/99", status=404, body="out of range")
+
+    with pytest.raises(MockRequestError) as exc_info:
+        make_mocker().delete_mock(99)
+    assert exc_info.value.status_code == 404
+
+
+@responses.activate
+def test_delete_all_mocks():
+    responses.add(
+        responses.DELETE, f"{BASE}/mocks", status=200, body="All mocks deleted"
+    )
+
+    make_mocker().delete_all_mocks()
+    assert len(responses.calls) == 1
+
+
+@responses.activate
+def test_delete_mocks_by_pattern():
+    responses.add(
+        responses.DELETE,
+        f"{BASE}/mocks/by-pattern",
+        status=200,
+        body="1 mock(s) deleted",
+    )
+
+    make_mocker().delete_mocks_by_pattern("/users/:id")
+
+    assert responses.calls[0].request.params == {"path_pattern": "/users/:id"}
+
+
+@responses.activate
+def test_delete_mocks_by_pattern_no_match_raises():
+    responses.add(
+        responses.DELETE,
+        f"{BASE}/mocks/by-pattern",
+        status=404,
+        body="No mocks found",
+    )
+
+    with pytest.raises(MockRequestError):
+        make_mocker().delete_mocks_by_pattern("/nope")