pathlib-next

A robust, extensible pathlib-like base for any resource addressable as a path or URI. Same method names, signatures, semantics and exception types as pathlib.Path wherever a pathlib.Path equivalent exists: write code once against Path/UriPath and it runs against your local disk, an in-memory tree, an archive member, an HTTP or WebDAV server, SFTP/FTP, S3, Google Cloud Storage, Azure Blob Storage or a GitHub/GitLab repository. Deliberate differences from pathlib are listed in Divergences from pathlib.

Features

Every scheme gets glob(), walk(), copy()/move(), rm() and PathSyncer from the base classes; LocalPath and a few schemes replace some of them where the backend has a faster way. The per-scheme notes (timeouts, host-key and certificate verification, authentication, limits) are in Schemes.

• One path interface over local files, in-memory trees, archive members and every URI scheme above.
• MemPath: a virtual filesystem for tests, mocks and transient data.
• PathSyncer: one-way, content-compared tree sync between any two implementations, with dry runs and event hooks.
• uripath command: read, write, cp, rm and sync across any of these paths, with - for stdin/stdout.
• Extensible two ways: subclass Path for a non-URI resource, or UriPath for a new URI scheme, and verify it with the bundled pytest contracts.

Installation

pip install pathlib-next

With no extras, pathlib_next.Path/LocalPath, pathlib_next.mempath.MemPath, the utilities, the test contracts and uripath on local paths all work; the uri extra is what makes pathlib_next.uri importable.

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()])

Any URI: UriPath returns the class registered for the scheme:

from pathlib_next.uri import UriPath

print(UriPath("file:data/report.txt").read_text())       # FileUri
print(UriPath("data:text/plain;base64,aGVsbG8=").read_text())  # DataUri

Archive members: <scheme>:<archive-uri>!/<member>, where the archive itself is any URI (file:, http:, sftp:, ...):

import zipfile
from pathlib_next.uri import UriPath

with zipfile.ZipFile("backup.zip", "w") as archive:
    archive.writestr("etc/config.ini", "[main]\n")

member = UriPath("zip:file:backup.zip!/etc/config.ini")
print(member.read_text())
print([child.name for child in member.parent.iterdir()])

Remote paths use the same API:

from pathlib_next.uri import UriPath

for child in UriPath("https://example.com/data/").iterdir():
    print(child.name, child.stat().st_size)

print(UriPath("sftp://user@host/var/log/app.log").read_text())
print(UriPath("s3://bucket/reports/2026.csv").stat().st_mtime)
print(UriPath("github://github.com/owner/repo/README.md?ref=main").read_text())

Copy and sync across schemes:

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

Command line

uripath reads, writes, copies, removes and syncs local paths and URIs, with - for stdin or stdout. It works on local paths with no extra installed; these commands run as written in an empty directory:

mkdir site
uripath write site/index.html "<h1>hi</h1>"
uripath read site/index.html
uripath cp site/index.html site/copy.html
uripath sync --dry-run --remove-missing site site-copy
uripath sync site site-copy
uripath rm --recursive site-copy

Either side can be a URI instead, with the extra for its scheme installed:

uripath cp report.txt sftp://host/tmp/report.txt
uripath sync --dry-run --remove-missing site/ s3://bucket/site/

The exit status is 0 on success, 1 when the operation failed, 2 for a wrong invocation, 130 on Ctrl-C and 141 when the reader of stdout went away. Every flag is described in the CLI guide.

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

Two first-class ways to add a path-addressable resource, covered with worked examples in Extending:

• Subclass Path directly for a non-URI resource (MemPath is the reference).
• Subclass UriPath and declare __SCHEMES for a new URI scheme; it is dispatched as soon as its module is imported, or through a pathlib_next.schemes entry point.

pathlib_next.testing provides the pytest contracts (PurePathContract, ReadPathContract, PathContract) and populate_fixture_tree() used to verify every built-in scheme.

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, without any extras on 3.9 and 3.14, and with the gs/az SDKs on 3.9 and 3.14.

Development

pip install -e ".[dev,uri,http,sftp,sftp-async,s3,gs,az]"
python -m pytest -q -rs

Tests for an extra that is not installed are skipped, 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.