repopath 0.1.0__tar.gz

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

repopath-0.1.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# 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 `repopath`: the `github:`, `gitlab:` and `git:` schemes of
+`pathlib-next` 0.9 (`pathlib_next.uri.schemes`) as a distribution of their own, and as
+paths that need no URI. It needs Python 3.9 or newer and `pathapi>=0.1.0,<0.2`,
+and nothing else; its one extra, `uri`, adds `pathapi-uri>=0.1.0,<0.2` and with it the
+schemes. Under *Changed*, the migration from `pathlib-next` comes in this order: the
+table of names, the table of URIs, 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
+
+- `RepoPath`, `GitHubPath` and `GitLabPath`: read-only `pathapi.Path` classes for a
+  repository tree on GitHub (and GitHub Enterprise) or GitLab (and self-hosted GitLab),
+  over the services' REST APIs, with no URI and no library beyond `pathapi`.
+  `GitHubPath("src/x.py", owner="acme", repo="widgets", ref="v1.2", instance="github.com",
+  token=None, backend=None)`; `GitLabPath` takes the same keywords and an owner that may
+  be a group path (`"acme/team"`).
+- `repo_owner`, the property of a path and of a URI path that names the account or group
+  that owns the repository. It is not called `owner`, the name `pathlib.Path.owner()` has for
+  the user that owns a file.
+- `RepoPath(*segments, instance=..., type=None, **options)` returns a `GitHubPath` or a
+  `GitLabPath`: `type` names the kind (`"github"`, `"gitlab"`), and without it the kind
+  is detected from `instance` (`github.com` and `gitlab.com`, in any case, with or
+  without `www.`). Any other instance without `type` is a `ValueError` that lists the
+  choices. `RepoPath.kinds()` lists the registered kinds, and a kind of your own is a
+  subclass whose class body sets `TYPE` and `INSTANCES`.
+- `repopath.uri`, for `uripath`: `RepoURIPath` (the `repo:` scheme, with the kind
+  detected from the host), `GitHubURIPath` (`github:`) and `GitLabURIPath` (`gitlab:`),
+  which delegate to the paths above. The entry points are declared whether or not
+  `uripath` is installed, and `import repopath` never imports it. Importing
+  `repopath.uri` without `uripath` raises an `ImportError` that names
+  `pip install "repopath[uri]"`.
+- `repopath.exceptions`: `RepoPathError`, the base of what this package raises on its
+  own, with `RateLimitError` (also a `BlockingIOError`, errno `EAGAIN`) and
+  `BadReplyError` (also an `OSError`, errno `EIO`); `InsecureTransportWarning` is there
+  too.
+- `RepoBackend` and `BaseRepoBackend` are in `repopath`. `RepoBackend` is a context
+  manager and sends through `pathapi.http`.
+
+### Changed
+
+- The names. `pathlib_next.uri.schemes` named the classes of the three schemes with a
+  `Path` suffix:
+
+  | Was | Is now |
+  | --- | --- |
+  | `schemes.github.GitHubPath` (`github:`) | `repopath.uri.GitHubURIPath`; the path that needs no URI is `repopath.GitHubPath` |
+  | `schemes.gitlab.GitLabPath` (`gitlab:`) | `repopath.uri.GitLabURIPath`; without a URI, `repopath.GitLabPath` |
+  | `schemes.git.GitPath` (`git:`) | `repopath.uri.RepoURIPath` (`repo:`); without a URI, `repopath.RepoPath` |
+  | `schemes.git.GitHubGitPath`, `GitLabGitPath` (`git+github:`, `git+gitlab:`) | `repopath.uri.GitHubURIPath`, `GitLabURIPath` (`github:`, `gitlab:`) |
+  | `schemes.github.RepoBackend`; `schemes._gitrepo.BaseRepoBackend` | `repopath.RepoBackend`, `BaseRepoBackend` |
+  | `schemes.github.InsecureTransportWarning` (also in `schemes.gitlab`) | `repopath.InsecureTransportWarning` |
+  | `pathlib-next[uri]`, `pathlib-next[http]` | `repopath[uri]` |
+
+- The URIs. `git:`, `git+github:` and `git+gitlab:` do not exist any more, and `uripath`
+  treats a URI of one of them as a path of an unknown scheme. What to do: rewrite the
+  URIs.
+
+  | Was | Is now |
+  | --- | --- |
+  | `git://github.com/o/r/f`, `git://gitlab.com/o/r/f` | `repo://github.com/o/r/f`, `repo://gitlab.com/o/r/f` (the kind is detected from the host) |
+  | `git+github://host/o/r/f` | `github://host/o/r/f` |
+  | `git+gitlab://host/o/r/f` | `gitlab://host/o/r/f` |
+  | `github://host/o/r/f`, `gitlab://host/o/r/f` | the same text |
+
+  `repo://` with a host that is not `github.com` or `gitlab.com` raises `URISyntaxError`
+  (a `ValueError`), as `git://` did, and names `github://host/...` and
+  `gitlab://host/...`.
+- A path that has an owner and a repository is built from them, not from a URI:
+  `GitHubPath("src/x.py", owner="acme", repo="widgets")`. The URI classes keep the
+  properties `repo_owner`, `repo`, `repo_path` and `ref`, and have `instance` and `kind`.
+- Rate limits and replies of the wrong shape have classes of their own. Was:
+  `OSError(EAGAIN)` and `OSError(EIO)`. Is: `RateLimitError` and `BadReplyError`, which
+  are those `OSError` types and carry the path as `filename`. What to do: nothing;
+  catch `RepoPathError` to catch both.
+- An error raised through a URI path names the URI in its message, whatever scheme
+  spelling built the path.
+- A URI that holds no owner and no repository (`github://github.com/acme`) is a path that
+  does not exist (`FileNotFoundError`, `exists()` is `False`) and no request is sent. Was:
+  a request for a repository with an empty name.
+- An owner or a repository that is empty, is a `.` or `..`, or (for `GitHubPath`) holds a
+  `/` is refused by the constructor with `ValueError`. Was: refused when the API URL was
+  built.
+- `is_local()` of a URI path of these schemes is `False` without resolving the host.
+  Was: the host name was looked up.
+- Requests send `User-Agent: repopath/<version>` instead of `User-Agent: pathlib-next`;
+  the version is `repopath.__version__`. A backend's `headers=` still replaces it.
+- The `requests` HTTP transport is provided by `pathapi-requests`.
+  `RepoBackend(session=...)` and `RepoBackend(**requests_args)` raise an `ImportError`
+  naming that distribution without it. What to do: install `pathapi-requests`
+  where one of them is used; with it installed they send through its transport and
+  nothing else is configured.
+- `uritools` is not a dependency of anything here, and `requests` is not installed with
+  the package.
+
+[Unreleased]: https://github.com/jose-pr/repopath/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jose-pr/repopath/releases/tag/v0.1.0

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

