objpath 0.1.0__tar.gz

objpath-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Category rule: nothing dot-prefixed at the repo root gets tracked except the
+# files re-included below (a category beats a list). Root-anchored on purpose;
+# nested dotfiles are governed by the specific rules further down.
+/.*
+!/.gitignore
+!/.gitattributes
+!/.github/
+
+# Private agent config. No trailing slash on `.agents` on purpose: it may be a
+# symlink, which git treats as a file, so a directory-only `.agents/` would not
+# match it. These stay even though /.* covers the root: they also catch nested
+# copies. *.local.* is an unshared, machine- or user-specific override and is
+# never committed (it is also excluded from the build in pyproject.toml).
+.agents
+*.local.*
+CLAUDE*
+.claude
+
+# Build/dist output and generated docs site
+build/
+dist/
+site/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+*.egg-info/
+.venv/
+.pyvenv/
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

objpath-0.1.0/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-14
+
+The first release of `objpath`: the Amazon S3, Google Cloud Storage and Azure Blob
+Storage support of `pathlib-next` 0.9.14 (`pathlib_next.uri.schemes.s3`, `.gs` and
+`.az`) as a distribution of its own, with paths that need no URI. It needs Python 3.9 or
+newer and `pathapi>=0.1.0,<0.2`. No store SDK is required to import it: the extras
+`s3` (`boto3>=1.36.0,<2`), `gs` (`google-cloud-storage>=3.0,<4`) and `az`
+(`azure-storage-blob>=12.4.0,<13` and `azure-identity>=1.0,<2`) add one, and `uri`
+(`pathapi-uri>=0.1.0,<0.2`) adds the `s3:`, `gs:` and `az:` schemes. Under *Changed*, the
+migration from `pathlib_next.uri.schemes` comes in this order: the table of names, the
+table of extras, then every change of behaviour with what to do about it.
+
+It is built on `pathapi`, which was published as `pathlib-next` up to 0.10.0 (import
+name `pathlib_next`); the old names below are the ones before the move.
+
+### Added
+
+- `S3Path`, `GSPath` and `AZPath`, `pathapi.Path` classes for the objects of a
+  bucket or container, built from keywords:
+  `S3Path("dir/key", bucket="bkt")`, `GSPath("dir/key", bucket="bkt")`,
+  `AZPath("dir/key", container="cont", account="acct")`. Nothing connects until the
+  first request. Client options (`region_name=`, `project=`, `credential=`, ...) build
+  the path's own backend, `backend=` shares one between paths built separately (giving it
+  together with a client option is a `TypeError`), and a
+  path joined from another keeps its bucket and its backend (`bucket=` or `container=`
+  on a joined path moves it to another bucket of the same backend). Paths built without
+  either use one default backend per process (`AZPath`: per account).
+- `S3Backend`, `GSBackend`, `AZBackend` and their contracts `BaseS3Backend`,
+  `BaseGSBackend` and `BaseAZBackend`. Every backend is a context manager: `close()`
+  closes the SDK client it built, the next use builds another, and calling it twice is
+  harmless.
+- `objpath.exceptions`: `ObjPathError`, a `pathapi.PathError`, with
+  `ObjectChangedError` and `UnreachableKeysError`, both also `OSError` (see *Changed*).
+- `objpath.uri`: `S3URIPath`, `GSURIPath` and `AZURIPath`, the `s3:`, `gs:` and `az:`
+  schemes of `uripath`, found by `uripath` through the entry points `s3`, `gs` and `az` of
+  the group `uripath.schemes`. Importing `objpath.uri` without `uripath` raises an
+  `ImportError` that names `pip install "objpath[uri]"`; `import objpath` never imports
+  `uripath` or an SDK.
+- `AZBackend.account`: the account that `account=`, else `connection_string=` or
+  `account_url=`, names.
+- `objpath.__version__`, read from the installed metadata.
+
+### Changed
+
+- The names. `pathlib_next.uri.schemes.s3`, `.gs` and `.az` are gone with no alias.
+
+  | Was | Now |
+  | --- | --- |
+  | `S3Path` (a `UriPath`) | `objpath.S3Path` for a path built from keywords; `objpath.uri.S3URIPath` for `URIPath("s3://...")` |
+  | `GsPath` | `objpath.GSPath`; `objpath.uri.GSURIPath` |
+  | `AzPath` | `objpath.AZPath`; `objpath.uri.AZURIPath` |
+  | `S3Backend`, `BaseS3Backend` | `objpath.S3Backend`, `objpath.BaseS3Backend` |
+  | `GsBackend`, `BaseGsBackend` | `objpath.GSBackend`, `objpath.BaseGSBackend` |
+  | `AzBackend`, `BaseAzBackend` | `objpath.AZBackend`, `objpath.BaseAZBackend` |
+  | `GsPath.bucket_name` | `GSPath.bucket` (and `GSURIPath.bucket`) |
+  | the entry-point group `pathlib_next.schemes`, entries `s3`, `gs`, `az` | the group `uripath.schemes`, entries `s3 = "objpath.uri:S3URIPath"`, `gs = "objpath.uri:GSURIPath"`, `az = "objpath.uri:AZURIPath"` |
+
+- What to install where `pathlib-next` had an extra. `pathlib-next` 0.10 has no `s3`,
+  `gs` or `az` extra.
+
+  | Was | Install now |
+  | --- | --- |
+  | `pathlib-next[s3]` | `objpath[s3]` |
+  | `pathlib-next[gs]` | `objpath[gs]` |
+  | `pathlib-next[az]` | `objpath[az]` |
+  | any of them, for `UriPath("s3://...")`, `gs://` or `az://` | add `objpath[uri]` (or install `uripath` beside it) |
+
+- A path is built from keywords, not from a URL. Was: `S3Path("s3://bkt/dir/key")`
+  parsed the URL, and the bucket came from its host. Now `S3Path("dir/key", bucket="bkt")`,
+  `GSPath("dir/key", bucket="bkt")` and `AZPath("dir/key", container="cont",
+  account="acct")`; a URL is a `URIPath` (`URIPath("s3://bkt/dir/key")`, which needs the
+  `uri` extra). A path without a bucket is a `TypeError` where it is built; an
+  `S3URIPath` with no bucket still raises `FileNotFoundError` when it is used.
+- `str(path)` of an `S3Path`, `GSPath` and `AZPath` is the URL (`s3://bkt/dir/key`), as
+  the URI paths' is. `repr()` is `S3Path('dir/key', bucket='bkt')`.
+- Two paths are equal when their class, bucket (account and container, for `AZPath`)
+  and key are; `x` and `/x` are one key.
+- An `AZPath` needs one of `account=`, `backend=`, a client option or an `AZPath` to join
+  from; without one it is a `TypeError` where it is built. Was: the account was the host of the
+  URL, and a URL without one raised `FileNotFoundError` when it was used (an `AZURIPath` still
+  does). For URI paths nothing else changes: `backend=` is used as it is for the path it is
+  given to, whatever bucket the URI names.
+- The account level of Azure is a URI feature. Was: `AzPath("az://account")` listed the
+  containers of the account. Now `AZPath` always names a container; `URIPath("az://account")`
+  is still a directory whose children are the containers.
+- A stream whose object was replaced while it was being read raises `ObjectChangedError`,
+  and a copy or removal of a prefix that holds keys a walk cannot reach raises
+  `UnreachableKeysError`. Was: a plain `OSError` (`ESTALE`, `EINVAL`). Both are still
+  `OSError` with the same `errno`, so `except OSError` and `errno` checks keep working.
+- `AZBackend(connection_string=...)` and `AZBackend(account_url=...)` carry the account they
+  name in `account`; `account` was `None` for them.
+- The Azure tuning settings. Was: the module settings `schemes.az.READ_CHUNK` (512 KiB per
+  ranged read request) and `schemes.az.COPY_POLL_TIMEOUT` (300 s to wait for a service copy).
+  Now: the class attributes `AZBackend.read_chunk` and `AZBackend.copy_timeout`
+  (`BaseAZBackend` holds the defaults); assign them on `AZBackend` or on a subclass of it.
+- `is_local()` of a store path is `False` without resolving anything. Was: the URI path resolved
+  the bucket or account name as if it were a host name, so `PathSyncer(quick_check=True)` made a
+  DNS lookup of it and read a name that resolved to this machine as local.
+- A write stream of a store that is garbage collected without being closed uploads nothing
+  and emits a `ResourceWarning`; `pathlib-next` closed it, and so uploaded it. What to do:
+  close the file, or use `with`.
+
+[Unreleased]: https://github.com/jose-pr/objpath/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jose-pr/objpath/releases/tag/v0.1.0

