rest-api-mocker 0.1.0__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+rest_api_mocker/__init__.py,sha256=uAOZvUicJ3PId1pyKKQtnoagP5jsCCkZNDg6MWO3FmE,427
+rest_api_mocker/client.py,sha256=bc5kiee20kZ2VjLisUKAKKm4DjFr_kC6xTOL9X7-4us,5543
+rest_api_mocker/exceptions.py,sha256=Vz6dhaoSF5MVkr3vvphltoS9TPGMS6YSz4GGlBMa3zo,689
+rest_api_mocker/models.py,sha256=P744NvqI51TedClje_aC-MXl9NX6cobZmJa1GDJBiOA,1576
+rest_api_mocker-0.1.0.dist-info/METADATA,sha256=2moHoMzs9QidxNiSg94DfXzGgooNz3Q3tFXKvRYna8Y,6248
+rest_api_mocker-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+rest_api_mocker-0.1.0.dist-info/licenses/LICENSE,sha256=eTbYou-toxlnYebu1uvLqlKtNK_RgQ-qNtYdgX9OFjs,1069
+rest_api_mocker-0.1.0.dist-info/RECORD,,

rest_api_mocker-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

rest_api_mocker-0.1.0.dist-info/licenses/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.