pytest-rowsmith 0.1.0__py3-none-any.whl

pytest_rowsmith/__init__.py

@@ -0,0 +1,420 @@
+"""pytest-rowsmith: reproducible fake test data from the Rowsmith API, cached for offline test runs.
+
+The client sends schemas only (column definitions, or a JSON Schema without its example and default values),
+never data. It uses the standard library alone (urllib),
+and reaches the network only when a generate call misses the cache or the cache is bypassed with
+``--rowsmith-refresh``. Importing this package or loading the plugin opens no connection.
+"""
+import base64
+import csv
+import hashlib
+import io
+import json
+import socket
+import time
+import urllib.error
+import urllib.request
+from http.client import HTTPException
+
+# The one place the version is set. pyproject.toml reads it from here, and the User-Agent carries it.
+__version__ = "0.1.0"
+
+DEFAULT_URL = "https://testdata-api.re-jam620.workers.dev"
+USER_AGENT = "pytest-rowsmith/" + __version__
+TOOL_HEADER = "pytest"
+TIMEOUT_S = 30.0
+FORMATS = ("csv", "json", "sql")
+# Response headers kept in the cache beside the body bytes.
+KEPT_HEADERS = ("content-type", "x-generator-version", "x-seed", "x-reproduce", "x-schema-version", "x-schema-unmapped",
+                "x-request-sha256", "x-output-sha256")
+# Schema keys whose values are examples or defaults: removed before a schema is sent (the service ignores them too).
+# Keys directly inside these maps are property or schema names, and are kept.
+EXAMPLE_KEYS = frozenset(("example", "examples", "default", "const"))
+NAME_MAPS = frozenset(("properties", "patternProperties", "$defs", "definitions", "schemas", "dependentSchemas"))
+CACHE_PREFIX = "rowsmith/v1/"
+
+MANIFEST_VERSION = 1
+
+__all__ = ["__version__", "Rowsmith", "RowsmithError", "RowsmithResult", "request_body", "assert_golden", "manifest_entry",
+           "DEFAULT_URL", "USER_AGENT", "MANIFEST_VERSION"]
+
+
+class RowsmithError(Exception):
+    """A generate call that did not return data: an HTTP error from the service or a network failure.
+
+    Attributes: ``status`` (int, or None when no HTTP answer arrived), ``error`` and ``next`` (the service's
+    text, when it sent them) and ``reproduce`` (the X-Reproduce line when the service sent one, otherwise the
+    request that was sent, in the same form).
+    """
+
+    def __init__(self, status, error, next_step, reproduce, url):
+        self.status = status
+        self.error = error
+        self.next = next_step
+        self.reproduce = reproduce
+        self.url = url
+        if status is None:
+            head = "Rowsmith API call failed with no HTTP answer: %s" % (error or "network error")
+        else:
+            head = "Rowsmith API answered HTTP %d: %s" % (status, error or "(no error text)")
+        parts = [head]
+        if next_step:
+            parts.append("Next: %s" % next_step)
+        parts.append("Reproduce: %s" % reproduce)
+        parts.append("URL: %s" % url)
+        super().__init__("\n".join(parts))
+
+
+class RowsmithResult:
+    """The bytes and kept headers of one generate answer, from the network or from the cache."""
+
+    def __init__(self, body, headers, request_body, from_cache, fmt):
+        self.body = body  # bytes, exactly as the service sent them
+        self.headers = dict(headers)  # lower-case names; only KEPT_HEADERS
+        self.request_body = request_body  # the exact bytes sent (and hashed for the cache key)
+        self.from_cache = from_cache
+        self.format = fmt
+
+    @property
+    def text(self):
+        return self.body.decode("utf-8")
+
+    @property
+    def sha256(self):
+        return hashlib.sha256(self.body).hexdigest()
+
+    @property
+    def output_sha256(self):
+        """The service's X-Output-SHA256 (sha256 of the body bytes); without that header, the same hash computed
+        here from the body bytes."""
+        return self.headers.get("x-output-sha256") or self.sha256
+
+    @property
+    def request_sha256(self):
+        """The service's X-Request-SHA256: the sha256 of the canonical request that X-Reproduce encodes (defaults
+        filled in, version pinned; for a schema request, the mapped columns). Without that header, the sha256 of the
+        body in a body-b64url X-Reproduce line (the exact bytes); otherwise None (run once with --rowsmith-refresh)."""
+        value = self.headers.get("x-request-sha256")
+        if value:
+            return value
+        line = self.headers.get("x-reproduce") or ""
+        if line.startswith("POST /v1/generate body-b64url="):
+            b64 = line.split("=", 1)[1]
+            return hashlib.sha256(base64.urlsafe_b64decode(b64 + "=" * (-len(b64) % 4))).hexdigest()
+        return None
+
+    @property
+    def schema_version(self):
+        """X-Schema-Version for a schema request; None for a columns request."""
+        return self.headers.get("x-schema-version")
+
+    @property
+    def generator_version(self):
+        return self.headers.get("x-generator-version")
+
+    @property
+    def seed(self):
+        value = self.headers.get("x-seed")
+        return int(value) if value is not None else None
+
+    @property
+    def schema_unmapped(self):
+        """For a schema request: the paths of the properties the service could not map (X-Schema-Unmapped),
+        e.g. ["tags", "address.zip"]; an empty list when every property mapped or for a columns request."""
+        value = self.headers.get("x-schema-unmapped")
+        return value.split(",") if value else []
+
+    @property
+    def reproduce(self):
+        """The service's X-Reproduce line (CSV and SQL answers carry one; JSON answers do not, so for JSON
+        this is the request that was sent, in the same form)."""
+        return self.headers.get("x-reproduce") or _request_line(self.request_body)
+
+    def parsed(self):
+        """List of dicts for csv and json; the text itself for sql. CSV values are strings."""
+        if self.format == "json":
+            return json.loads(self.text)
+        if self.format == "csv":
+            return list(csv.DictReader(io.StringIO(self.text, newline="")))
+        return self.text
+
+
+def _self_contained(result):
+    """A reproduce line that regenerates the bytes by itself: X-Reproduce when it carries the body, otherwise the
+    request this client sent (version pinned too, so it regenerates the same bytes or is refused with 409)."""
+    line = result.headers.get("x-reproduce") or ""
+    return line if line.startswith("POST /v1/generate body-b64url=") else _request_line(result.request_body)
+
+
+def manifest_entry(result, name):
+    """One golden-manifest entry for a RowsmithResult: a dict with name, request_sha256, output_sha256,
+    output_version, schema_version (None for a columns request) and reproduce. Collect entries as
+    {"rowsmith_manifest": 1, "entries": [...]} and keep the file beside your eval."""
+    if not isinstance(name, str) or not name:
+        raise TypeError("name must be a non-empty string, e.g. \"orders-v1\"")
+    request_sha256 = result.request_sha256
+    if request_sha256 is None:
+        raise ValueError("this answer has no request sha256 (no X-Request-SHA256 header and no body-b64url X-Reproduce line); run once with --rowsmith-refresh")
+    return {
+        "name": name,
+        "request_sha256": request_sha256,
+        "output_sha256": result.sha256,
+        "output_version": result.generator_version,
+        "schema_version": result.schema_version,
+        "reproduce": _self_contained(result),
+    }
+
+
+def assert_golden(result, expected):
+    """Fails (AssertionError) unless the sha256 of result's body bytes is ``expected``: a hex string, or a manifest
+    entry dict (whose request_sha256 must then match too). The message names both hashes and the reproduce line."""
+    __tracebackhide__ = True
+    entry = expected if isinstance(expected, dict) else {"output_sha256": expected}
+    want = entry.get("output_sha256")
+    if not isinstance(want, str) or len(want) != 64:
+        raise TypeError("expected must be a 64-character sha256 hex string or a manifest entry")
+    label = " (%s)" % entry["name"] if entry.get("name") else ""
+    lines = []
+    if entry.get("request_sha256") and entry["request_sha256"] != result.request_sha256:
+        lines.append("Rowsmith request differs from the golden entry%s: expected request sha256 %s, got %s."
+                     % (label, entry["request_sha256"], result.request_sha256))
+    if result.sha256 != want.lower():
+        lines.append("Rowsmith output differs from the golden entry%s: expected output sha256 %s, got %s "
+                     "(output version %s, schema version %s, %s)."
+                     % (label, want, result.sha256, result.generator_version, result.schema_version or "none",
+                        "from the cache" if result.from_cache else "from the service"))
+    if lines:
+        lines.append("Reproduce: %s" % _self_contained(result))
+        raise AssertionError("\n".join(lines))
+
+
+def strip_examples(value, names=False):
+    """A copy of a JSON Schema without example, examples, default, const and x-* keys (their values never leave
+    this machine). Keys directly inside properties, $defs, definitions and components.schemas are names, and kept."""
+    if isinstance(value, list):
+        return [strip_examples(v) for v in value]
+    if not isinstance(value, dict):
+        return value
+    out = {}
+    for k, v in value.items():
+        if not names and (k in EXAMPLE_KEYS or (isinstance(k, str) and k.startswith("x-"))):
+            continue
+        out[k] = strip_examples(v, not names and k in NAME_MAPS)
+    return out
+
+
+def _ref_target(ref):
+    """Mirrors Doc.lookup in the service (src/schemain.ts): (container, name) for a local $ref, else None.
+    #/$defs/X and #/definitions/X are read from the document root, #/components/schemas/X from
+    components.schemas; parts are unescaped (~1 is /, ~0 is ~) after splitting on /; refs over 512 UTF-16 units
+    are not followed."""
+    if not isinstance(ref, str) or not ref.startswith("#/") or len(ref.encode("utf-16-le")) // 2 > 512:
+        return None
+    parts = [p.replace("~1", "/").replace("~0", "~") for p in ref[2:].split("/")]
+    if len(parts) == 2 and parts[0] in ("$defs", "definitions"):
+        return parts[0], parts[1]
+    if len(parts) == 3 and parts[0] == "components" and parts[1] == "schemas":
+        return "components", parts[2]
+    return None
+
+
+def minimal_openapi(schema):
+    """For {"openapi": <document>, "component": <name>}: the same wrapper holding only the named component and the
+    schemas it reaches through local $refs (the forms the service follows), transitively and each once, so cycles
+    end. Kept schemas keep their names and paths and the document's order; paths, servers, security, info and
+    unreached schemas are not sent. Applied after strip_examples, so a $ref inside an example, default, const or
+    x-* value is never followed. A missing or non-local ref is not followed (the service reports it unmapped, as
+    with the full document). Any other input is returned as is."""
+    if not isinstance(schema, dict) or not isinstance(schema.get("component"), str) or not isinstance(schema.get("openapi"), dict):
+        return schema
+    if any(k not in ("openapi", "component") for k in schema):
+        return schema  # the service refuses it
+    doc = schema["openapi"]
+    comps = doc.get("components")
+    containers = {
+        "components": comps["schemas"] if isinstance(comps, dict) and isinstance(comps.get("schemas"), dict) else None,
+        "$defs": doc["$defs"] if isinstance(doc.get("$defs"), dict) else None,
+        "definitions": doc["definitions"] if isinstance(doc.get("definitions"), dict) else None,
+    }
+    reached = {"components": set(), "$defs": set(), "definitions": set()}
+    todo = [("components", schema["component"])]
+    while todo:
+        where, name = todo.pop()
+        container = containers[where]
+        if container is None or name in reached[where]:
+            continue
+        target = container.get(name)
+        if not isinstance(target, dict):
+            continue  # missing: left for the service to report
+        reached[where].add(name)
+        stack = [target]
+        while stack:
+            v = stack.pop()
+            if isinstance(v, list):
+                stack.extend(v)
+            elif isinstance(v, dict):
+                for k, x in v.items():
+                    t = _ref_target(x) if k == "$ref" else None
+                    if t:
+                        todo.append(t)
+                    else:
+                        stack.append(x)
+
+    def keep(where):
+        return {n: s for n, s in (containers[where] or {}).items() if n in reached[where]}
+
+    out = {}
+    if "openapi" in doc:
+        out["openapi"] = doc["openapi"]
+    out["components"] = {"schemas": keep("components")}
+    if reached["$defs"]:
+        out["$defs"] = keep("$defs")
+    if reached["definitions"]:
+        out["definitions"] = keep("definitions")
+    return {"openapi": out, "component": schema["component"]}
+
+
+def request_body(columns=None, rows=10, seed=1, format="json", table=None, version="1", schema=None):
+    """The exact JSON bytes sent to POST /v1/generate. Key order is fixed, so the bytes (and the cache key,
+    their sha256) depend only on the arguments. Pass exactly one of ``columns`` (the column grammar) and
+    ``schema`` (a JSON Schema dict, e.g. a Pydantic ``model_json_schema()`` or Zod export, or
+    ``{"openapi": <document>, "component": "<name>"}``)."""
+    if (columns is None) == (schema is None):
+        raise ValueError("pass exactly one of columns and schema")
+    if schema is not None and not isinstance(schema, dict):
+        raise TypeError("schema must be a dict (a JSON Schema object)")
+    if format not in FORMATS:
+        raise ValueError("format must be one of %s, not %r" % (", ".join(FORMATS), format))
+    if isinstance(seed, bool) or not isinstance(seed, int):
+        raise TypeError("seed must be an int")
+    if isinstance(rows, bool) or not isinstance(rows, int):
+        raise TypeError("rows must be an int")
+    if not isinstance(version, str) or not version:
+        raise TypeError("version must be a non-empty string, e.g. \"1\"")
+    body = {}
+    if table is not None:
+        body["table"] = table
+    body["rows"] = rows
+    body["seed"] = seed
+    body["format"] = format
+    body["version"] = version
+    if schema is not None:
+        body["schema"] = minimal_openapi(strip_examples(schema))
+    else:
+        body["columns"] = list(columns)
+    return json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def _request_line(body):
+    b64 = base64.urlsafe_b64encode(body).decode("ascii").rstrip("=")
+    return "POST /v1/generate body-b64url=" + b64
+
+
+class Rowsmith:
+    """Client behind the ``rowsmith`` fixture.
+
+    ``cache`` is any object with ``get(key, default)`` and ``set(key, value)`` taking JSON values, such as
+    pytest's ``config.cache``; None keeps answers in memory for the life of the client only.
+    """
+
+    def __init__(self, base_url=DEFAULT_URL, cache=None, refresh=False, timeout=TIMEOUT_S, retry_delay=1.0):
+        self.base_url = base_url.rstrip("/")
+        self.cache = cache
+        self.refresh = refresh
+        self.timeout = timeout
+        self.retry_delay = retry_delay
+        self.network_calls = 0
+        self._memory = {}
+
+    # The golden-manifest helpers, on the fixture too: rowsmith.assert_golden(...), rowsmith.manifest_entry(...).
+    assert_golden = staticmethod(assert_golden)
+    manifest_entry = staticmethod(manifest_entry)
+
+    def generate(self, columns=None, rows=10, seed=1, format="json", table=None, version="1", schema=None):
+        """Rows for csv and json (a list of dicts), the SQL text for sql. Pass columns or schema."""
+        return self.fetch(columns, rows=rows, seed=seed, format=format, table=table, version=version, schema=schema).parsed()
+
+    def fetch(self, columns=None, rows=10, seed=1, format="json", table=None, version="1", schema=None):
+        """The full answer (bytes, headers, reproduce line) as a RowsmithResult. Pass columns or schema."""
+        body = request_body(columns, rows=rows, seed=seed, format=format, table=table, version=version, schema=schema)
+        key = CACHE_PREFIX + hashlib.sha256(body).hexdigest()
+        if key in self._memory:
+            return self._memory[key]
+        result = None if self.refresh else self._from_cache(key, body, format)
+        if result is None:
+            status, headers, data = self._post(body)
+            kept = {h: headers[h] for h in KEPT_HEADERS if h in headers}
+            result = RowsmithResult(data, kept, body, False, format)
+            if self.cache is not None:
+                self.cache.set(key, {
+                    "body_b64": base64.b64encode(data).decode("ascii"),
+                    "body_sha256": hashlib.sha256(data).hexdigest(),
+                    "headers": kept,
+                })
+        self._memory[key] = result
+        return result
+
+    def _from_cache(self, key, body, fmt):
+        if self.cache is None:
+            return None
+        entry = self.cache.get(key, None)
+        if not isinstance(entry, dict):
+            return None
+        try:
+            data = base64.b64decode(entry["body_b64"], validate=True)
+            headers = dict(entry["headers"])
+        except (KeyError, TypeError, ValueError):
+            return None
+        if hashlib.sha256(data).hexdigest() != entry.get("body_sha256"):
+            return None
+        return RowsmithResult(data, headers, body, True, fmt)
+
+    def _post(self, body):
+        url = self.base_url + "/v1/generate"
+        attempts = 2  # no retry on 4xx; exactly one retry on a 5xx or a network error
+        for attempt in range(attempts):
+            last = attempt == attempts - 1
+            req = urllib.request.Request(url, data=body, method="POST", headers={
+                "Content-Type": "application/json",
+                "Accept": "*/*",
+                "User-Agent": USER_AGENT,
+                "x-rowsmith-tool": TOOL_HEADER,
+            })
+            self.network_calls += 1
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    headers = {k.lower(): v for k, v in resp.headers.items()}
+                    return resp.status, headers, resp.read()
+            except urllib.error.HTTPError as e:
+                headers = {k.lower(): v for k, v in (e.headers or {}).items()}
+                try:
+                    raw = e.read()
+                except (OSError, HTTPException):
+                    raw = b""
+                if e.code >= 500 and not last:
+                    time.sleep(self.retry_delay)
+                    continue
+                raise self._http_error(e.code, headers, raw, body, url) from None
+            except (urllib.error.URLError, socket.timeout, OSError, HTTPException) as e:
+                if not last:
+                    time.sleep(self.retry_delay)
+                    continue
+                reason = getattr(e, "reason", None) or e
+                raise RowsmithError(None, "%s: %s" % (type(e).__name__, reason), None, _request_line(body), url) from None
+        raise AssertionError("unreachable")
+
+    @staticmethod
+    def _http_error(status, headers, raw, body, url):
+        error = nxt = None
+        try:
+            doc = json.loads(raw.decode("utf-8"))
+            if isinstance(doc, dict):
+                error = doc.get("error")
+                nxt = doc.get("next")
+        except (UnicodeDecodeError, ValueError):
+            text = raw.decode("utf-8", "replace").strip()
+            error = text[:300] if text else None
+        if status == 429 and headers.get("retry-after"):
+            nxt = (nxt + " " if nxt else "") + "(Retry-After: %s s)" % headers["retry-after"]
+        reproduce = headers.get("x-reproduce") or _request_line(body)
+        return RowsmithError(status, error, nxt, reproduce, url)