objpath-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jose A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

objpath-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: objpath
+Version: 0.1.0
+Summary: pathlib-style paths for S3, Google Cloud Storage and Azure Blob Storage, and the s3:, gs: and az: schemes for uripath
+Project-URL: Homepage, https://github.com/jose-pr/objpath/
+Project-URL: Documentation, https://jose-pr.github.io/objpath/
+Project-URL: Issues, https://github.com/jose-pr/objpath/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
+Requires-Dist: pathapi<0.2,>=0.1.0
+Provides-Extra: all
+Requires-Dist: azure-identity<2,>=1.0; extra == 'all'
+Requires-Dist: azure-storage-blob<13,>=12.4.0; extra == 'all'
+Requires-Dist: boto3<2,>=1.36.0; extra == 'all'
+Requires-Dist: google-cloud-storage<4,>=3.0; extra == 'all'
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 'all'
+Provides-Extra: az
+Requires-Dist: azure-identity<2,>=1.0; extra == 'az'
+Requires-Dist: azure-storage-blob<13,>=12.4.0; extra == 'az'
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: moto[s3]; 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'
+Provides-Extra: gs
+Requires-Dist: google-cloud-storage<4,>=3.0; extra == 'gs'
+Provides-Extra: s3
+Requires-Dist: boto3<2,>=1.36.0; extra == 's3'
+Provides-Extra: uri
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 'uri'
+Description-Content-Type: text/markdown
+
+# objpath
+
+[![Version](https://img.shields.io/pypi/v/objpath.svg)](https://pypi.org/project/objpath/)
+[![Python versions](https://img.shields.io/pypi/pyversions/objpath.svg)](https://pypi.org/project/objpath/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/objpath/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/objpath/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/objpath/test.yml)](https://github.com/jose-pr/objpath/actions/workflows/test.yml)
+
+**`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`](https://github.com/jose-pr/pathapi) alone; with
+[`uripath`](https://github.com/jose-pr/uripath) installed the same package also
+provides the `s3:`, `gs:` and `az:` schemes. It is documented at
+<https://jose-pr.github.io/objpath/>.
+
+## Features
+
+| Store | Class | Extra | Directories | Server-side copy | Checksum | Append |
+| --- | --- | --- | --- | --- | --- | --- |
+| Amazon S3 and S3-compatible | `S3Path` | `s3` | key prefixes, `mkdir()` writes a marker object | `CopyObject`, same client | ETag MD5, `crc32`, `crc32c`, `crc64nvme`, `sha1`, `sha256` | no |
+| Google Cloud Storage | `GSPath` | `gs` | key prefixes, `mkdir()` writes a marker object | `copy_blob`, same client | `md5`, `crc32c` | no |
+| Azure Blob Storage | `AZPath` | `az` | key prefixes, `mkdir()` writes a marker blob | service copy, same container and client | `Content-MD5` | no |
+
+- **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
+
+```bash
+pip install "objpath[s3]"
+```
+
+Requires `pathapi`, which pip installs with it, and Python 3.9 or newer.
+
+| Install | Adds |
+| --- | --- |
+| `pip install objpath` | the paths and the backend contracts; no SDK |
+| `pip install "objpath[s3]"` | `boto3>=1.36.0,<2` for `S3Path` |
+| `pip install "objpath[gs]"` | `google-cloud-storage>=3.0,<4` for `GSPath` |
+| `pip install "objpath[az]"` | `azure-storage-blob` and `azure-identity` for `AZPath` |
+| `pip install "objpath[uri]"` | `uripath` and with it the `s3:`, `gs:` and `az:` schemes |
+| `pip install "objpath[all]"` | all of the above |
+
+## 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:
+
+<!-- example: skip: connects to S3 -->
+```python
+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:
+
+<!-- example: skip: connects to a store -->
+```python
+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:
+
+<!-- example: skip: connects to S3 -->
+```python
+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:
+
+<!-- example: skip: connects to S3 -->
+```python
+from uripath import URIPath
+
+print(URIPath("s3://data/reports/2026.csv").read_text())
+```
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `objpath` | `S3Path`, `GSPath`, `AZPath`, the backends `S3Backend`, `GSBackend`, `AZBackend` and the contracts `BaseS3Backend`, `BaseGSBackend`, `BaseAZBackend`, the exceptions and `__version__` |
+| `objpath.exceptions` | `ObjPathError`, `ObjectChangedError` and `UnreachableKeysError` |
+| `objpath.uri` | `S3URIPath`, `GSURIPath` and `AZURIPath`, the schemes of `uripath` (needs the `uri` extra) |
+
+The full reference is on the [documentation site](https://jose-pr.github.io/objpath/);
+an agent-oriented API summary ships inside the package as `objpath/AGENTS.md`.
+
+## Development
+
+```bash
+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`](https://github.com/jose-pr/objpath/blob/main/AGENTS.md). To preview the
+documentation: `pip install -e ".[all,docs]"` then `mkdocs serve`.
+
+Changes are recorded in the
+[changelog](https://github.com/jose-pr/objpath/blob/main/CHANGELOG.md).
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](https://github.com/jose-pr/objpath/blob/main/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](https://github.com/jose-pr/objpath/blob/main/LICENSE).

objpath-0.1.0/README.md

@@ -0,0 +1,153 @@
+# objpath
+
+[![Version](https://img.shields.io/pypi/v/objpath.svg)](https://pypi.org/project/objpath/)
+[![Python versions](https://img.shields.io/pypi/pyversions/objpath.svg)](https://pypi.org/project/objpath/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/objpath/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/objpath/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/objpath/test.yml)](https://github.com/jose-pr/objpath/actions/workflows/test.yml)
+
+**`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`](https://github.com/jose-pr/pathapi) alone; with
+[`uripath`](https://github.com/jose-pr/uripath) installed the same package also
+provides the `s3:`, `gs:` and `az:` schemes. It is documented at
+<https://jose-pr.github.io/objpath/>.
+
+## Features
+
+| Store | Class | Extra | Directories | Server-side copy | Checksum | Append |
+| --- | --- | --- | --- | --- | --- | --- |
+| Amazon S3 and S3-compatible | `S3Path` | `s3` | key prefixes, `mkdir()` writes a marker object | `CopyObject`, same client | ETag MD5, `crc32`, `crc32c`, `crc64nvme`, `sha1`, `sha256` | no |
+| Google Cloud Storage | `GSPath` | `gs` | key prefixes, `mkdir()` writes a marker object | `copy_blob`, same client | `md5`, `crc32c` | no |
+| Azure Blob Storage | `AZPath` | `az` | key prefixes, `mkdir()` writes a marker blob | service copy, same container and client | `Content-MD5` | no |
+
+- **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
+
+```bash
+pip install "objpath[s3]"
+```
+
+Requires `pathapi`, which pip installs with it, and Python 3.9 or newer.
+
+| Install | Adds |
+| --- | --- |
+| `pip install objpath` | the paths and the backend contracts; no SDK |
+| `pip install "objpath[s3]"` | `boto3>=1.36.0,<2` for `S3Path` |
+| `pip install "objpath[gs]"` | `google-cloud-storage>=3.0,<4` for `GSPath` |
+| `pip install "objpath[az]"` | `azure-storage-blob` and `azure-identity` for `AZPath` |
+| `pip install "objpath[uri]"` | `uripath` and with it the `s3:`, `gs:` and `az:` schemes |
+| `pip install "objpath[all]"` | all of the above |
+
+## 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:
+
+<!-- example: skip: connects to S3 -->
+```python
+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:
+
+<!-- example: skip: connects to a store -->
+```python
+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:
+
+<!-- example: skip: connects to S3 -->
+```python
+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:
+
+<!-- example: skip: connects to S3 -->
+```python
+from uripath import URIPath
+
+print(URIPath("s3://data/reports/2026.csv").read_text())
+```
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `objpath` | `S3Path`, `GSPath`, `AZPath`, the backends `S3Backend`, `GSBackend`, `AZBackend` and the contracts `BaseS3Backend`, `BaseGSBackend`, `BaseAZBackend`, the exceptions and `__version__` |
+| `objpath.exceptions` | `ObjPathError`, `ObjectChangedError` and `UnreachableKeysError` |
+| `objpath.uri` | `S3URIPath`, `GSURIPath` and `AZURIPath`, the schemes of `uripath` (needs the `uri` extra) |
+
+The full reference is on the [documentation site](https://jose-pr.github.io/objpath/);
+an agent-oriented API summary ships inside the package as `objpath/AGENTS.md`.
+
+## Development
+
+```bash
+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`](https://github.com/jose-pr/objpath/blob/main/AGENTS.md). To preview the
+documentation: `pip install -e ".[all,docs]"` then `mkdocs serve`.
+
+Changes are recorded in the
+[changelog](https://github.com/jose-pr/objpath/blob/main/CHANGELOG.md).
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](https://github.com/jose-pr/objpath/blob/main/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](https://github.com/jose-pr/objpath/blob/main/LICENSE).

objpath-0.1.0/docs/api/exceptions.md

@@ -0,0 +1,10 @@
+# Exceptions
+
+`ObjPathError` is the base of what this package raises on its own. A caller's bad
+argument is a plain `ValueError` or `TypeError`, and a failed request is the `OSError`
+of the kind `pathlib` raises.
+
+::: objpath.exceptions
+    options:
+      show_if_no_docstring: true
+      filters: ["!^_"]

objpath-0.1.0/docs/api/paths.md

@@ -0,0 +1,18 @@
+# Paths and backends
+
+The paths need no URI. Each store needs its own extra: `s3`, `gs` or `az`.
+
+::: objpath
+    options:
+      show_if_no_docstring: true
+      filters: ["!^_"]
+      members:
+        - S3Path
+        - S3Backend
+        - BaseS3Backend
+        - GSPath
+        - GSBackend
+        - BaseGSBackend
+        - AZPath
+        - AZBackend
+        - BaseAZBackend

objpath-0.1.0/docs/api/uri.md

@@ -0,0 +1,8 @@
+# The `s3:`, `gs:` and `az:` schemes
+
+Needs `uripath`: `pip install "objpath[uri]"`.
+
+::: objpath.uri
+    options:
+      show_if_no_docstring: true
+      filters: ["!^_"]

objpath-0.1.0/docs/benchmarks.md

@@ -0,0 +1,49 @@
+# Benchmarks
+
+`objpath` includes a benchmark harness at `benchmarks/bench.py` that times `S3Path`, and the
+`s3:` scheme of `uripath` on the same operations. It needs `moto` and `boto3`:
+`pip install -e ".[dev,s3,uri]"`.
+
+## Run It
+
+```bash
+python benchmarks/bench.py            # run the benchmarks
+python benchmarks/bench.py --help     # options; runs nothing
+```
+
+## Saved Results
+
+Every metric is timed over several samples. `--save` writes the run as JSON to
+`benchmarks/results/<name>.json`, with the minimum, median and maximum milliseconds per
+call of each metric plus the interpreter, platform and git commit it ran on:
+
+```bash
+python benchmarks/bench.py --save
+python benchmarks/bench.py --save --samples 9
+```
+
+`--samples N` applies one sample count to every case; without it each case takes five.
+The result schema and the committed results are described in
+[`benchmarks/README.md`](https://github.com/jose-pr/objpath/blob/main/benchmarks/README.md).
+
+Compare two runs on their medians, and only between runs from the same machine and
+interpreter. A run on a developer machine is a sanity check; performance claims in release
+notes come from CI runs.
+
+## What It Covers
+
+- `stat()` of an object, `iterdir()` and `walk()` of 72 entries
+- `read_bytes()` and `write_bytes()` of 256 KiB, `mkdir()`, `rename()`, `unlink()` and a
+  server-side `copy()`
+- `rm(recursive=True)` of a 33-object tree, and the number of requests it sends
+  (one `HeadObject`, one `ListObjectsV2` and one `DeleteObjects`)
+- each of the above through `S3Path` (metric group `s3`) and through
+  `URIPath("s3://...")` (group `s3-uri`), so the cost of the URI layer is the difference
+  between the two groups
+
+## Caveats
+
+The bucket is held by `moto` in the benchmark's own process, with no network latency, so
+the numbers show the overhead of the path layer and of moto, not how a store behaves over
+a link. Timings depend on the machine, the interpreter and what else is running; compare
+medians, as described above.

objpath-0.1.0/docs/changelog.md

@@ -0,0 +1,3 @@
+# Changelog
+
+--8<-- "CHANGELOG.md"