pytest-resources 0.2.2__tar.gz → 0.3.0__tar.gz

{pytest_resources-0.2.2 → pytest_resources-0.3.0}/CHANGELOG.md

@@ -6,6 +6,29 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-25
+
+### Changed
+
+- **The default loader is now the Python standard library** (`json` + `tomllib`): the core
+  ships with zero third-party dependencies. e-serde is no longer auto-selected when present,
+  so `JSONC` / `YAML` / `INI` decode to raw `bytes` unless you opt in.
+- The `[serde]` extra is now an explicit opt-in on equal footing with `[objects]` /
+  `[files]`, documented as the recommended fast, multi-format official loader.
+
+### Added
+
+- `eserde_loaders()` (exported): the e-serde codec table. Register it from `conftest.py`
+  via `pytest_resource_loaders` to make e-serde the project's loader; it raises
+  `ExtraNotInstalledError` (naming the `[serde]` extra) when the extra is absent.
+
+## [0.2.3] - 2026-09-25
+
+### Fixed
+
+- `ExtraNotInstalledError` now emits a single **uv-only** install hint (dropped the
+  redundant `pip` line), matching the project's toolchain and the docs.
+
 ## [0.2.2] - 2026-09-24
 
 ### Changed
@@ -79,7 +102,9 @@ First release.
 - A module-lifetime decode cache per tree, and typed misses (`EntryNotFoundError` /
   `KeyError`) that carry a `difflib` "did you mean" hint.
 
-[unreleased]: https://github.com/damvolkov/pytest-resources/compare/v0.2.2...HEAD
+[unreleased]: https://github.com/damvolkov/pytest-resources/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/damvolkov/pytest-resources/releases/tag/v0.3.0
+[0.2.3]: https://github.com/damvolkov/pytest-resources/releases/tag/v0.2.3
 [0.2.2]: https://github.com/damvolkov/pytest-resources/releases/tag/v0.2.2
 [0.2.1]: https://github.com/damvolkov/pytest-resources/releases/tag/v0.2.1
 [0.2.0]: https://github.com/damvolkov/pytest-resources/releases/tag/v0.2.0