pytest_rowsmith/plugin.py

@@ -0,0 +1,36 @@
+"""The pytest plugin: the ``rowsmith`` fixture, the ``--rowsmith-refresh`` option and the ``rowsmith_url`` ini
+option. Loading it defines hooks only; it opens no connection."""
+import os
+
+import pytest
+
+from . import DEFAULT_URL, Rowsmith
+
+
+def pytest_addoption(parser):
+    group = parser.getgroup("rowsmith", "Rowsmith fake test data")
+    group.addoption(
+        "--rowsmith-refresh",
+        action="store_true",
+        default=False,
+        help="Ignore cached Rowsmith answers: call the API once per schema in this run and replace the cache.",
+    )
+    parser.addini(
+        "rowsmith_url",
+        help="Base URL of the Rowsmith API (default %s). The ROWSMITH_URL environment variable wins." % DEFAULT_URL,
+        default="",
+    )
+
+
+def base_url(config):
+    return os.environ.get("ROWSMITH_URL") or config.getini("rowsmith_url") or DEFAULT_URL
+
+
+@pytest.fixture(scope="session")
+def rowsmith(pytestconfig):
+    """A Rowsmith client whose answers are cached in pytest's cache (.pytest_cache), keyed by the request."""
+    return Rowsmith(
+        base_url=base_url(pytestconfig),
+        cache=getattr(pytestconfig, "cache", None),
+        refresh=pytestconfig.getoption("rowsmith_refresh"),
+    )

