sftppath 0.1.0__tar.gz

sftppath-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/

sftppath-0.1.0/CHANGELOG.md

@@ -0,0 +1,104 @@
+# 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 `sftppath`: the SFTP support of `pathlib-next` 0.9.14
+(`pathlib_next.uri.schemes.sftp`) as a distribution of its own, with a path that
+needs no URI. It needs Python 3.9 or newer and `pathapi>=0.1.0,<0.2`.
+Neither SSH library is required to import it: the extras `paramiko`
+(`paramiko>=5.0,<6`) and `asyncssh` (`asyncssh>=2.20.0`, below 3) add one, and
+`uri` (`pathapi-uri>=0.1.0,<0.2`) adds the `sftp:` scheme. With neither SSH library a
+path can still be built, joined and compared, and its first request raises an
+`ImportError` that names both extras; naming `SFTPBackend` or `AsyncSSHBackend`
+without its library raises one that names its extra. Under *Changed*, the
+migration from `pathlib_next.uri.schemes.sftp` 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
+
+- `SFTPPath`, a `pathapi.Path` for a directory tree on an SFTP server, built
+  from keywords: `SFTPPath("/srv/x", host="h", port=2222, user="u", password="p")`.
+  Nothing connects until the first request. `backend=` shares one connection
+  between paths built separately; a path joined from another keeps its backend.
+- `SFTPBackend` (paramiko), `AsyncSSHBackend` (asyncssh), `BaseSFTPBackend` and
+  `CheckFileSFTPBackend`, each the connections to one server and account. Every
+  backend is a context manager, `close()` returns when the connections are
+  closed, and may be called twice. `SFTPEndpoint`, `DEFAULT_PORT` and
+  `DEFAULT_SSH_CONFIG` are exported too.
+- `sftppath.exceptions`: `SFTPPathError`, a `pathapi.PathError`, with
+  `SFTPAuthenticationError` (also `PermissionError`) and `SFTPHostKeyError`
+  (also `ConnectionError`).
+- `sftppath.uri`: `SFTPURIPath`, the `sftp:` scheme of `uripath`, found by
+  `uripath` through the entry point `sftp` of the group `uripath.schemes`, and
+  `SFTPURIBackend`, which builds the backend of each server a URI names. Importing
+  `sftppath.uri` without `uripath` raises an `ImportError` that names
+  `pip install "sftppath[uri]"`; `import sftppath` never imports `uripath`.
+- `SFTPPath.is_local()`: true for a loopback address, `localhost` and a backend
+  with no host, so `PathSyncer(quick_check=True)` applies to a real server.
+- `sftppath.__version__`, read from the installed metadata.
+
+### Changed
+
+- The names. `pathlib_next.uri.schemes.sftp` is gone with no alias.
+
+  | Was | Now |
+  | --- | --- |
+  | `SftpPath` (a `UriPath`) | `sftppath.SFTPPath` for a path built from keywords; `sftppath.uri.SFTPURIPath` for `URIPath("sftp://...")` |
+  | `SftpBackend` | `sftppath.SFTPBackend` |
+  | `AsyncsshSftpBackend` | `sftppath.AsyncSSHBackend` |
+  | `BaseSftpBackend` | `sftppath.BaseSFTPBackend` |
+  | `CheckFileSftpBackend` | `sftppath.CheckFileSFTPBackend` |
+  | `SftpAuthenticationError`, `SftpHostKeyError` | `sftppath.SFTPAuthenticationError`, `sftppath.SFTPHostKeyError` (in `sftppath.exceptions`) |
+  | `_DEFAULT_SSH_CONFIG` | `sftppath.DEFAULT_SSH_CONFIG` |
+  | `PATHLIB_NEXT_SFTP_BACKEND` | `SFTPPATH_BACKEND`; the old variable is not read |
+  | the logger `pathlib_next.sftp` | the logger `sftppath` |
+  | the entry-point group `pathlib_next.schemes`, entry `sftp` | the group `uripath.schemes`, entry `sftp = "sftppath.uri:SFTPURIPath"` |
+
+- What to install where `pathlib-next` had an extra. `pathlib-next` 0.10 has no
+  `sftp` or `sftp-async` extra.
+
+  | Was | Install now |
+  | --- | --- |
+  | `pathlib-next[sftp]` | `sftppath[paramiko]` |
+  | `pathlib-next[sftp-async]` | `sftppath[asyncssh]` |
+  | either, for `UriPath("sftp://...")` | add `sftppath[uri]` (or install `uripath` beside it) |
+
+- A backend is the connections to one server and account. Was: one backend
+  served every host a path named, and `client(source)`, `opts(source)` and
+  `transport(source)` took the `Source` of the URI; a backend was built with its
+  options only (`SftpBackend(connect_opts, hostkeypolicy, ...)`). Now the host,
+  port, user and password are arguments of the backend
+  (`SFTPBackend("h", 2222, user="u", password="p", connect_opts=...)`,
+  `AsyncSSHBackend("h", ...)`), and `client()`, `opts()` and `transport()` take
+  nothing. A `BaseSFTPBackend` subclass overrides `client(self)`. For URI paths,
+  give `backend=` an `SFTPURIBackend(SFTPBackend, connect_opts=...)` (the
+  options of the backend class; the user, password and port come from the URI)
+  or a `BaseSFTPBackend` for the one server. `BaseSftpBackend.default()` and the
+  `default(ssh_config=)` classmethods are removed.
+- A relative or empty path is read from the server root. Was: `sftp://host` (no
+  path) listed the home directory of the account. Now it is `/`, and
+  `SFTPPath("x", host=h)` is `/x`. Name the directory you mean
+  (`/home/user`).
+- `SFTPPath.readlink()` returns a path on the same backend, so dot segments of
+  the target collapse as they do for `pathlib`. The `SFTPURIPath` keeps the text
+  verbatim in `.path`.
+- `SFTPPath.iterdir()` yields children without the attributes the listing
+  carried, so `is_dir()` on each costs a request; `walk()`, `glob()` and
+  `rm(recursive=True)` still use the listing. The children an `SFTPURIPath`
+  yields carry them, as before.
+- An error that has a file name and no second one prints only the first; it
+  printed `-> None` after it.
+
+[Unreleased]: https://github.com/jose-pr/sftppath/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jose-pr/sftppath/releases/tag/v0.1.0

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

