pathapi 0.1.0__py3-none-any.whl

pathapi/testing/_fixtures.py

@@ -0,0 +1,83 @@
+"""The standard fixture tree and the names the contracts share."""
+
+from __future__ import annotations
+
+import errno as _errno
+
+#: The standard tree `ReadPathContract`/`PathContract` expect under `root`:
+#: relative POSIX name -> file content, or `None` for a directory.
+FIXTURE_TREE = {
+    "a.txt": "a",
+    "b.py": "b",
+    ".hidden.txt": "hidden",
+    "sub": None,
+    "sub/c.py": "c",
+    "sub/nested": None,
+    "sub/nested/d.py": "d",
+    "empty_dir": None,
+}
+
+#: What pathlib raises for a file operation (read, write, unlink) aimed at a
+#: directory: `IsADirectoryError` on Linux, `PermissionError` on Windows and
+#: (for unlink) macOS.
+DIRECTORY_ERRORS = (IsADirectoryError, PermissionError)
+
+#: errno values `rmdir()` of a non-empty directory may carry (POSIX allows
+#: either; Windows maps ERROR_DIR_NOT_EMPTY to ENOTEMPTY).
+NOT_EMPTY_ERRNOS = (_errno.ENOTEMPTY, _errno.EEXIST)
+
+
+def populate_fixture_tree(root):
+    """Create the standard contract tree (`FIXTURE_TREE`) under `root`, an
+    existing empty directory, through the path's own `mkdir()` and
+    `write_text()` -- works for any `Path` implementation (or a stdlib
+    `pathlib.Path`). Returns `root`."""
+    for name, content in FIXTURE_TREE.items():
+        path = root.joinpath(*name.split("/"))
+        if content is None:
+            path.mkdir()
+        else:
+            path.write_text(content)
+    return root
+
+
+def _rel(root, path):
+    """`path` relative to `root` as a POSIX string ("." for `root` itself).
+
+    Built from `name`/`parent` only, so it holds for implementations whose
+    `relative_to()` is missing or spells the root differently. A root URI
+    with and without its trailing "/" (`http://host` vs `http://host/`)
+    counts as the same directory."""
+    names = []
+    while path != root and str(path).rstrip("/") != str(root).rstrip("/"):
+        parent = path.parent
+        if parent == path or len(names) > 64:
+            raise AssertionError(f"{path!r} is not below {root!r}")
+        names.append(path.name)
+        path = parent
+    return "/".join(reversed(names)) or "."
+
+
+#: Names that URL-shaped or shell-shaped code tends to cut, decode or fold, stored,
+#: listed and read back exactly as written. Several pairs differ only after a cut
+#: at `#` or a percent-decode, so a backend that applies either stores one name.
+UNUSUAL_NAMES = (
+    "with space.txt",
+    "hash#one.txt",
+    "hash#two.txt",
+    "pct%41.txt",
+    "pctA.txt",
+    "100%.txt",
+    "plus+amp&eq=.txt",
+    "Mixed Case.TXT",
+)
+
+#: The same, holding `?`, which not every file system can store.
+QUESTION_MARK_NAMES = ("q?one.txt", "q?two.txt", "q?x#y%41.txt")
+
+
+def _payload():
+    """About 290 KiB holding every byte value, runs of CR and LF, and a
+    counter that makes a dropped, repeated or reordered chunk visible."""
+    block = bytes(range(256)) + b"\r\n\r\n\n\r\x00\x00\x00"
+    return b"".join(index.to_bytes(4, "big") + block for index in range(1100))

pathapi/testing/_read.py

