Merge branch 'main' into feature/inline-types

.coveragerc

@@ -9,3 +9,7 @@ disable_warnings =
 
 [report]
 show_missing = True
+exclude_also =
+	# jaraco/skeleton#97
+	@overload
+	if TYPE_CHECKING:

.github/workflows/main.yml

@@ -1,40 +1,31 @@
 name: tests
 
-on: [push, pull_request]
+on:
+  merge_group:
+  push:
+    branches-ignore:
+    # temporary GH branches relating to merge queues (jaraco/skeleton#93)
+    - gh-readonly-queue/**
+    tags:
+    # required if branches-ignore is supplied (jaraco/skeleton#103)
+    - '**'
+  pull_request:
 
 permissions:
   contents: read
 
 env:
-  # Environment variables to support color support (jaraco/skeleton#66):
-  # Request colored output from CLI tools supporting it. Different tools
-  # interpret the value differently. For some, just being set is sufficient.
-  # For others, it must be a non-zero integer. For yet others, being set
-  # to a non-empty value is sufficient. For tox, it must be one of
-  # <blank>, 0, 1, false, no, off, on, true, yes. The only enabling value
-  # in common is "1".
+  # Environment variable to support color support (jaraco/skeleton#66)
   FORCE_COLOR: 1
-  # MyPy's color enforcement (must be a non-zero number)
-  MYPY_FORCE_COLOR: -42
-  # Recognized by the `py` package, dependency of `pytest` (must be "1")
-  PY_COLORS: 1
-  # Make tox-wrapped tools see color requests
-  TOX_TESTENV_PASSENV: >-
-    FORCE_COLOR
-    MYPY_FORCE_COLOR
-    NO_COLOR
-    PY_COLORS
-    PYTEST_THEME
-    PYTEST_THEME_MODE
 
   # Suppress noisy pip warnings
   PIP_DISABLE_PIP_VERSION_CHECK: 'true'
   PIP_NO_PYTHON_VERSION_WARNING: 'true'
   PIP_NO_WARN_SCRIPT_LOCATION: 'true'
 
-  # Disable the spinner, noise in GHA; TODO(webknjaz): Fix this upstream
-  # Must be "1".
-  TOX_PARALLEL_NO_SPINNER: 1
+  # Ensure tests can sense settings about the environment
+  TOX_OVERRIDE: >-
+    testenv.pass_env+=GITHUB_*,FORCE_COLOR
 
 
 jobs:
@@ -43,7 +34,6 @@ jobs:
       matrix:
         python:
         - "3.8"
-        - "3.11"
         - "3.12"
         platform:
         - ubuntu-latest
@@ -54,43 +44,51 @@ jobs:
           platform: ubuntu-latest
         - python: "3.10"
           platform: ubuntu-latest
-        - python: pypy3.9
+        - python: "3.11"
+          platform: ubuntu-latest
+        - python: pypy3.10
           platform: ubuntu-latest
     runs-on: ${{ matrix.platform }}
-    continue-on-error: ${{ matrix.python == '3.12' }}
+    continue-on-error: ${{ matrix.python == '3.13' }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python }}
           allow-prereleases: true
       - name: Install tox
-        run: |
-          python -m pip install tox
+        run: python -m pip install tox
       - name: Run
         run: tox
 
-  docs:
+  collateral:
+    strategy:
+      fail-fast: false
+      matrix:
+        job:
+        - diffcov
+        - docs
     runs-on: ubuntu-latest
-    env:
-      TOXENV: docs
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Setup Python
         uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
       - name: Install tox
-        run: |
-          python -m pip install tox
-      - name: Run
-        run: tox
+        run: python -m pip install tox
+      - name: Eval ${{ matrix.job }}
+        run: tox -e ${{ matrix.job }}
 
   check:  # This job does nothing and is only used for the branch protection
     if: always()
 
     needs:
     - test
-    - docs
+    - collateral
 
     runs-on: ubuntu-latest
 
@@ -109,14 +107,13 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: 3.x
       - name: Install tox
-        run: |
-          python -m pip install tox
+        run: python -m pip install tox
       - name: Run
         run: tox -e release
         env:

.pre-commit-config.yaml

@@ -1,5 +1,6 @@
 repos:
-- repo: https://github.com/psf/black
-  rev: 22.6.0
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.1.8
   hooks:
-  - id: black
+  - id: ruff
+  - id: ruff-format

.readthedocs.yaml

@@ -7,6 +7,10 @@ python:
 
 # required boilerplate readthedocs/readthedocs.org#10401
 build:
-  os: ubuntu-22.04
+  os: ubuntu-lts-latest
   tools:
-    python: "3"
+    python: latest
+  # post-checkout job to ensure the clone isn't shallow jaraco/skeleton#114
+  jobs:
+    post_checkout:
+    - git fetch --unshallow || true

NEWS.rst

@@ -1,3 +1,31 @@
+v16.10.0
+========
+
+Features
+--------
+
+- Added .with_name and .with_stem.
+- Prefer .suffix to .ext and deprecate .ext.
+
+
+v16.9.0
+=======
+
+Features
+--------
+
+- Added ``.iterdir()`` and deprecated ``.listdir()``. (#214)
+
+
+v16.8.0
+=======
+
+Features
+--------
+
+- Use '.' as the default path. (#216)
+
+
 v16.7.1
 =======
 

README.rst

@@ -3,22 +3,18 @@
 
 .. image:: https://img.shields.io/pypi/pyversions/path.svg
 
-.. image:: https://github.com/jaraco/path/workflows/tests/badge.svg
+.. image:: https://github.com/jaraco/path/actions/workflows/main.yml/badge.svg
    :target: https://github.com/jaraco/path/actions?query=workflow%3A%22tests%22
    :alt: tests
 
 .. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json
     :target: https://github.com/astral-sh/ruff
     :alt: Ruff
 
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-   :target: https://github.com/psf/black
-   :alt: Code style: Black
-
 .. image:: https://readthedocs.org/projects/path/badge/?version=latest
    :target: https://path.readthedocs.io/en/latest/?badge=latest
 
-.. image:: https://img.shields.io/badge/skeleton-2023-informational
+.. image:: https://img.shields.io/badge/skeleton-2024-informational
    :target: https://blog.jaraco.com/skeleton
 
 .. image:: https://tidelift.com/badges/package/pypi/path
@@ -63,6 +59,8 @@ based on ``path``.
 Advantages
 ==========
 
+Path pie provides a superior experience to similar offerings.
+
 Python 3.4 introduced
 `pathlib <https://docs.python.org/3/library/pathlib.html>`_,
 which shares many characteristics with ``path``. In particular,
@@ -75,26 +73,29 @@ has several advantages over ``pathlib``:
 - ``path`` implements ``Path`` objects as a subclass of ``str``, and as a
   result these ``Path`` objects may be passed directly to other APIs that
   expect simple text representations of paths, whereas with ``pathlib``, one
-  must first cast values to strings before passing them to APIs unaware of
-  ``pathlib``. This shortcoming was somewhat `mitigated by PEP 519
-  <https://www.python.org/dev/peps/pep-0519/>`_, in Python 3.6.
+  must first cast values to strings before passing them to APIs that do
+  not honor `PEP 519 <https://www.python.org/dev/peps/pep-0519/>`_
+  ``PathLike`` interface.
 - ``path`` give quality of life features beyond exposing basic functionality
   of a path. ``path`` provides methods like ``rmtree`` (from shlib) and
   ``remove_p`` (remove a file if it exists), properties like ``.permissions``,
   and sophisticated ``walk``, ``TempDir``, and ``chmod`` behaviors.
 - As a PyPI-hosted package, ``path`` is free to iterate
   faster than a stdlib package. Contributions are welcome
   and encouraged.
-- ``path`` provides a uniform abstraction over its Path object,
+- ``path`` provides superior portability using a uniform abstraction
+  over its single Path object,
   freeing the implementer to subclass it readily. One cannot
   subclass a ``pathlib.Path`` to add functionality, but must
   subclass ``Path``, ``PosixPath``, and ``WindowsPath``, even
-  if one only wishes to add a ``__dict__`` to the subclass
+  to do something as simple as to add a ``__dict__`` to the subclass
   instances.  ``path`` instead allows the ``Path.module``
   object to be overridden by subclasses, defaulting to the
   ``os.path``. Even advanced uses of ``path.Path`` that
   subclass the model do not need to be concerned with
-  OS-specific nuances.
+  OS-specific nuances. ``path.Path`` objects are inherently "pure",
+  not requiring the author to distinguish between pure and non-pure
+  variants.
 
 This path project has the explicit aim to provide compatibility
 with ``pathlib`` objects where possible, such that a ``path.Path``
@@ -119,10 +120,3 @@ Available as part of the Tidelift Subscription.
 This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.
 
 `Learn more <https://tidelift.com/subscription/pkg/pypi-path?utm_source=pypi-path&utm_medium=referral&utm_campaign=github>`_.
-
-Security Contact
-================
-
-To report a security vulnerability, please use the
-`Tidelift security contact <https://tidelift.com/security>`_.
-Tidelift will coordinate the fix and disclosure.

SECURITY.md

@@ -0,0 +1,3 @@
+# Security Contact
+
+To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.

newsfragments/220.bugfix.rst

@@ -0,0 +1 @@
+Add type annotation for iterdir.