sftppath-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.5
+Name: sftppath
+Version: 0.1.0
+Summary: pathlib-style paths for SFTP servers, on paramiko or asyncssh, and the sftp: scheme for uripath
+Project-URL: Homepage, https://github.com/jose-pr/sftppath/
+Project-URL: Documentation, https://jose-pr.github.io/sftppath/
+Project-URL: Issues, https://github.com/jose-pr/sftppath/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: asyncssh<2.22,>=2.20.0; (python_version < '3.10') and extra == 'all'
+Requires-Dist: asyncssh<3,>=2.20.0; (python_version >= '3.10') and extra == 'all'
+Requires-Dist: paramiko<6,>=5.0; extra == 'all'
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 'all'
+Provides-Extra: asyncssh
+Requires-Dist: asyncssh<2.22,>=2.20.0; (python_version < '3.10') and extra == 'asyncssh'
+Requires-Dist: asyncssh<3,>=2.20.0; (python_version >= '3.10') and extra == 'asyncssh'
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; 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: paramiko
+Requires-Dist: paramiko<6,>=5.0; extra == 'paramiko'
+Provides-Extra: uri
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 'uri'
+Description-Content-Type: text/markdown
+
+# sftppath
+
+[![Version](https://img.shields.io/pypi/v/sftppath.svg)](https://pypi.org/project/sftppath/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sftppath.svg)](https://pypi.org/project/sftppath/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/sftppath/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/sftppath/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/sftppath/test.yml)](https://github.com/jose-pr/sftppath/actions/workflows/test.yml)
+
+**`pathlib` for SFTP servers.** `SFTPPath("/srv/data/report.txt", host="files.example.org")`
+has the method names, signatures and exception types of `pathlib.Path`, over
+paramiko or asyncssh, and needs no URI. It builds on
+[`pathapi`](https://github.com/jose-pr/pathapi) alone; with
+[`uripath`](https://github.com/jose-pr/uripath) installed it also provides the
+`sftp:` scheme. It is documented at <https://jose-pr.github.io/sftppath/>.
+
+## Features
+
+- **A `pathlib` path on a server**: `open`, `read_text`, `iterdir`, `glob`,
+  `stat`, `mkdir`, `rename`, `replace`, `chmod`, `symlink_to`, `readlink` and
+  the rest, plus `walk`, `copy`, `move`, `rm` and `PathSyncer` from
+  `pathapi`. Nothing connects until the first request.
+- **Two backends, one behaviour**: `SFTPBackend` (paramiko) and `AsyncSSHBackend`
+  (asyncssh) raise the same exceptions for the same server answers; the choice is
+  a keyword, a subclass attribute or `SFTPPATH_BACKEND`.
+- **Native tree operations**: on asyncssh a recursive `copy()` and `rm()` run as
+  concurrent requests on one connection, bounded by `max_concurrency`.
+- **ssh_config**: `HostName`, `Port`, `User`, `IdentityFile`, `ProxyCommand` and
+  `Include` apply to the host you name; host keys are verified.
+- **Server-side checksums**: `checksum()` uses the `check-file-handle`
+  extension where the server has it, and `PathSyncer` falls back to streaming
+  where it does not.
+- **No SSH library at import**: `import sftppath` loads neither library nor
+  `uripath`. Errors are `OSError` subclasses, `SFTPAuthenticationError` and
+  `SFTPHostKeyError`; no library exception crosses the API.
+- **The `sftp:` scheme** for `uripath`: `URIPath("sftp://user@host/dir")` is an
+  `SFTPURIPath` that delegates to an `SFTPPath`.
+
+## Installation
+
+```bash
+pip install "sftppath[paramiko]"
+```
+
+Requires `pathapi`, which pip installs with it, and Python 3.9 or newer.
+
+| Install | Adds |
+| --- | --- |
+| `pip install sftppath` | the path and the backend contract; no SSH library |
+| `pip install "sftppath[paramiko]"` | the paramiko backend (`paramiko>=5.0,<6`) |
+| `pip install "sftppath[asyncssh]"` | the asyncssh backend and the native tree operations (`asyncssh>=2.20`) |
+| `pip install "sftppath[uri]"` | `uripath` and with it the `sftp:` scheme |
+| `pip install "sftppath[all]"` | the three above |
+
+## Quick start
+
+**A path on a server**: the endpoint goes in as keywords; the user, password and
+port may come from your `~/.ssh/config` instead:
+
+<!-- example: skip: connects to a server -->
+```python
+from sftppath import SFTPPath
+
+report = SFTPPath("/srv/data/report.txt", host="files.example.org", user="deploy")
+print(report.read_text())
+for child in report.parent.iterdir():
+    print(child.name, child.stat().st_size)
+```
+
+**Share a connection**: a backend is the connections to one server and
+account, and a context manager:
+
+<!-- example: skip: connects to a server -->
+```python
+from sftppath import SFTPBackend, SFTPPath
+
+with SFTPBackend("files.example.org", user="deploy", timeout=10) as backend:
+    root = SFTPPath("/srv/data", backend=backend)
+    (root / "out").mkdir(exist_ok=True)
+    (root / "out" / "n.txt").write_text("1")
+    root.copy(SFTPPath("/srv/backup", backend=backend), recursive=True)
+```
+
+**Mirror a tree** with `PathSyncer`, onto a local directory:
+
+<!-- example: skip: connects to a server -->
+```python
+from pathapi import LocalPath
+from pathapi.sync import PathSyncer
+from sftppath import SFTPPath
+
+remote = SFTPPath("/var/log", host="files.example.org", user="deploy")
+PathSyncer(remove_missing=True).sync(remote, LocalPath("mirror"))
+```
+
+**The scheme**, with `uripath` installed:
+
+<!-- example: skip: connects to a server -->
+```python
+from uripath import URIPath
+
+print(URIPath("sftp://deploy@files.example.org/srv/data/report.txt").read_text())
+```
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `sftppath` | `SFTPPath`, the backends `SFTPBackend`, `AsyncSSHBackend`, `BaseSFTPBackend` and `CheckFileSFTPBackend`, `SFTPEndpoint`, `DEFAULT_PORT`, `DEFAULT_SSH_CONFIG`, the errors and `__version__` |
+| `sftppath.exceptions` | `SFTPPathError`, `SFTPAuthenticationError` and `SFTPHostKeyError` |
+| `sftppath.uri` | `SFTPURIPath` and `SFTPURIBackend`, the `sftp:` scheme of `uripath` (needs the `uri` extra) |
+
+The full reference is on the [documentation site](https://jose-pr.github.io/sftppath/);
+an agent-oriented API summary ships inside the package as `sftppath/AGENTS.md`.
+
+## Development
+
+```bash
+pip install -e ".[dev,all]"
+python -m pytest -q -rs
+```
+
+The tests start SSH servers of their own on the loopback interface with
+throwaway keys; they never reach another host. A test for a library or 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/sftppath/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/sftppath/blob/main/CHANGELOG.md).
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](https://github.com/jose-pr/sftppath/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/sftppath/blob/main/LICENSE).

sftppath-0.1.0/README.md

@@ -0,0 +1,143 @@
+# sftppath
+
+[![Version](https://img.shields.io/pypi/v/sftppath.svg)](https://pypi.org/project/sftppath/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sftppath.svg)](https://pypi.org/project/sftppath/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/sftppath/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/sftppath/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/sftppath/test.yml)](https://github.com/jose-pr/sftppath/actions/workflows/test.yml)
+
+**`pathlib` for SFTP servers.** `SFTPPath("/srv/data/report.txt", host="files.example.org")`
+has the method names, signatures and exception types of `pathlib.Path`, over
+paramiko or asyncssh, and needs no URI. It builds on
+[`pathapi`](https://github.com/jose-pr/pathapi) alone; with
+[`uripath`](https://github.com/jose-pr/uripath) installed it also provides the
+`sftp:` scheme. It is documented at <https://jose-pr.github.io/sftppath/>.
+
+## Features
+
+- **A `pathlib` path on a server**: `open`, `read_text`, `iterdir`, `glob`,
+  `stat`, `mkdir`, `rename`, `replace`, `chmod`, `symlink_to`, `readlink` and
+  the rest, plus `walk`, `copy`, `move`, `rm` and `PathSyncer` from
+  `pathapi`. Nothing connects until the first request.
+- **Two backends, one behaviour**: `SFTPBackend` (paramiko) and `AsyncSSHBackend`
+  (asyncssh) raise the same exceptions for the same server answers; the choice is
+  a keyword, a subclass attribute or `SFTPPATH_BACKEND`.
+- **Native tree operations**: on asyncssh a recursive `copy()` and `rm()` run as
+  concurrent requests on one connection, bounded by `max_concurrency`.
+- **ssh_config**: `HostName`, `Port`, `User`, `IdentityFile`, `ProxyCommand` and
+  `Include` apply to the host you name; host keys are verified.
+- **Server-side checksums**: `checksum()` uses the `check-file-handle`
+  extension where the server has it, and `PathSyncer` falls back to streaming
+  where it does not.
+- **No SSH library at import**: `import sftppath` loads neither library nor
+  `uripath`. Errors are `OSError` subclasses, `SFTPAuthenticationError` and
+  `SFTPHostKeyError`; no library exception crosses the API.
+- **The `sftp:` scheme** for `uripath`: `URIPath("sftp://user@host/dir")` is an
+  `SFTPURIPath` that delegates to an `SFTPPath`.
+
+## Installation
+
+```bash
+pip install "sftppath[paramiko]"
+```
+
+Requires `pathapi`, which pip installs with it, and Python 3.9 or newer.
+
+| Install | Adds |
+| --- | --- |
+| `pip install sftppath` | the path and the backend contract; no SSH library |
+| `pip install "sftppath[paramiko]"` | the paramiko backend (`paramiko>=5.0,<6`) |
+| `pip install "sftppath[asyncssh]"` | the asyncssh backend and the native tree operations (`asyncssh>=2.20`) |
+| `pip install "sftppath[uri]"` | `uripath` and with it the `sftp:` scheme |
+| `pip install "sftppath[all]"` | the three above |
+
+## Quick start
+
+**A path on a server**: the endpoint goes in as keywords; the user, password and
+port may come from your `~/.ssh/config` instead:
+
+<!-- example: skip: connects to a server -->
+```python
+from sftppath import SFTPPath
+
+report = SFTPPath("/srv/data/report.txt", host="files.example.org", user="deploy")
+print(report.read_text())
+for child in report.parent.iterdir():
+    print(child.name, child.stat().st_size)
+```
+
+**Share a connection**: a backend is the connections to one server and
+account, and a context manager:
+
+<!-- example: skip: connects to a server -->
+```python
+from sftppath import SFTPBackend, SFTPPath
+
+with SFTPBackend("files.example.org", user="deploy", timeout=10) as backend:
+    root = SFTPPath("/srv/data", backend=backend)
+    (root / "out").mkdir(exist_ok=True)
+    (root / "out" / "n.txt").write_text("1")
+    root.copy(SFTPPath("/srv/backup", backend=backend), recursive=True)
+```
+
+**Mirror a tree** with `PathSyncer`, onto a local directory:
+
+<!-- example: skip: connects to a server -->
+```python
+from pathapi import LocalPath
+from pathapi.sync import PathSyncer
+from sftppath import SFTPPath
+
+remote = SFTPPath("/var/log", host="files.example.org", user="deploy")
+PathSyncer(remove_missing=True).sync(remote, LocalPath("mirror"))
+```
+
+**The scheme**, with `uripath` installed:
+
+<!-- example: skip: connects to a server -->
+```python
+from uripath import URIPath
+
+print(URIPath("sftp://deploy@files.example.org/srv/data/report.txt").read_text())
+```
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `sftppath` | `SFTPPath`, the backends `SFTPBackend`, `AsyncSSHBackend`, `BaseSFTPBackend` and `CheckFileSFTPBackend`, `SFTPEndpoint`, `DEFAULT_PORT`, `DEFAULT_SSH_CONFIG`, the errors and `__version__` |
+| `sftppath.exceptions` | `SFTPPathError`, `SFTPAuthenticationError` and `SFTPHostKeyError` |
+| `sftppath.uri` | `SFTPURIPath` and `SFTPURIBackend`, the `sftp:` scheme of `uripath` (needs the `uri` extra) |
+
+The full reference is on the [documentation site](https://jose-pr.github.io/sftppath/);
+an agent-oriented API summary ships inside the package as `sftppath/AGENTS.md`.
+
+## Development
+
+```bash
+pip install -e ".[dev,all]"
+python -m pytest -q -rs
+```
+
+The tests start SSH servers of their own on the loopback interface with
+throwaway keys; they never reach another host. A test for a library or 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/sftppath/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/sftppath/blob/main/CHANGELOG.md).
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](https://github.com/jose-pr/sftppath/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/sftppath/blob/main/LICENSE).

sftppath-0.1.0/docs/api/exceptions.md

@@ -0,0 +1,10 @@
+# Exceptions
+
+`SFTPPathError` 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.
+
+::: sftppath.exceptions
+    options:
+      show_if_no_docstring: true
+      filters: ["!^_"]

sftppath-0.1.0/docs/api/sftp.md

@@ -0,0 +1,17 @@
+# SFTP paths
+
+::: sftppath
+    options:
+      show_if_no_docstring: true
+      filters: ["!^_"]
+      members:
+        - SFTPPath
+        - SFTPEndpoint
+        - BaseSFTPBackend
+        - CheckFileSFTPBackend
+        - DEFAULT_PORT
+        - DEFAULT_SSH_CONFIG
+
+::: sftppath.SFTPBackend
+
+::: sftppath.AsyncSSHBackend

sftppath-0.1.0/docs/api/uri.md

@@ -0,0 +1,8 @@
+# The `sftp:` scheme
+
+Needs `uripath`: `pip install "sftppath[uri]"`.
+
+::: sftppath.uri
+    options:
+      show_if_no_docstring: true
+      filters: ["!^_"]

sftppath-0.1.0/docs/benchmarks.md

@@ -0,0 +1,61 @@
+# Benchmarks
+
+`sftppath` includes a benchmark harness at `benchmarks/bench.py` that times
+`SFTPPath` over paramiko and over asyncssh, and the `sftp:` scheme of `uripath`
+on the same operations. It needs both SSH libraries and `uripath`:
+`pip install -e ".[dev,all]"`.
+
+## Run It
+
+```bash
+python benchmarks/bench.py            # run the benchmarks
+python benchmarks/bench.py --help     # options and suites; runs nothing
+```
+
+A suite name after the options runs part of the matrix: `sftp-batch`,
+`sftp-recursive`, `sftp-recursive-copy` or `sftp-recursive-large`.
+
+## 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 uses
+its own (1-5). The result schema, the suites and the committed results are
+described in
+[`benchmarks/README.md`](https://github.com/jose-pr/sftppath/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()`, listing (`iterdir()`), `walk()` and `glob()` of a small tree
+- `read_bytes()`, `write_bytes()` of 256 KiB, `mkdir()`, `rename()`, `unlink()`
+  and a single-file `copy()`
+- recursive `copy()` and `rm()` of 4-, 9- and 128-file trees, and the asyncssh
+  recursive copy at several `max_concurrency` values
+- a cold connect and `stat()` on a new backend
+- each of the above on a paramiko backend and on an asyncssh backend, and for
+  both through `SFTPPath` (metric group `sftp`) and through
+  `URIPath("sftp://...", backend=SFTPURIBackend(...))` (group `sftp-uri`), so
+  the cost of the URI layer is the difference between the two groups
+
+The cases run against an in-process asyncssh server on 127.0.0.1, so nothing
+leaves the machine. Without `uripath` the `sftp-uri` group is skipped and the
+run records why.
+
+## Caveats
+
+The server and the client share one machine and one interpreter, with no
+network latency, so the numbers show the overhead of a backend and of the path
+layer, not how a remote link behaves. Timings depend on the machine, the
+interpreter and what else is running; compare medians, as described above.

sftppath-0.1.0/docs/changelog.md

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

sftppath-0.1.0/docs/divergences.md

@@ -0,0 +1,24 @@
+# Divergences from `pathlib`
+
+`sftppath` targets `pathlib.Path` parity: same method names, signatures,
+semantics and exception types wherever a `pathlib.Path` equivalent exists.
+Extensions (extra optional kwargs, new methods like `rm()` and `copy()`) are
+allowed. Any *behavioral* divergence from `pathlib` on a method that exists in
+both must be listed here -- no silent divergence.
+
+The divergences below apply to `SFTPPath` and `SFTPURIPath`. The ones of the
+generic `Path` operations that every path inherits (`touch()` on a non-local
+backend, `rm()` and its policies, `chown()`, `Path.replace()`, a `with` block
+that raised while writing) are on the documentation site of `pathapi`,
+<https://jose-pr.github.io/pathapi/divergences/>.
+
+| Method | `pathlib` | `SFTPPath` | Why |
+| --- | --- | --- | --- |
+| A relative path, and the empty path | relative to the current working directory | names are read from the server root: `SFTPPath("x", host=h)` is `/x`, the empty path is `/` | A tree served by a backend has no working directory, and two spellings of one name must be one file (`==`, `copy()` and `move()` ask). |
+| `rename(target)` onto an existing file | POSIX `rename(2)`: replaces | Replaces through `posix-rename@openssh.com` where the server supports it; otherwise raises `FileExistsError`. | Plain SFTPv3 rename refuses an existing target with an uninformative failure. |
+| `rename(str)` | a relative `str` is relative to the current working directory | a `str` is a sibling name (relative to `self.parent`); an absolute one is a path on the same server | There is no working directory; a sibling is what a rename within a directory means. |
+| `replace(target)` onto an existing file | `os.replace` is one atomic call | One `posix-rename@openssh.com` request where the server has it (atomic; a refusal leaves both entries as they were). Without it the target is removed and then this entry renamed, so a failure between the two loses the target; a bare failure from the server is treated as the extension being absent. | Removing first left a window in which the target did not exist on every overwrite. |
+| `chmod(mode, follow_symlinks=False)` | supported where the platform has `lchmod` | `NotImplementedError` on the paramiko backend; supported on asyncssh | paramiko has no call for it. |
+| `hardlink_to(target)` | supported | `NotImplementedError` on the paramiko backend; supported on asyncssh, and only onto a path of the same server | SFTPv3 has no core hard-link operation. |
+| `chown(uid, gid)` | not a `pathlib` method | numeric ids only; a partial change reads the other field first and raises `NotImplementedError` when the server names owners instead of numbering them | SFTPv3 carries the owner as one numeric pair. |
+| `os.fspath()` of an `SFTPURIPath` | the local path | the path on the *server* (`.path`); `host_fspath()` says so | Meant for building a command line that runs on that host. `os.fspath()` of an `SFTPPath` is `NotImplementedError`. |