Merge branch 'master' into virtualenv-prompt-opt

.github/workflows/main.yml

@@ -31,11 +31,11 @@ jobs:
         python-version: ["3.7", "3.8", "3.9", "3.10"]
         include:
           - os: Ubuntu
-            image: ubuntu-latest
+            image: ubuntu-22.04
           - os: Windows
             image: windows-2022
           - os: macOS
-            image: macos-11
+            image: macos-12
       fail-fast: false
     defaults:
       run:
@@ -81,15 +81,15 @@ jobs:
       - name: Install dependencies
         run: poetry install
 
+      - name: Run mypy
+        run: poetry run mypy
+
       - name: Install pytest plugin
         run: poetry run pip install pytest-github-actions-annotate-failures
 
       - name: Run pytest
         run: poetry run python -m pytest -p no:sugar -q tests/
 
-      - name: Run mypy
-        run: poetry run mypy
-
       - name: Run pytest (integration suite)
         env:
           POETRY_TEST_INTEGRATION_GIT_USERNAME: ${GITHUB_ACTOR}

.pre-commit-config.yaml

@@ -52,6 +52,12 @@ repos:
         args: [--py37-plus]
         exclude: ^(install|get)-poetry.py$
 
+  - repo: https://github.com/hadialqattan/pycln
+    rev: v1.3.2
+    hooks:
+      - id: pycln
+        args: [--all]
+
   - repo: https://github.com/pycqa/isort
     rev: 5.10.1
     hooks:

docs/_index.md

@@ -43,9 +43,14 @@ curl -sSL https://install.python-poetry.org | python3 -
 
 **windows powershell install instructions**
 ```powershell
-(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
+(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
 ```
 
+{{% note %}}
+If you have installed Python through the Microsoft Store, replace `py` with `python` in the command
+above.
+{{% /note %}}
+
 {{% note %}}
 Note that the installer does not support Python < 3.7.
 {{% /note %}}

docs/cli.md

@@ -357,11 +357,15 @@ If the package(s) you want to install provide extras, you can specify them
 when adding the package:
 
 ```bash
-poetry add requests[security,socks]
+poetry add "requests[security,socks]"
 poetry add "requests[security,socks]~=2.22.0"
 poetry add "git+https://github.com/pallets/flask.git@1.1.1[dotenv,dev]"
 ```
 
+{{% warning %}}
+Some shells may treat square braces (`[` and `]`) as special characters. It is suggested to always quote arguments containing these characters to prevent unexpected shell expansion.
+{{% /warning %}}
+
 If you want to add a package to a specific group of dependencies, you can use the `--group (-G)` option:
 
 ```bash
@@ -509,6 +513,7 @@ See [Configuration]({{< relref "configuration" >}}) for all available settings.
 
 * `--unset`: Remove the configuration element named by `setting-key`.
 * `--list`: Show the list of current config variables.
+* `--local`: Set/Get settings that are specific to a project (in the local configuration file `poetry.toml`).
 
 ## run
 
@@ -623,6 +628,7 @@ The table below illustrates the effect of these rules with concrete examples.
 ### Options
 
 * `--short (-s)`: Output the version number only.
+* `--dry-run`: Do not update pyproject.toml file.
 
 ## export
 

docs/plugins.md

@@ -67,11 +67,8 @@ from poetry.poetry import Poetry
 class MyPlugin(Plugin):
 
     def activate(self, poetry: Poetry, io: IO):
-        version = self.get_custom_version()
-        io.write_line(f"Setting package version to <b>{version}</b>")
-        poetry.package.set_version(version)
-
-    def get_custom_version(self) -> str:
+        io.write_line("Setting readme")
+        poetry.package.readme = "README.md"
         ...
 ```
 

docs/pyproject.md

@@ -17,12 +17,20 @@ The `tool.poetry` section of the `pyproject.toml` file is composed of multiple s
 
 The name of the package. **Required**
 
+```toml
+name = "my-package"
+```
+
 ## version
 
 The version of the package. **Required**
 
 This should be a valid [PEP 440](https://peps.python.org/pep-0440/) string.
 
+```toml
+version = "0.1.0"
+```
+
 {{% note %}}
 
 If you would like to use semantic versioning for your project, please see
@@ -34,6 +42,10 @@ If you would like to use semantic versioning for your project, please see
 
 A short description of the package. **Required**
 
+```toml
+description = "A short description of the package."
+```
+
 ## license
 
 The license of the package.
@@ -61,40 +73,76 @@ More identifiers are listed at the [SPDX Open Source License Registry](https://s
 If your project is proprietary and does not use a specific licence, you can set this value as `Proprietary`.
 {{% /note %}}
 
+```toml
+license = "MIT"
+```
+
 ## authors
 
 The authors of the package. **Required**
 
 This is a list of authors and should contain at least one author. Authors must be in the form `name <email>`.
 
+```toml
+authors = [
+    "Sébastien Eustace <sebastien@eustace.io>",
+]
+```
+
 ## maintainers
 
 The maintainers of the package. **Optional**
 
 This is a list of maintainers and should be distinct from authors. Maintainers may contain an email and be in the form `name <email>`.
 
+```toml
+maintainers = [
+    "Richard Brave <email@example.org>",
+]
+```
+
 ## readme
 
 The readme file of the package. **Optional**
 
 The file can be either `README.rst` or `README.md`.
 
+```toml
+readme = "README.md" # or "README.rst"
+```
+
 ## homepage
 
 An URL to the website of the project. **Optional**
 
+```toml
+homepage = "https://python-poetry.org/"
+```
+
 ## repository
 
 An URL to the repository of the project. **Optional**
 
+```toml
+repository = "https://github.com/python-poetry/poetry"
+```
+
 ## documentation
 
 An URL to the documentation of the project. **Optional**
 
+```toml
+documentation = "https://python-poetry.org/docs/"
+```
+
 ## keywords
 
 A list of keywords that the package is related to. **Optional**
 
+```toml
+keywords = ["packaging", "poetry"]
+```
+
 ## classifiers
 
 A list of PyPI [trove classifiers](https://pypi.org/classifiers/) that describe the project. **Optional**