pyrrange 0.1.0__py3-none-any.whl

pyrrange/__init__.py

@@ -0,0 +1,10 @@
+from pyrrange._version import __version__ as __version__
+from pyrrange.arrange import Arrange, StepError, step
+from pyrrange.scene import Scene
+
+__all__ = [
+    "Arrange",
+    "Scene",
+    "StepError",
+    "step",
+]

pyrrange/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

pyrrange/arrange.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar, overload
+
+from pyrrange.context import Context
+from pyrrange.scene import Scene
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class StepError(Exception):
+    def __init__(
+        self,
+        step_name: str,
+        step_index: int,
+        total_steps: int,
+        arrange_class: str,
+        previous_result: Any,
+    ) -> None:
+        self.step_name = step_name
+        self.step_index = step_index
+        self.total_steps = total_steps
+        self.arrange_class = arrange_class
+        self.previous_result = previous_result
+        super().__init__(
+            f"Step {step_index}/{total_steps} '{step_name}' failed on {arrange_class}\n"
+            f"  Previous result: {previous_result!r}"
+        )
+
+
+@overload
+def step(fn: F) -> F: ...  # pragma: no cover
+
+
+@overload
+def step(label: str) -> Callable[[F], F]: ...  # pragma: no cover
+
+
+def step(fn: F | str | None = None, label: str | None = None) -> F | Callable[[F], F]:  # type: ignore[misc]
+    if isinstance(fn, str):
+        return _make_step_decorator(fn)
+
+    if fn is None:
+        return _make_step_decorator(label)
+
+    return _make_step_decorator(None)(fn)
+
+
+def _make_step_decorator(label: str | None) -> Callable[[F], F]:
+    def decorator(fn: F) -> F:
+        step_label = label or fn.__name__
+
+        @wraps(fn)
+        def wrapper(self: Arrange, *args: Any, **kwargs: Any) -> Arrange:
+            self._recorded_steps.append(_StepRecord(fn, step_label, args, kwargs))
+            return self
+
+        wrapper.__annotations__ = {"return": Arrange}
+        wrapper._original = fn  # type: ignore[attr-defined]
+        wrapper._step_label = step_label  # type: ignore[attr-defined]
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def _resolve_kwargs(
+    fn: Callable[..., Any],
+    context: Context,
+    recorded_args: tuple[Any, ...],
+    recorded_kwargs: dict[str, Any],
+    skip_self: bool,
+) -> dict[str, Any]:
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.values())
+
+    if skip_self and params:
+        params = params[1:]
+
+    resolved: dict[str, Any] = {}
+
+    for param in params:
+        if param.name in recorded_kwargs:
+            continue
+        if param.default is inspect.Parameter.empty and param.name in context:
+            resolved[param.name] = context[param.name]
+
+    unresolved = [p for p in params if p.name not in resolved and p.name not in recorded_kwargs]
+    for i, arg in enumerate(recorded_args):
+        if i < len(unresolved):
+            resolved[unresolved[i].name] = arg
+
+    resolved.update(recorded_kwargs)
+
+    return resolved
+
+
+class _StepRecord:
+    __slots__ = ("args", "fn", "kwargs", "label")
+
+    def __init__(self, fn: Callable[..., Any], label: str, args: tuple[Any, ...], kwargs: dict[str, Any]) -> None:
+        self.fn = fn
+        self.label = label
+        self.args = args
+        self.kwargs = kwargs
+
+    def execute(self, arrange: Arrange) -> Any:
+        kwargs = _resolve_kwargs(self.fn, arrange._context, self.args, self.kwargs, skip_self=True)
+        return self.fn(arrange, **kwargs)
+
+
+class _ThenRecord:
+    __slots__ = ("args", "fn", "kwargs", "label")
+
+    def __init__(self, fn: Callable[..., Any], label: str, args: tuple[Any, ...], kwargs: dict[str, Any]) -> None:
+        self.fn = fn
+        self.label = label
+        self.args = args
+        self.kwargs = kwargs
+
+    def execute(self, _arrange: Arrange) -> Any:
+        kwargs = _resolve_kwargs(self.fn, _arrange._context, self.args, self.kwargs, skip_self=False)
+        return self.fn(**kwargs)
+
+
+class Arrange:
+    def __init__(self) -> None:
+        self._recorded_steps: list[_StepRecord | _ThenRecord] = []
+        self._context: Context = Context()
+
+    def then(self, label: str, fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Arrange:
+        self._recorded_steps.append(_ThenRecord(fn, label, args, kwargs))
+        return self
+
+    def teardown(self, scene: Scene) -> None:
+        """Hook for cleaning up resources after a test.
+
+        Override in subclasses to release external state that cannot be
+        rolled back automatically — polymorphic model deletion, external
+        service cleanup, file removal, etc. The base implementation is a
+        no-op so calling ``scene.teardown()`` is always safe.
+
+        Called automatically when a Scene is used as a context manager
+        (``with ... as scene:``), or manually via ``scene.teardown()``.
+
+        :param scene: The Scene produced by ``arrange()``. Use
+            ``scene["label"]`` or ``scene.label`` to access step results
+            that need cleanup.
+        """
+
+    def arrange(self) -> Scene:
+        total = len(self._recorded_steps)
+        for index, record in enumerate(self._recorded_steps, start=1):
+            try:
+                result = record.execute(self)
+            except StepError:
+                raise
+            except Exception as exc:
+                raise StepError(
+                    step_name=record.label,
+                    step_index=index,
+                    total_steps=total,
+                    arrange_class=type(self).__name__,
+                    previous_result=self._context._last_result,
+                ) from exc
+            self._context.set_result(record.label, result)
+        scene_cls = getattr(type(self), "SceneType", Scene)
+        return scene_cls(self._context, self)

pyrrange/context.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class Context:
+    def __init__(self) -> None:
+        self._registry: dict[str, Any] = {}
+        self._last_result: Any = None
+
+    def set_result(self, label: str, value: Any) -> None:
+        self._last_result = value
+        self._registry[label] = value
+
+    def __getitem__(self, label: str) -> Any:
+        if label not in self._registry:
+            raise KeyError(f"No step result for label '{label}'. Available: {list(self._registry.keys())}")
+        return self._registry[label]
+
+    def __contains__(self, label: str) -> bool:
+        return label in self._registry
+
+    def __repr__(self) -> str:
+        return f"Context({list(self._registry.keys())})"

pyrrange/scene.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pyrrange.context import Context
+
+if TYPE_CHECKING:
+    from pyrrange.arrange import Arrange
+
+
+class Scene:
+    def __init__(self, context: Context, arrange: Arrange) -> None:
+        self._context = context
+        self._arrange = arrange
+
+    def __getitem__(self, label: str) -> Any:
+        return self._context[label]
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self._context[name]
+        except KeyError:
+            raise AttributeError(f"Scene has no label '{name}'. Available: {self._context!r}") from None
+
+    def __contains__(self, label: str) -> bool:
+        return label in self._context
+
+    def teardown(self) -> None:
+        self._arrange.teardown(self)
+
+    def __enter__(self) -> Scene:
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any) -> None:
+        self.teardown()
+
+    def __repr__(self) -> str:
+        return f"Scene({self._context!r})"

