Metadata-Version: 2.4
Name: opovid
Version: 0.1.7
Summary: Core runtime for the Opovid testing library.
Author-email: Opovid contributors <opensource@sunrise.water>
License-Expression: Apache-2.0
Project-URL: Homepage, https://gitlab.com/sunrise.water/opovid
Project-URL: Issues, https://gitlab.com/sunrise.water/opovid/-/issues
Project-URL: Source, https://gitlab.com/sunrise.water/opovid
Keywords: screenplay,testing,test-automation,tdd
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
Requires-Dist: twine<7,>=6.1; extra == "dev"

# Opovid Python Runtime

This directory contains the Python runtime for Opovid.

The first Python slice ships the framework-agnostic core plus the shared remembered-state ability:

- `Actor` and the preferred `User` facade
- `task`, `question`, and `check` helpers
- `with_retry` for wrapping flaky or eventually-consistent tasks
- nested execution reports and timeline events
- `render_timeline`, `timeline_to_json`, and `summarize_failure` diagnostics
- listener hooks for step boundaries
- `RememberTheState` for small actor-local state

## Install Locally

From this directory:

```bash
python3 -m pip install -e .
```

## Basic Usage

```python
from opovid import Actor, RememberTheState, remembered_by, question, task

casey = Actor.named("Casey").can(RememberTheState.using_defaults())

casey.attempts_to(
    task("remembers a subscription", lambda actor: remembered_by(actor).remember("plan", "pro"))
)

plan = casey.asks_for(question("reads the selected plan", lambda actor: remembered_by(actor).recall("plan")))

assert plan == "pro"
```

## Module Layout

The Python runtime follows the same concept boundaries as the TypeScript, Java, and Ruby runtimes:

- `actor.py`, `user.py`, and `attempt_chain.py` own the user/actor flow.
- `task.py`, `question.py`, and `check.py` keep the executable contracts separate.
- `execution.py` and `execution_options.py` own reports, timelines, errors, listeners, and execution options.
- `timeline.py` owns text/JSON timeline rendering and failure summaries.
- `retry.py` owns retry task wrappers.
- `actor_memory.py`, `remember_the_state.py`, and `memory.py` provide the shared remembered-state ability.
- `core.py` and `__init__.py` are public re-export entrypoints.

The Python runtime does not currently include the scenario `spec` module available in the TypeScript, Java, and Ruby
runtimes.

## Run Tests

From this directory:

```bash
PYTHONPATH=src python3 -m unittest discover -s tests
```

## Lint And Format

Ruff is the Python runtime's linter and formatter.

```bash
python3 -m pip install -e ".[dev]"
ruff check .
ruff format --check .
```

## Publish

The Python runtime publishes as `opovid` on PyPI.

Tagged releases are handled by the root GitLab release pipeline. The Python release job builds the source distribution and wheel, checks them with Twine, and uploads with PyPI Trusted Publishing through GitLab OIDC. Configure the PyPI trusted publisher for the `sunrise.water/opovid` GitLab project, the top-level `.gitlab-ci.yml` workflow, and the `release` environment before the first publish.

Browser flows remain intentionally centered in the TypeScript runtime with Playwright. The Python runtime is currently focused on service, request, job, and plain unit/integration flows.
