Merge branch 'main' into removeUnnecessaryExplicitCwd

.cirrus.yml

@@ -60,7 +60,7 @@ tests_task:
     # TODO: caching
     - alias: mypy
       name: "Tests / FreeBSD (Python ${PYTHON_VERSION}) / mypy"
-      skip: "!changesInclude('.cirrus.yml', 'poetry.lock', 'pyproject.toml', 'src/**.py')"
+      skip: "!changesInclude('.cirrus.yml', 'poetry.lock', 'pyproject.toml', 'src/**.py', 'tests/**')"
       mypy_script: poetry run mypy
 
 status_task:

.github/workflows/.tests-matrix.yaml

@@ -28,7 +28,7 @@ jobs:
     runs-on: ${{ inputs.runner }}
     if: inputs.run-mypy
     steps:
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
 
       - uses: ./.github/actions/bootstrap-poetry
         id: bootstrap-poetry
@@ -37,7 +37,7 @@ jobs:
 
       - uses: ./.github/actions/poetry-install
 
-      - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4
+      - uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4.0.2
         with:
           path: .mypy_cache
           key: mypy-${{ runner.os }}-py${{ steps.bootstrap-poetry.outputs.python-version }}-${{ hashFiles('pyproject.toml', 'poetry.lock') }}
@@ -52,7 +52,7 @@ jobs:
     runs-on: ${{ inputs.runner }}
     if: inputs.run-pytest
     steps:
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
 
       - uses: ./.github/actions/bootstrap-poetry
         with:
@@ -74,7 +74,7 @@ jobs:
     runs-on: ${{ inputs.runner }}
     if: inputs.run-pytest-export
     steps:
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
 
       - uses: ./.github/actions/bootstrap-poetry
         with:
@@ -87,7 +87,7 @@ jobs:
       - run: poetry run pip list --format json | jq -r '.[] | "\(.name)=\(.version)"' >> $GITHUB_OUTPUT
         id: package-versions
 
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
         with:
           path: poetry-plugin-export
           repository: python-poetry/poetry-plugin-export

.github/workflows/backport.yaml

@@ -15,26 +15,19 @@ jobs:
     if: >
       github.event.pull_request.merged
       && (
-          (github.event.action == 'closed' && contains(github.event.pull_request.labels.*.name, 'backport/'))
+        github.event.action == 'closed'
         ||
           (github.event.action == 'labeled' && contains(github.event.label.name, 'backport/')
         )
       )
     steps:
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
-      # This workflow requires a non-GHA token in order to trigger downstream CI, and to access the 'fork' repository.
-      - uses: actions/create-github-app-token@78e5f2ddc08efcb88fbbee6cfa3fed770ba550c3 # v1
+      - uses: actions/create-github-app-token@7bfa3a4717ef143a604ee0a99d859b8886a96d00 # v1.9.3
         id: app-token
         with:
           app-id: ${{ secrets.POETRY_TOKEN_APP_ID }}
           private-key: ${{ secrets.POETRY_TOKEN_APP_KEY }}
-      - name: backport.sh
-        run: |
-          git config --global user.name  "${{ steps.app-token.outputs.slug }}[bot]"
-          git config --global user.email "${{ steps.app-token.outputs.slug }}[bot]@users.noreply.github.com"
-
-          gh repo fork --remote-name fork
-
-          ./.github/scripts/backport.sh --pr ${{ github.event.pull_request.number }} --comment --remote fork
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+      - uses: tibdex/backport@9565281eda0731b1d20c4025c43339fb0a23812e # v2.0.4
+        with:
+          github_token: ${{ steps.app-token.outputs.token }}
+          title_template: "[<%= base %>] <%= title %>"
+          label_pattern: "^backport/(?<base>([^ ]+))$"

.github/workflows/docs.yaml

@@ -27,20 +27,20 @@ jobs:
       contents: read
       pull-requests: write
     steps:
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
         with:
           repository: python-poetry/website
 
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
         with:
           path: poetry
           ref: ${{ github.event.pull_request.head.sha }}
 
-      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4
+      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: "18"
 
-      - uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d # v2
+      - uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d # v2.6.0
         with:
           hugo-version: '0.83.1'
 
@@ -59,7 +59,7 @@ jobs:
           # Build the static website.
           hugo -v --minify
 
