From 67204d0dd8d8eb716e751535c1c803f0b0c167a4 Mon Sep 17 00:00:00 2001 From: Andreas Poehlmann Date: Mon, 29 Sep 2025 23:01:27 +0200 Subject: [PATCH 1/6] upath: update README with new class diagram --- README.md | 60 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 44 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 485f5354..a28e1c16 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,12 @@ [![Codestyle black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Changelog](https://img.shields.io/badge/changelog-Keep%20a%20Changelog-%23E05735)](./CHANGELOG.md) -Universal Pathlib is a Python library that extends the [`pathlib.Path`][pathlib] -API to support a variety of backend filesystems via [`filesystem_spec`][fsspec]. +Universal Pathlib is a Python library that extends the +[`pathlib_abc.JoinablePath`][pathlib_abc] API to provide a +[`pathlib.Path`][pathlib]-like interface for a variety of backend filesystems +via [`filesystem_spec`][fsspec]. +[pathlib_abc]: https://github.com/barneygale/pathlib-abc [pathlib]: https://docs.python.org/3/library/pathlib.html [fsspec]: https://filesystem-spec.readthedocs.io/en/latest/intro.html @@ -44,9 +47,9 @@ project as a dependency if you want to use it with `s3` and `http` filesystems: ```toml [project] name = "myproject" -requires-python = ">=3.8" +requires-python = ">=3.9" dependencies = [ - "universal_pathlib>=0.2.5", + "universal_pathlib>=0.3.0", "fsspec[s3,http]", ] ``` @@ -106,33 +109,51 @@ And of course, contributions for new filesystems are welcome! ### Class hierarchy -The class hierarchy for `UPath` implementations and their relation to the stdlib -`pathlib` classes are visualized in the following diagram: +The class hierarchy for `UPath` implementations and their relation to base classes +in `pathlib_abc` and the stdlib `pathlib` classes are visualized in the following +diagram: ```mermaid flowchart TB + + subgraph p0[pathlib_abc] + X ----> Y + X ----> Z + end + subgraph s0[pathlib] - A---> B + X --> A + + A----> B A--> AP A--> AW + Y --> B + Z --> B + B--> BP - AP---> BP + AP----> BP B--> BW - AW---> BW + AW----> BW end subgraph s1[upath] - B ---> U + Y ---> U + Z ---> U + U --> UP U --> UW - BP --> UP - BW --> UW + BP ---> UP + BW ---> UW U --> UL U --> US3 U --> UH U -.-> UO end + X(JoinablePath) + Y(WritablePath) + Z(ReadablePath) + A(PurePath) AP(PurePosixPath) AW(PureWindowsPath) @@ -148,14 +169,17 @@ flowchart TB UH(HttpPath) UO(...Path) + classDef na fill:#f7f7f7,stroke:#02a822,stroke-width:2px,color:#333 classDef np fill:#f7f7f7,stroke:#2166ac,stroke-width:2px,color:#333 classDef nu fill:#f7f7f7,stroke:#b2182b,stroke-width:2px,color:#333 + class X,Y,Z na class A,AP,AW,B,BP,BW,UP,UW np class U,UL,US3,UH,UO nu style UO stroke-dasharray: 3 3 + style p0 fill:none,stroke:#0a2,stroke-width:3px,stroke-dasharray:3,color:#0a2 style s0 fill:none,stroke:#07b,stroke-width:3px,stroke-dasharray:3,color:#07b style s1 fill:none,stroke:#d02,stroke-width:3px,stroke-dasharray:3,color:#d02 ``` @@ -170,16 +194,20 @@ correct behavior for filesystems that are not tested in the test-suite. ### Local paths and url paths -If a local path is provided `UPath` will return a `PosixUPath` or `WindowsUPath` -instance. These two implementations are 100% compatible with the `PosixPath` and -`WindowsPath` classes of their specific Python version. They're tested against a -large subset of the CPython pathlib test-suite to ensure compatibility. +If a local path is without protocol is provided `UPath` will return a `PosixUPath` +or `WindowsUPath` instance. These two implementations are 100% compatible with +the `PosixPath` and `WindowsPath` classes of their specific Python version. +They're tested against a large subset of the CPython pathlib test-suite to ensure +compatibility. If a local urlpath is provided, i.e. a "file://" or "local://" URI, the returned instance type will be a `FilePath` instance. This class is a subclass of `UPath` that provides file access via `LocalFileSystem` from `fsspec`. You can use it to ensure that all your local file access is done through `fsspec` as well. +All local UPath types are `os.PathLike`, but only the `PosixUPath` and +`WindowsUPath` are subclasses of `pathlib.Path`. + ### UPath public class API The public class interface of `UPath` extends `pathlib.Path` via attributes that From ce7281824d3c3ca5fcf69188b6ba1dfb03051e67 Mon Sep 17 00:00:00 2001 From: Andreas Poehlmann Date: Mon, 29 Sep 2025 23:15:28 +0200 Subject: [PATCH 2/6] tests: enable tests for 3.14 for all os-es --- .github/workflows/tests.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 52346c04..92580972 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -21,15 +21,13 @@ jobs: fail-fast: false matrix: os: [ubuntu-latest, windows-latest, macos-latest] - pyv: ['3.9', '3.10', '3.11', '3.12', '3.13'] + pyv: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14'] session: ['tests'] include: - os: ubuntu-latest pyv: '3.9' session: 'tests-minversion' - - os: ubuntu-latest - pyv: '3.14' steps: - name: Check out the repository From a257f73bc270baf119c84dcaf8e3ba07dfc66a45 Mon Sep 17 00:00:00 2001 From: Andreas Poehlmann Date: Mon, 29 Sep 2025 23:29:21 +0200 Subject: [PATCH 3/6] typechecking: run tests on 3.14 too --- noxfile.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/noxfile.py b/noxfile.py index d5aeb9b9..c4d739a3 100644 --- a/noxfile.py +++ b/noxfile.py @@ -102,9 +102,9 @@ def type_checking(session): session.run("python", "-m", "mypy") -@nox.session(python=["3.9", "3.10", "3.11", "3.12", "3.13"]) +@nox.session(python=["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]) def typesafety(session): - session.install("-e", ".[tests,typechecking]") + session.install("-e", ".[typechecking]") session.run( "python", "-m", From d2d1630c09145e252094037d33e05e3d8baae993 Mon Sep 17 00:00:00 2001 From: Andreas Poehlmann Date: Mon, 29 Sep 2025 23:41:35 +0200 Subject: [PATCH 4/6] update changelog --- CHANGELOG.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ee6f29a3..d1a976ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ... +## [0.3.0] - 2025-09-29 +### Fixed +- upath: support relative paths (#405) +- upath: implement chain functionality (#346) +- upath: fix upath suffixes (#407) +- upath: update flavours (#350, #351, #400, #403, #411) +- upath: fix GH test skipping (#361) +- ci: update ubuntu runners (#359) +- ci: address skip_existing deprecation (#369) +- tests: split protocol mismatch test (#365) +- tests: ensure non-local upaths raise with builtin open (#368) +- tests: add an xfail test for // behaviour on s3 (#370) +- tests: fix xfail call args (#409) +- tests: add a os.PathLike test (#410) + +### Added +- upath: api extensions via `upath.extensions.ProxyUPath` (#372) +- upath: add upath.types in preparation for deriving from pathlib-abc (#364) +- upath: add optional support for pydantic (#395) +- upath: list late registered protocols (#358) +- repo: add a security policy (#327) +- ci: start running against 3.14 (#363) + +### Changed +- upath: inherit from `pathlib_abc.ReadablePath` and `pathlib_abc.WritablePath` (#366, #402, #404) +- upath: drop Python 3.8 (#360) +- upath: remove deprecated accessor support (#362) + ## [0.2.6] - 2024-12-13 ### Fixed - upath: add support for 'abfss' protocol in WrappedFileSystemFlavour (#311) @@ -183,7 +211,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - started a changelog to keep track of significant changes -[Unreleased]: https://github.com/fsspec/universal_pathlib/compare/v0.2.6...HEAD +[Unreleased]: https://github.com/fsspec/universal_pathlib/compare/v0.3.0...HEAD +[0.3.0]: https://github.com/fsspec/universal_pathlib/compare/v0.2.6...v0.3.0 [0.2.6]: https://github.com/fsspec/universal_pathlib/compare/v0.2.5...v0.2.6 [0.2.5]: https://github.com/fsspec/universal_pathlib/compare/v0.2.4...v0.2.5 [0.2.4]: https://github.com/fsspec/universal_pathlib/compare/v0.2.3...v0.2.4 From 42e3fa1f6e80786daf3d4f0df5091b6839ef80ba Mon Sep 17 00:00:00 2001 From: Andreas Poehlmann Date: Mon, 29 Sep 2025 23:47:15 +0200 Subject: [PATCH 5/6] ci: add 3.14 to typesafety runs --- .github/workflows/tests.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 92580972..83d18720 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -56,6 +56,7 @@ jobs: 3.11 3.12 3.13 + 3.14 - name: Install nox run: python -m pip install --upgrade nox From 5fe6cb2e0049134dc9e0a94258788142fb48ab1e Mon Sep 17 00:00:00 2001 From: Andreas Poehlmann Date: Mon, 29 Sep 2025 23:54:06 +0200 Subject: [PATCH 6/6] ci: run typesafety via uvx nox --- .github/workflows/tests.yml | 32 +++++++++++++------------------- 1 file changed, 13 insertions(+), 19 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 83d18720..aea00a6a 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -42,27 +42,21 @@ jobs: typesafety: runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + pyv: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14'] steps: - - name: Check out the repository - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: | - 3.9 - 3.10 - 3.11 - 3.12 - 3.13 - 3.14 - - - name: Install nox - run: python -m pip install --upgrade nox - - - name: Run typesafety checks - run: nox -s typesafety + - name: Check out the repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: hynek/setup-cached-uv@v2 + + - name: Run tests + run: uvx nox --sessions typesafety --python ${{ matrix.pyv }} lint: runs-on: ubuntu-latest