objpath

pathlib for S3, Google Cloud Storage and Azure Blob buckets. S3Path("reports/2026.csv", bucket="data") has the method names, signatures and exception types of pathlib.Path, and GSPath and AZPath do the same for the other two stores; none needs a URI. They build on pathapi alone; with uripath installed the same package also provides the s3:, gs: and az: schemes. It is documented at https://jose-pr.github.io/objpath/.

Features

• A pathlib path on a bucket: open, read_text, iterdir, glob, stat, mkdir, rename and the rest, plus walk, copy, move, rm and PathSyncer from pathapi. Nothing connects until the first request.
• Directories without directories: is_dir() is a prefix test, listings use a delimiter and carry the size and time of each object, and the keys a walk cannot reach (an empty segment, a name that is both an object and a prefix) are named and refused instead of copied or removed half way.
• Batch deletes and server-side copies: rm(recursive=True) deletes a thousand keys a request, and a copy within a store moves no byte through your process.
• Safe writes: uploads are spooled and sent on close(); a with block that raised uploads nothing. A read is one version of the object, and an object replaced meanwhile is an error, not a mix.
• The SDKs stay out of the way: import objpath loads no SDK and not uripath; a store used without its extra raises an ImportError naming it. No SDK exception crosses the API: errors are the OSError types pathlib raises, TimeoutError and ConnectionError.
• The s3:, gs: and az: schemes for uripath: URIPath("s3://data/reports") is an S3URIPath that delegates to an S3Path.

Installation

pip install "objpath[s3]"

Requires pathapi, which pip installs with it, and Python 3.9 or newer.

Quick start

A path in a bucket: the bucket is a keyword, the segments are the key, and the credentials are the ones boto3 finds:

from objpath import S3Path

report = S3Path("reports/2026.csv", bucket="data")
print(report.read_text())
for child in report.parent.iterdir():
    print(child.name, child.stat().st_size)

Another store, or another endpoint: client options build the path's own backend, and a backend shared between paths is one client and one connection pool:

from objpath import AZPath, GSPath, S3Backend, S3Path

blob = AZPath("logs/app.log", container="ops", account="mycompany")
gcs = GSPath("models/latest", bucket="ml", project="my-project")

with S3Backend(endpoint_url="https://minio.example.org", region_name="us-east-1") as backend:
    root = S3Path(bucket="backups", backend=backend)
    (root / "2026").mkdir(exist_ok=True)
    (root / "2026" / "n.txt").write_text("1")
    root.copy(S3Path("mirror", bucket="backups", backend=backend), recursive=True)

Mirror a tree with PathSyncer, onto a local directory:

from pathapi import LocalPath
from pathapi.sync import PathSyncer
from objpath import S3Path

PathSyncer(remove_missing=True).sync(S3Path("logs", bucket="data"), LocalPath("mirror"))

The schemes, with uripath installed:

from uripath import URIPath

print(URIPath("s3://data/reports/2026.csv").read_text())

API overview

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

Development

pip install -e ".[dev,all]"
python -m pytest -q -rs

The S3 tests run against moto in the test process, and the Google Cloud Storage and Azure tests against fake servers on the loopback interface; none reaches another host. A test for an extra that is not installed is skipped, so check the skip list (-rs). Contributor notes (virtual environments, formatting, CI, releases) are in the repository's AGENTS.md. To preview the documentation: pip install -e ".[all,docs]" then mkdocs serve.

Changes are recorded in the changelog.

Releasing

This project follows Semantic Versioning and keeps a CHANGELOG.md. Pushing a tag matching v* triggers the release workflow: test gate → build (checking the tag names the version built) → a strict docs build as a gate → GitHub release → publish. The release workflow never deploys the docs site itself: for a final release its last job dispatches the docs workflow at the tag, which owns every Pages deploy.

License

MIT — see LICENSE.