{pytest_resources-0.2.2 → pytest_resources-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytest-resources
-Version: 0.2.2
+Version: 0.3.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
@@ -33,10 +33,11 @@ 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`.
+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`](https://pypi.org/project/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
@@ -70,18 +71,18 @@ def test_profile(resources: pr.Resources):
 ## Install
 
 ```bash
-uv add --group test "pytest-resources[serde]"   # e-serde default codecs
-uv add --group test pytest-resources            # stdlib-only (json + tomllib)
+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
+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;
-calling a synthesis method without its extra raises `ExtraNotInstalledError` with the
-exact install command — the plugin never hard-depends on polyfactory or faker-file.
+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
 
@@ -97,7 +98,7 @@ exact install command — the plugin never hard-depends on polyfactory or faker-
 | **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 |
+| **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
@@ -139,6 +140,19 @@ def pytest_resource_loaders(register):
 `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`](https://pypi.org/project/e-serde/) your official loader — ultrarapid,
+native Rust/C, and it decodes JSONC/YAML/INI too:
+
+```python
+from pytest_resources import eserde_loaders
+
+def pytest_resource_loaders(register):
+    register(eserde_loaders())
+```
+
 ## Programmatic use
 
 Outside pytest, build a tree yourself:
@@ -150,7 +164,8 @@ 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
+table = pr.default_loaders()                                    # stdlib codecs (json + tomllib)
+tree = pr.build_resources(Path("fixtures"), pr.eserde_loaders())  # opt into e-serde instead
 ```
 
 ## Development

{pytest_resources-0.2.2 → pytest_resources-0.3.0}/README.md

@@ -1,9 +1,10 @@
 # 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`.
+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`](https://pypi.org/project/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
@@ -37,18 +38,18 @@ def test_profile(resources: pr.Resources):
 ## Install
 
 ```bash
-uv add --group test "pytest-resources[serde]"   # e-serde default codecs
-uv add --group test pytest-resources            # stdlib-only (json + tomllib)
+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
+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;
-calling a synthesis method without its extra raises `ExtraNotInstalledError` with the
-exact install command — the plugin never hard-depends on polyfactory or faker-file.
+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
 
@@ -64,7 +65,7 @@ exact install command — the plugin never hard-depends on polyfactory or faker-
 | **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 |
+| **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
@@ -106,6 +107,19 @@ def pytest_resource_loaders(register):
 `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`](https://pypi.org/project/e-serde/) your official loader — ultrarapid,
+native Rust/C, and it decodes JSONC/YAML/INI too:
+
+```python
+from pytest_resources import eserde_loaders
+
+def pytest_resource_loaders(register):
+    register(eserde_loaders())
+```
+
 ## Programmatic use
 
 Outside pytest, build a tree yourself:
@@ -117,7 +131,8 @@ 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
+table = pr.default_loaders()                                    # stdlib codecs (json + tomllib)
+tree = pr.build_resources(Path("fixtures"), pr.eserde_loaders())  # opt into e-serde instead
 ```
 
 ## Development

{pytest_resources-0.2.2 → pytest_resources-0.3.0}/src/pytest_resources/__init__.py

@@ -14,7 +14,7 @@ from importlib.metadata import PackageNotFoundError, version
 from pytest_resources.errors import EntryNotFoundError, ExtraNotInstalledError, 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.loaders import Loader, default_loaders, eserde_loaders
 from pytest_resources.nodes import ResourceNode, Resources
 
 try:
@@ -34,4 +34,5 @@ __all__ = [
     "abuild_resources",
     "build_resources",
     "default_loaders",
+    "eserde_loaders",
 ]

{pytest_resources-0.2.2 → pytest_resources-0.3.0}/src/pytest_resources/loaders.py

@@ -1,9 +1,10 @@
-"""pytest_resources.loaders: pluggable decoders, e-serde preferred, stdlib fallback.
+"""pytest_resources.loaders: pluggable decoders, stdlib by default, e-serde opt-in.
 
-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.
+The system accepts any canonical ``bytes -> object`` loader. ``default_loaders()``
+returns the standard-library table (``json`` + ``tomllib``) — the light, dependency-free
+default. [`e-serde`](https://pypi.org/project/e-serde/) is an optional ``[serde]`` extra:
+call :func:`eserde_loaders` and register it to swap in the fast, multi-format backend.
+Kinds with no parser hand back raw bytes for the caller to decode.
 """
 
 from __future__ import annotations
@@ -14,6 +15,7 @@ from functools import partial
 from tomllib import loads as _toml_loads
 from typing import Any
 
+from pytest_resources.errors import ExtraNotInstalledError
 from pytest_resources.formats import FileType
 
 Loader = Callable[[bytes], Any]
@@ -39,10 +41,33 @@ def _lines(loader: Loader, data: bytes) -> list[Any]:
     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
+def default_loaders() -> dict[FileType, Loader]:
+    """The default codec table — the standard library only; kinds without one stay bytes."""
+    table: dict[FileType, Loader] = dict.fromkeys(FileType, _raw)
+    table |= _stdlib_loaders()
+    return table
+
+
+def eserde_loaders() -> dict[FileType, Loader]:
+    """The recommended fast table backed by e-serde — needs the optional `[serde]` extra.
+
+    Register it from a ``conftest.py`` to make e-serde the project's official loader::
+
+        from pytest_resources import eserde_loaders
+
 
+        def pytest_resource_loaders(register):
+            register(eserde_loaders())
+    """
+    try:
+        from eserde import Format, loads  # noqa: PLC0415 -- optional fast path, not a core dep
+    except ImportError as exc:
+        msg = (
+            "`eserde_loaders()` requires the 'serde' extra.\n"
+            'Install it with:  uv add --group test "pytest-resources[serde]"\n'
+            "Underlying import failed: eserde"
+        )
+        raise ExtraNotInstalledError(msg) from exc
     json_row = partial(loads, format=Format.JSON)
     return {
         FileType.JSON: json_row,
@@ -65,13 +90,3 @@ def _stdlib_loaders() -> dict[FileType, Loader]:
         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-0.2.2 → pytest_resources-0.3.0}/src/pytest_resources/synth.py

@@ -116,8 +116,7 @@ class SynthProvider:
             return
         msg = (
             f"`Resources.{method}()` requires the '{extra}' extra.\n"
-            f'Install it with:  uv add --group test "pytest-resources[{extra}]"   '
-            f'(pip: pip install "pytest-resources[{extra}]")\n'
+            f'Install it with:  uv add --group test "pytest-resources[{extra}]"\n'
             f"Underlying import failed: {module}"
         )
         raise ExtraNotInstalledError(msg)

pytest_resources-0.3.0/tests/unit/test_loaders.py

@@ -0,0 +1,68 @@
+"""tests/unit: the loader tables — the stdlib default and the opt-in e-serde table."""
+
+import json
+import sys
+
+import pytest
+
+from pytest_resources import FileType
+from pytest_resources.errors import ExtraNotInstalledError
+from pytest_resources.loaders import _lines, _raw, _text, default_loaders, eserde_loaders
+
+
+def test_default_loaders_covers_every_kind() -> None:
+    assert set(default_loaders()) == set(FileType)
+
+
+def test_default_loaders_is_stdlib() -> None:
+    table = default_loaders()
+    assert table[FileType.JSON](b'{"a": 1, "b": [1, 2]}') == {"a": 1, "b": [1, 2]}
+    assert table[FileType.TOML](b"a = 1\n") == {"a": 1}
+    assert table[FileType.NDJSON](b'{"i": 1}\n\n{"i": 2}') == [{"i": 1}, {"i": 2}]
+    assert table[FileType.MARKDOWN](b"# t\n") == "# t\n"
+
+
+@pytest.mark.parametrize("fmt", [FileType.CSV, FileType.YAML, FileType.INI, FileType.JSONC, FileType.HTML])
+def test_default_loaders_leaves_the_rest_as_bytes(fmt: FileType) -> None:
+    assert default_loaders()[fmt](b"raw") == b"raw"  # no stdlib codec -> honest bytes
+
+
+def test_default_loaders_does_not_pick_eserde() -> None:
+    pytest.importorskip("eserde")  # e-serde is optional: the default must ignore it, even when installed
+    assert default_loaders()[FileType.JSONC](b'{"a": 1}') == b'{"a": 1}'
+
+
+@pytest.mark.parametrize(
+    ("fmt", "blob", "want"),
+    [
+        (FileType.JSON, b'{"a": 1}', {"a": 1}),
+        (FileType.JSONC, b'{"a": 1 /* c */}', {"a": 1}),
+        (FileType.INI, b"[s]\nk = v\n", {"s": {"k": "v"}}),
+        (FileType.TOML, b"a = 1\n", {"a": 1}),
+        (FileType.YAML, b"a: 1\n", {"a": 1}),
+    ],
+)
+def test_eserde_loaders_decodes_config_kinds(fmt: FileType, blob: bytes, want: dict) -> None:
+    pytest.importorskip("eserde")
+    assert eserde_loaders()[fmt](blob) == want
+
+
+def test_eserde_loaders_requires_the_extra(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setitem(sys.modules, "eserde", None)  # forces the ImportError path
+    with pytest.raises(ExtraNotInstalledError) as exc:
+        eserde_loaders()
+    assert "pytest-resources[serde]" in str(exc.value)
+    assert "uv add" in str(exc.value)
+
+
+def test_eserde_loaders_is_importable_without_calling_it() -> None:
+    assert callable(eserde_loaders)  # importing loaders must not import e-serde eagerly
+
+
+def test_lines_splits_and_decodes_per_line() -> None:
+    assert _lines(json.loads, b'{"i": 1}\n\n{"i": 2}\n') == [{"i": 1}, {"i": 2}]
+
+
+def test_text_and_raw_helpers() -> None:
+    assert _text("café".encode()) == "café"
+    assert _raw(b"x") == b"x"

{pytest_resources-0.2.2 → pytest_resources-0.3.0}/tests/unit/test_plugin.py

@@ -35,7 +35,7 @@ def test_resources_fixture_is_indexed_tree(resources: Resources) -> None:
     assert isinstance(resources, pr.Resources)
     assert resources.structured.sample["id"] == "sample1"
     assert resources.config.settings["owner"]["name"] == "damien"
-    assert resources.config.manifest == {"ok": True, "retries": 3}
+    assert isinstance(resources.config.manifest, bytes)  # JSONC has no stdlib codec -> bytes by default
     assert isinstance(resources.unstructured.sample, str)
 
 

{pytest_resources-0.2.2 → pytest_resources-0.3.0}/tests/unit/test_synth.py

@@ -39,7 +39,7 @@ def test_synth_file_without_files_explains_the_extra(monkeypatch: pytest.MonkeyP
         provider.file(FileType.PDF)
     msg = str(excinfo.value)
     assert "pytest-resources[files]" in msg
-    assert "pip install" in msg
+    assert "uv add" in msg
     assert "faker-file" in msg
     assert "file" in msg
 

pytest_resources-0.2.2/tests/unit/test_loaders.py

@@ -1,59 +0,0 @@
-"""tests/unit: the pluggable loader table and its e-serde / stdlib backends."""
-
-import json
-import sys
-
-import pytest
-
-from pytest_resources import FileType
-from pytest_resources.loaders import _lines, _raw, _text, default_loaders
-
-
-def test_default_loaders_covers_every_kind() -> None:
-    assert set(default_loaders()) == set(FileType)
-
-
-def test_json_kind_decodes_to_native_dict() -> None:
-    assert default_loaders()[FileType.JSON](b'{"a": 1, "b": [1, 2]}') == {"a": 1, "b": [1, 2]}
-
-
-def test_text_and_markdown_decode_to_str() -> None:
-    table = default_loaders()
-    assert table[FileType.TEXT](b"hi") == "hi"
-    assert isinstance(table[FileType.MARKDOWN](b"# t\n"), str)
-
-
-def test_unbound_kind_hands_back_raw_bytes() -> None:
-    assert default_loaders()[FileType.CSV](b"a,b") == b"a,b"
-    assert _raw(b"x") == b"x"
-
-
-def test_lines_splits_and_decodes_per_line() -> None:
-    assert _lines(json.loads, b'{"i": 1}\n\n{"i": 2}\n') == [{"i": 1}, {"i": 2}]
-
-
-def test_text_helper_decodes_utf8() -> None:
-    assert _text("café".encode()) == "café"
-
-
-def test_stdlib_fallback_when_eserde_absent(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setitem(sys.modules, "eserde", None)  # forces ImportError inside default_loaders
-    table = default_loaders()
-    assert table[FileType.JSON](b'{"a": 1}') == {"a": 1}
-    assert table[FileType.TOML](b"a = 1\n") == {"a": 1}
-    assert table[FileType.NDJSON](b'{"i": 1}\n{"i": 2}') == [{"i": 1}, {"i": 2}]
-    assert table[FileType.INI](b"[s]\nk=v") == b"[s]\nk=v"  # not a stdlib codec -> bytes
-
-
-@pytest.mark.parametrize(
-    ("fmt", "blob", "want"),
-    [
-        (FileType.JSONC, b'{"a": 1 /* c */}', {"a": 1}),
-        (FileType.INI, b"[s]\nk = v\n", {"s": {"k": "v"}}),
-        (FileType.TOML, b"a = 1\n", {"a": 1}),
-        (FileType.YAML, b"a: 1\n", {"a": 1}),
-    ],
-)
-def test_eserde_native_config_kinds(fmt: FileType, blob: bytes, want: dict) -> None:
-    pytest.importorskip("eserde")
-    assert default_loaders()[fmt](blob) == want