pathlib-next 0.3.5__tar.gz → 0.4.0__tar.gz

pathlib_next-0.4.0/.gitignore

@@ -0,0 +1,25 @@
+# Build/dist output and generated docs site
+dist/
+build/
+site/
+
+# Agent/harness tooling
+AGENTS.md
+.agents/
+CLAUDE.md
+CLAUDE.local.md
+.claude/
+
+# Python-specific
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+.venv/
+
+# Legacy project patterns
+/_*
+[a-zA-Z]*__
+[a-zA-Z]*__.*

pathlib_next-0.4.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# 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.4.0] - 2026-07-11
+
+### Added
+- Standardized repository layout and relocated examples to `examples/` directory.
+- Configured MkDocs documentation site with dynamic API reference using `mkdocstrings`.
+- Added GitHub Actions workflows for matrix testing (`test.yml`) and release pipelines (`release.yml`).
+- Added typing marker `py.typed` for PEP 561 compliance.
+
+### Changed
+- Added backward compatibility support for Python 3.9 and 3.10: added `from __future__ import annotations` across the codebase, refactored runtime-evaluated union types to use `typing.Union`, and provided fallbacks for `TypeAlias` and `ParamSpec`.
+- Updated package requirement to `requires-python = ">=3.9"`.
+
+## [0.3.5] - 2026-07-11
+
+### Added
+- Split path into protocols that can be standalone.
+- Sync error handling.
+- Generic Path Protocol based pathlib implementation for URI paths with file access support for sftp, http, file schemes.
+
+[Unreleased]: https://github.com/jose-pr/pathlib_next/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/jose-pr/pathlib_next/releases/tag/v0.4.0
+[0.3.5]: https://github.com/jose-pr/pathlib_next/releases/tag/v0.3.5

{pathlib_next-0.3.5 → pathlib_next-0.4.0}/LICENSE

@@ -1,21 +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.
+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.

