pytest-resources
Lazy, typed, attribute-navigable fixtures for test resource files — decoded through the
Python standard library by default (json + tomllib, zero extra dependencies),
extensible to any canonical bytes -> object loader. The optional
e-serde extra is recommended as the fast,
multi-format official loader; anything without a parser is handed back as raw bytes.
You point it at one or more directories of sample files; it recursively indexes the tree without reading anything, and you reach, filter, randomise and synthesize parsed values the way they read:
from dataclasses import dataclass
import pytest_resources as pr
@dataclass
class User:
name: str
age: int
def test_profile(resources: pr.Resources):
user = resources.structured.user # sample dir -> dict (decoded, cached)
body = resources.unstructured.intro # a .md -> str
blob = resources.binary.logo # no codec bound -> raw bytes
jsons = resources.data.select("*.json") # filter a folder (glob / regex / kind)
pick = resources.data.choice("*.json") # random pick, seeded per run
ada = resources.make(User, name="ada") # random model instance [objects]
squad = resources.batch(User, 8) # a typed list of them [objects]
pdf = resources.file("report.pdf") # synthetic file, indexed [files]
Install
uv add --group test pytest-resources # default: stdlib (json + tomllib), zero extra deps
uv add --group test "pytest-resources[serde]" # e-serde — fast, multi-format loader (recommended)
uv add --group test "pytest-resources[objects]" # resources.make()/batch(): random model objects
uv add --group test "pytest-resources[files]" # resources.file(): synthetic files, 25 formats
uv add --group test "pytest-resources[random]" # both synthesis backends
The resources fixture auto-loads via the pytest11 entry point — no imports in your
conftest.py. Everything (index, navigation, synthesis) is async-test friendly:
make/batch are pure in-memory CPU and abuild_resources/awalk keep the loop free;
a missing extra raises ExtraNotInstalledError with the exact install command — the plugin
never hard-depends on e-serde, polyfactory or faker-file.
What you get
| Idea | Mechanism |
|---|---|
| Recursive index, zero read | each root is walked once (off the loop); only paths are held |
| Lazy + cached | a file decodes on first access and is memoized for the session |
| Attr / item / iter views | r.a.b, r["a"]["b"], list(r.a) → list of decoded values |
| Extract from a folder | select/first · paths · walk/awalk (sync/async, lazy) · similar (fuzzy) · as_dict, by glob / regex / kind |
| Randomise the pick | r.a.choice(...) (session-seeded) or pass your own rng |
| Synthesize on the fly | make(Model | hint, seed, **pins) / batch(Model | hint, n) for objects, file(kind | name, ...) for real files adopted into the tree — optional [objects] / [files] / [random] extras |
| Typed by suffix | FileType (StrEnum) resolves the extension; the loader table decodes |
| Open-ended fallback | CSV/TSV/PDF/… and any unknown kind stay raw bytes |
| Many roots, one tree | CLI / ini / pytest_resources_roots hook, merged (later wins), auto-created |
| Pluggable codecs | override or add any kind through the pytest_resource_loaders hook |
| Stdlib default, e-serde opt-in | json/tomllib by default; register eserde_loaders() for the fast multi-format backend |
| Friendly misses | EntryNotFoundError / KeyError carry a "did you mean" hint |
Configuring the roots
By default the plugin indexes <rootdir>/tests/resources (and creates it if missing).
Point it at one or several directories:
# pyproject.toml
[tool.pytest.ini_options]
resources_root = ["fixtures", "fixtures/shared"] # default: <rootdir>/tests/resources
Or per run (--resources-root is repeatable), or additively from your conftest.py:
from pathlib import Path
def pytest_resources_roots(roots):
roots.append(Path("tests/fixtures/shared"))
CLI wins over ini, which wins over the default. Every resolved root is merged into one navigable tree; on a top-level clash the later root wins.
Custom loaders (the extension seam)
The plugin never assumes e-serde. Bind any parser declaratively in your conftest.py:
from pytest_resources import FileType
import yaml, csv, io
def pytest_resource_loaders(register):
register({FileType.CSV: lambda b: list(csv.DictReader(io.StringIO(b.decode())))})
register({FileType.YAML: yaml.safe_load})
register merges into the session's table, so you can override a default kind as easily
as add an unknown one. Kinds left unbound hand back raw bytes.
The recommended official loader: e-serde
The default is the standard library. Install the [serde] extra and register one call to
make e-serde your official loader — ultrarapid,
native Rust/C, and it decodes JSONC/YAML/INI too:
from pytest_resources import eserde_loaders
def pytest_resource_loaders(register):
register(eserde_loaders())
Programmatic use
Outside pytest, build a tree yourself:
from pathlib import Path
import pytest_resources as pr
tree = pr.build_resources(Path("fixtures")) # sync, one root
tree = pr.build_resources([Path("a"), Path("b")]) # merged roots, later wins
tree = await pr.abuild_resources(Path("fixtures")) # off the event loop
table = pr.default_loaders() # stdlib codecs (json + tomllib)
tree = pr.build_resources(Path("fixtures"), pr.eserde_loaders()) # opt into e-serde instead
Development
make install # uv sync + git hooks
make check # ruff + ty + tach + validate + tests
make ci # everything the pipeline runs (adds coverage gate + docs + zizmor)
License
MIT
Metadata
Release files for pytest-resources 0.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pytest_resources-0.3.3.tar.gz | 30.2 kB | Without provenance | Details for pytest_resources-0.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pytest_resources-0.3.3-py3-none-any.whl | Python 3 | none | any | Details for pytest_resources-0.3.3-py3-none-any.whl |
Total release size: 49.3 kB
Release files / pytest_resources-0.3.3.tar.gz
| Download URL | pytest_resources-0.3.3.tar.gz |
|---|---|
| Size | 30.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d1116f857bfa8580f5beffce50743230aeef662f6eb5382fc927f59555f563bd
|
|
BLAKE2b-256 checksum How to use checksums |
3043755f55e85f97ba60f9b7078268d35570fea431f68153d7a14aae9e10d111
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pytest_resources-0.3.3-py3-none-any.whl
| Download URL | pytest_resources-0.3.3-py3-none-any.whl |
|---|---|
| Size | 19.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c2792572bc571b85971fd7d9b59728cbc6f224d44d84dd7f8896160973295e44
|
|
BLAKE2b-256 checksum How to use checksums |
1098975cc848ae9f1b338af4757981cd63d3c784af99b401979e75133e580de0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for pytest-resources 0.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.