pytest-resources 0.1.0__py3-none-any.whl

pytest_resources/__init__.py

@@ -0,0 +1,36 @@
+"""pytest-resources — lazy, typed, attribute-navigable resource fixtures for pytest.
+
+One façade over the package. The pytest plugin (`resources` fixture, options and
+hooks) lives in :mod:`pytest_resources.plugin` and auto-loads via the ``pytest11``
+entry point; this module is the import-time surface for programmatic use.
+
+    import pytest_resources as pr
+    resources = pr.build_resources(Path("tests/resources"))
+    sample = resources.structured.sample          # decoded per its FileType, cached
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from pytest_resources.errors import EntryNotFoundError, ResourceError
+from pytest_resources.formats import FileType
+from pytest_resources.index import abuild_resources, build_resources
+from pytest_resources.loaders import Loader, default_loaders
+from pytest_resources.nodes import ResourceNode, Resources
+
+try:
+    __version__: str = version("pytest-resources")
+except PackageNotFoundError:  # source tree, not installed
+    __version__ = "0.0.0+dev"
+
+__all__ = [
+    "EntryNotFoundError",
+    "FileType",
+    "Loader",
+    "ResourceError",
+    "ResourceNode",
+    "Resources",
+    "__version__",
+    "abuild_resources",
+    "build_resources",
+    "default_loaders",
+]

pytest_resources/errors.py

@@ -0,0 +1,13 @@
+"""pytest_resources.errors: the typed failure surface of the resources plugin."""
+
+
+class ResourceError(Exception):
+    """Base for every resources-plugin failure."""
+
+
+class EntryNotFoundError(ResourceError, AttributeError):
+    """A node was asked for an entry the indexed tree does not hold.
+
+    Subclasses ``AttributeError`` so attribute access keeps its protocol while the
+    error stays typed and catchable as ``ResourceError``.
+    """

pytest_resources/formats.py

@@ -0,0 +1,67 @@
+"""pytest_resources.formats: canonical file kinds and suffix resolution."""
+
+from __future__ import annotations
+
+from enum import StrEnum, auto
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+    from typing import Final
+
+
+class FileType(StrEnum):
+    """The kinds the loader system recognises; any other suffix resolves to ``BINARY``."""
+
+    JSON = auto()
+    JSONC = auto()
+    NDJSON = auto()
+    YAML = auto()
+    TOML = auto()
+    INI = auto()
+    CSV = auto()
+    TSV = auto()
+    MARKDOWN = auto()
+    TEXT = auto()
+    HTML = auto()
+    XML = auto()
+    PYTHON = auto()
+    BINARY = auto()
+
+    @classmethod
+    def of(cls, suffix: str) -> FileType:
+        """Kind resolved from a file suffix through the frozen table; unknown is ``BINARY``."""
+        return _SUFFIXES.get(suffix.casefold(), FileType.BINARY)
+
+    @classmethod
+    def of_path(cls, path: Path) -> FileType:
+        """Kind resolved from a path's extension."""
+        return cls.of(path.suffix)
+
+
+_SUFFIXES: Final[Mapping[str, FileType]] = MappingProxyType(
+    {
+        ".json": FileType.JSON,
+        ".jsonc": FileType.JSONC,
+        ".jsonl": FileType.NDJSON,
+        ".ndjson": FileType.NDJSON,
+        ".yaml": FileType.YAML,
+        ".yml": FileType.YAML,
+        ".toml": FileType.TOML,
+        ".ini": FileType.INI,
+        ".cfg": FileType.INI,
+        ".conf": FileType.INI,
+        ".csv": FileType.CSV,
+        ".tsv": FileType.TSV,
+        ".md": FileType.MARKDOWN,
+        ".markdown": FileType.MARKDOWN,
+        ".txt": FileType.TEXT,
+        ".rst": FileType.TEXT,
+        ".html": FileType.HTML,
+        ".htm": FileType.HTML,
+        ".xml": FileType.XML,
+        ".py": FileType.PYTHON,
+    }
+)

pytest_resources/hooks.py

