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 shares the same glob(), walk(), copy()/move(), rm() and PathSyncer implementations. 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 cp report.txt sftp://host/tmp/report.txt
uripath sync --dry-run --remove-missing site/ s3://bucket/site/

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.

API overview

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

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.

License

MIT; see LICENSE.