@@ -0,0 +1,279 @@
+"""The contracts of a pure path and of a read-only path."""
+
+from __future__ import annotations
+
+import pickle
+import stat as _stat
+import pytest
+
+from ..protocols import Create, Listing, Move, Remove, Utime, supports
+
+from ._fixtures import DIRECTORY_ERRORS, _rel
+
+#: The protocol each switch defaults to asking `supports()` about.
+_SWITCH_PROTOCOLS = {
+    "supports_listing": Listing,
+    "supports_mkdir": Create,
+    "supports_delete": Remove,
+    "supports_utime": Utime,
+    "supports_rename": Move,
+}
+
+
+class PurePathContract:
+    """Contract tests for pure path (logical) operations, not requiring any I/O."""
+
+    def test_pure_basics(self, root):
+        p = root / "dir" / "file.txt"
+        assert p.name == "file.txt"
+        assert p.suffix == ".txt"
+        assert p.stem == "file"
+
+        # parent and parents
+        assert p.parent.name == "dir"
+        assert len(p.parents) >= 2
+        assert p.parents[0].name == "dir"
+
+    def test_pure_joinpath_truediv(self, root):
+        p = root / "a"
+        assert (p / "b").name == "b"
+        assert p.joinpath("b", "c").name == "c"
+
+    def test_pure_match(self, root):
+        p = root / "dir" / "file.txt"
+        assert p.match("*.txt")
+        assert not p.match("*.py")
+
+
+class ReadPathContract(PurePathContract):
+    """Contract tests for read-only path operations.
+
+    Subclasses must provide a `root` fixture pointing to a fresh directory
+    pre-populated with the standard tree -- see `populate_fixture_tree()` and
+    `FIXTURE_TREE`:
+
+    - a.txt (content: "a")
+    - b.py (content: "b")
+    - .hidden.txt (content: "hidden")
+    - sub/c.py (content: "c")
+    - sub/nested/d.py (content: "d")
+    - empty_dir/
+
+    Capability attributes (all default True; set one False only for a
+    documented gap, and the affected tests skip): `supports_listing`,
+    `supports_empty_directories`, `distinguishes_file_types`,
+    `supports_pickle`.
+    """
+
+    supports_listing = None
+    supports_empty_directories = True
+    distinguishes_file_types = True
+    supports_pickle = True
+
+    def _require(self, capability, root=None):
+        value = getattr(self, capability)
+        if value is None:
+            # Not set: the class under test says, by the protocol the switch stands for.
+            protocol = _SWITCH_PROTOCOLS.get(capability)
+            if root is not None and protocol is not None:
+                self._support(root, protocol)
+        elif not value:
+            pytest.skip(f"{type(self).__name__}.{capability} is False")
+
+    def _has(self, capability, root):
+        """Whether a switch is on: as set, else as the class under test supports it."""
+        value = getattr(self, capability)
+        if value is None:
+            return supports(root, _SWITCH_PROTOCOLS[capability])
+        return bool(value)
+
+    def _support(self, root, *protocols):
+        """Skip when the class under test does not implement a protocol the
+        test needs; the skip names it."""
+        for protocol in protocols:
+            if not supports(root, protocol):
+                pytest.skip(
+                    f"{type(root).__name__} does not support {protocol.__name__}"
+                )
+
+    def test_exists_and_types(self, root):
+        assert root.exists()
+        assert root.is_dir()
+
+        a = root / "a.txt"
+        assert a.exists()
+        assert a.is_file()
+        assert not a.is_dir()
+
+        sub = root / "sub"
+        assert sub.exists()
+        assert sub.is_dir()
+        assert not sub.is_file()
+
+        assert not (root / "nonexistent").exists()
+        assert not (root / "nonexistent").is_file()
+        assert not (root / "nonexistent").is_dir()
+
+    def test_a_pickled_path_is_equal_to_the_original(self, root):
+        # A worker process receives a path by pickle. The copy must be the
+        # same value: equal, hashing alike, and for a URI path placed on the
+        # same filesystem as the original.
+        self._require("supports_pickle")
+        path = root / "a.txt"
+        again = pickle.loads(pickle.dumps(path))
+        assert type(again) is type(path)
+        assert again == path
+        assert hash(again) == hash(path)
+        if hasattr(path, "_supplied_backend"):
+            assert again._same_filesystem(path)
+            assert path._same_filesystem(again)
+
+    def test_read_text_and_bytes(self, root):
+        assert (root / "a.txt").read_text() == "a"
+        assert (root / "a.txt").read_bytes() == b"a"
+        assert (root / "sub" / "c.py").read_text() == "c"
+        assert (root / "sub" / "nested" / "d.py").read_bytes() == b"d"
+
+    def test_open_read_modes(self, root):
+        f = root / ".hidden.txt"
+        with f.open() as fh:
+            assert fh.read() == "hidden"
+        with f.open("r") as fh:
+            assert fh.read() == "hidden"
+        with f.open("rt") as fh:
+            assert fh.read() == "hidden"
+        with f.open("rb") as fh:
+            assert fh.read() == b"hidden"
+
+    def test_iterdir_lists_children(self, root):
+        self._require("supports_listing", root)
+        names = {p.name for p in root.iterdir()}
+        assert names == {"a.txt", "b.py", ".hidden.txt", "sub", "empty_dir"}
+        if self.supports_empty_directories:
+            assert list((root / "empty_dir").iterdir()) == []
+
+    def test_iterdir_missing_raises_file_not_found(self, root):
+        self._require("supports_listing", root)
+        with pytest.raises(FileNotFoundError):
+            list((root / "nonexistent").iterdir())
+
+    def test_iterdir_file_raises_not_a_directory(self, root):
+        self._require("supports_listing", root)
+        self._require("distinguishes_file_types")
+        with pytest.raises(NotADirectoryError):
+            list((root / "a.txt").iterdir())
+
+    def test_stat(self, root):
+        st = (root / "a.txt").stat()
+        assert st.st_size == 1
+        assert isinstance(st.st_mtime, (int, float))
+        # A second, longer file: a backend that reports one size for all.
+        assert (root / ".hidden.txt").stat().st_size == len("hidden")
+
+    def test_stat_tells_a_directory_from_a_file(self, root):
+        self._require("distinguishes_file_types")
+        assert _stat.S_ISREG((root / "a.txt").stat().st_mode)
+        assert not _stat.S_ISDIR((root / "a.txt").stat().st_mode)
+        assert _stat.S_ISDIR((root / "sub").stat().st_mode)
+        assert not _stat.S_ISREG((root / "sub").stat().st_mode)
+
+    def test_listing_metadata_agrees_with_stat(self, root):
+        # `_scandir()` carries the metadata `walk()`, `rm()` and `PathSyncer` trust without
+        # a `stat()` per entry; `None` means unknown, never a different answer, and a
+        # stat with `size_known` False answers the type alone.
+        self._require("supports_listing", root)
+        listed = dict(root._scandir())
+        assert set(listed) == {"a.txt", "b.py", ".hidden.txt", "sub", "empty_dir"}
+        for name, entry in listed.items():
+            if entry is None:
+                continue
+            real = (root / name).stat()
+            assert _stat.S_ISDIR(entry.st_mode) == _stat.S_ISDIR(real.st_mode), name
+            if not _stat.S_ISDIR(real.st_mode) and getattr(entry, "size_known", True):
+                assert entry.st_size == real.st_size, name
+
+    def test_stat_missing_raises_file_not_found(self, root):
+        with pytest.raises(FileNotFoundError):
+            (root / "nonexistent").stat()
+
+    def test_read_missing_raises_file_not_found(self, root):
+        with pytest.raises(FileNotFoundError):
+            (root / "nonexistent.txt").read_bytes()
+        with pytest.raises(FileNotFoundError):
+            (root / "nonexistent" / "x.txt").read_text()
+
+    def test_read_directory_raises(self, root):
+        self._require("distinguishes_file_types")
+        with pytest.raises(DIRECTORY_ERRORS):
+            (root / "sub").read_bytes()
+
+    def test_nothing_exists_below_a_file(self, root):
+        below = root / "a.txt" / "x"
+        assert below.exists() is False
+        assert below.is_file() is False
+        assert below.is_dir() is False
+        with pytest.raises((FileNotFoundError, NotADirectoryError)):
+            below.read_bytes()
+        with pytest.raises((FileNotFoundError, NotADirectoryError)):
+            below.stat()
+
+    def test_partial_reads_continue_where_the_last_stopped(self, root):
+        with (root / ".hidden.txt").open("rb") as fh:
+            assert fh.read(2) == b"hi"
+            assert fh.read(3) == b"dde"
+            assert fh.read() == b"n"
+            assert fh.read() == b""
+
+    def test_glob(self, root):
+        self._require("supports_listing", root)
+        assert {_rel(root, p) for p in root.glob("*.py")} == {"b.py"}
+        # pathlib matches hidden names with "*".
+        assert {_rel(root, p) for p in root.glob("*")} == {
+            "a.txt",
+            "b.py",
+            ".hidden.txt",
+            "sub",
+            "empty_dir",
+        }
+        assert {_rel(root, p) for p in root.glob("sub/*.py")} == {"sub/c.py"}
+        # A trailing separator selects directories only -- with `native=False`,
+        # the one rule for every interpreter. The default follows the running
+        # one, and pathlib ignored a trailing separator before 3.11.
+        assert {_rel(root, p) for p in root.glob("*/", native=False)} == {
+            "sub",
+            "empty_dir",
+        }
+
+    def test_glob_recursive(self, root):
+        self._require("supports_listing", root)
+        expected = {"b.py", "sub/c.py", "sub/nested/d.py"}
+        assert {_rel(root, p) for p in root.glob("**/*.py")} == expected
+        assert {_rel(root, p) for p in root.rglob("*.py")} == expected
+
+    def test_glob_missing_or_file_parent_selects_nothing(self, root):
+        self._require("supports_listing", root)
+        assert list((root / "nonexistent").glob("*")) == []
+        assert list((root / "a.txt").glob("*")) == []
+        assert list(root.glob("*.nonexistent")) == []
+
+    def test_walk(self, root):
+        self._require("supports_listing", root)
+        expected = {
+            ".": (["empty_dir", "sub"], [".hidden.txt", "a.txt", "b.py"]),
+            "sub": (["nested"], ["c.py"]),
+            "sub/nested": ([], ["d.py"]),
+            "empty_dir": ([], []),
+        }
+        top_down = list(root.walk())
+        actual = {
+            _rel(root, d): (sorted(dirs), sorted(files)) for d, dirs, files in top_down
+        }
+        if not self.supports_empty_directories:
+            del actual["empty_dir"], expected["empty_dir"]
+        assert actual == expected
+        assert _rel(root, top_down[0][0]) == "."
+
+        bottom_up = [_rel(root, d) for d, _, _ in root.walk(top_down=False)]
+        assert sorted(bottom_up) == sorted(_rel(root, d) for d, _, _ in top_down)
+        assert bottom_up[-1] == "."
+        assert bottom_up.index("sub/nested") < bottom_up.index("sub")

pathapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.5
+Name: pathapi
+Version: 0.1.0
+Summary: Generic Path Protocol based pathlib
+Project-URL: Homepage, https://github.com/jose-pr/pathapi/
+Project-URL: Documentation, https://jose-pr.github.io/pathapi/
+Project-URL: Issues, https://github.com/jose-pr/pathapi/issues
+Author: Jose A
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: cryptography; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: pyftpdlib; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# pathapi
+
+[![Version](https://img.shields.io/pypi/v/pathapi.svg)](https://pypi.org/project/pathapi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pathapi.svg)](https://pypi.org/project/pathapi/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/pathapi/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pathapi/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/pathapi/test.yml)](https://github.com/jose-pr/pathapi/actions/workflows/test.yml)
+
+A **robust, extensible pathlib-like base** for any resource addressable as a
+path. Same method names, signatures, semantics and exception types as
+`pathlib.Path` wherever a `pathlib.Path` equivalent exists: write code once
+against `Path` and it runs against your local disk, an in-memory tree, an FTP
+server or the members of a zip or tar file, and against any path class built on
+it. It has no dependencies. Deliberate differences from `pathlib` are listed in
+[Divergences from pathlib](https://jose-pr.github.io/pathapi/divergences/).
+
+`pathapi` was published as `pathlib-next` up to 0.10.0; `pip install pathlib-next`
+now installs a shim that depends on this package. See the changelog for the
+migration from `pathlib_next`.
+
+## Features
+
+| Class | Read | Write | List | Stat | mkdir | Delete | rename |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| local path (`LocalPath`) | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| in-memory (`MemPath`) | Yes | Yes | Yes | Yes | Yes | Yes | No (`move()` copies) |
+| FTP and FTPS (`FTPPath`) | Yes | Yes | Yes (MLSD, NLST fallback) | Yes | Yes | Yes | Yes |
+| zip members (`ZipPath`) | Yes | Local archive only | Yes | Yes | Local archive only | Local archive only | Local archive only |
+| tar members (`TarPath`, incl. gz/bz2/xz) | Yes | No | Yes | Yes | No | No | No |
+| `ArchivePath` | As `ZipPath`/`TarPath` for the format it detects | | | | | | |
+
+Every class gets `glob()`, `walk()`, `copy()`/`move()`, `rm()` and `PathSyncer`
+from the base classes; `LocalPath` and the other classes replace some of them
+where the backend has a faster way.
+
+- **One path interface** over local files, in-memory trees, FTP servers and
+  archive members, and over any class built on `Path`.
+- **`MemPath`**: a virtual filesystem for tests, mocks and transient data.
+- **`FTPPath`, `ZipPath`, `TarPath`, `ArchivePath`**: an FTP server and the
+  members of a zip or tar file as paths, on the standard library alone.
+- **`pathapi.http`**: `HTTPClient` and a transport contract for HTTP
+  requests on the standard library (redirects that never carry
+  `Authorization` to another origin, TLS verified by default, a `proxies=`
+  provider); the `requests` library plugs in as a transport through the
+  `pathapi-requests` distribution.
+- **`PathSyncer`**: one-way, content-compared tree sync between any two
+  implementations, with dry runs and event hooks.
+- **Extensible**: subclass `Path` for any resource, and verify it with the
+  bundled pytest contracts.
+
+Paths for other places are separate distributions built on this one:
+
+| Distribution | Provides |
+| --- | --- |
+| [`uripath`](https://github.com/jose-pr/uripath) | `URIPath`: one class for any URI, with the schemes `file:`, `data:`, `ftp:`, `zip:`, `tar:`, `http:` and `dav:`, and the `uripath` command |
+| [`sftppath`](https://github.com/jose-pr/sftppath) | `SFTPPath` (paramiko or asyncssh) |
+| [`objpath`](https://github.com/jose-pr/objpath) | `S3Path`, `GSPath` and `AZPath` (Amazon S3, Google Cloud Storage, Azure Blob Storage) |
+| [`repopath`](https://github.com/jose-pr/repopath) | `RepoPath`, `GitHubPath` and `GitLabPath` (the REST APIs of the hosting services) |
+| [`pathapi-requests`](https://github.com/jose-pr/pathapi-requests) | `RequestsTransport`, the HTTP transport that sends through a `requests.Session` |
+
+## Installation
+
+```bash
+pip install pathapi
+```
+
+There are no extras and no dependencies: everything above runs on the standard
+library. `pytest` is needed only to import `pathapi.testing` and
+`pathapi.http.testing`.
+
+## Quick start
+
+**Local filesystem**, as `pathlib.Path`:
+
+```python
+from pathapi import Path
+
+p = Path("data") / "report.txt"
+p.parent.mkdir(parents=True, exist_ok=True)
+p.write_text("hello")
+print(p.read_text())
+```
+
+**In memory**, no disk I/O:
+
+```python
+from pathapi.mempath import MemPath
+
+p = MemPath("/config/settings.json")
+p.parent.mkdir(parents=True, exist_ok=True)
+p.write_text('{"debug": true}')
+print([child.name for child in p.parent.iterdir()])
+```
+
+**Archive members**: the segments are the member path and the archive is any
+path:
+
+```python
+import zipfile
+from pathapi import ZipPath
+
+with zipfile.ZipFile("backup.zip", "w") as archive:
+    archive.writestr("etc/config.ini", "[main]\n")
+
+member = ZipPath("etc/config.ini", archive="backup.zip")
+print(member.read_text())
+print([child.name for child in member.parent.iterdir()])
+```
+
+**FTP**: nothing connects until the first operation:
+
+<!-- example: skip: reads from a remote host -->
+```python
+from pathapi import FTPPath
+
+for child in FTPPath("/pub", host="ftp.example.com", user="anonymous").iterdir():
+    print(child.name, child.stat().st_size)
+```
+
+**Copy and sync across classes**:
+
+```python
+from pathapi import Path
+from pathapi.mempath import MemPath
+from pathapi.sync import PathSyncer
+
+source = MemPath("/site")
+(source / "css").mkdir(parents=True)
+(source / "index.html").write_text("<h1>hi</h1>")
+
+PathSyncer(remove_missing=True).sync(source, Path("site-copy"))
+print(sorted(p.name for p in Path("site-copy").iterdir()))
+```
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `pathapi.path` | `Pathname`/`Path` base classes and the derived operations |
+| `pathapi.fspath` | `LocalPath`, `PosixPathname`, `WindowsPathname` |
+| `pathapi.mempath` | `MemPath` in-memory filesystem |
+| `pathapi.ftp` | `FTPPath`, `FTPBackend` (FTP and FTPS on `ftplib`) |
+| `pathapi.archive` | `ZipPath`, `TarPath`, `ArchivePath` (members of a zip or tar file), `make_archive`, `unpack_archive` |
+| `pathapi.http` | `HTTPClient`, `HTTPTransport`, `HTTPResponse` (HTTP requests on `http.client`) |
+| `pathapi.protocols` | `Stat`, `Chmod`, `BinaryOpen`, `NativeChecksum` |
+| `pathapi.sync` | `PathSyncer`, `SyncEvent`, `PathAndStat` |
+| `pathapi.glob` | the glob engine behind `Path.glob()` |
+| `pathapi.checksum` | `md5`, `sha256`, `stream`, `native` |
+| `pathapi.providers` | the helpers a class built on `Path` calls |
+| `pathapi.exceptions` | `PathError`, `NonRelativePatternError` |
+| `pathapi.testing` | pytest contracts for custom implementations |
+| `pathapi.http.testing` | testing support (not stable API): the pytest suite that holds an HTTP transport to the promises of the built-in one |
+
+The full reference is on the [documentation site](https://jose-pr.github.io/pathapi/);
+an agent-oriented API summary ships inside the package as
+`pathapi/AGENTS.md`.
+
+## Extending
+
+Subclass `Path` for a resource of your own (`MemPath` is the reference), as
+worked through in
+[Extending](https://jose-pr.github.io/pathapi/guides/extending/).
+`pathapi.testing` provides the pytest contracts (`PurePathContract`,
+`ReadPathContract`, `PathContract`) and `populate_fixture_tree()` that every
+class of the package and of the distributions above is verified with.
+
+## Supported Python versions
+
+Python 3.9 through 3.14. CI runs the full suite on Ubuntu for every version
+from 3.9 to 3.14, on Windows and macOS for 3.9 and 3.14, and with nothing but
+`pytest` and `pyftpdlib` installed on 3.9 and 3.14.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q -rs
+```
+
+Tests that need an optional package are skipped when it is missing, so check
+the skip list (`-rs`). Contributor notes (virtual environments, formatting, CI,
+releases) are in the repository's
+[`AGENTS.md`](https://github.com/jose-pr/pathapi/blob/main/AGENTS.md);
+benchmarks are described in
+[Benchmarks](https://jose-pr.github.io/pathapi/benchmarks/). To preview
+the documentation: `pip install -e ".[docs]"` then `mkdocs serve`.
+
+Changes are recorded in the
+[changelog](https://github.com/jose-pr/pathapi/blob/main/CHANGELOG.md).
+
+### Releasing
+
+1. Move the `[Unreleased]` entries of `CHANGELOG.md` under a new
+   `## [x.y.z] - <date>` heading and add its link definition at the bottom.
+2. Bump `version` in `pyproject.toml` in the same commit.
+3. Before 1.0 the minor version changes only when the documented API breaks;
+   new methods, new optional arguments and fixes are patch releases.
+4. Run the full suite on the oldest and the newest supported Python,
+   `mkdocs build --strict` and `python -m build`.
+5. Push `main`, then the `v*` tag: the release workflow tests, builds and
+   publishes to PyPI and creates the GitHub release.
+
+## License
+
+MIT; see [LICENSE](https://github.com/jose-pr/pathapi/blob/main/LICENSE).