@@ -0,0 +1,44 @@
+"""pytest_resources.hooks: the extension seams for loaders and resource roots.
+
+A project implements these in its own ``conftest.py`` to add or override the default
+codec table, or to contribute extra resource directories, without touching the plugin.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pytest_resources.formats import FileType
+from pytest_resources.loaders import Loader
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+Register = Callable[[Mapping[FileType, Loader]], None]
+
+
+@pytest.hookspec
+def pytest_resource_loaders(register: Register) -> None:
+    """Bind or override resource loaders declaratively.
+
+    ``register`` merges a ``{FileType: bytes -> object}`` mapping into the session's
+    codec table, so an existing kind can be swapped and an unknown one introduced::
+
+        def pytest_resource_loaders(register):
+            register({FileType.CSV: my_csv_rows, FileType.YAML: ruamel_round_trip})
+    """
+
+
+@pytest.hookspec
+def pytest_resources_roots(roots: list[Path]) -> None:
+    """Contribute extra resource root directories to the indexed tree.
+
+    ``roots`` is the resolved base list (CLI / ini / default); implementations append to
+    it, and appended roots win over earlier ones on a top-level key clash::
+
+        def pytest_resources_roots(roots):
+            roots.append(Path("tests/fixtures/shared"))
+    """

pytest_resources/index.py

@@ -0,0 +1,92 @@
+"""pytest_resources.index: recursive directory indexing without reading contents."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from operator import attrgetter
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pytest_resources.errors import ResourceError
+from pytest_resources.loaders import default_loaders
+from pytest_resources.nodes import ResourceNode, Resources, _Context
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+    from pytest_resources.formats import FileType
+    from pytest_resources.loaders import Loader
+
+##### PRIVATE #####
+
+
+def _key(name: str) -> str:
+    """Identifier-safe attribute name from a file stem or a directory name."""
+    return re.sub(r"\W|^(?=\d)", "_", Path(name).stem)
+
+
+def _visible(name: str) -> bool:
+    return not name.startswith(".") and name != "__pycache__"
+
+
+def _children(path: Path, context: _Context) -> dict[str, Path | ResourceNode]:
+    entries = sorted(path.iterdir(), key=attrgetter("name"))
+    return {
+        _key(entry.name): (_node(entry, context) if entry.is_dir() else entry)
+        for entry in entries
+        if _visible(entry.name)
+    }
+
+
+def _node(path: Path, context: _Context) -> ResourceNode:
+    return ResourceNode(path, _children(path, context), context)
+
+
+def _context(registry: Mapping[FileType, Loader] | None) -> _Context:
+    ### A None registry means the best default table; a mapping is copied, never shared.
+    return _Context(default_loaders() if registry is None else dict(registry))
+
+
+def _roots(root: Path | Iterable[Path]) -> tuple[Path, ...]:
+    ### One root or many: a lone Path and a sequence of them share the same code path.
+    match root:
+        case Path() as single:
+            return (single,)
+        case _:
+            return tuple(root)
+
+
+def _merge(paths: tuple[Path, ...], context: _Context) -> dict[str, Path | ResourceNode]:
+    ### Flat top-level merge across roots; a later root overrides an earlier key.
+    merged: dict[str, Path | ResourceNode] = {}
+    for path in paths:
+        merged |= _children(path, context)
+    return merged
+
+
+def _ensure_dir(root: Path) -> Path:
+    if not root.is_dir():
+        msg = f"resources root is not a directory: {root}"
+        raise ResourceError(msg)
+    return root
+
+
+############################################################
+
+##### PUBLIC #####
+
+
+def build_resources(root: Path | Iterable[Path], registry: Mapping[FileType, Loader] | None = None) -> Resources:
+    """Index ``root`` (one path or several) recursively — read on access, later roots win."""
+    paths = tuple(map(_ensure_dir, _roots(root)))
+    context = _context(registry)
+    return Resources(paths[0], _merge(paths, context), context)
+
+
+async def abuild_resources(root: Path | Iterable[Path], registry: Mapping[FileType, Loader] | None = None) -> Resources:
+    """Same index, walked off the event loop for large trees."""
+    paths = tuple(map(_ensure_dir, _roots(root)))
+    context = _context(registry)
+    children = await asyncio.to_thread(_merge, paths, context)
+    return Resources(paths[0], children, context)

pytest_resources/loaders.py

