loremfile 0.2.0__tar.gz → 0.3.1__tar.gz

{loremfile-0.2.0 → loremfile-0.3.1}/PKG-INFO

@@ -1,18 +1,19 @@
 Metadata-Version: 2.4
 Name: loremfile
-Version: 0.2.0
+Version: 0.3.1
 Summary: Download CC0 sample files from loremfile.dev and verify every byte
 Author: the loremfile.dev contributors
 License-Expression: MIT
 Project-URL: Homepage, https://loremfile.dev
 Project-URL: Source, https://github.com/kumarprabhashanand/loremfile
 Project-URL: Issues, https://github.com/kumarprabhashanand/loremfile/issues
-Keywords: fixtures,test-data,sample-files,cc0,download,mcp
+Keywords: fixtures,test-data,sample-files,cc0,download,mcp,pytest
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: Pytest
 Classifier: Environment :: Console
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -45,11 +46,35 @@ correctly by default: every file is verified, and a file that fails is not writt
 
 Every command takes `--json` for scripts, `--quiet`, and `--catalog-version X.Y.Z` to
 refuse to run if loremfile.dev has moved on. `get` also takes `--force` (overwrite) and
-`--dry-run` (what it would fetch, and how many bytes).
+`--dry-run` (what it would fetch, and how many bytes). `get`, `list` and `verify` leave out the
+`sample.{format}` aliases, which repeat another file's bytes, unless you pass `--include-aliases`;
+a path you name is always fetched.
 
 Exit codes: `0` fine, `1` a file failed verification or is missing, `2` the request was
 wrong, `3` loremfile.dev could not be read.
 
+## In a pytest suite
+
+For files too big to commit: multi-megabyte video, audio and archives that would otherwise
+bloat a repository. Installing the client gives pytest a `loremfile` fixture:
+
+```python
+def test_reads_a_real_mp4(loremfile):
+    video = loremfile("mp4/10mb.mp4")  # a pathlib.Path
+    ...
+```
+
+The first call downloads the file into `.pytest_cache` and checks its SHA-256 against the
+manifest; a file that does not match is never returned. Published files never change at
+their path, so after that the file and its manifest entry are reused and the suite needs no
+network for them. In CI, cache `.pytest_cache/d/loremfile` between runs to keep it that way;
+`pytest --cache-clear` starts over.
+
+It is not for every suite. If your tests may not touch the network, or the file you need is
+a 4 KB PDF, commit the file: that is simpler and needs nothing from us. The fixture takes a
+path only (`loremfile list` finds one), needs pytest 8.0 or newer, and does nothing until a
+test asks for it.
+
 ## MCP server
 
 <!-- mcp-name: io.github.kumarprabhashanand/loremfile -->
@@ -94,7 +119,7 @@ oldest CPython still receiving security fixes when a release is cut; a new one i
 supported within six weeks of its release, and an end-of-life one is dropped in the next
 minor release.
 
-Zero dependencies — standard library only.
+Zero dependencies: standard library only.
 
 ## In GitHub Actions, prefer the action
 
@@ -105,15 +130,15 @@ Zero dependencies — standard library only.
 ```
 
 It is shell only and needs no install step. This client is for everywhere else: a laptop,
-a Makefile, a CI system that is not Actions, or Windows — which the action does not
+a Makefile, a CI system that is not Actions, or Windows, which the action does not
 support because it needs `sha256sum`.
 
 ## One name, two tools
 
 The console script installed here is `loremfile`, which is also the name of the
 repository's own development CLI (the one that generates and publishes the fixtures).
-They are never installed together — that tool lives only inside the project's toolchain
-image — but a contributor who installs both into one environment gets whichever was
+They are never installed together (that tool lives only inside the project's toolchain
+image), but a contributor who installs both into one environment gets whichever was
 installed last. The published package contains the client only: no generators, no
 validators, no uploader, no infrastructure code.
 

{loremfile-0.2.0 → loremfile-0.3.1}/README.md

@@ -26,11 +26,35 @@ correctly by default: every file is verified, and a file that fails is not writt
 
 Every command takes `--json` for scripts, `--quiet`, and `--catalog-version X.Y.Z` to
 refuse to run if loremfile.dev has moved on. `get` also takes `--force` (overwrite) and
-`--dry-run` (what it would fetch, and how many bytes).
+`--dry-run` (what it would fetch, and how many bytes). `get`, `list` and `verify` leave out the
+`sample.{format}` aliases, which repeat another file's bytes, unless you pass `--include-aliases`;
+a path you name is always fetched.
 
 Exit codes: `0` fine, `1` a file failed verification or is missing, `2` the request was
 wrong, `3` loremfile.dev could not be read.
 
+## In a pytest suite
+
+For files too big to commit: multi-megabyte video, audio and archives that would otherwise
+bloat a repository. Installing the client gives pytest a `loremfile` fixture:
+
+```python
+def test_reads_a_real_mp4(loremfile):
+    video = loremfile("mp4/10mb.mp4")  # a pathlib.Path
+    ...
+```
+
+The first call downloads the file into `.pytest_cache` and checks its SHA-256 against the
+manifest; a file that does not match is never returned. Published files never change at
+their path, so after that the file and its manifest entry are reused and the suite needs no
+network for them. In CI, cache `.pytest_cache/d/loremfile` between runs to keep it that way;
+`pytest --cache-clear` starts over.
+
+It is not for every suite. If your tests may not touch the network, or the file you need is
+a 4 KB PDF, commit the file: that is simpler and needs nothing from us. The fixture takes a
+path only (`loremfile list` finds one), needs pytest 8.0 or newer, and does nothing until a
+test asks for it.
+
 ## MCP server
 
 <!-- mcp-name: io.github.kumarprabhashanand/loremfile -->
@@ -75,7 +99,7 @@ oldest CPython still receiving security fixes when a release is cut; a new one i
 supported within six weeks of its release, and an end-of-life one is dropped in the next
 minor release.
 
-Zero dependencies — standard library only.
+Zero dependencies: standard library only.
 
 ## In GitHub Actions, prefer the action
 
@@ -86,15 +110,15 @@ Zero dependencies — standard library only.
 ```
 
 It is shell only and needs no install step. This client is for everywhere else: a laptop,