pathlib_next-0.4.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: pathlib_next
+Version: 0.4.0
+Summary: Generic Path Protocol based pathlib
+Project-URL: Homepage, https://github.com/jose-pr/pathlib_next/
+Project-URL: Documentation, https://jose-pr.github.io/pathlib_next/
+Project-URL: Issues, https://github.com/jose-pr/pathlib_next/issues
+Author: Jose A
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest; 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: http
+Requires-Dist: bs4; extra == 'http'
+Requires-Dist: htmllistparse; extra == 'http'
+Requires-Dist: requests; extra == 'http'
+Requires-Dist: uritools; extra == 'http'
+Provides-Extra: sftp
+Requires-Dist: paramiko; extra == 'sftp'
+Requires-Dist: uritools; extra == 'sftp'
+Provides-Extra: uri
+Requires-Dist: uritools; extra == 'uri'
+Description-Content-Type: text/markdown
+
+# pathlib_next
+
+[![Version](https://img.shields.io/pypi/v/pathlib_next.svg)](https://pypi.org/project/pathlib_next/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pathlib_next.svg)](https://pypi.org/project/pathlib_next/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pathlib_next/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/pathlib_next/test.yml)](https://github.com/jose-pr/pathlib_next/actions/workflows/test.yml)
+
+Generic Path Protocol based pathlib implementation for URI paths with file access support for sftp, http, file schemes.
+
+## Features
+
+- **Unified URI Interface** — Access resources on sftp, http, or local file schemes using python's familiar pathlib syntax.
+- **In-memory filesystem** — `MemPath` provides a lightweight, virtual file system helper for mock files, testing, or transient storage.
+- **Path synchronization** — `PathSyncer` allows syncing directory structures across different paths with customizable checksums.
+- **Query & Source Parsing** — Parse and serialize complex URL query strings and URI sources easily.
+
+## Installation
+
+```bash
+pip install pathlib_next
+```
+
+Optional features/extras:
+
+| Extra/flag | Adds | Needed for |
+| --- | --- | --- |
+| `uri` | `uritools` | URI parsing capabilities |
+| `http` | `requests`, `bs4`, `htmllistparse` | Read and list files over HTTP/HTTPS |
+| `sftp` | `paramiko` | SFTP path operations and transfers |
+
+## Quick start
+
+### Unified Path Operations
+
+```python
+from pathlib_next import Path
+from pathlib_next.uri import UriPath
+
+# Use the unified path interface
+local_path = Path("./my_folder")
+http_path = UriPath("http://example.com/data.txt")
+
+# Read and print text if it exists
+if http_path.exists():
+    print(http_path.read_text())
+```
+
+## API overview
+
+| Module/Package | Purpose |
+| --- | --- |
+| `pathlib_next.path` | Base Path implementation and protocols |
+| `pathlib_next.uri` | URI/URL specific path support and Query utils |
+| `pathlib_next.mempath` | In-memory transient path structure |
+| `pathlib_next.utils.sync` | Synchronization functions and PathSyncer class |
+
+## Supported Python versions
+
+Python >= 3.9
+
+## Development
+
+See `AGENTS.md` (and the language-specific directive it points to, e.g. `PYTHON.md`)
+for environment setup, dependency install, and test commands.
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](CHANGELOG.md). Pushing a tag matching `v*` triggers the release
+workflow: test gate → build → publish → docs deploy (see `AGENTS.md`'s "Repository
+Structure" section and the language-specific CI/CD notes for the concrete jobs).
+
+### Documentation site
+
+MkDocs builds the API reference from `docs/`, published on every
+release. To preview locally: `mkdocs serve`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pathlib_next-0.4.0/README.md

@@ -0,0 +1,81 @@
+# pathlib_next
+
+[![Version](https://img.shields.io/pypi/v/pathlib_next.svg)](https://pypi.org/project/pathlib_next/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pathlib_next.svg)](https://pypi.org/project/pathlib_next/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pathlib_next/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/pathlib_next/test.yml)](https://github.com/jose-pr/pathlib_next/actions/workflows/test.yml)
+
+Generic Path Protocol based pathlib implementation for URI paths with file access support for sftp, http, file schemes.
+
+## Features
+
+- **Unified URI Interface** — Access resources on sftp, http, or local file schemes using python's familiar pathlib syntax.
+- **In-memory filesystem** — `MemPath` provides a lightweight, virtual file system helper for mock files, testing, or transient storage.
+- **Path synchronization** — `PathSyncer` allows syncing directory structures across different paths with customizable checksums.
+- **Query & Source Parsing** — Parse and serialize complex URL query strings and URI sources easily.
+
+## Installation
+
+```bash
+pip install pathlib_next
+```
+
+Optional features/extras:
+
+| Extra/flag | Adds | Needed for |
+| --- | --- | --- |
+| `uri` | `uritools` | URI parsing capabilities |
+| `http` | `requests`, `bs4`, `htmllistparse` | Read and list files over HTTP/HTTPS |
+| `sftp` | `paramiko` | SFTP path operations and transfers |
+
+## Quick start
+
+### Unified Path Operations
+
+```python
+from pathlib_next import Path
+from pathlib_next.uri import UriPath
+
+# Use the unified path interface
+local_path = Path("./my_folder")
+http_path = UriPath("http://example.com/data.txt")
+
+# Read and print text if it exists
+if http_path.exists():
+    print(http_path.read_text())
+```
+
+## API overview
+
+| Module/Package | Purpose |
+| --- | --- |
+| `pathlib_next.path` | Base Path implementation and protocols |
+| `pathlib_next.uri` | URI/URL specific path support and Query utils |
+| `pathlib_next.mempath` | In-memory transient path structure |
+| `pathlib_next.utils.sync` | Synchronization functions and PathSyncer class |
+
+## Supported Python versions
+
+Python >= 3.9
+
+## Development
+
+See `AGENTS.md` (and the language-specific directive it points to, e.g. `PYTHON.md`)
+for environment setup, dependency install, and test commands.
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](CHANGELOG.md). Pushing a tag matching `v*` triggers the release
+workflow: test gate → build → publish → docs deploy (see `AGENTS.md`'s "Repository
+Structure" section and the language-specific CI/CD notes for the concrete jobs).
+
+### Documentation site
+
+MkDocs builds the API reference from `docs/`, published on every
+release. To preview locally: `mkdocs serve`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pathlib_next-0.4.0/docs/api/reference.md

@@ -0,0 +1,3 @@
+# API Reference
+
+::: pathlib_next

pathlib_next-0.4.0/docs/changelog.md

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

pathlib_next-0.4.0/docs/index.md

@@ -0,0 +1,29 @@
+# pathlib_next
+
+Generic Path Protocol based pathlib implementation for URI paths with file access support for sftp, http, file schemes.
+
+For the full feature list, installation extras, quick-start examples for every
+integration, and known limitations, see the
+[project README](https://github.com/jose-pr/pathlib_next#readme). This site adds the
+generated [API reference](api/reference.md) and the [changelog](changelog.md).
+
+## Installation
+
+```bash
+pip install pathlib_next
+```
+
+## Quick start
+
+```python
+from pathlib_next import Path
+from pathlib_next.uri import UriPath
+
+# Use the unified path interface
+local_path = Path("./my_folder")
+http_path = UriPath("http://example.com/data.txt")
+
+# Read and print text if it exists
+if http_path.exists():
+    print(http_path.read_text())
+```

{pathlib_next-0.3.5/src → pathlib_next-0.4.0/examples}/example.py

@@ -1,70 +1,70 @@
-import os
-
-from pathlib_next import Path, glob
-from pathlib_next.mempath import MemPath
-from pathlib_next.uri import Query, Source, Uri, UriPath
-from pathlib_next.utils.sync import PathAndStat, PathSyncer
-
-rootless = Uri("sftp://root@sftpexample")
-rootless.source
-authkeys = rootless / "root/.ssh/authorized_keys"
-keys = authkeys.as_uri()
-
-local = Path("./_ssh")
-
-mempath = MemPath("test/test3") / "subpath"
-mempath.parent.mkdir(parents=True, exist_ok=True)
-mempath.write_text("test")
-check = mempath.read_text()
-mempath.parent.rm(recursive=True)
-
-query = Query({"test": "://$#!1", "test2&": [1, 2]})
-q2 = Query(str(query)).to_dict()
-for name, value in query:
-    print(f"{name}: {value}")
-src = Source(scheme="scheme", userinfo="user", host="123.com", port=0)
-test = {**src}
-test2 = [*src]
-dest = UriPath("file:./_ssh")
-
-#
-# Norm test
-#
-with_dots = UriPath("a/b/c/d/../../test/.")
-print(with_dots.normalized_path)
-
-source_host = UriPath("file://test.com/path1/path2/path3/path4")
-source_host.is_local()
-
-rel_to = source_host.relative_to("/path1/path2")
-dest = UriPath(dest)
-test_ = UriPath("file:") / "test"
-empty = UriPath()
-uri = dest.as_uri()
-
-test1 = dest / "test" / "test2/"
-print(test1)
-
-sftp_root = UriPath("sftp://root@sftpexample/")
-print(sftp_root.as_posix())
-authkeys = sftp_root / "root/.ssh/authorized_keys"
-print(authkeys.as_posix())
-
-
-def checksum(uri: PathAndStat):
-    stat = uri.stat
-    return hash(stat.st_size)
-
-
-syncer = PathSyncer(checksum, remove_missing=False)
-syncer.sync((sftp_root / "root/.ssh"), dest, dry_run=False)
-
-rocky_repo = UriPath("http://dl.rockylinux.org/pub")
-
-glob_test = UriPath("file:src/**/*.py")
-
-for path in glob.glob(glob_test, recursive=True):
-    print(path)
-
-print(rocky_repo.is_dir())
-print(list(rocky_repo.iterdir()))
+import os
+
+from pathlib_next import Path, glob
+from pathlib_next.mempath import MemPath
+from pathlib_next.uri import Query, Source, Uri, UriPath
+from pathlib_next.utils.sync import PathAndStat, PathSyncer
+
+rootless = Uri("sftp://root@sftpexample")
+rootless.source
+authkeys = rootless / "root/.ssh/authorized_keys"
+keys = authkeys.as_uri()
+
+local = Path("./_ssh")
+
+mempath = MemPath("test/test3") / "subpath"
+mempath.parent.mkdir(parents=True, exist_ok=True)
+mempath.write_text("test")
+check = mempath.read_text()
+mempath.parent.rm(recursive=True)
+
+query = Query({"test": "://$#!1", "test2&": [1, 2]})
+q2 = Query(str(query)).to_dict()
+for name, value in query:
+    print(f"{name}: {value}")
+src = Source(scheme="scheme", userinfo="user", host="123.com", port=0)
+test = {**src}
+test2 = [*src]
+dest = UriPath("file:./_ssh")
+
+#
+# Norm test
+#
+with_dots = UriPath("a/b/c/d/../../test/.")
+print(with_dots.normalized_path)
+
+source_host = UriPath("file://test.com/path1/path2/path3/path4")
+source_host.is_local()
+
+rel_to = source_host.relative_to("/path1/path2")
+dest = UriPath(dest)
+test_ = UriPath("file:") / "test"
+empty = UriPath()
+uri = dest.as_uri()
+
+test1 = dest / "test" / "test2/"
+print(test1)
+
+sftp_root = UriPath("sftp://root@sftpexample/")
+print(sftp_root.as_posix())
+authkeys = sftp_root / "root/.ssh/authorized_keys"
+print(authkeys.as_posix())
+
+
+def checksum(uri: PathAndStat):
+    stat = uri.stat
+    return hash(stat.st_size)
+
+
+syncer = PathSyncer(checksum, remove_missing=False)
+syncer.sync((sftp_root / "root/.ssh"), dest, dry_run=False)
+
+rocky_repo = UriPath("http://dl.rockylinux.org/pub")
+
+glob_test = UriPath("file:src/**/*.py")
+
+for path in glob.glob(glob_test, recursive=True):
+    print(path)
+
+print(rocky_repo.is_dir())
+print(list(rocky_repo.iterdir()))

pathlib_next-0.4.0/mkdocs.yml

@@ -0,0 +1,46 @@
+site_name: pathlib_next
+site_description: Generic Path Protocol based pathlib
+site_url: https://jose-pr.github.io/pathlib_next/
+repo_url: https://github.com/jose-pr/pathlib_next
+repo_name: jose-pr/pathlib_next
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.sections
+    - content.code.copy
+
+nav:
+  - Home: index.md
+  - API Reference: api/reference.md
+  - Changelog: changelog.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_source: true
+            show_root_heading: true
+            merge_init_into_class: true
+            show_if_no_docstring: true
+
+markdown_extensions:
+  - admonition
+  - tables
+  - pymdownx.snippets:
+      base_path: ["."]
+  - pymdownx.superfences

{pathlib_next-0.3.5 → pathlib_next-0.4.0}/pyproject.toml

@@ -1,30 +1,36 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "pathlib_next"
-version = "0.3.5"
-authors = [{ name = "Jose A" }]
-description = "Generic Path Protocol based pathlib"
-readme = "README.md"
-requires-python = ">=3.11"
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-]
-dependencies = []
-[project.optional-dependencies]
-uri = ["uritools"]
-http = ["requests", "pathlib_next[uri]", 'htmllistparse', 'bs4']
-sftp = ["paramiko", "pathlib_next[uri]"]
-dev = ['build', 'twine', 'hatchling', 'pytest']
-
-
-[project.urls]
-Homepage = "https://github.com/jose-pr/pathlib_next/"
-Issues = "https://github.com/jose-pr/pathlib_next/issues"
-
-[tool.hatch.build.targets.sdist]
-exclude = ["/.*"]
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pathlib_next"
+version = "0.4.0"
+authors = [{ name = "Jose A" }]
+description = "Generic Path Protocol based pathlib"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+[project.optional-dependencies]
+uri = ["uritools"]
+http = ["requests", "pathlib_next[uri]", 'htmllistparse', 'bs4']
+sftp = ["paramiko", "pathlib_next[uri]"]
+dev = ['build', 'twine', 'hatchling', 'pytest']
+docs = ['mkdocs', 'mkdocs-material', 'mkdocstrings[python]']
+
+[project.urls]
+Homepage = "https://github.com/jose-pr/pathlib_next/"
+Documentation = "https://jose-pr.github.io/pathlib_next/"
+Issues = "https://github.com/jose-pr/pathlib_next/issues"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/.*"]
+
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

{pathlib_next-0.3.5 → pathlib_next-0.4.0}/src/pathlib_next/__init__.py

@@ -1,10 +1,10 @@
-try:
-    from .uri import Uri as Uri
-    from .uri import UriPath as UriPath
-    from .uri.schemes import *
-except ImportError:
-    pass
-from .fspath import *
-from .path import *
-from .utils import glob as glob
-from .utils import sync as sync
+try:
+    from .uri import Uri as Uri
+    from .uri import UriPath as UriPath
+    from .uri.schemes import *
+except ImportError:
+    pass
+from .fspath import *
+from .path import *
+from .utils import glob as glob
+from .utils import sync as sync