@@ -0,0 +1,77 @@
+"""pytest_resources.loaders: pluggable decoders, e-serde preferred, stdlib fallback.
+
+The system accepts any canonical ``bytes -> object`` loader. ``default_loaders``
+returns the best table available: e-serde's unified native codecs when installed,
+otherwise the standard library (json + tomllib). Kinds with no parser hand back raw
+bytes for the caller to decode.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from functools import partial
+from tomllib import loads as _toml_loads
+from typing import Any
+
+from pytest_resources.formats import FileType
+
+Loader = Callable[[bytes], Any]
+
+
+def _raw(data: bytes) -> bytes:
+    """Passthrough for kinds with no parser bound."""
+    return data
+
+
+def _text(data: bytes) -> str:
+    """UTF-8 decode for textual kinds."""
+    return data.decode()
+
+
+def _toml(data: bytes) -> dict[str, Any]:
+    """TOML decode through the standard-library reader."""
+    return _toml_loads(data.decode())
+
+
+def _lines(loader: Loader, data: bytes) -> list[Any]:
+    """Split into non-empty lines and decode each with `loader`."""
+    return [loader(line) for line in data.splitlines() if line.strip()]
+
+
+def _eserde_loaders() -> dict[FileType, Loader]:
+    """Config-codec table backed by e-serde (native Rust/C decoders, native dicts out)."""
+    from eserde import Format, loads  # noqa: PLC0415 -- optional fast path, not a core dep
+
+    json_row = partial(loads, format=Format.JSON)
+    return {
+        FileType.JSON: json_row,
+        FileType.JSONC: partial(loads, format=Format.JSONC),
+        FileType.YAML: partial(loads, format=Format.YAML),
+        FileType.TOML: partial(loads, format=Format.TOML),
+        FileType.INI: partial(loads, format=Format.INI),
+        FileType.NDJSON: partial(_lines, json_row),
+        FileType.MARKDOWN: _text,
+        FileType.TEXT: _text,
+    }
+
+
+def _stdlib_loaders() -> dict[FileType, Loader]:
+    """Config-codec table from the standard library alone (json + tomllib)."""
+    return {
+        FileType.JSON: json.loads,
+        FileType.TOML: _toml,
+        FileType.NDJSON: partial(_lines, json.loads),
+        FileType.MARKDOWN: _text,
+        FileType.TEXT: _text,
+    }
+
+
+def default_loaders() -> dict[FileType, Loader]:
+    """A fresh codec table: e-serde when importable, else the stdlib; other kinds stay bytes."""
+    table: dict[FileType, Loader] = dict.fromkeys(FileType, _raw)
+    try:
+        table |= _eserde_loaders()
+    except ImportError:
+        table |= _stdlib_loaders()
+    return table

pytest_resources/nodes.py

@@ -0,0 +1,206 @@
+"""pytest_resources.nodes: the lazy, attribute-navigable tree over indexed files."""
+
+from __future__ import annotations
+
+import difflib
+import fnmatch
+import random
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pytest_resources.errors import EntryNotFoundError, ResourceError
+from pytest_resources.formats import FileType
+from pytest_resources.loaders import _raw
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterator, Mapping
+    from re import Pattern
+    from typing import Any
+
+    from pytest_resources.loaders import Loader
+
+_MISSING = object()
+
+##### PRIVATE #####
+
+
+def _matcher(pattern: str | Pattern[str]) -> Pattern[str]:
+    """A glob string becomes an anchored regex over the name; a compiled pattern is taken as-is."""
+    return pattern if isinstance(pattern, re.Pattern) else re.compile(fnmatch.translate(pattern))
+
+
+def _accept(path: Path, kind: FileType | None, matchers: tuple[Pattern[str], ...]) -> bool:
+    """A file passes when its canonical kind matches and any matcher hits its name."""
+    right_kind = kind is None or FileType.of_path(path) is kind
+    return right_kind and (not matchers or any(m.search(path.name) for m in matchers))
+
+
+############################################################
+
+
+class _Context:
+    """Loader registry and decode cache shared by every node of one indexed tree."""
+
+    __slots__ = ("_cache", "_registry")
+
+    def __init__(self, registry: Mapping[FileType, Loader]) -> None:
+        self._registry = registry
+        self._cache: dict[Path, Any] = {}
+
+    def load(self, path: Path) -> Any:
+        cached = self._cache.get(path, _MISSING)
+        return cached if cached is not _MISSING else self._decode(path)
+
+    def _decode(self, path: Path) -> Any:
+        ### The FileType decides the codec; an unbound kind hands back raw bytes.
+        loaded = self._registry.get(FileType.of_path(path), _raw)(path.read_bytes())
+        self._cache[path] = loaded
+        return loaded
+
+
+class ResourceNode:
+    """A lazily resolved directory: attribute, item and iteration views agree."""
+
+    __slots__ = ("_context", "_entries", "_path")
+
+    def __init__(self, path: Path, entries: dict[str, Path | ResourceNode], context: _Context) -> None:
+        self._path = path
+        self._entries = entries
+        self._context = context
+
+    ##### PRIVATE #####
+
+    def _value(self, entry: object) -> Any:
+        match entry:
+            case Path() as file:
+                return self._context.load(file)
+            case _:
+                return entry
+
+    def _absent(self, name: str) -> str:
+        ### One message for both miss paths; difflib nudges the nearest name, if any.
+        hint = difflib.get_close_matches(name, self._entries, n=1)
+        return f"{self._path.name!r} has no entry {name!r}" + (f" — did you mean {hint[0]!r}?" if hint else "")
+
+    def _files(self, patterns: tuple[str | Pattern[str], ...], kind: FileType | None) -> list[Path]:
+        matchers = tuple(map(_matcher, patterns))
+        return [file for file in self._entries.values() if isinstance(file, Path) and _accept(file, kind, matchers)]
+
+    def _walk(self, matchers: tuple[Pattern[str], ...], kind: FileType | None) -> Iterator[Path]:
+        for entry in self._entries.values():
+            if isinstance(entry, ResourceNode):
+                yield from entry._walk(matchers, kind)
+            if isinstance(entry, Path) and _accept(entry, kind, matchers):
+                yield entry
+
+    async def _awalk(self, matchers: tuple[Pattern[str], ...], kind: FileType | None) -> AsyncIterator[Path]:
+        for entry in self._entries.values():
+            if isinstance(entry, ResourceNode):
+                async for path in entry._awalk(matchers, kind):
+                    yield path
+            if isinstance(entry, Path) and _accept(entry, kind, matchers):
+                yield entry
+
+    ############################################################
+
+    ##### PUBLIC #####
+
+    @property
+    def path(self) -> Path:
+        """Absolute path this node indexes."""
+        return self._path
+
+    def keys(self) -> list[str]:
+        """Every entry name, files and directories alike."""
+        return list(self._entries)
+
+    def values(self) -> list[Any]:
+        """Every file entry parsed; directories stay out of the value stream."""
+        return self.select()
+
+    def items(self) -> list[tuple[str, Any]]:
+        """``(name, resolved)`` pairs: files parsed, directories as nodes."""
+        return [(name, self._value(entry)) for name, entry in self._entries.items()]
+
+    def as_dict(self) -> dict[str, Any]:
+        """Plain nested ``dict`` of the subtree: folders recurse, files are decoded values."""
+        return {
+            name: child.as_dict() if isinstance(child, ResourceNode) else self._context.load(child)
+            for name, child in self._entries.items()
+        }
+
+    def select(self, *patterns: str | Pattern[str], kind: FileType | None = None) -> list[Any]:
+        """Decoded values of files in this folder, narrowed by glob/regex and optional kind."""
+        return [self._context.load(file) for file in self._files(patterns, kind)]
+
+    def first(self, *patterns: str | Pattern[str], kind: FileType | None = None) -> Any:
+        """The first matching file value in name order (deterministic twin of ``choice``)."""
+        files = self._files(patterns, kind)
+        if not files:
+            msg = f"{self._path.name!r} has no matching file"
+            raise ResourceError(msg)
+        return self._context.load(files[0])
+
+    def paths(self, *patterns: str | Pattern[str], kind: FileType | None = None) -> list[Path]:
+        """Paths of files in this folder under the same filters — for raw bytes or ``open()``."""
+        return self._files(patterns, kind)
+
+    def walk(self, *patterns: str | Pattern[str], kind: FileType | None = None) -> Iterator[Path]:
+        """Depth-first Paths of every file in this subtree passing the filters, lazily."""
+        return self._walk(tuple(map(_matcher, patterns)), kind)
+
+    def awalk(self, *patterns: str | Pattern[str], kind: FileType | None = None) -> AsyncIterator[Path]:
+        """Async-generator twin of ``walk`` for streaming a large tree with ``async for``."""
+        return self._awalk(tuple(map(_matcher, patterns)), kind)
+
+    def similar(self, term: str, kind: FileType | None = None, *, n: int = 3, cutoff: float = 0.6) -> list[Any]:
+        """Decoded values whose file stem is lexically close to ``term`` (best first)."""
+        by_stem: dict[str, list[Path]] = {}
+        for file in self._files((), kind):
+            by_stem.setdefault(file.stem, []).append(file)
+        hits = difflib.get_close_matches(term, by_stem, n=n, cutoff=cutoff)
+        return [self._context.load(file) for stem in hits for file in by_stem[stem]]
+
+    def choice(
+        self,
+        *patterns: str | Pattern[str],
+        kind: FileType | None = None,
+        rng: random.Random | None = None,
+    ) -> Any:
+        """One random file value from the selection (default RNG honours the session seed)."""
+        candidates = self.select(*patterns, kind=kind)
+        if not candidates:
+            msg = f"{self._path.name!r} has no file to choose from"
+            raise ResourceError(msg)
+        return (rng or random).choice(candidates)
+
+    def __getattr__(self, name: str) -> Any:
+        entry = self._entries.get(name, _MISSING)
+        if entry is _MISSING:
+            raise EntryNotFoundError(self._absent(name))
+        return self._value(entry)
+
+    def __getitem__(self, name: str) -> Any:
+        entry = self._entries.get(name, _MISSING)
+        if entry is _MISSING:
+            raise KeyError(self._absent(name))
+        return self._value(entry)
+
+    def __iter__(self) -> Iterator[Any]:
+        return (self._context.load(entry) for entry in self._entries.values() if isinstance(entry, Path))
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._entries
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self._path.name!r}, entries={len(self._entries)})"
+
+
+class Resources(ResourceNode):
+    """Root of an indexed resources tree — the object the ``resources`` fixture yields."""
+
+    __slots__ = ()

pytest_resources/plugin.py

@@ -0,0 +1,68 @@
+"""pytest_resources.plugin: the pytest entry point — options, hook wiring, fixture.
+
+Auto-loaded through the ``pytest11`` entry point. It exposes the ``resources``
+fixture and the extension seams (``--resources-root``/``resources_root`` ini and the
+``pytest_resource_loaders`` / ``pytest_resources_roots`` hooks).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from pytest_resources import hooks
+from pytest_resources.index import build_resources
+from pytest_resources.loaders import default_loaders
+
+if TYPE_CHECKING:
+    from pytest_resources.nodes import Resources
+
+
+def pytest_addoption(parser: Any) -> None:
+    """Register the resources roots as a repeatable CLI option and an ini list."""
+    group = parser.getgroup("resources", "lazy typed resource fixtures")
+    parser.addini("resources_root", "Directories indexed by the `resources` fixture.", type="linelist")
+    group.addoption(
+        "--resources-root",
+        dest="resources_roots",
+        action="append",
+        default=None,
+        metavar="DIR",
+        help="Add a resources root directory (repeatable). CLI wins over the ini list.",
+    )
+
+
+def pytest_configure(config: Any) -> None:
+    """Publish the loader- and root-extension hookspecs so conftests may implement them."""
+    config.pluginmanager.add_hookspecs(hooks)
+
+
+##### PRIVATE #####
+
+
+def _resolve_roots(config: Any) -> list[Path]:
+    ### CLI > ini > default; each source is a list, the first non-empty one is the base.
+    chosen = config.getoption("resources_roots") or config.getini("resources_root") or []
+    if chosen:
+        return [Path(entry) for entry in chosen]
+    return [config.rootpath / "tests" / "resources"]
+
+
+############################################################
+
+##### FIXTURES #####
+
+
+@pytest.fixture(scope="session")
+def resources(request: Any) -> Resources:
+    """The session's indexed resources tree: default + hook roots, default + hook loaders."""
+    config = request.config
+    registry = default_loaders()
+    config.pluginmanager.hook.pytest_resource_loaders(register=registry.update)
+    roots = _resolve_roots(config)
+    config.pluginmanager.hook.pytest_resources_roots(roots=roots)
+    for root in roots:
+        root.mkdir(parents=True, exist_ok=True)
+    return build_resources(roots, registry)