-a Makefile, a CI system that is not Actions, or Windows — which the action does not
+a Makefile, a CI system that is not Actions, or Windows, which the action does not
 support because it needs `sha256sum`.
 
 ## One name, two tools
 
 The console script installed here is `loremfile`, which is also the name of the
 repository's own development CLI (the one that generates and publishes the fixtures).
-They are never installed together — that tool lives only inside the project's toolchain
-image — but a contributor who installs both into one environment gets whichever was
+They are never installed together (that tool lives only inside the project's toolchain
+image), but a contributor who installs both into one environment gets whichever was
 installed last. The published package contains the client only: no generators, no
 validators, no uploader, no infrastructure code.
 

{loremfile-0.2.0 → loremfile-0.3.1}/pyproject.toml

@@ -11,7 +11,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loremfile"
-version = "0.2.0"
+version = "0.3.1"
 description = "Download CC0 sample files from loremfile.dev and verify every byte"
 readme = "README.md"
 # A range, and a policy: the floor is the oldest CPython still receiving security fixes
@@ -21,13 +21,14 @@ readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
 authors = [{ name = "the loremfile.dev contributors" }]
-keywords = ["fixtures", "test-data", "sample-files", "cc0", "download", "mcp"]
+keywords = ["fixtures", "test-data", "sample-files", "cc0", "download", "mcp", "pytest"]
 classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Testing",
+  "Framework :: Pytest",
   "Environment :: Console",
 ]
 # Deliberately empty, and a decision rather than an omission: the client is standard
@@ -37,6 +38,11 @@ dependencies = []
 [project.scripts]
 loremfile = "loremfile_client.cli:main"
 
+# The `loremfile` fixture. pytest loads this in every run where the client is installed,
+# so the module does nothing until a test asks for the fixture (tests/test_pytest_plugin.py).
+[project.entry-points.pytest11]
+loremfile = "loremfile_client.pytest_plugin"
+
 [project.urls]
 Homepage = "https://loremfile.dev"
 Source = "https://github.com/kumarprabhashanand/loremfile"

{loremfile-0.2.0 → loremfile-0.3.1}/src/loremfile.egg-info/PKG-INFO

@@ -1,18 +1,19 @@
 Metadata-Version: 2.4
 Name: loremfile
-Version: 0.2.0
+Version: 0.3.1
 Summary: Download CC0 sample files from loremfile.dev and verify every byte
 Author: the loremfile.dev contributors
 License-Expression: MIT
 Project-URL: Homepage, https://loremfile.dev
 Project-URL: Source, https://github.com/kumarprabhashanand/loremfile
 Project-URL: Issues, https://github.com/kumarprabhashanand/loremfile/issues
-Keywords: fixtures,test-data,sample-files,cc0,download,mcp
+Keywords: fixtures,test-data,sample-files,cc0,download,mcp,pytest
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: Pytest
 Classifier: Environment :: Console
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -45,11 +46,35 @@ correctly by default: every file is verified, and a file that fails is not writt
 
 Every command takes `--json` for scripts, `--quiet`, and `--catalog-version X.Y.Z` to
 refuse to run if loremfile.dev has moved on. `get` also takes `--force` (overwrite) and
-`--dry-run` (what it would fetch, and how many bytes).
+`--dry-run` (what it would fetch, and how many bytes). `get`, `list` and `verify` leave out the
+`sample.{format}` aliases, which repeat another file's bytes, unless you pass `--include-aliases`;
+a path you name is always fetched.
 
 Exit codes: `0` fine, `1` a file failed verification or is missing, `2` the request was
 wrong, `3` loremfile.dev could not be read.
 
+## In a pytest suite
+
+For files too big to commit: multi-megabyte video, audio and archives that would otherwise
+bloat a repository. Installing the client gives pytest a `loremfile` fixture:
+
+```python
+def test_reads_a_real_mp4(loremfile):
+    video = loremfile("mp4/10mb.mp4")  # a pathlib.Path
+    ...
+```
+
+The first call downloads the file into `.pytest_cache` and checks its SHA-256 against the
+manifest; a file that does not match is never returned. Published files never change at
+their path, so after that the file and its manifest entry are reused and the suite needs no
+network for them. In CI, cache `.pytest_cache/d/loremfile` between runs to keep it that way;
+`pytest --cache-clear` starts over.
+
+It is not for every suite. If your tests may not touch the network, or the file you need is
+a 4 KB PDF, commit the file: that is simpler and needs nothing from us. The fixture takes a
+path only (`loremfile list` finds one), needs pytest 8.0 or newer, and does nothing until a
+test asks for it.
+
 ## MCP server
 
 <!-- mcp-name: io.github.kumarprabhashanand/loremfile -->