pytest_rowsmith-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: pytest-rowsmith
+Version: 0.1.0
+Summary: pytest fixture for reproducible fake test data (CSV, JSON, SQL) from the free Rowsmith API, cached for offline runs.
+Author: meiorz
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/meiorz/rowsmith-mcp/tree/main/pytest-rowsmith
+Project-URL: Source, https://github.com/meiorz/rowsmith-mcp
+Project-URL: Issues, https://github.com/meiorz/rowsmith-mcp/issues
+Keywords: pytest,fixtures,test data,fake data,csv,sql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytest>=7
+Dynamic: license-file
+
+# pytest-rowsmith
+
+A pytest plugin with one fixture, `rowsmith`, that gives your tests reproducible fake test data (CSV, JSON or
+SQL INSERTs) generated from a table schema by the Rowsmith API.
+
+**Network use.** The plugin calls the Rowsmith API over the network (POST
+https://testdata-api.re-jam620.workers.dev/v1/generate) only when a test calls `rowsmith.generate()` or
+`rowsmith.fetch()` and that request is not in the cache yet: the first time a schema (with its rows, seed,
+format, table and version) is used, or every schema once per run with `--rowsmith-refresh`. Importing the package,
+loading the plugin and creating the fixture make no network call. Calls go to the free Rowsmith API under its terms
+of use (https://testdata-api.re-jam620.workers.dev/terms) and count against your daily limit.
+
+- Free, rate-limited, no account, no API key.
+- The same schema and seed give byte-identical output for the same generator version. The plugin pins the
+  version in every request (`"version": "1"` by default), so cached answers stay valid.
+- Send schemas only. Never send real data.
+- Identifiers come only from reserved or invalid ranges: emails use example.com, example.net, example.org and
+  mail.test; phones, card numbers and SSN- and IBAN-shaped values come from reserved or invalid ranges too.
+- No runtime dependency besides pytest; HTTP goes through the standard library's urllib.
+
+## Install
+```sh
+pip install pytest-rowsmith
+```
+Or from the public repository at the plugin's release tag pytest-rowsmith-v0.1.0:
+```sh
+pip install "git+https://github.com/meiorz/rowsmith-mcp@pytest-rowsmith-v0.1.0#subdirectory=pytest-rowsmith"
+```
+The install from the repository needs git and network access to PyPI for the build tool (setuptools); nothing is
+compiled. pytest loads the plugin automatically. Python 3.9 or later.
+
+## Example
+```python
+ORDERS = [
+    {"name": "order_id", "type": "sequence", "prefix": "ord_", "pad": 4},
+    {"name": "email", "type": "email"},
+    {"name": "total_usd", "type": "decimal", "min": 1, "max": 500},
+]
+
+def test_orders(rowsmith):
+    orders = rowsmith.generate(ORDERS, rows=20, seed=42)
+    assert len(orders) == 20 and orders[0]["order_id"] == "ord_0001"
+    assert all(o["email"].rsplit("@", 1)[1] in ("example.com", "example.net", "example.org", "mail.test") for o in orders)
+```
+The column types and their options are listed at https://testdata-api.re-jam620.workers.dev/v1/types; the full
+API is described at https://testdata-api.re-jam620.workers.dev/openapi.json.
+
+### From your own schema
+Instead of `columns`, pass `schema=`: a JSON Schema dict (type object with properties), such as a Pydantic
+model's `model_json_schema()` or a Zod export, or an OpenAPI component as
+`{"openapi": <document dict>, "component": "Order"}`. The service maps it to columns; properties it cannot map
+(arrays, patterns and other unsupported forms) are left out, never guessed, and listed in
+`fetch(...).schema_unmapped`. Before sending, the plugin removes `example`, `examples`, `default`, `const` and `x-*`
+keys from the schema, so their values do not leave your machine; the service ignores them too.
+For an OpenAPI component, only the named component and the schemas it references are sent.
+```python
+from myapp.models import User  # a Pydantic model
+
+def test_users(rowsmith):
+    users = rowsmith.generate(schema=User.model_json_schema(), rows=20, seed=42)
+    assert len(users) == 20
+```
+
+## The fixture
+`rowsmith` is session-scoped. Its methods take the same arguments:
+
+| Argument | Default | Meaning |
+|---|---|---|
+| `columns` | | list of column definitions, as in the API; pass `columns` or `schema` |
+| `schema` | | a JSON Schema dict, or `{"openapi": ..., "component": ...}`; pass `columns` or `schema` |
+| `rows` | `10` | 1 to 500 |
+| `seed` | `1` | always sent, so every call is reproducible |
+| `format` | `"json"` | `"csv"`, `"json"` or `"sql"` |
+| `table` | not sent | table name (used in SQL output) |
+| `version` | `"1"` | generator version, always sent |
+
+- `rowsmith.generate(columns, ...)` (or `generate(schema=..., ...)`) returns a list of dicts for `json` (values typed as in the JSON) and `csv`
+  (values are strings), and the SQL text for `sql`.
+- `rowsmith.fetch(columns, ...)` returns a `RowsmithResult` with `body` (the exact bytes), `text`, `sha256`,
+  `headers`, `generator_version`, `seed`, `reproduce`, `schema_unmapped`, `schema_version`, `output_sha256`,
+  `request_sha256`, `from_cache` and `parsed()`. `reproduce` is the service's
+  X-Reproduce line (sent with CSV and SQL answers, and kept in the cache); JSON answers carry none, so for them it
+  is the request that was sent, in the same form.
+- On anything other than a successful answer the call raises `pytest_rowsmith.RowsmithError`. Its message names
+  the HTTP status, the service's error and `next` text, and the reproduce line. A 4xx answer is not retried; a 5xx
+  answer or a network error is retried exactly once, 1 second later. There is no fallback to random or local data.
+- Each request times out after 30 s.
+
+`pytest_rowsmith.Rowsmith` is the same client outside pytest (`Rowsmith(base_url=..., cache=None)`).
+
+## Golden manifests
+Pin a dataset for an eval and detect drift. The service sends `X-Output-SHA256` (the sha256 of the body bytes) and
+`X-Request-SHA256` (the sha256 of the canonical request, the same for a schema and the columns it maps to) with
+every answer; the result exposes them as `output_sha256` and `request_sha256`, and the cache keeps them.
+`request_sha256` is the X-Request-SHA256 header; without it, the sha256 of the body in a body-b64url X-Reproduce
+line; otherwise None, and a run with `--rowsmith-refresh` fetches the answer again with its headers.
+`output_sha256` without its header is computed from the body bytes.
+```python
+ORDERS = [{"name": "order_id", "type": "sequence", "prefix": "ord_", "pad": 4}, {"name": "email", "type": "email"}]
+
+def test_orders_are_golden(rowsmith):
+    result = rowsmith.fetch(ORDERS, rows=20, seed=42, format="csv")
+    entry = rowsmith.manifest_entry(result, "orders-v1")  # save it once, e.g. into tests/golden.json
+    rowsmith.assert_golden(result, entry["output_sha256"])  # later: compare against the saved entry or its hash
+```
+- `rowsmith.manifest_entry(result, name)` returns `{"name", "request_sha256", "output_sha256", "output_version",
+  "schema_version", "reproduce"}`, one entry of `{"rowsmith_manifest": 1, "entries": [...]}` (the format is in the
+  service's llms.txt). `reproduce` regenerates the bytes by itself: the service's X-Reproduce line when it carries
+  the body, otherwise the request the plugin sent.
+- `rowsmith.assert_golden(result, expected)` takes a sha256 hex string or a manifest entry (then the request hash
+  must match too) and fails with both hashes, the versions, whether the answer came from the cache, and the
+  reproduce line. Both are also importable from `pytest_rowsmith`.
+- The plugin pins the version in every request. A pinned version is served as long as the service runs; a retired version answers 409. A version's output is not changed in place: a golden test checks its bytes on every build.
+
+## Caching and offline runs
+Answers are stored in pytest's own cache (`.pytest_cache/v/rowsmith/v1/` in your project), one entry per request,
+keyed by the sha256 of the exact request-body bytes. An entry holds the response bytes and the headers
+content-type, x-generator-version, x-seed, x-reproduce, x-request-sha256 and x-output-sha256, plus
+x-schema-version and x-schema-unmapped for a schema request. A suite therefore calls the API once per distinct
+request and then runs offline, as long as `.pytest_cache` is kept. A damaged entry is fetched again.
+
+- `pytest --rowsmith-refresh` ignores the cache: each distinct request is sent once in that run and its entry is
+  replaced.
+- `pytest --cache-clear` removes the cache, Rowsmith entries included.
+- With pytest's cache disabled (`-p no:cacheprovider`), answers are kept in memory for the run only.
+- The cache key does not include the base URL.
+
+## Configuration
+| Setting | Where | Default |
+|---|---|---|
+| API base URL | `ROWSMITH_URL` environment variable, or `rowsmith_url` in your pytest ini file; the variable wins | `https://testdata-api.re-jam620.workers.dev` |
+| Bypass the cache | `--rowsmith-refresh` | off |
+
+Every request sends `User-Agent: pytest-rowsmith/<version>` and `x-rowsmith-tool: pytest`. The service counts these calls under tool pytest in its aggregate usage totals (counts only; nothing per caller).
+
+## Limits and terms
+Up to 500 rows and 50 columns per call, with daily limits per caller; over a limit the call fails with the
+service's 429 message. Use of the Rowsmith service is under its terms of use:
+https://testdata-api.re-jam620.workers.dev/terms. Data notice: https://testdata-api.re-jam620.workers.dev/privacy.
+
+The MIT licence covers this plugin's code only.
+
+## Development
+```sh
+PYTHONPATH=src python -m pytest                    # offline: a local stub server stands in for the API
+ROWSMITH_LIVE=1 PYTHONPATH=src python -m pytest    # adds the live golden test (one real API call)
+```

pytest_rowsmith-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pytest_rowsmith/__init__.py,sha256=Qgpyu0ruAMgYhAlmOrXkpQe-ROK9QSnnthjpH7cXGTk,19832
+pytest_rowsmith/plugin.py,sha256=kvKOuOgOHScMWAGgr70m66nkvwyFx5rK3IB77K-08UA,1212
+pytest_rowsmith-0.1.0.dist-info/licenses/LICENSE,sha256=IpjKGfsXI0G31Oyqm-bIWq75BRVeioKRMmIK3zEGzZY,1063
+pytest_rowsmith-0.1.0.dist-info/METADATA,sha256=5bJSSV3d7mEY5Zw-MeBp69d3kpK2SF-JrQDsNZRJSLg,10330
+pytest_rowsmith-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pytest_rowsmith-0.1.0.dist-info/entry_points.txt,sha256=rclv29oEkAASsj4ddFJnQIMnz_c024GgZaIL4uv8RsQ,45
+pytest_rowsmith-0.1.0.dist-info/top_level.txt,sha256=zozwhHtWM7TANGcvnAMexQ8pMS2ePDguWm-ctJ-ItaQ,16
+pytest_rowsmith-0.1.0.dist-info/RECORD,,

pytest_rowsmith-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pytest_rowsmith-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+rowsmith = pytest_rowsmith.plugin

pytest_rowsmith-0.1.0.dist-info/licenses/LICENSE

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

pytest_rowsmith-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pytest_rowsmith