Merge branch 'master' into update-tox-faq-entry

.github/ISSUE_TEMPLATE/---bug-report.md

@@ -22,7 +22,7 @@ assignees: ''
 - **pyproject.toml**: <!-- Replace with a link to a Gist (https://gist.github.com/) containing your sanitized pyproject.toml -->
 
 <!-- All the below steps should be completed before submitting your issue. Checked checkbox should look like this: [x] -->
-- [ ] I am on the [latest](https://github.com/python-poetry/poetry/releases/latest) stable Poetry version, installed using a recommended method.
+- [ ] I am on the [latest](https://github.com/python-poetry/poetry/releases/latest) stable Poetry version, installed using a [recommended method](https://python-poetry.org/docs/#installation).
 - [ ] I have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repo and believe that this is not a duplicate.
 - [ ] I have consulted the [FAQ](https://python-poetry.org/docs/faq/) and [blog](https://python-poetry.org/blog/) for any relevant entries or release notes.
 - [ ] If an exception occurs when executing a command, I executed it again in debug mode (`-vvv` option) and have included the output below.

.github/workflows/docs.yml

@@ -16,6 +16,10 @@ on:
       - "**"
       - "!docs/**"
 
+permissions:
+  contents: read
+  pull-requests: write
+
 jobs:
   deploy:
     name: Build & Deploy
@@ -36,7 +40,7 @@ jobs:
           ref: ${{ github.event.pull_request.head.sha }}
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.10"
 
@@ -51,7 +55,7 @@ jobs:
       - name: Fetch Documentation
         run: |
           python -m pip install poetry
-          poetry install --only main
+          poetry install --no-root --only main
           poetry run python bin/website build --local ./poetry
 
       - name: Install Hugo

.github/workflows/main.yml

@@ -44,7 +44,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 

.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up Python 3.10
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.10"
 

.pre-commit-config.yaml

@@ -21,17 +21,17 @@ repos:
       - id: check-docstring-first
 
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 23.10.1
+    rev: 23.12.1
     hooks:
       - id: black
         exclude: tests/([^/]*/)*fixtures/
 
   - repo: https://github.com/pre-commit/pre-commit
-    rev: v3.5.0
+    rev: v3.6.0
     hooks:
       - id: validate_manifest
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.4
+    rev: v0.1.9
     hooks:
     -   id: ruff

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Change Log
 
+
+## [1.7.1] - 2023-11-16
+
+### Fixed
+
+- Fix an issue where sdists that call CLI tools of their build requirements could not be installed ([#8630](https://github.com/python-poetry/poetry/pull/8630)).
+- Fix an issue where sdists with symlinks could not be installed due to a broken tarfile datafilter ([#8649](https://github.com/python-poetry/poetry/pull/8649)).
+- Fix an issue where `poetry init` failed when trying to add dependencies ([#8655](https://github.com/python-poetry/poetry/pull/8655)).
+- Fix an issue where `poetry install` failed if `virtualenvs.create` was set to `false` ([#8672](https://github.com/python-poetry/poetry/pull/8672)).
+
+
 ## [1.7.0] - 2023-11-03
 
 ### Added
@@ -2024,7 +2035,8 @@ Initial release
 
 
 
-[Unreleased]: https://github.com/python-poetry/poetry/compare/1.7.0...master
+[Unreleased]: https://github.com/python-poetry/poetry/compare/1.7.1...master
+[1.7.1]: https://github.com/python-poetry/poetry/releases/tag/1.7.1
 [1.7.0]: https://github.com/python-poetry/poetry/releases/tag/1.7.0
 [1.6.1]: https://github.com/python-poetry/poetry/releases/tag/1.6.1
 [1.6.0]: https://github.com/python-poetry/poetry/releases/tag/1.6.0

docs/_index.md

@@ -25,9 +25,10 @@ on Linux, macOS and Windows.
 
 {{% warning %}}
 Poetry should always be installed in a dedicated virtual environment to isolate it from the rest of your system.
-In no case, it should be installed in the environment of the project that is to be managed by Poetry.
+It should in no case be installed in the environment of the project that is to be managed by Poetry.
 This ensures that Poetry's own dependencies will not be accidentally upgraded or uninstalled.
 (Each of the following installation methods ensures that Poetry is installed into an isolated environment.)
+In addition, the isolated virtual environment in which poetry is installed should not be activated for running poetry commands.
 {{% /warning %}}
 
 {{% note %}}
@@ -175,6 +176,8 @@ You can also install Poetry from a `git` repository by using the `--git` option:
 ```bash
 curl -sSL https://install.python-poetry.org | python3 - --git https://github.com/python-poetry/poetry.git@master
 ````
+If you want to install different versions of Poetry in parallel, a good approach is the installation with pipx and suffix.
+
 {{< /step >}}
 {{< step >}}
 **Add Poetry to your PATH**

docs/basic-usage.md

@@ -128,6 +128,19 @@ any Poetry commands that expect to manipulate an environment.
 To run your script simply use `poetry run python your_script.py`.
 Likewise if you have command line tools such as `pytest` or `black` you can run them using `poetry run pytest`.
 
+{{% note %}}
+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
 
 The easiest way to activate the virtual environment is to create a nested shell with `poetry shell`.

docs/cli.md

@@ -189,7 +189,7 @@ The `--sync` can be combined with group-related options:
 ```bash
 poetry install --without dev --sync
 poetry install --with docs --sync
-poetry install --only dev
+poetry install --only dev --sync
 ```
 
 You can also specify the extras you want installed
@@ -287,10 +287,13 @@ If you just want to update a few packages and not all, you can list them as such
 poetry update requests toml
 ```
 
-Note that this will not update versions for dependencies outside their version constraints specified
-in the `pyproject.toml` file. In other terms, `poetry update foo` will be a no-op if the version constraint
-specified for `foo` is `~2.3` or `2.3` and `2.4` is available. In order for `foo` to be updated, you must
-update the constraint, for example `^2.3`. You can do this using the `add` command.
+Note that this will not update versions for dependencies outside their
+[version constraints]({{< relref "dependency-specification#version-constraints" >}})
+specified in the `pyproject.toml` file.
+In other terms, `poetry update foo` will be a no-op if the version constraint
+specified for `foo` is `~2.3` or `2.3` and `2.4` is available.
+In order for `foo` to be updated, you must update the constraint, for example `^2.3`.
+You can do this using the `add` command.
 
 ### Options
 
@@ -503,7 +506,7 @@ required by
 ### Options
 
 * `--without`: The dependency groups to ignore.
-* `--why`: When showing the full list, or a `--tree` for a single package, display why a package is included.
+* `--why`: When showing the full list, or a `--tree` for a single package, display whether they are a direct dependency or required by other packages.
 * `--with`: The optional dependency groups to include.
 * `--only`: The only dependency groups to include.
 * `--no-dev`: Do not list the dev dependencies. (**Deprecated**, use `--without dev` or `--only main` instead)
@@ -577,6 +580,14 @@ poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]
 `setting-key` is a configuration option name and `setting-value1` is a configuration value.
 See [Configuration]({{< relref "configuration" >}}) for all available settings.
 
+{{% warning %}}
+Use `--` to terminate option parsing if your values may start with a hyphen (`-`), e.g.
+```bash
+poetry config http-basic.custom-repo gitlab-ci-token -- ${GITLAB_JOB_TOKEN}
+```
+Without `--` this command will fail if `${GITLAB_JOB_TOKEN}` starts with a hyphen.
+{{% /warning%}}
+
 ### Options
 
 * `--unset`: Remove the configuration element named by `setting-key`.

docs/faq.md

@@ -204,7 +204,7 @@ For example, you might have a Dockerfile that looks something like this:
 FROM python
 COPY pyproject.toml poetry.lock .
 COPY src/ ./src
-RUN pip install poetry && poetry install --no-dev
+RUN pip install poetry && poetry install --without dev
 ```
 
 As soon as *any* source file changes, the cache for the `RUN` layer will be invalidated, which forces all 3rd party dependencies (likely the slowest step out of these) to be installed again if you changed any files in `src/`.
@@ -221,7 +221,7 @@ FROM python
 COPY pyproject.toml poetry.lock .
 RUN pip install poetry && poetry install --no-root --no-directory
 COPY src/ ./src
-RUN poetry install --no-dev
+RUN poetry install --without dev
 ```
 
 The two key options we are using here are `--no-root` (skips installing the project source) and `--no-directory` (skips installing any local directory path dependencies, you can omit this if you don't have any).

docs/managing-environments.md

@@ -88,13 +88,13 @@ poetry env info
 will output something similar to this:
 
 ```text
-Virtual environment
+Virtualenv
 Python:         3.7.1
 Implementation: CPython
 Path:           /path/to/poetry/cache/virtualenvs/test-O3eWbxRl-py3.7
 Valid:          True
 
-System
+Base
 Platform: darwin
 OS:       posix
 Python:   /path/to/main/python

docs/pre-commit-hooks.md

@@ -58,7 +58,7 @@ This hook is provided by the [Export Poetry Plugin](https://github.com/python-po
 {{% /warning %}}
 
 {{% note %}}
-It is recommended to run the [`poetry-lock`](#poetry-lock) hook prior to this one.
+It is recommended to run the [`poetry-lock`](#poetry-lock) hook or [`poetry-check`](#poetry-check) with argument `--lock` prior to this one.
 {{% /note %}}
 
 ### Arguments

docs/repositories.md

@@ -232,6 +232,14 @@ poetry source add --priority=supplemental https://foo.bar/simple/
 
 There can be more than one supplemental package source.
 
+{{% warning %}}
+
+Take into account that someone could publish a new package to a primary source
+which matches a package in your supplemental source. They could coincidentally
+or intentionally replace your dependency with something you did not expect.
+
+{{% /warning %}}
+
 
 #### Explicit Package Sources
 
@@ -430,7 +438,7 @@ poetry config repositories.testpypi https://test.pypi.org/legacy/
 [Legacy Upload API](https://warehouse.pypa.io/api-reference/legacy.html#upload-api) URLs are
 typically different to the same one provided by the repository for the simple API. You'll note that
 in the example of [Test PyPI](https://test.pypi.org/), both the host (`test.pypi.org`) as
-well as the path (`/legacy`) are different to it's simple API (`https://test.pypi.org/simple`).
+well as the path (`/legacy`) are different to its simple API (`https://test.pypi.org/simple`).
 
 {{% /note %}}
 
@@ -490,11 +498,12 @@ if it exists for you use case instead of doing it yourself.
 Alternatively, you can use environment variables to provide the credentials:
 
 ```bash
-export POETRY_PYPI_TOKEN_PYPI=my-token
-export POETRY_HTTP_BASIC_PYPI_USERNAME=<username>
-export POETRY_HTTP_BASIC_PYPI_PASSWORD=<password>
+export POETRY_PYPI_TOKEN_FOO=my-token
+export POETRY_HTTP_BASIC_FOO_USERNAME=<username>
+export POETRY_HTTP_BASIC_FOO_PASSWORD=<password>
 ```
 
+where `FOO` is the name of the repository in uppercase (e.g. `PYPI`).
 See [Using environment variables]({{< relref "configuration#using-environment-variables" >}}) for more information
 on how to configure Poetry with environment variables.