@@ -94,7 +119,7 @@ oldest CPython still receiving security fixes when a release is cut; a new one i
 supported within six weeks of its release, and an end-of-life one is dropped in the next
 minor release.
 
-Zero dependencies — standard library only.
+Zero dependencies: standard library only.
 
 ## In GitHub Actions, prefer the action
 
@@ -105,15 +130,15 @@ Zero dependencies — standard library only.
 ```
 
 It is shell only and needs no install step. This client is for everywhere else: a laptop,
-a Makefile, a CI system that is not Actions, or Windows — which the action does not
+a Makefile, a CI system that is not Actions, or Windows, which the action does not
 support because it needs `sha256sum`.
 
 ## One name, two tools
 
 The console script installed here is `loremfile`, which is also the name of the
 repository's own development CLI (the one that generates and publishes the fixtures).
-They are never installed together — that tool lives only inside the project's toolchain
-image — but a contributor who installs both into one environment gets whichever was
+They are never installed together (that tool lives only inside the project's toolchain
+image), but a contributor who installs both into one environment gets whichever was
 installed last. The published package contains the client only: no generators, no
 validators, no uploader, no infrastructure code.
 

{loremfile-0.2.0 → loremfile-0.3.1}/src/loremfile.egg-info/SOURCES.txt

@@ -10,8 +10,10 @@ src/loremfile_client/__main__.py
 src/loremfile_client/api.py
 src/loremfile_client/cli.py
 src/loremfile_client/mcp.py
+src/loremfile_client/pytest_plugin.py
 src/loremfile_client/tools.json
 tests/test_commands.py
 tests/test_mcp.py
 tests/test_only_loremfile_dev.py
-tests/test_packaging.py
+tests/test_packaging.py
+tests/test_pytest_plugin.py

{loremfile-0.2.0 → loremfile-0.3.1}/src/loremfile.egg-info/entry_points.txt

@@ -1,2 +1,5 @@
 [console_scripts]
 loremfile = loremfile_client.cli:main
+
+[pytest11]
+loremfile = loremfile_client.pytest_plugin

{loremfile-0.2.0 → loremfile-0.3.1}/src/loremfile_client/__init__.py

@@ -1,3 +1,3 @@
 """A small client for loremfile.dev: download CC0 sample files and verify every byte."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"

{loremfile-0.2.0 → loremfile-0.3.1}/src/loremfile_client/api.py

@@ -153,13 +153,28 @@ def active(document: dict[str, Any]) -> list[dict[str, Any]]:
     return [e for e in document.get("fixtures", []) if e.get("status", "active") == "active"]
 
 
+#: A `sample.{format}` alias is a second URL for bytes that already have one. Its manifest entry is
+#: the only place that says so, and the field that does is `generator`; its original is
+#: `generator_params.of`. (`aliasOf`, which 1.15.0 carried until 1.15.1, matches nothing.)
+ALIAS_GENERATOR = "alias.copy"
+
+
+def is_alias(entry: dict[str, Any]) -> bool:
+    return entry.get("generator") == ALIAS_GENERATOR
+
+
 def select(
     entries: list[dict[str, Any]],
     *,
     paths: list[str] | None = None,
     formats: list[str] | None = None,
+    include_aliases: bool = False,
 ) -> list[dict[str, Any]]:
-    """The entries a request names, or `Refused` naming what does not exist."""
+    """The entries a request names, or `Refused` naming what does not exist.
+
+    A format selects its files, not the aliases that repeat them, unless `include_aliases`; a
+    path that is named is always honoured, alias or not.
+    """
     wanted_paths, wanted_formats = set(paths or []), set(formats or [])
     if not wanted_paths and not wanted_formats:
         raise Refused("name at least one path or format")
@@ -172,7 +187,10 @@ def select(
     if unknown_formats:
         raise Refused(f"no such format: {', '.join(unknown_formats)}")
     chosen = {
-        e["path"]: e for e in entries if e["path"] in wanted_paths or e["format"] in wanted_formats
+        e["path"]: e
+        for e in entries
+        if e["path"] in wanted_paths
+        or (e["format"] in wanted_formats and (include_aliases or not is_alias(e)))
     }
     return [chosen[path] for path in sorted(chosen)]
 

{loremfile-0.2.0 → loremfile-0.3.1}/src/loremfile_client/cli.py

@@ -29,6 +29,13 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--version", action="version", version=f"loremfile {__version__}")
     subcommands = parser.add_subparsers(dest="command", required=True)
 
+    def aliases(sub: argparse.ArgumentParser) -> None:
+        sub.add_argument(
+            "--include-aliases",
+            action="store_true",
+            help="Also the sample.{format} copies, which repeat another file's bytes.",
+        )
+
     def shared(sub: argparse.ArgumentParser) -> None:
         sub.add_argument("--json", action="store_true", help="Print one JSON object.")
         sub.add_argument("--quiet", action="store_true", help="Print nothing but failures.")
@@ -50,18 +57,21 @@ def build_parser() -> argparse.ArgumentParser:
     get.add_argument("--dest", default=DEFAULT_DEST, type=Path, help=f"Default: {DEFAULT_DEST}")
     get.add_argument("--force", action="store_true", help="Overwrite files already there.")
     get.add_argument("--dry-run", action="store_true", help="List what would be fetched.")
+    aliases(get)
     shared(get)
 
     listing = subcommands.add_parser("list", help="What is published, without downloading.")
     listing.add_argument("--format", action="append", default=[], metavar="FMT")
     listing.add_argument("--tag", action="append", default=[], metavar="TAG")
     listing.add_argument("--max-bytes", type=int, metavar="N")
+    aliases(listing)
     shared(listing)
 
     check = subcommands.add_parser("verify", help="Check files on disk against the manifest.")
     check.add_argument("paths", nargs="*", metavar="PATH")
     check.add_argument("--format", action="append", default=[], metavar="FMT")
     check.add_argument("--dest", default=DEFAULT_DEST, type=Path, help=f"Default: {DEFAULT_DEST}")
+    aliases(check)
     shared(check)
 
     subcommands.add_parser(
@@ -88,6 +98,7 @@ def run_get(args: argparse.Namespace) -> int:
         api.active(api.manifest(catalog_version=args.catalog_version)),
         paths=args.paths,
         formats=args.format,
+        include_aliases=args.include_aliases,
     )
     if args.dry_run:
         total = sum(e["bytes"] for e in entries)
@@ -108,6 +119,8 @@ def run_get(args: argparse.Namespace) -> int:
 
 def run_list(args: argparse.Namespace) -> int:
     entries = api.active(api.manifest(catalog_version=args.catalog_version))
+    if not args.include_aliases:
+        entries = [e for e in entries if not api.is_alias(e)]
     if args.format:
         entries = [e for e in entries if e["format"] in set(args.format)]
     if args.tag:
@@ -124,9 +137,12 @@ def run_list(args: argparse.Namespace) -> int:
 def run_verify(args: argparse.Namespace) -> int:
     entries = api.active(api.manifest(catalog_version=args.catalog_version))
     if args.paths or args.format:
-        entries = api.select(entries, paths=args.paths, formats=args.format)
+        entries = api.select(
+            entries, paths=args.paths, formats=args.format, include_aliases=args.include_aliases
+        )
     else:
-        # Everything the destination actually holds, so `verify` alone checks a directory.
+        # Everything the destination actually holds, so `verify` alone checks a directory,
+        # aliases included: a copy that is on disk was put there on purpose.
         entries = [e for e in entries if (args.dest / Path(e["path"])).is_file()]
     results = [api.verify(entry, args.dest) for entry in entries]
     failing = [r for r in results if not r.ok]

{loremfile-0.2.0 → loremfile-0.3.1}/src/loremfile_client/mcp.py

@@ -148,12 +148,15 @@ def list_fixtures(document: dict[str, Any], args: Any) -> dict[str, Any]:  # noq
         args.get("limit", MISSING), "limit", low=1, high=MAX_LIMIT, fallback=DEFAULT_LIMIT
     )
     offset = _integer(args.get("offset", MISSING), "offset", low=0, high=None, fallback=0)
-    # The same filters as `loremfile list`: any of the formats, any of the tags, all three.
+    # The same filters as `loremfile list`: any of the formats, any of the tags, all three. The
+    # sample.{format} aliases repeat another file's bytes and stay out; describe_fixture and
+    # verify_file still take one by path.
     matches = sorted(
         (
             e
             for e in api.active(document)
-            if (not formats or e["format"] in formats)
+            if not api.is_alias(e)
+            and (not formats or e["format"] in formats)
             and (not tags or set(tags) & set(e.get("tags") or []))
             and (max_bytes is None or e["bytes"] <= max_bytes)
         ),

loremfile-0.3.1/src/loremfile_client/pytest_plugin.py

@@ -0,0 +1,110 @@
+"""The `loremfile` pytest fixture: a published file, verified, as a local path.
+
+pytest imports this module through the `pytest11` entry point in every run where the
+client is installed, whether or not a test asks for the fixture. So importing it does
+nothing: no network, no files, no hooks, no options. All the work happens the first time
+a test calls the fixture, and `tests/test_pytest_plugin.py` holds that as a test.
+
+Published files never change at their path, so a cached file and its cached manifest entry
+are final. The manifest is fetched again only for a path the cached copy does not list,
+and once that cache is filled a suite runs without the network.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from loremfile_client import api
+
+
+class Files:
+    """One session's fetcher over a cache directory. Called with a path, returns a file."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.files = root / "files"
+        self.cached_manifest = root / "manifest.json"
+        self.entries: dict[str, dict[str, Any]] | None = None
+        self.refreshed = False
+        self.downloads = 0
+        self.ready: dict[str, Path] = {}
+
+    def __call__(self, path: str) -> Path:
+        if path in self.ready:
+            return self.ready[path]
+        entry = self.entry(path)
+        if not api.verify(entry, self.files).ok:
+            self.download(entry)
+        local = api.target(self.files, path)
+        self.ready[path] = local
+        return local
+
+    def entry(self, path: str) -> dict[str, Any]:
+        if self.entries is None:
+            self.entries = self.read_cached()
+        if path not in self.entries and not self.refreshed:
+            self.entries = self.refresh()
+        # `select` is the CLI's own refusal, so an unknown or removed path reads the same.
+        return api.select(list(self.entries.values()), paths=[path])[0]
+
+    def read_cached(self) -> dict[str, dict[str, Any]]:
+        try:
+            document = json.loads(self.cached_manifest.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return {}
+        return {e["path"]: e for e in api.active(document)}
+
+    def refresh(self) -> dict[str, dict[str, Any]]:
+        document = api.manifest()
+        self.refreshed = True
+        try:  # noqa: SIM105 - contextlib would be a new import for one line
+            self.write_cached(document)
+        except OSError:
+            pass  # only the next session pays: this one has the document in memory
+        return {e["path"]: e for e in api.active(document)}
+
+    def write_cached(self, document: dict[str, Any]) -> None:
+        """Written beside its final name and renamed, so a parallel worker never reads half."""
+        self.root.mkdir(parents=True, exist_ok=True)
+        handle = tempfile.NamedTemporaryFile(  # noqa: SIM115 - closed by the `with` below
+            "w", dir=self.root, suffix=".part", delete=False, encoding="utf-8"
+        )
+        partial = Path(handle.name)
+        try:
+            with handle:
+                json.dump(document, handle)
+            partial.replace(self.cached_manifest)
+        finally:
+            partial.unlink(missing_ok=True)
+
+    def download(self, entry: dict[str, Any]) -> None:
+        if self.downloads:
+            api.pace()
+        self.downloads += 1
+        try:
+            api.download(entry, self.files, force=True)
+        except OSError:
+            # On Windows the final rename fails while another xdist worker has the file
+            # open. If that worker already put the verified bytes there, they are ours too.
+            if not api.verify(entry, self.files).ok:
+                raise
+
+
+@pytest.fixture(scope="session")
+def loremfile(
+    pytestconfig: pytest.Config, tmp_path_factory: pytest.TempPathFactory
+) -> Callable[[str], Path]:
+    """loremfile(path) -> Path: a loremfile.dev file, checked against its published SHA-256.
+
+    Cached in .pytest_cache, so each file is downloaded once; `--cache-clear` starts over.
+    """
+    # `-p no:cacheprovider` removes the attribute itself; a file then lasts one session.
+    cache = getattr(pytestconfig, "cache", None)
+    root = cache.mkdir("loremfile") if cache is not None else tmp_path_factory.mktemp("loremfile")
+    return Files(root)

{loremfile-0.2.0 → loremfile-0.3.1}/tests/test_commands.py

@@ -10,7 +10,7 @@ from pathlib import Path
 import pytest
 from loremfile_client import api, cli
 
-from conftest import BODIES, Handler
+from conftest import ALIASES, BODIES, MANIFEST, Handler
 
 
 def run(*argv: str) -> int:
@@ -28,6 +28,80 @@ def test_get_by_format_takes_every_file_of_it(server: str, dest: Path) -> None:
     assert sorted(p.name for p in (dest / "pdf").iterdir()) == ["other.pdf", "small.pdf"]
 
 
+def test_the_fake_manifest_carries_an_alias_the_way_the_real_one_does() -> None:
+    """Control for the tests below: they mean nothing if the alias is not really there."""
+    aliases = [e for e in MANIFEST["fixtures"] if e.get("generator") == "alias.copy"]
+    assert [e["path"] for e in aliases] == list(ALIASES) == ["pdf/sample.pdf"]
+    assert aliases[0]["generator_params"] == {"of": "pdf/small.pdf"}
+    assert "aliasOf" not in aliases[0], "docs/04 §1.4: there is no such field"
+    assert aliases[0]["sha256"] == next(
+        e["sha256"] for e in MANIFEST["fixtures"] if e["path"] == "pdf/small.pdf"
+    )
+
+
+def test_get_by_format_leaves_the_aliases_out_unless_asked(server: str, dest: Path) -> None:
+    assert run("get", "--format", "pdf", "--dest", str(dest)) == cli.OK
+    assert not (dest / "pdf" / "sample.pdf").exists()
+    assert run("get", "--format", "pdf", "--include-aliases", "--dest", str(dest)) == cli.OK
+    assert (dest / "pdf" / "sample.pdf").read_bytes() == BODIES["pdf/small.pdf"]
+
+
+def test_a_dry_run_counts_the_bytes_it_would_fetch_without_the_duplicate(
+    server: str, capsys: pytest.CaptureFixture
+) -> None:
+    run("get", "--format", "pdf", "--dry-run", "--json")
+    without = json.loads(capsys.readouterr().out)["summary"]
+    run("get", "--format", "pdf", "--include-aliases", "--dry-run", "--json")
+    with_aliases = json.loads(capsys.readouterr().out)["summary"]
+    assert (without["files"], with_aliases["files"]) == (2, 3)
+    assert with_aliases["bytes"] - without["bytes"] == len(BODIES["pdf/small.pdf"])
+
+
+def test_a_path_named_outright_is_fetched_even_when_it_is_an_alias(server: str, dest: Path) -> None:
+    assert run("get", "pdf/sample.pdf", "--dest", str(dest)) == cli.OK
+    assert (dest / "pdf" / "sample.pdf").read_bytes() == BODIES["pdf/small.pdf"]
+
+
+def test_filtering_on_the_field_the_manifest_does_not_have_would_match_nothing() -> None:
+    """The mistake the 1.15.1 brief warns about, made on purpose: `aliasOf` finds no alias."""
+    entries = api.active(MANIFEST)
+    assert [e["path"] for e in entries if "aliasOf" in e] == []
+    assert [e["path"] for e in entries if api.is_alias(e)] == ["pdf/sample.pdf"]
+
+
+def test_list_leaves_the_aliases_out_unless_asked(
+    server: str, capsys: pytest.CaptureFixture
+) -> None:
+    def listed(*argv: str) -> set[str]:
+        run("list", *argv, "--json")
+        return {item["path"] for item in json.loads(capsys.readouterr().out)["items"]}
+
+    assert "pdf/sample.pdf" not in listed()
+    assert "pdf/sample.pdf" not in listed("--format", "pdf")
+    assert "pdf/sample.pdf" in listed("--format", "pdf", "--include-aliases")
+    assert listed("--include-aliases") == listed() | set(ALIASES)
+
+
+def test_verify_checks_an_alias_that_is_on_disk_and_by_format_only_with_the_flag(
+    server: str, dest: Path
+) -> None:
+    assert run("get", "pdf/sample.pdf", "--dest", str(dest)) == cli.OK
+    assert run("verify", "--dest", str(dest)) == cli.OK
+    (dest / "pdf" / "sample.pdf").write_bytes(b"not what was published")
+    assert run("verify", "--dest", str(dest)) == cli.FAILED, "a held alias is checked"
+    assert run("verify", "--format", "pdf", "--dest", str(dest)) == cli.FAILED, (
+        "small.pdf and other.pdf are missing"
+    )
+    (dest / "pdf" / "small.pdf").write_bytes(BODIES["pdf/small.pdf"])
+    (dest / "pdf" / "other.pdf").write_bytes(BODIES["pdf/other.pdf"])
+    assert run("verify", "--format", "pdf", "--dest", str(dest)) == cli.OK, (
+        "the bad alias is skipped"
+    )
+    assert (
+        run("verify", "--format", "pdf", "--include-aliases", "--dest", str(dest)) == cli.FAILED
+    ), "and asked for, it is checked"
+
+
 def test_a_withdrawn_entry_is_not_offered(server: str, dest: Path) -> None:
     assert run("get", "pdf/withdrawn.pdf", "--dest", str(dest)) == cli.REFUSED
 

{loremfile-0.2.0 → loremfile-0.3.1}/tests/test_mcp.py

@@ -232,6 +232,16 @@ def test_list_fixtures_pages_and_says_where_it_is(child: Client, server: str) ->
     assert (last["count"], last["next_offset"]) == (1, None)
 
 
+def test_list_fixtures_leaves_the_sample_aliases_out_and_describe_still_finds_one(
+    child: Client,
+) -> None:
+    listed = child.call("list_fixtures", {"format": ["pdf"]})["structuredContent"]
+    assert [f["path"] for f in listed["fixtures"]] == ["pdf/other.pdf", "pdf/small.pdf"]
+    assert listed["total"] == 2
+    described = child.call("describe_fixture", {"path": "pdf/sample.pdf"})["structuredContent"]
+    assert described["path"] == "pdf/sample.pdf", "control: the alias exists and can be asked for"
+
+
 def test_list_fixtures_filters_as_loremfile_list_does(child: Client) -> None:
     def paths(arguments: dict[str, Any]) -> list[str]:
         result = child.call("list_fixtures", arguments)["structuredContent"]

{loremfile-0.2.0 → loremfile-0.3.1}/tests/test_only_loremfile_dev.py

@@ -110,10 +110,16 @@ def test_the_client_imports_nothing_but_the_standard_library() -> None:
     }
     imported: set[str] = set()
     for source in PACKAGE.glob("*.py"):
+        found: set[str] = set()
         for node in ast.walk(ast.parse(source.read_text(encoding="utf-8"))):
             if isinstance(node, ast.Import):
-                imported |= {alias.name.split(".")[0] for alias in node.names}
+                found |= {alias.name.split(".")[0] for alias in node.names}
             elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
-                imported.add(node.module.split(".")[0])
+                found.add(node.module.split(".")[0])
+        # The one exemption, by name: only pytest imports the plugin, so pytest is present.
+        if source.name == "pytest_plugin.py":
+            assert "pytest" in found, "the exemption names a module that no longer needs it"
+            found.discard("pytest")
+        imported |= found
     assert imported, "empty-set control: the scan found the imports"
     assert imported <= allowed, imported - allowed

{loremfile-0.2.0 → loremfile-0.3.1}/tests/test_packaging.py

@@ -46,6 +46,13 @@ def test_the_console_script_is_the_client_entry_point() -> None:
     assert "loremfile = loremfile_client.cli:main" in text
 
 
+def test_the_wheel_registers_the_pytest_plugin() -> None:
+    with zipfile.ZipFile(wheel()) as archive:
+        entry_points = next(n for n in archive.namelist() if n.endswith("entry_points.txt"))
+        text = archive.read(entry_points).decode()
+    assert "[pytest11]\nloremfile = loremfile_client.pytest_plugin" in text
+
+
 def test_the_wheel_carries_the_mcp_tool_surface() -> None:
     """mcp.py reads tools.json at import; a wheel without it is a server that cannot start."""
     source = CLIENT / "src" / "loremfile_client" / "tools.json"

loremfile-0.3.1/tests/test_pytest_plugin.py

@@ -0,0 +1,234 @@
+"""The `loremfile` fixture: what it returns, when it needs the network, and that it is inert.
+
+pytest loads the plugin in every run where the client is installed, so the property that
+matters most is the one nobody would notice breaking: a suite that never asks for the
+fixture must not pay for it. The subprocess tests below run a real pytest with the socket
+module refused, and each has a control that watches the same guard catch the plugin.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from importlib import metadata
+from pathlib import Path
+from typing import Any
+
+import pytest
+from loremfile_client import api, pytest_plugin
+from loremfile_client.pytest_plugin import Files
+
+from conftest import BODIES, Handler
+
+SMALL = BODIES["pdf/small.pdf"]
+
+
+class NetworkUsed(Exception):
+    pass
+
+
+def no_network(path: str) -> Any:
+    raise NetworkUsed(path)
+
+
+def test_a_file_arrives_verified_at_a_path(server: str, tmp_path: Path) -> None:
+    local = Files(tmp_path / "cache")("pdf/small.pdf")
+    assert local == (tmp_path / "cache" / "files" / "pdf" / "small.pdf").resolve()
+    assert local.read_bytes() == SMALL
+
+
+def test_a_filled_cache_needs_no_network(
+    server: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    Files(tmp_path / "cache")("pdf/small.pdf")
+    monkeypatch.setattr(api, "_open", no_network)
+    assert Files(tmp_path / "cache")("pdf/small.pdf").read_bytes() == SMALL
+
+
+def test_control_an_empty_cache_does_need_it(
+    server: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(api, "_open", no_network)
+    with pytest.raises(NetworkUsed):
+        Files(tmp_path / "cache")("pdf/small.pdf")
+
+
+def test_a_path_the_cached_copy_lacks_refreshes_it_once(
+    server: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    root = tmp_path / "cache"
+    Files(root)("pdf/small.pdf")
+    # A cached copy from before svg/square.svg was published.
+    document = json.loads((root / "manifest.json").read_text(encoding="utf-8"))
+    document["fixtures"] = [e for e in document["fixtures"] if e["path"] != "svg/square.svg"]
+    (root / "manifest.json").write_text(json.dumps(document), encoding="utf-8")
+    fetched: list[int] = []
+    real = api.manifest
+    monkeypatch.setattr(api, "manifest", lambda **kw: fetched.append(1) or real(**kw))
+
+    get = Files(root)
+    assert get("svg/square.svg").read_bytes() == BODIES["svg/square.svg"]
+    with pytest.raises(api.Refused, match=re.escape("not published: pdf/not-real.pdf")):
+        get("pdf/not-real.pdf")
+    assert fetched == [1]
+
+
+@pytest.mark.parametrize("path", ["pdf/not-real.pdf", "pdf/withdrawn.pdf"])
+def test_an_unpublished_or_removed_path_is_refused(server: str, tmp_path: Path, path: str) -> None:
+    with pytest.raises(api.Refused, match=re.escape(f"not published: {path}")):
+        Files(tmp_path / "cache")(path)
+
+
+def test_bytes_that_do_not_match_are_never_returned(server: str, tmp_path: Path) -> None:
+    Handler.corrupt = {"pdf/small.pdf"}
+    with pytest.raises(api.Mismatch):
+        Files(tmp_path / "cache")("pdf/small.pdf")
+    assert not (tmp_path / "cache" / "files" / "pdf" / "small.pdf").exists()
+
+
+def test_a_cached_file_that_changed_is_fetched_again(server: str, tmp_path: Path) -> None:
+    root = tmp_path / "cache"
+    Files(root)("pdf/small.pdf").write_bytes(b"edited by someone")
+    assert Files(root)("pdf/small.pdf").read_bytes() == SMALL
+
+
+def test_a_rename_another_worker_won_is_accepted(
+    server: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    real = api.download
+
+    def raced(entry: dict[str, Any], dest: Path, *, force: bool = False) -> api.Result:
+        real(entry, dest, force=force)
+        raise PermissionError("the file is open in another process")
+
+    monkeypatch.setattr(api, "download", raced)
+    assert Files(tmp_path / "cache")("pdf/small.pdf").read_bytes() == SMALL
+
+
+def test_control_a_failed_rename_with_nothing_verified_is_raised(
+    server: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    def failed(entry: dict[str, Any], dest: Path, *, force: bool = False) -> api.Result:
+        raise PermissionError("the file is open in another process")
+
+    monkeypatch.setattr(api, "download", failed)
+    with pytest.raises(PermissionError):
+        Files(tmp_path / "cache")("pdf/small.pdf")
+
+
+def test_the_plugin_adds_no_hooks() -> None:
+    assert [name for name in vars(pytest_plugin) if name.startswith("pytest_")] == []
+    assert callable(pytest_plugin.loremfile), "control: the module read is the plugin"
+
+
+def test_the_client_imports_without_pytest() -> None:
+    """The CLI and the MCP server must not drag pytest in; the control proves the probe sees it."""
+    probe = (
+        "import sys, {}; print(sorted(m for m in sys.modules"
+        " if m.split('.')[0] == 'pytest' or m.endswith('pytest_plugin')))"
+    )
+    client = subprocess.run(  # noqa: S603 - fixed argv, no shell
+        [sys.executable, "-c", probe.format("loremfile_client.cli, loremfile_client.mcp")],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert client.stdout.strip() == "[]"
+    control = subprocess.run(  # noqa: S603 - fixed argv, no shell
+        [sys.executable, "-c", probe.format("loremfile_client.pytest_plugin")],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert "'pytest'" in control.stdout
+
+
+# --- a real pytest, in a subprocess, with the network refused --------------------------
+
+#: Installed before pytest starts, so it is in place when the plugin is imported.
+GUARD = """
+import json, os, socket, sys
+attempts = []
+def refuse(*args, **kwargs):
+    attempts.append(repr(args[:2]))
+    raise OSError("network refused by the test")
+socket.socket.connect = refuse
+socket.create_connection = refuse
+socket.getaddrinfo = refuse
+import pytest
+code = pytest.main(sys.argv[1:])
+with open(os.environ["GUARD_LOG"], "w") as log:
+    json.dump(attempts, log)
+sys.exit(code)
+"""
+
+USES_IT = """
+def test_it(loremfile):
+    assert loremfile("pdf/small.pdf").read_bytes() == b"%PDF-1.4 pretend\\n"
+"""
+
+IGNORES_IT = """
+def test_it(request):
+    assert request.config.pluginmanager.get_plugin("loremfile") is not None
+"""
+
+
+def entry_point_installed() -> None:
+    """Fails rather than skips: an inertness test that quietly does not run proves nothing."""
+    found = [ep.value for ep in metadata.entry_points(group="pytest11") if ep.name == "loremfile"]
+    assert found == ["loremfile_client.pytest_plugin"], (
+        f"pytest11 entry points named loremfile: {found}; install the client's wheel first"
+    )
+
+
+def pytest_run(
+    where: Path, source: str, *args: str, guarded: bool = False
+) -> tuple[int, list[str]]:
+    entry_point_installed()
+    (where / "pytest.ini").write_text("[pytest]\n", encoding="utf-8")
+    (where / "test_it.py").write_text(source, encoding="utf-8")
+    log = where / "attempts.json"
+    env = {**os.environ, "GUARD_LOG": str(log)}
+    env.pop("PYTEST_DISABLE_PLUGIN_AUTOLOAD", None)
+    env.pop("PYTEST_ADDOPTS", None)
+    if guarded:
+        command = [sys.executable, "-c", GUARD, "-q", *args]
+    else:
+        command = [sys.executable, "-m", "pytest", "-q", *args]
+    done = subprocess.run(  # noqa: S603 - fixed argv, no shell
+        command, cwd=where, env=env, capture_output=True, text=True, timeout=120, check=False
+    )
+    attempts = json.loads(log.read_text(encoding="utf-8")) if guarded else []
+    assert done.returncode in (0, 1), done.stdout + done.stderr
+    return done.returncode, attempts
+
+
+def test_a_suite_that_never_asks_for_it_pays_nothing(tmp_path: Path) -> None:
+    code, attempts = pytest_run(tmp_path, IGNORES_IT, guarded=True)
+    assert (code, attempts) == (0, [])
+    assert not (tmp_path / ".pytest_cache" / "d" / "loremfile").exists()
+
+
+def test_control_the_guard_sees_the_plugin_reach_out(server: str, tmp_path: Path) -> None:
+    code, attempts = pytest_run(tmp_path, USES_IT, guarded=True)
+    assert code == 1
+    assert attempts, "the guard recorded nothing, so the test above could not have failed"
+
+
+def test_once_the_cache_is_filled_the_suite_runs_offline(server: str, tmp_path: Path) -> None:
+    assert pytest_run(tmp_path, USES_IT) == (0, [])
+    # Where the README tells CI to cache, and the path the inertness test finds absent.
+    cached = tmp_path / ".pytest_cache" / "d" / "loremfile" / "files" / "pdf" / "small.pdf"
+    assert cached.read_bytes() == SMALL
+    assert pytest_run(tmp_path, USES_IT, guarded=True) == (0, [])
+    # Control: the same offline run with the cache cleared has to reach out, and fails.
+    code, attempts = pytest_run(tmp_path, USES_IT, "--cache-clear", guarded=True)
+    assert code == 1
+    assert attempts
+
+
+def test_without_the_cache_provider_it_still_works(server: str, tmp_path: Path) -> None:
+    assert pytest_run(tmp_path, USES_IT, "-p", "no:cacheprovider") == (0, [])