pathapi-uri 0.1.0__py3-none-any.whl

pathapi_uri-0.1.0.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.5
+Name: pathapi-uri
+Version: 0.1.0
+Summary: pathlib-style paths for URIs: file:, data:, ftp:, zip:, tar:, http:, dav:
+Project-URL: Homepage, https://github.com/jose-pr/uripath/
+Project-URL: Documentation, https://jose-pr.github.io/uripath/
+Project-URL: Issues, https://github.com/jose-pr/uripath/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: netimps<0.5,>=0.4.0
+Requires-Dist: pathapi<0.2,>=0.1.0
+Provides-Extra: cli
+Requires-Dist: duho<0.8,>=0.7.3; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: cheroot; extra == 'dev'
+Requires-Dist: cryptography; extra == 'dev'
+Requires-Dist: duho<0.8,>=0.7.3; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: pyftpdlib; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: requests; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Requires-Dist: uritools<7,>=5.0; extra == 'dev'
+Requires-Dist: wsgidav; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# uripath
+
+[![Version](https://img.shields.io/pypi/v/pathapi-uri.svg)](https://pypi.org/project/pathapi-uri/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pathapi-uri.svg)](https://pypi.org/project/pathapi-uri/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/uripath/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/uripath/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/uripath/test.yml)](https://github.com/jose-pr/uripath/actions/workflows/test.yml)
+
+Installed as `pathapi-uri` from PyPI; imported, and run as a command, as `uripath`.
+
+**One `pathlib`-style API for URIs.** `URIPath("https://...")`, `URIPath("zip:...")`
+and `URIPath("ftp://...")` return the class registered for the scheme, and each
+has the method names, signatures and exception types of `pathlib.Path`: write
+code once and run it against a local file, an archive member, an FTP or WebDAV
+server, a web directory or, through the `repopath` distribution, a GitHub or GitLab
+repository. It builds on
+[`pathapi`](https://github.com/jose-pr/pathapi) and is documented at
+<https://jose-pr.github.io/uripath/>.
+
+## Features
+
+| Scheme (class) | Needs | Read | Write | List | Stat | mkdir | Delete | rename |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `file:` (`FileURIPath`) | nothing | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `data:` (`DataURIPath`, RFC 2397) | nothing | Yes | No | No | Yes | No | No | No |
+| `zip:` (`ZipURIPath`) | nothing | Yes | Local `file:` archive only | Yes | Yes | Local archive only | Local archive only | Local archive only |
+| `tar:` (`TarURIPath`, incl. gz/bz2/xz) | nothing | Yes | No | Yes | Yes | No | No | No |
+| `archive:`, `archive+zip:`, `archive+tar:` | nothing | As `zip:`/`tar:` for the detected or pinned format | | | | | | |
+| `ftp:` / `ftps:` (`FTPURIPath`) | nothing | Yes | Yes | Yes (MLSD, NLST fallback) | Yes | Yes | Yes | Yes |
+| `http:` / `https:` (`HTTPURIPath`) | nothing | Yes | Yes (PUT, configurable) | Yes (HTML index) | Yes | No | Yes (DELETE) | No |
+| `dav:` / `davs:` (`DAVURIPath`, WebDAV) | nothing | Yes | Yes (no append) | Yes (PROPFIND) | Yes | Yes | Yes | Yes |
+| `sftp:` | `sftppath[paramiko]` or `[asyncssh]` | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| `s3:` | `objpath[s3]` | Yes | Yes (no append) | Yes (prefixes) | Yes | Yes (marker object) | Yes | Yes (same bucket) |
+| `gs:` | `objpath[gs]` | Yes | Yes (no append) | Yes (prefixes) | Yes | Yes (marker object) | Yes | Yes (same bucket) |
+| `az:` | `objpath[az]` | Yes | Yes (no append) | Yes (prefixes) | Yes | Yes (marker blob) | Yes | Yes (same container) |
+| `repo:` | `repopath` | Yes | No | Yes | Yes | No | No | No |
+| `github:` | `repopath` | Yes | No | Yes | Yes | No | No | No |
+| `gitlab:` | `repopath` | Yes | No | Yes | Yes | No | No | No |
+
+The last seven rows are other distributions: a path of one of those schemes
+builds, joins and prints without it, and its first use of the server raises an
+`ImportError` that names what to install. The `requests` HTTP transport
+(`with_session()`, `~/.netrc`, SOCKS proxies) is the distribution
+`pathapi-requests`: once it is installed, `with_session()` and
+`PATHAPI_HTTP_TRANSPORT=requests` use it, with nothing to configure.
+
+Every scheme gets `glob()`, `walk()`, `copy()`/`move()`, `rm()` and `PathSyncer`
+from the `pathapi` base classes. The per-scheme notes (timeouts,
+certificate verification, authentication, limits) are in
+[Schemes](https://jose-pr.github.io/uripath/guides/schemes/).
+
+- **Pure URI algebra**: `URI` parses, joins and compares URIs with no I/O and
+  no scheme class needed; `Source` and `Query` are its authority and query.
+- **HTTP on the standard library**: `http:` and `dav:` send through a
+  replaceable transport built on `http.client`.
+- **Extensible**: subclass `URIPath` and declare `__SCHEMES` for a new scheme,
+  or register it through a `uripath.schemes` entry point.
+- **`uripath` command**: `read`, `write`, `cp`, `rm` and `sync` across local
+  paths and URIs, with `-` for stdin/stdout (`pip install "pathapi-uri[cli]"`).
+
+## Installation
+
+```bash
+pip install pathapi-uri
+```
+
+Requires `pathapi` and `netimps`, which pip installs with it.
+
+| Install | Adds |
+| --- | --- |
+| `pip install pathapi-uri` | every scheme whose Needs is nothing in the table above |
+| `pip install "pathapi-uri[cli]"` | the `uripath` command (its only extra) |
+| `pip install "sftppath[paramiko]"` or `[asyncssh]` | `sftp:` |
+| `pip install "objpath[s3]"`, `[gs]` or `[az]` | `s3:`, `gs:`, `az:` |
+| `pip install pathapi-requests` | the `requests` HTTP transport |
+
+## Quick start
+
+**Any URI**: `URIPath` returns the class registered for the scheme:
+
+```python
+from uripath import URIPath
+
+report = URIPath("file:data/report.txt")                    # FileURIPath
+report.parent.mkdir(parents=True, exist_ok=True)
+report.write_text("hello")
+print(report.read_text())
+print(URIPath("data:text/plain;base64,aGVsbG8=").read_text())  # DataURIPath
+```
+
+**Archive members**: `<scheme>:<archive-uri>!/<member>`, where the archive
+itself is any URI (`file:`, `http:`, `ftp:`, ...):
+
+```python
+import zipfile
+from uripath 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:
+
+<!-- example: skip: reads from remote hosts -->
+```python
+from uripath import URIPath
+
+for child in URIPath("https://example.com/data/").iterdir():
+    print(child.name, child.stat().st_size)
+
+print(URIPath("ftp://user@host/pub/README").read_text())
+```
+
+**Copy and sync across schemes**, with the `pathapi` syncer:
+
+```python
+from pathapi.sync import PathSyncer
+from uripath import URIPath
+
+source = URIPath("file:site")
+(source / "css").mkdir(parents=True)
+(source / "index.html").write_text("<h1>hi</h1>")
+
+PathSyncer(remove_missing=True).sync(source, URIPath("file:site-copy"))
+print(sorted(p.name for p in URIPath("file:site-copy").iterdir()))
+```
+
+## Command line
+
+`uripath` reads, writes, copies, removes and syncs local paths and URIs, with
+`-` for stdin or stdout. It is built on `duho` and needs the `cli` extra,
+`pip install "pathapi-uri[cli]"`; without it the command says so and exits with
+status 1. These commands run as written in an empty directory:
+
+```bash
+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:
+
+<!-- example: skip: needs an FTP host and a web server -->
+```bash
+uripath cp report.txt ftp://host/tmp/report.txt
+uripath sync --dry-run --remove-missing site/ ftp://host/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](https://jose-pr.github.io/uripath/guides/cli/), and `uripath` can
+be served to an agent as a set of tools.
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `uripath` | `URI`, `URIPath`, `URILike`, `Source`, `Query`, `QueryLike`, the functions `as_path` and `copy_stream`, the errors `URIPathError`, `URISyntaxError` and `UnsupportedSchemeError`, and `__version__` |
+| `uripath.source` | `Source` (scheme, userinfo, host, port), `same_authority` and the helpers that read and compose a URI's text |
+| `uripath.query` | `Query`, an immutable query value, and `QueryLike` |
+| `uripath.exceptions` | The errors above |
+| `uripath.schemes` | The contract and registry of schemes, `DerivedBackend`, `DelegatingURIPath`, and every built-in scheme's classes: `FileURIPath`, `DataURIPath`, `ZipURIPath`, `TarURIPath`, `ArchiveURIPath`, `FTPURIPath`, `HTTPURIPath`, `DAVURIPath` and their backends |
+
+The full reference is on the [documentation site](https://jose-pr.github.io/uripath/);
+an agent-oriented API summary ships inside the package as `uripath/AGENTS.md`.
+
+## Extending
+
+Subclass `URIPath` and declare `__SCHEMES` for a new URI scheme; it is
+dispatched as soon as its module is imported, or through a `uripath.schemes`
+entry point. A scheme name belongs to one class: a second claim raises unless
+the class statement says `replace=True`, and `URIPath.schemes()` /
+`URIPath.scheme_class(name)` read the registry. Worked examples:
+[Extending](https://jose-pr.github.io/uripath/guides/extending/). The pytest
+contracts that verify a scheme are in `pathapi.testing`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q -rs
+```
+
+Tests for a server 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`](https://github.com/jose-pr/uripath/blob/main/AGENTS.md). To
+preview the documentation: `pip install -e ".[docs]"` then `mkdocs serve`.
+
+Changes are recorded in the
+[changelog](https://github.com/jose-pr/uripath/blob/main/CHANGELOG.md).
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](https://github.com/jose-pr/uripath/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/uripath/blob/main/LICENSE).

pathapi_uri-0.1.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+uripath/AGENTS.md,sha256=Siu2tupwH9zjC786iGrNqd7Ua_3CCWQV7ewarWpWgXw,60774
+uripath/__init__.py,sha256=MyRZR1EkKrzeIIFrog6kWdygGwz60b9td7FRdgjOJKQ,598
+uripath/__main__.py,sha256=WlXs7327vTmE4SW9MiExqWfdbyBrqgK3hG8w0yDsrRw,162
+uripath/_pathtext.py,sha256=mEauPI4JikCIeA7LnriYv-t5k737T79msPhGaiYSvx8,1150
+uripath/_rfc3986.py,sha256=r7pEImk9mk58K-8j0IXbmZ4iGBn0C5_tFaXtDbw5vnw,2445
+uripath/_transfer.py,sha256=6bZtY7Mkn3G4eWPVInmg9J_5TBhIWXb8r3toba2Sl9Y,3347
+uripath/_uri.py,sha256=tIRSnWzq0rY3U0S4rWWaZBrOLuiRkJgOcOj9InKajvk,42454
+uripath/_version.py,sha256=jOvOnkZ6UGEKfqW8caogg-zZOdIoCWwrsp1-jjctUQI,311
+uripath/exceptions.py,sha256=A0g181e49M-GiuxmibBKPVRiFcVs9wWebb-pttNxHIQ,1223
+uripath/py.typed,sha256=bWew9mHgMy8LqMu7RuqQXFXLBxh2CRx0dUbSx-3wE48,27
+uripath/query.py,sha256=wCXcSKs7MEMF5pQxE6toUPM0nYL1HSVnOh3NyHcKL5Q,8594
+uripath/cli/__init__.py,sha256=xOoqJLXNHc8smiXkY4Czw8ySqSlzd6k6WN3tRZbjGvo,1716
+uripath/cli/_common.py,sha256=_7vhMIUPDRMjMozcG8_1ifJs3dfTPyE7gdkKVIY05Ao,1514
+uripath/cli/_root.py,sha256=_BdjkJ8hXK4dQbnCNYSao_ys4P_yajJ5LOskqr_sP-8,2283
+uripath/cli/cp.py,sha256=1rvgaFgDvp1wLqoA_-Wbuc_ABDWGnudkXqh-pdd90-E,1906
+uripath/cli/read.py,sha256=Ar74NiUhQ3AlnjgSl7AmUUq4-pjqA5GA3hVL2AbYN4k,512
+uripath/cli/rm.py,sha256=l_TMgkD4czzLMke4abVcp99a-HcoM8DPrtoeDO9-L6Y,978
+uripath/cli/sync.py,sha256=XbWWJ31UOEhaF2tdU6UTf9PD25HsBW6urgwpTis6kwA,2491
+uripath/cli/write.py,sha256=FCTr5_A7eU2PfF5salIRgnXG4A28Pcn7zcTbj90QkDQ,1379
+uripath/schemes/__init__.py,sha256=MnXUo9bxMbpM51tB3CGgAl-Sh9G3kiFt8W2Yk_YSaMk,3892
+uripath/schemes/_archive.py,sha256=aY-FXbwIz2ZwxcxfJxy39hPlBG9KC75Z1PQ7kv-gm1M,15196
+uripath/schemes/_data.py,sha256=Izob7ZXE9Tteb6uvwgpvkOnKTHdm_B2JNjoOnWsGL5c,3827
+uripath/schemes/_dav.py,sha256=mPlUEZRALzDnCdEUTBM5bO5lmYt01YiOrHRfZpUpM6Q,18388
+uripath/schemes/_delegate.py,sha256=Ajb-fOYYZHgU7LGPcqJnX2wLz1YKj6hITRS6DQKUHsU,4034
+uripath/schemes/_elsewhere.py,sha256=SdSDelq1CQSg7GLAxlwZTs0Zeu6tWrilYTaSrlXRQTY,3098
+uripath/schemes/_file.py,sha256=0R3BO0vJfuHqjO0mf5faoLVh_mJot2NksrxYvkq1MUA,7265
+uripath/schemes/_ftp.py,sha256=7CFw4gY2E6hAqTp5sMLrENokFCiY3MWUUZHHveaIsnQ,7426
+uripath/schemes/_httpdate.py,sha256=71fB8KWcj5VtnBHgps6hnAYG84vbqsh5AXd68cjOQVY,2063
+uripath/schemes/_path.py,sha256=C-dI3-twVjizu1lC7rKfPf--RLLK-kxO9VCb1pITsq4,25876
+uripath/schemes/_registry.py,sha256=mZkCwuzY4CTDKjLV2eSnBr_1RuYQmvxvSlUbnLS7UKg,5029
+uripath/schemes/_http/__init__.py,sha256=ZrjSeXjblag0YAROTLfqo7yi_TFYw7ge8ZlAdaDAhYk,168
+uripath/schemes/_http/_backend.py,sha256=l4BLGz4AB4wlsZGLHsRLGbZehvtFKA86eO_GGNC_0eo,4978
+uripath/schemes/_http/_headers.py,sha256=pxyZUXH4uZWVBkL5Pwpwzm_IB7F3L_H7-Ej3rB8aDlM,358
+uripath/schemes/_http/_listing.py,sha256=ZtClzN2VjcXf2EGl53OR12UHG4aqDvth3z8ewivPm-4,15133
+uripath/schemes/_http/_path.py,sha256=oKgniub6kXplC9KxDHbVmma0mZ2zhIUwrEgUi8aCDUQ,15256
+uripath/schemes/_http/_settings.py,sha256=1n25z94FdEeE2jZAzYdBwp9NECBLUOfEIaM2nRFek8Q,228
+uripath/schemes/_http/_streams.py,sha256=de4Fl_wYQLhkFjc3Sa--pFt6QFkdcBFWbp0lT1AotFU,8083
+uripath/source/__init__.py,sha256=UlQeQ5g2TEcdHCdnT69mcHQIuLAsW1rjU6lkDFZaAoc,497
+uripath/source/_compose.py,sha256=PVe5OSzGY8GRXBW71QXyU7j7aNbJrdnDlxrARDppCAc,7955
+uripath/source/_locality.py,sha256=rDHKH1-EtfMshVCpUed9NzZqtffNO-gsTUYbbailS9I,1548
+uripath/source/_parse.py,sha256=lGi-LZhGZnIr79CEIU-Z6t-Uu375eXBioQ9PKXaUROc,7287
+uripath/source/_source.py,sha256=mmVsH-edCrawTH8_20HI6e5tCg1tH8yFSbuqE5xoOEs,9914
+uripath/README.md,sha256=C3klhOStQ3YOL5_s03jAVgegynFqFQtcUo5d8QZ9cH4,9848
+pathapi_uri-0.1.0.dist-info/METADATA,sha256=EzetO7NjuCYhtvlJJtytHsFr9dpNV_ey-D29aMQ-LuI,11659
+pathapi_uri-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pathapi_uri-0.1.0.dist-info/entry_points.txt,sha256=xQUo69cFOuRvN13oVKcdfQ_SxDIkipjAZQ83g6ihG4o,542
+pathapi_uri-0.1.0.dist-info/licenses/LICENSE,sha256=bBY0SeXglEP0yGEOZbyqRTbNfXD0DVpkr-3mBq7-BPQ,1063
+pathapi_uri-0.1.0.dist-info/RECORD,,

pathapi_uri-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

pathapi_uri-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,17 @@
+[console_scripts]
+uripath = uripath.cli:main
+
+[uripath.schemes]
+archive = uripath.schemes:ArchiveURIPath
+archive+tar = uripath.schemes:ArchiveTarURIPath
+archive+zip = uripath.schemes:ArchiveZipURIPath
+data = uripath.schemes:DataURIPath
+dav = uripath.schemes:DAVURIPath
+davs = uripath.schemes:DAVURIPath
+file = uripath.schemes:FileURIPath
+ftp = uripath.schemes:FTPURIPath
+ftps = uripath.schemes:FTPURIPath
+http = uripath.schemes:HTTPURIPath
+https = uripath.schemes:HTTPURIPath
+tar = uripath.schemes:TarURIPath
+zip = uripath.schemes:ZipURIPath

pathapi_uri-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.