-      - uses: amondnet/vercel-action@16e87c0a08142b0d0d33b76aeaf20823c381b9b9 # v25
+      - uses: amondnet/vercel-action@16e87c0a08142b0d0d33b76aeaf20823c381b9b9 # v25.2.0
         with:
           vercel-token: ${{ secrets.VERCEL_TOKEN }}
           github-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/lock-threads.yaml

@@ -14,7 +14,7 @@ jobs:
     permissions:
       issues: write
     steps:
-      - uses: dessant/lock-threads@1bf7ec25051fe7c00bdd17e6a7cf3d7bfb7dc771 # v5
+      - uses: dessant/lock-threads@1bf7ec25051fe7c00bdd17e6a7cf3d7bfb7dc771 # v5.0.1
         with:
           process-only: issues
           issue-inactive-days: 30
@@ -29,7 +29,7 @@ jobs:
       issues: write
       pull-requests: write
     steps:
-      - uses: dessant/lock-threads@1bf7ec25051fe7c00bdd17e6a7cf3d7bfb7dc771 # v5
+      - uses: dessant/lock-threads@1bf7ec25051fe7c00bdd17e6a7cf3d7bfb7dc771 # v5.0.1
         with:
           process-only: prs
           pr-inactive-days: 30

.github/workflows/release.yaml

@@ -9,11 +9,11 @@ jobs:
     name: Build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
 
       - run: pipx run build
 
-      - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4
+      - uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4.3.3
         with:
           name: distfiles
           path: dist/
@@ -26,7 +26,7 @@ jobs:
       contents: write
     needs: build
     steps:
-      - uses: actions/download-artifact@c850b930e6ba138125429b7e5c93fc707a7f8427 # v4
+      - uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4.1.7
         with:
           name: distfiles
 
@@ -42,10 +42,10 @@ jobs:
       id-token: write
     needs: build
     steps:
-      - uses: actions/download-artifact@c850b930e6ba138125429b7e5c93fc707a7f8427 # v4
+      - uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4.1.7
         with:
           name: distfiles
 
-      - uses: pypa/gh-action-pypi-publish@81e9d935c883d0b210363ab89cf05f3894778450 # release/v1
+      - uses: pypa/gh-action-pypi-publish@81e9d935c883d0b210363ab89cf05f3894778450 # v1.8.14
         with:
           print-hash: true

.github/workflows/tests.yaml

@@ -23,9 +23,9 @@ jobs:
       src: ${{ steps.changes.outputs.src }}
       tests: ${{ steps.changes.outputs.tests }}
     steps:
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
 
-      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
         id: changes
         with:
           filters: |
@@ -54,7 +54,7 @@ jobs:
     if: needs.changes.outputs.project == 'true'
     needs: changes
     steps:
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
 
       - uses: ./.github/actions/bootstrap-poetry
 
@@ -66,7 +66,7 @@ jobs:
     if: needs.changes.outputs.project == 'true'
     needs: lockfile
     steps:
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
 
       - run: pipx run build
 
@@ -85,7 +85,7 @@ jobs:
     if: needs.changes.outputs.fixtures-pypi == 'true'
     needs: changes
     steps:
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
 
       - uses: ./.github/actions/bootstrap-poetry
 
@@ -108,7 +108,7 @@ jobs:
     with:
       runner: ${{ matrix.os.image }}
       python-version: ${{ matrix.python-version }}
-      run-mypy: ${{ needs.changes.outputs.src == 'true' }}
+      run-mypy: ${{ needs.changes.outputs.tests == 'true' }}
       run-pytest: ${{ needs.changes.outputs.tests == 'true' }}
       run-pytest-export: ${{ needs.changes.outputs.src == 'true' }}
     secrets: inherit

docs/basic-usage.md

