pathlib-next

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.

Features

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.
• pathlib_next.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 pathlib-next-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:

Installation

pip install pathlib-next

There are no extras and no dependencies: everything above runs on the standard library. pytest is needed only to import pathlib_next.testing and pathlib_next.http.testing.

Quick start

Local filesystem, as pathlib.Path:

from pathlib_next 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:

from pathlib_next.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:

import zipfile
from pathlib_next 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:

from pathlib_next 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:

from pathlib_next import Path
from pathlib_next.mempath import MemPath
from pathlib_next.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

The full reference is on the documentation site; an agent-oriented API summary ships inside the package as pathlib_next/AGENTS.md.

Extending

Subclass Path for a resource of your own (MemPath is the reference), as worked through in Extending. pathlib_next.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

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; benchmarks are described in Benchmarks. To preview the documentation: pip install -e ".[docs]" then mkdocs serve.

Changes are recorded in the changelog.

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.