objpath 0.1.0__py3-none-any.whl

objpath-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,31 @@
+objpath/AGENTS.md,sha256=nS4tBJ-ozc_iG2YuOzpDPpCU_iAAoJYf0_4M4jRjkv4,18565
+objpath/__init__.py,sha256=GnK1zSHe3O8KgsGuTrTOVwN_zAESaUh_Gy-gyHDMMmI,2013
+objpath/_az.py,sha256=5qCioOcDojMFwa0d3hmOC5laZd3hcXaK5BluZXZWYSQ,21975
+objpath/_az_backend.py,sha256=Dy7qkKGnFt_gv11qbPDHMXALrcjl5O8NmaDdpbxjhw8,5435
+objpath/_az_errors.py,sha256=tlS2zP3pyWKa-9dx07H-mrqZr3YdxTGm8McnfTw6szo,4226
+objpath/_clients.py,sha256=4UlpMr6KxNM-MauehWq7NESv3Pz7q-vj-oP-9tbePK8,3686
+objpath/_digests.py,sha256=im-yEzmzzUwt0Gu8SHxAJFxkgBXpy1PIQKc1j7yisGA,259
+objpath/_failures.py,sha256=YJJNF40Xmi4SQxv3JxPdvcmOO26MlluheLlm01pf2_w,3309
+objpath/_gs.py,sha256=4cEGIR5Rog_Cknmz9jf7Zs5Gp3oLSO9y_rc3UCP1FjU,18450
+objpath/_gs_backend.py,sha256=WgnVYpCaL0Qy5Q5q5kjn0l9EQNZNzT40QtD8V644_fU,3556
+objpath/_gs_errors.py,sha256=QCkBwLXtXhBgbwbYVIlU4Ds_yKDtdn_gJJ7UZRLzXsc,4551
+objpath/_keys.py,sha256=Eh9i5vpRJJQFdam0jxVns8U1MOuaoFhfP2Qj9_wat0I,4423
+objpath/_optional.py,sha256=jBbIdrp3dA15_D2JKA_CiSzoprGvkrD6UQkRM4eVOuM,2159
+objpath/_places.py,sha256=vtDR5Kh3_H_2qqs0BoSZGDGdSGDXhj9VRi7PNqDdjYk,1055
+objpath/_reader.py,sha256=8NDZy5AUEr4HFm0vCtPUFmNCYGRPA3_5yRI3XEvPkRE,2893
+objpath/_s3.py,sha256=PA3jpHZfwtsgWMF5LzThYsMu8m3_z8WUCUm3XESH13A,19523
+objpath/_s3_backend.py,sha256=RR1vTAQLFaTXiW47tn6Y4exMQVFn9TZbcbjGX4SSU_E,2250
+objpath/_s3_errors.py,sha256=MSqThOnyzSbnJkP1ysAhHwxdjdWNdG9vHWwm84zH1Ik,4278
+objpath/_storepath.py,sha256=TiNXbH9ZwlCTbfJUBZxCwyZshw3_sVJbT6pb1rDUa3A,22637
+objpath/_uri_store.py,sha256=GwLHPqIEL7_FfN1Ym7SRyN7y3qGR94jof6N83OQBinc,6273
+objpath/_version.py,sha256=hcDoVXoHoOHn8E5oO2MSjjLQkA0eBxQFd6fM-olPsms,307
+objpath/_writer.py,sha256=Pzge-9HkNLyb49Xm-6OWGeL8VGljm4grglI3cbEvhfk,3425
+objpath/exceptions.py,sha256=EH9LRqsKeNrZU11FPLBzOyD4bqgWP3W7Uri3rFTKGQY,1164
+objpath/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+objpath/uri.py,sha256=LbwBSvPPPIUixkZLoZ9rpNEwUxYbS4WyD7vD1Ni4MHo,7631
+objpath/README.md,sha256=sr0xiNtPreB948zLBirXEuSe2Kfw8VgSF0xnwRlQO2Q,7157
+objpath-0.1.0.dist-info/METADATA,sha256=VxiH7aupz1yZcgWzxivtOclkzk2DRit_jYJ8IYHlNNs,9255
+objpath-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+objpath-0.1.0.dist-info/entry_points.txt,sha256=fJRzVbr7g-wZY-cRB0k5mS6Pah3xcszthQZMZMxSQQc,99
+objpath-0.1.0.dist-info/licenses/LICENSE,sha256=bBY0SeXglEP0yGEOZbyqRTbNfXD0DVpkr-3mBq7-BPQ,1063
+objpath-0.1.0.dist-info/RECORD,,

objpath-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

objpath-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[uripath.schemes]
+az = objpath.uri:AZURIPath
+gs = objpath.uri:GSURIPath
+s3 = objpath.uri:S3URIPath

objpath-0.1.0.dist-info/licenses/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.