@@ -63,8 +63,29 @@ Similarly, the traditional `MANIFEST.in` file is replaced by the `tool.poetry.re
 `tool.poetry.exclude` sections. `tool.poetry.exclude` is additionally implicitly populated by your `.gitignore`. For
 full documentation on the project format, see the [pyproject section]({{< relref "pyproject" >}}) of the documentation.
 
+### Setting a Python Version
+
+{{% note %}}
+Unlike with other packages, Poetry will not automatically install a python interpreter for you.
+If you want to run Python files in your package like a script or application, you must _bring your own_ python interpreter to run them.
+{{% /note %}}
+
 Poetry will require you to explicitly specify what versions of Python you intend to support, and its universal locking
 will guarantee that your project is installable (and all dependencies claim support for) all supported Python versions.
+Again, it's important to remember that -- unlike other dependencies -- setting a Python version is merely specifying which versions of Python you intend to support.
+
+For example, in this `pyproject.toml` file:
+
+```toml
+[tool.poetry.dependencies]
+python = "^3.7.0"
+```
+
+we are allowing any version of Python 3 that is greater than `3.7.0`.
+
+When you run `poetry install`, you must have access to some version of a Python inrepreter that satisfies this constraint available on your system.
+Poetry will not install a Python interpreter for you.
+If you use a tool like `pyenv`, you can use the experimental configuration value [`virtualenvs.prefer-active-python`]({{< relref "configuration/#virtualenvsprefer-active-python-experimental" >}}).
 
 ### Initialising a pre-existing project
 
@@ -155,13 +176,15 @@ Likewise if you have command line tools such as `pytest` or `black` you can run
 If managing your own virtual environment externally, you do not need to use `poetry run` or `poetry shell` since
 you will, presumably, already have activated that virtual environment and made available the correct python instance.
 For example, these commands should output the same python path:
+
 ```shell
 conda activate your_env_name
 which python
 poetry run which python
 poetry shell
 which python
 ```
+
 {{% /note %}}
 
 ### Activating the virtual environment
@@ -197,7 +220,7 @@ You can also combine these into a one-liner, such as `source $(poetry env info -
 To deactivate this virtual environment simply use `deactivate`.
 
 |                   | POSIX Shell                                     | Windows (PowerShell)                                     | Exit/Deactivate |
-|-------------------| ----------------------------------------------- |----------------------------------------------------------| --------------- |
+| ----------------- | ----------------------------------------------- | -------------------------------------------------------- | --------------- |
 | Sub-shell         | `poetry shell`                                  | `poetry shell`                                           | `exit`          |
 | Manual Activation | `source {path_to_venv}/bin/activate`            | `{path_to_venv}\Scripts\activate.ps1`                    | `deactivate`    |
 | One-liner         | `source $(poetry env info --path)/bin/activate` | `& ((poetry env info --path) + "\Scripts\activate.ps1")` | `deactivate`    |
@@ -273,7 +296,6 @@ the dependencies installed are still working even if your dependencies released
 {{% warning %}} If you have added the recommended [`[build-system]`]({{< relref "pyproject#poetry-and-pep-517" >}}) section to your project's pyproject.toml then you _can_ successfully install your project and its dependencies into a virtual environment using a command like `pip install -e .`. However, pip will not use the lock file to determine dependency versions as the poetry-core build system is intended for library developers (see next section).
 {{% /warning %}}
 
-
 #### As a library developer
 
 Library developers have more to consider. Your users are application developers, and your library will run in a Python environment you don't control.

docs/plugins.md

@@ -202,7 +202,9 @@ pipx inject poetry poetry-plugin
 If you want to uninstall a plugin, you can run:
 
 ```shell
-pipx runpip poetry uninstall poetry-plugin
+pipx uninject poetry poetry-plugin          # For pipx versions >= 1.2.0
+
+pipx runpip poetry uninstall poetry-plugin  # For pipx versions  < 1.2.0
 ```
 
 ### With `pip`

docs/repositories.md

@@ -511,6 +511,10 @@ Once you have created a new token, you can tell Poetry to use it:
 ```bash
 poetry config pypi-token.pypi <my-token>
 ```
+If you have configured **testpypi** as a [Publishable Repository](#publishable-repositories), the token can be set using
+```bash
+poetry config pypi-token.testpypi <your-token>
+```
 
 If you still want to use your username and password, you can do so with the following
 call to `config`.

pyproject.toml

@@ -33,7 +33,7 @@ python = "^3.8"
 
 poetry-core = "1.9.0"
 poetry-plugin-export = "^1.7.0"
-build = "^1.1.1"
+build = "^1.2.1"
 cachecontrol = { version = "^0.14.0", extras = ["filecache"] }
 cleo = "^2.1.0"
 dulwich = "^0.21.2"
@@ -42,7 +42,7 @@ importlib-metadata = { version = ">=4.4", python = "<3.10" }
 installer = "^0.7.0"
 keyring = "^24.3.1"
 # packaging uses calver, so version is unclamped
-packaging = ">=23.1"
+packaging = ">=24.0"
 pexpect = "^4.7.0"
 pkginfo = "^1.10"
 platformdirs = ">=3.0.0,<5"