repopath-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: repopath
+Version: 0.1.0
+Summary: pathlib-style, read-only paths for the repository trees of GitHub and GitLab, and the repo:, github: and gitlab: schemes for uripath
+Project-URL: Homepage, https://github.com/jose-pr/repopath/
+Project-URL: Documentation, https://jose-pr.github.io/repopath/
+Project-URL: Issues, https://github.com/jose-pr/repopath/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: pathapi-uri<0.2,>=0.1.0; extra == 'all'
+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: uri
+Requires-Dist: pathapi-uri<0.2,>=0.1.0; extra == 'uri'
+Description-Content-Type: text/markdown
+
+# repopath
+
+[![Version](https://img.shields.io/pypi/v/repopath.svg)](https://pypi.org/project/repopath/)
+[![Python versions](https://img.shields.io/pypi/pyversions/repopath.svg)](https://pypi.org/project/repopath/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/repopath/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/repopath/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/repopath/test.yml)](https://github.com/jose-pr/repopath/actions/workflows/test.yml)
+
+**`pathlib` for the repository trees of GitHub and GitLab, read-only.**
+`GitHubPath("src/mod.py", owner="acme", repo="widgets", ref="v1.2")` has the method
+names, signatures and exception types of `pathlib.Path`, and `GitLabPath` does the same
+for GitLab; `RepoPath` is the class that returns either. None needs a URI, and all
+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 `repo:`, `github:` and `gitlab:` schemes. It is documented at
+<https://jose-pr.github.io/repopath/>.
+
+The classes are clients of the hosting services' REST APIs. They speak no git
+protocol: there is no clone, no commit and no `git:` URL, and the tree is read-only.
+
+## Features
+
+| Kind | Class | `type=` | Detected for | API |
+| --- | --- | --- | --- | --- |
+| GitHub and GitHub Enterprise | `GitHubPath` | `"github"` | `github.com` | contents API at `api.github.com`, or `https://<instance>/api/v3` |
+| GitLab and self-hosted GitLab | `GitLabPath` | `"gitlab"` | `gitlab.com` | REST API v4 at `https://<instance>/api/v4` |
+
+- **A `pathlib` path in a repository**: `open`, `read_text`, `iterdir`, `glob`, `stat`
+  and the rest, plus `walk`, `copy` out of the tree and `PathSyncer` as a source, from
+  `pathapi`. Nothing connects until the first request.
+- **One class for the kind**: `RepoPath("f", owner="acme", repo="widgets",
+  instance="github.com")` is a `GitHubPath`; another instance needs `type=`, and
+  `RepoPath.kinds()` lists the kinds. A kind is a subclass that registers itself.
+- **Cheap listings**: a directory is one request and each child carries the size and
+  type the listing gave, so `walk()` and `glob()` cost one request per directory;
+  `stat()` of a file is a `HEAD`. Listings past GitHub's 1,000-entry cap and GitLab's
+  pages are read to the end.
+- **Authentication that stays out of sight**: `token=` is sent as a bearer token to the
+  API's own origin only, and shown by no `str()`, `repr()`, pickle or error message. A
+  token over plain `http://` to another host warns.
+- **No library to install**: requests go through `pathapi.http`, on the standard
+  library, with a replaceable transport. Errors are the `OSError` types `pathlib` raises,
+  `RateLimitError` (a `BlockingIOError`) for a rate limit and `BadReplyError` for a reply
+  that is not the shape the API documents.
+- **The `repo:`, `github:` and `gitlab:` schemes** for `uripath`:
+  `URIPath("github://github.com/acme/widgets/src/mod.py?ref=v1.2")` is a
+  `GitHubURIPath` that delegates to a `GitHubPath`.
+
+## Installation
+
+```bash
+pip install repopath
+```
+
+Requires `pathapi`, which pip installs with it, and Python 3.9 or newer.
+
+| Install | Adds |
+| --- | --- |
+| `pip install repopath` | the paths and the backends; no other library |
+| `pip install "repopath[uri]"` | `uripath` and with it the `repo:`, `github:` and `gitlab:` schemes |
+| `pip install "repopath[all]"` | all of the above |
+
+## Quick start
+
+**A path in a repository**: the owner and repository are keywords, the segments are the
+path inside it, and `ref` is a branch, a tag or a commit:
+
+<!-- example: skip: reads from GitHub -->
+```python
+from repopath import GitHubPath
+
+readme = GitHubPath("README.md", owner="psf", repo="requests")
+print(readme.read_text()[:200])
+for child in readme.parent.iterdir():
+    print(child.name, child.is_dir())
+```
+
+**Another kind, or another instance**: `instance` names the server, `type` the kind when
+the instance does not tell, and `token` is the credential:
+
+<!-- example: skip: reads from GitLab -->
+```python
+from repopath import GitLabPath, RepoPath
+
+doc = RepoPath("doc", owner="gitlab-org", repo="gitlab", instance="gitlab.com")
+private = RepoPath(
+    "src", owner="team/tools", repo="app", instance="git.example.org",
+    type="gitlab", token="glpat-...",
+)
+assert isinstance(doc, GitLabPath)
+```
+
+**Copy a tree** out of a repository with `pathapi`:
+
+<!-- example: skip: reads from GitHub -->
+```python
+from pathapi import LocalPath
+from repopath import GitHubPath
+
+GitHubPath("docs", owner="psf", repo="requests", ref="main").copy(
+    LocalPath("docs-copy"), recursive=True
+)
+```
+
+**The schemes**, with `uripath` installed:
+
+<!-- example: skip: reads from GitHub -->
+```python
+from uripath import URIPath
+
+print(URIPath("repo://github.com/psf/requests/README.md?ref=main").read_text()[:200])
+```
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `repopath` | `RepoPath`, `GitHubPath`, `GitLabPath`, the backends `RepoBackend` and `BaseRepoBackend`, the exceptions `RepoPathError`, `RateLimitError` and `BadReplyError`, the warning `InsecureTransportWarning` and `__version__` |
+| `repopath.exceptions` | The exceptions and the warning |
+| `repopath.uri` | `RepoURIPath`, `GitHubURIPath` and `GitLabURIPath`, the schemes of `uripath` (needs the `uri` extra) |
+
+The full reference is on the [documentation site](https://jose-pr.github.io/repopath/);
+an agent-oriented API summary ships inside the package as `repopath/AGENTS.md`.
+
+## Development
+
+```bash
+pip install -e ".[dev,all]"
+python -m pytest -q -rs
+```
+
+The tests send every request to a fake of the API on the loopback interface; none
+reaches another host. A test that needs `uripath` is skipped without it, 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/repopath/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/repopath/blob/main/CHANGELOG.md).
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](https://github.com/jose-pr/repopath/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/repopath/blob/main/LICENSE).

repopath-0.1.0/README.md

@@ -0,0 +1,152 @@
+# repopath
+
+[![Version](https://img.shields.io/pypi/v/repopath.svg)](https://pypi.org/project/repopath/)
+[![Python versions](https://img.shields.io/pypi/pyversions/repopath.svg)](https://pypi.org/project/repopath/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/repopath/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/repopath/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/repopath/test.yml)](https://github.com/jose-pr/repopath/actions/workflows/test.yml)
+
+**`pathlib` for the repository trees of GitHub and GitLab, read-only.**
+`GitHubPath("src/mod.py", owner="acme", repo="widgets", ref="v1.2")` has the method
+names, signatures and exception types of `pathlib.Path`, and `GitLabPath` does the same
+for GitLab; `RepoPath` is the class that returns either. None needs a URI, and all
+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 `repo:`, `github:` and `gitlab:` schemes. It is documented at
+<https://jose-pr.github.io/repopath/>.
+
+The classes are clients of the hosting services' REST APIs. They speak no git
+protocol: there is no clone, no commit and no `git:` URL, and the tree is read-only.
+
+## Features
+
+| Kind | Class | `type=` | Detected for | API |
+| --- | --- | --- | --- | --- |
+| GitHub and GitHub Enterprise | `GitHubPath` | `"github"` | `github.com` | contents API at `api.github.com`, or `https://<instance>/api/v3` |
+| GitLab and self-hosted GitLab | `GitLabPath` | `"gitlab"` | `gitlab.com` | REST API v4 at `https://<instance>/api/v4` |
+
+- **A `pathlib` path in a repository**: `open`, `read_text`, `iterdir`, `glob`, `stat`
+  and the rest, plus `walk`, `copy` out of the tree and `PathSyncer` as a source, from
+  `pathapi`. Nothing connects until the first request.
+- **One class for the kind**: `RepoPath("f", owner="acme", repo="widgets",
+  instance="github.com")` is a `GitHubPath`; another instance needs `type=`, and
+  `RepoPath.kinds()` lists the kinds. A kind is a subclass that registers itself.
+- **Cheap listings**: a directory is one request and each child carries the size and
+  type the listing gave, so `walk()` and `glob()` cost one request per directory;
+  `stat()` of a file is a `HEAD`. Listings past GitHub's 1,000-entry cap and GitLab's
+  pages are read to the end.
+- **Authentication that stays out of sight**: `token=` is sent as a bearer token to the
+  API's own origin only, and shown by no `str()`, `repr()`, pickle or error message. A
+  token over plain `http://` to another host warns.
+- **No library to install**: requests go through `pathapi.http`, on the standard
+  library, with a replaceable transport. Errors are the `OSError` types `pathlib` raises,
+  `RateLimitError` (a `BlockingIOError`) for a rate limit and `BadReplyError` for a reply
+  that is not the shape the API documents.
+- **The `repo:`, `github:` and `gitlab:` schemes** for `uripath`:
+  `URIPath("github://github.com/acme/widgets/src/mod.py?ref=v1.2")` is a
+  `GitHubURIPath` that delegates to a `GitHubPath`.
+
+## Installation
+
+```bash
+pip install repopath
+```
+
+Requires `pathapi`, which pip installs with it, and Python 3.9 or newer.
+
+| Install | Adds |
+| --- | --- |
+| `pip install repopath` | the paths and the backends; no other library |
+| `pip install "repopath[uri]"` | `uripath` and with it the `repo:`, `github:` and `gitlab:` schemes |
+| `pip install "repopath[all]"` | all of the above |
+
+## Quick start
+
+**A path in a repository**: the owner and repository are keywords, the segments are the
+path inside it, and `ref` is a branch, a tag or a commit:
+
+<!-- example: skip: reads from GitHub -->
+```python
+from repopath import GitHubPath
+
+readme = GitHubPath("README.md", owner="psf", repo="requests")
+print(readme.read_text()[:200])
+for child in readme.parent.iterdir():
+    print(child.name, child.is_dir())
+```
+
+**Another kind, or another instance**: `instance` names the server, `type` the kind when
+the instance does not tell, and `token` is the credential:
+
+<!-- example: skip: reads from GitLab -->
+```python
+from repopath import GitLabPath, RepoPath
+
+doc = RepoPath("doc", owner="gitlab-org", repo="gitlab", instance="gitlab.com")
+private = RepoPath(
+    "src", owner="team/tools", repo="app", instance="git.example.org",
+    type="gitlab", token="glpat-...",
+)
+assert isinstance(doc, GitLabPath)
+```
+
+**Copy a tree** out of a repository with `pathapi`:
+
+<!-- example: skip: reads from GitHub -->
+```python
+from pathapi import LocalPath
+from repopath import GitHubPath
+
+GitHubPath("docs", owner="psf", repo="requests", ref="main").copy(
+    LocalPath("docs-copy"), recursive=True
+)
+```
+
+**The schemes**, with `uripath` installed:
+
+<!-- example: skip: reads from GitHub -->
+```python
+from uripath import URIPath
+
+print(URIPath("repo://github.com/psf/requests/README.md?ref=main").read_text()[:200])
+```
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `repopath` | `RepoPath`, `GitHubPath`, `GitLabPath`, the backends `RepoBackend` and `BaseRepoBackend`, the exceptions `RepoPathError`, `RateLimitError` and `BadReplyError`, the warning `InsecureTransportWarning` and `__version__` |
+| `repopath.exceptions` | The exceptions and the warning |
+| `repopath.uri` | `RepoURIPath`, `GitHubURIPath` and `GitLabURIPath`, the schemes of `uripath` (needs the `uri` extra) |
+
+The full reference is on the [documentation site](https://jose-pr.github.io/repopath/);
+an agent-oriented API summary ships inside the package as `repopath/AGENTS.md`.
+
+## Development
+
+```bash
+pip install -e ".[dev,all]"
+python -m pytest -q -rs
+```
+
+The tests send every request to a fake of the API on the loopback interface; none
+reaches another host. A test that needs `uripath` is skipped without it, 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/repopath/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/repopath/blob/main/CHANGELOG.md).
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](https://github.com/jose-pr/repopath/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/repopath/blob/main/LICENSE).

repopath-0.1.0/docs/api/exceptions.md

@@ -0,0 +1,11 @@
+# Exceptions
+
+`RepoPathError` 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; the two failures no builtin names are `RateLimitError`
+and `BadReplyError`.
+
+::: repopath.exceptions
+    options:
+      show_if_no_docstring: true
+      filters: ["!^_"]

repopath-0.1.0/docs/api/paths.md

@@ -0,0 +1,24 @@
+# Paths and backends
+
+The paths need no URI and no library beyond `pathapi`.
+
+`GitHubPath` and `GitLabPath` share a base class: the properties it defines
+(`owner`, `repo`, `ref`, `instance`, `repo_path`) are listed under each of them.
+
+::: repopath
+    options:
+      show_if_no_docstring: true
+      filters: ["!^_"]
+      inherited_members:
+        - repo_owner
+        - repo
+        - ref
+        - instance
+        - repo_path
+        - as_uri
+      members:
+        - RepoPath
+        - GitHubPath
+        - GitLabPath
+        - RepoBackend
+        - BaseRepoBackend

repopath-0.1.0/docs/api/uri.md

@@ -0,0 +1,15 @@
+# The `repo:`, `github:` and `gitlab:` schemes
+
+Needs `uripath`: `pip install "repopath[uri]"`.
+
+::: repopath.uri
+    options:
+      show_if_no_docstring: true
+      filters: ["!^_"]
+      inherited_members:
+        - kind
+        - instance
+        - repo_owner
+        - repo
+        - repo_path
+        - ref

repopath-0.1.0/docs/benchmarks.md

@@ -0,0 +1,58 @@
+# Benchmarks
+
+`repopath` includes a benchmark harness at `benchmarks/bench.py` that times `GitHubPath`,
+`GitLabPath` and `RepoPath`, and the `github:`, `gitlab:` and `repo:` schemes of `uripath`
+on the same operations. It needs only the `uri` extra for the URI classes:
+`pip install -e ".[dev,uri]"`.
+
+## Run It
+
+```bash
+python benchmarks/bench.py            # run the benchmarks
+python benchmarks/bench.py --help     # options; runs nothing
+python benchmarks/bench.py --suite pure
+```
+
+## 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 the pure-path operations
+take nine and the ones that send requests take five. The result schema and the committed
+results are described in
+[`benchmarks/README.md`](https://github.com/jose-pr/repopath/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
+
+- the pure-path operations (construct, join with `/`, `parent`, `str()`, `as_uri()`, `==`
+  and `hash()`, and the parse of a URI) on a backend that refuses every request
+- `stat()` of a file and of a directory, `iterdir()` of 100 entries and `read_bytes()` of a
+  small file
+- `walk()` of a tree of 197 files in 19 directories, and the number of requests it sends:
+  one per directory, none per file
+- GitLab's default-branch lookup: a `stat()` that has to look it up, and the number of
+  lookups over several reads when the paths share one backend and when they do not
+- each of the above through the path classes (metric groups `github`, `gitlab`, `repo`) and
+  through the URI classes (`github-uri`, `gitlab-uri`, `repo-uri`), so the cost of the URI
+  layer is the difference between the two groups
+
+## Caveats
+
+The API is a loopback fake in the benchmark's own process, with no network latency, so the
+numbers show the overhead of the path layer and of the fake, not how a hosting service
+behaves over a link. The fake reads its whole tree from disk on every request, so a
+request costs the same few milliseconds whatever the path layer does: the timings of the
+operations that send requests are mostly that, and the request counts show the difference a
+change makes. Timings depend on the machine, the interpreter and what else is running;
+compare medians, as described above.

repopath-0.1.0/docs/changelog.md

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