pyrrange-0.1.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: pyrrange
+Version: 0.1.0
+Summary: Expressive, fluent test scenario preparation for Python.
+Project-URL: Homepage, https://github.com/othercodes/pyrrange
+Project-URL: Repository, https://github.com/othercodes/pyrrange.git
+Project-URL: Issues, https://github.com/othercodes/pyrrange/issues
+Author-email: Unay Santisteban <usantisteban@othercode.io>
+License: MIT
+License-File: LICENSE
+Keywords: arrange,fluent,pytest,scenarios,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pyrrange
+
+[![Build Status](https://github.com/othercodes/pyrrange/actions/workflows/test.yml/badge.svg)](https://github.com/othercodes/pyrrange/actions/workflows/test.yml)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=othercodes_pyrrange&metric=coverage)](https://sonarcloud.io/summary/new_code?id=othercodes_pyrrange)
+
+Expressive, fluent test scenario preparation for Python.
+
+## Why
+
+In large codebases, the arrange phase of tests becomes the bottleneck. Fixtures are one-size-fits-all — the same `user` fixture creates a full object graph whether the test needs a simple login check or a complete checkout flow. Tests pay for setup they don't need, and there's no way to declare "give me just enough state for *this* test."
+
+Pyrrange solves this by letting tests declare exactly what state they need through a fluent chain of operations. Each step calls a real domain operation (not a factory), so the state is built the same way production builds it.
+
+## Features
+
+- Fluent, chainable API for test state preparation
+- Operation-based: steps call real use cases, not create DB rows directly
+- Labeled results: access any step's output by name via attribute or dict access
+- Automatic dependency injection: step parameters are resolved from context by name
+- Optional typed scenes: declare a `SceneType` for full IDE autocomplete and type checking
+- Inline steps via `.then()` for ad-hoc logic
+- Teardown support with context manager for guaranteed cleanup
+- Framework-agnostic: works with Django, FastAPI, or any Python project
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install pyrrange
+```
+
+## Usage
+
+### Define an Arrange
+
+Subclass `Arrange` and define `@step` methods. Each step declares what it needs via its parameter names — pyrrange injects values from the context automatically.
+
+```python
+from pyrrange import Arrange, step
+
+
+class AccountArrange(Arrange):
+    @step("user")
+    def register(self, email="user@example.com", password="secret"):
+        user = register_user(email=email, password=password)
+        return user
+
+    @step("user")
+    def verified(self, user):
+        verify_email(user)
+        return user
+
+    @step("user")
+    def as_admin(self, user):
+        user.is_admin = True
+        user.save()
+        return user
+```
+
+### How injection works
+
+Parameters are resolved using a simple rule:
+
+- **No default value** + name matches a label in context → **injected automatically**
+- **Has default value** → **uses the default**, never injected (safe from silent overrides)
+- **Caller provides a value** → **caller always wins**
+
+```python
+@step("user")
+def register(self, email="user@example.com"):
+    # `email` has a default → not injected, uses "user@example.com"
+    # Override via chain: .register(email="other@example.com")
+    ...
+
+@step("user")
+def verified(self, user):
+    # `user` has no default → injected from context["user"]
+    ...
+
+@step("checkout")
+def purchase(self, api_client, payment_method, config=None):
+    # `api_client` → injected from context["api_client"]
+    # `payment_method` → injected from context["payment_method"]
+    # `config` has a default → not injected, uses None
+    ...
+```
+
+This means every dependency is **typed in the signature** — your IDE gives autocomplete and your type checker validates usage.
+
+### Use in tests
+
+With context manager (recommended — guarantees teardown):
+
+```python
+def test_login(account_arrange):
+    with account_arrange.register().arrange() as scene:
+        response = client.post("/login", {"email": scene.user.email, "password": "secret"})
+        assert response.status_code == 200
+```
+
+Without context manager:
+
+```python
+def test_login(account_arrange):
+    scene = account_arrange.register().arrange()
+    response = client.post("/login", {"email": scene.user.email, "password": "secret"})
+    assert response.status_code == 200
+    scene.teardown()
+```
+
+Each test declares only the steps it needs:
+
+```python
+# Just a registered user
+scene = account_arrange.register().arrange()
+
+# Registered and verified
+scene = account_arrange.register().verified().arrange()
+
+# Full admin user
+scene = account_arrange.register().verified().as_admin().arrange()
+```
+
+### Labels
+
+Steps are labeled by default with the method name. Use `@step("label")` to set a custom label. Same label overwrites (latest wins).
+
+```python
+class OrderArrange(Arrange):
+    @step("order")
+    def create(self, total=100):
+        return create_order(total=total)
+
+    @step("order")
+    def paid(self, order):
+        process_payment(order)
+        return order
+
+    @step("receipt")
+    def with_receipt(self, order):
+        return generate_receipt(order)
+
+scene = OrderArrange().create().paid().with_receipt().arrange()
+order = scene.order
+receipt = scene.receipt
+```
+
+> **Note:** When multiple steps share the same label (like `"order"` above), the label always points to the latest result. Steps that need the value use injection by matching the label name in their parameter list.
+
+### Inline steps with `.then()`
+
+Use `.then()` to add a step without defining a method. Parameter names are matched against context labels, just like `@step` methods.
+
+```python
+def create_api_token(user):
+    return Token.objects.create(user=user)
+
+scene = (
+    account_arrange
+        .register()
+        .verified()
+        .then("token", create_api_token)
+        .arrange()
+)
+user = scene.user
+token = scene.token
+```
+
+Works with lambdas too — the parameter name is the injection key:
+
+```python
+scene = (
+    account_arrange
+        .register()
+        .then("email", lambda user: user.email)
+        .arrange()
+)
+```
+
+### Teardown
+
+Override `teardown` on your Arrange to clean up resources. This is where you handle cleanup that Django's transaction rollback can't cover — polymorphic model deletion, external service state, file cleanup.
+
+```python
+class AccountArrange(Arrange):
+    @step("user")
+    def register(self, email="user@example.com"):
+        return register_user(email=email)
+
+    def teardown(self, scene):
+        scene.user.delete()
+```
+
+Use the context manager to guarantee teardown runs, even if the test crashes:
+
+```python
+with account_arrange.register().arrange() as scene:
+    user = scene.user
+    # ... test ...
+# teardown runs automatically on exit
+```
+
+You can also call `scene.teardown()` manually if you prefer explicit control.
+
+### Typed Scene
+
+By default, `scene.user` returns `Any`. For full IDE autocomplete and type checking, declare a `SceneType` on your Arrange:
+
+```python
+from pyrrange import Arrange, Scene, step
+
+class AccountArrange(Arrange):
+    class SceneType(Scene):
+        user: User
+        api_client: APIClient
+
+    @step("user")
+    def register(self, email="user@example.com") -> User:
+        return register_user(email=email)
+
+    @step("api_client")
+    def with_client(self, user: User) -> APIClient:
+        return create_client(user)
+```
+
+When `SceneType` is declared, `.arrange()` returns an instance of that subclass. Your IDE sees `scene.user` as `User` and `scene.api_client` as `APIClient`.
+
+`SceneType` is optional — without it, attribute access still works but returns `Any`. Both `scene.user` and `scene["user"]` are always available.
+
+### Expose arranges as fixtures
+
+```python
+@pytest.fixture
+def account_arrange():
+    return AccountArrange()
+
+def test_something(account_arrange):
+    with account_arrange.register().verified().arrange() as scene:
+        user = scene.user
+```
+
+### Chain shortcuts
+
+For common step combinations, define convenience methods on your Arrange:
+
+```python
+class AccountArrange(Arrange):
+    @step("user")
+    def register(self, email="user@example.com"):
+        ...
+
+    @step("user")
+    def verified(self, user):
+        ...
+
+    @step("api_client")
+    def with_authenticated_client(self, user):
+        ...
+
+    def authenticated(self):
+        return self.register().verified().with_authenticated_client()
+
+# In tests:
+scene = account_arrange.authenticated().arrange()
+```
+
+These are plain Python methods — no framework magic.

pyrrange-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pyrrange/__init__.py,sha256=BSU6baGwsaSfaY2_jXIIXvkAJla_I1Ajtykix_dTIos,216
+pyrrange/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+pyrrange/arrange.py,sha256=9xOTuV6onI3uixPFLvy_w34xmWpYsKG7w9ynYlH2JUA,5521
+pyrrange/context.py,sha256=KQ9QpJsRwsj_Aje6PDe0DICY-P2rOFipZYMyQd14npM,730
+pyrrange/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyrrange/scene.py,sha256=29w2ngQ0TKlygQaRILn7Ya7j3r9lXkCg8Lk96lN2eaA,1056
+pyrrange-0.1.0.dist-info/METADATA,sha256=FMqTrrP-x94GN1IgvCYpZBJ72084I0xgYkT4R1u204s,9211
+pyrrange-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pyrrange-0.1.0.dist-info/licenses/LICENSE,sha256=X5h01ro10ODbeI9g2ZqD33l_L6YGuzd6g8liUET4ayY,1073
+pyrrange-0.1.0.dist-info/RECORD,,

pyrrange-0.1.0.dist-info/WHEEL

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

pyrrange-0.1.0.dist-info/licenses/LICENSE

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