pytest_resources/py.typed

@@ -0,0 +1 @@
+# Marker file indicating the package ships PEP 561 type information.

pytest_resources-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: pytest-resources
+Version: 0.1.0
+Summary: Lazy, typed, attribute-navigable fixtures for test resource files, with pluggable canonical loaders (e-serde by default).
+Project-URL: Homepage, https://github.com/damvolkov/pytest-resources
+Project-URL: Source, https://github.com/damvolkov/pytest-resources
+Project-URL: Issues, https://github.com/damvolkov/pytest-resources/issues
+Project-URL: Changelog, https://github.com/damvolkov/pytest-resources/blob/main/CHANGELOG.md
+Author-email: damvolkov <damvolkovv@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: config,e-serde,fixtures,json,pytest,pytest-plugin,resources,testing,toml,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: pytest>=8.0
+Provides-Extra: serde
+Requires-Dist: e-serde<0.3,>=0.2.0; extra == 'serde'
+Description-Content-Type: text/markdown
+
+# pytest-resources
+
+Lazy, typed, attribute-navigable fixtures for test resource files — JSON / JSONC / YAML /
+TOML / INI decoded through [`e-serde`](https://pypi.org/project/e-serde/) by default,
+extensible to **any** canonical `bytes -> object` loader, and anything else 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 and randomise parsed values the way they
+read:
+
+```python
+import pytest_resources as pr
+
+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
+```
+
+## Install
+
+```bash
+uv add --group test "pytest-resources[serde]"   # e-serde default codecs
+uv add --group test pytest-resources            # stdlib-only (json + tomllib)
+```
+
+The `resources` fixture auto-loads via the `pytest11` entry point — no imports in your
+`conftest.py`.
+
+## 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` |
+| **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 |
+| **e-serde default, optional** | native Rust/C config codecs when installed; stdlib otherwise |
+| **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:
+
+```toml
+# 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`:
+
+```python
+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`:
+
+```python
+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**.
+
+## Programmatic use
+
+Outside pytest, build a tree yourself:
+
+```python
+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()                                    # best available codecs
+```
+
+## Development
+
+```bash
+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

pytest_resources-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+pytest_resources/__init__.py,sha256=hyMQFQ8_nl6lqARmhrlLZh-TeiDcg292Mqu1dq3RdyA,1243
+pytest_resources/errors.py,sha256=8ztkYQwSnEzoEt79zyy7jQ4NL9mTcVbrdi_QoAEpkE4,445
+pytest_resources/formats.py,sha256=J3MHZJlETlemzgMpDD4vOLcMuBkPPWFZjoAXUjH8Y5E,1801
+pytest_resources/hooks.py,sha256=wfG_4FAJ93KjT6Yla4Ao-MuwkCVWyLpnWgxuFrJ8iK4,1443
+pytest_resources/index.py,sha256=331rwIl3nfk1KywssQ47SeO0jT0_CsWSVOVrDbZSSd0,3105
+pytest_resources/loaders.py,sha256=VyGr5upGnTPntIeIt1MDFu-FE0RrNL3qtKrV_Vi945A,2525
+pytest_resources/nodes.py,sha256=hDzgHqYL_bKQETUr25PMtAnsqYXbri3cHsmJ0rzaIbw,8333
+pytest_resources/plugin.py,sha256=cTQhBnyeh6CB5ZTiLXog9g18vi2OaBtMhr-xON854Uw,2357
+pytest_resources/py.typed,sha256=_PWtaTGz6Go8JPgNcU0NeRu6NuAC329-7awL4h_zVVM,69
+pytest_resources-0.1.0.dist-info/METADATA,sha256=_KgAlNzRf5gEgacmsCQlQv21Us-j6Layh_X_qrbmPYI,5486
+pytest_resources-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pytest_resources-0.1.0.dist-info/entry_points.txt,sha256=3Cw2AUax2cq4b0aJRj-JNeUxEPZsEnRPSnTOhlAwJ3U,47
+pytest_resources-0.1.0.dist-info/licenses/LICENSE,sha256=4K5VRrESrMWeDdFrydaJe4ZtvcVCfF3FSMdxK6893cE,1070
+pytest_resources-0.1.0.dist-info/RECORD,,

pytest_resources-0.1.0.dist-info/WHEEL

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

pytest_resources-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+resources = pytest_resources.plugin

pytest_resources-0.1.0.dist-info/licenses/LICENSE

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