"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/pyproject.md" between
poetry-1.1.15.tar.gz and poetry-1.2.0.tar.gz

About: Poetry is a tool for dependency management and packaging in Python.

[ To the main poetry source changes report ]

pyproject.md  (poetry-1.1.15):pyproject.md  (poetry-1.2.0)
skipping to change at line 20 skipping to change at line 20
--- ---
# The `pyproject.toml` file # The `pyproject.toml` file
The `tool.poetry` section of the `pyproject.toml` file is composed of multiple s ections. The `tool.poetry` section of the `pyproject.toml` file is composed of multiple s ections.
## name ## name
The name of the package. **Required** The name of the package. **Required**
This should be a valid name as defined by [PEP 508](https://peps.python.org/pep-
0508/#names).
```toml
name = "my-package"
```
## version ## version
The version of the package. **Required** The version of the package. **Required**
This should follow [semantic versioning](http://semver.org/). However it will no This should be a valid [PEP 440](https://peps.python.org/pep-0440/) string.
t be enforced and you remain
free to follow another specification. ```toml
version = "0.1.0"
```
{{% note %}}
If you would like to use semantic versioning for your project, please see
[here]({{< relref "libraries#versioning" >}}).
{{% /note %}}
## description ## description
A short description of the package. **Required** A short description of the package. **Required**
```toml
description = "A short description of the package."
```
## license ## license
The license of the package. The license of the package.
The recommended notation for the most common licenses is (alphabetical): The recommended notation for the most common licenses is (alphabetical):
* Apache-2.0 * Apache-2.0
* BSD-2-Clause * BSD-2-Clause
* BSD-3-Clause * BSD-3-Clause
* BSD-4-Clause * BSD-4-Clause
skipping to change at line 54 skipping to change at line 74
* GPL-3.0-or-later * GPL-3.0-or-later
* LGPL-2.1-only * LGPL-2.1-only
* LGPL-2.1-or-later * LGPL-2.1-or-later
* LGPL-3.0-only * LGPL-3.0-only
* LGPL-3.0-or-later * LGPL-3.0-or-later
* MIT * MIT
Optional, but it is highly recommended to supply this. Optional, but it is highly recommended to supply this.
More identifiers are listed at the [SPDX Open Source License Registry](https://s pdx.org/licenses/). More identifiers are listed at the [SPDX Open Source License Registry](https://s pdx.org/licenses/).
```toml
license = "MIT"
```
{{% note %}} {{% note %}}
If your project is proprietary and does not use a specific licence, you can set this value as `Proprietary`. If your project is proprietary and does not use a specific licence, you can set this value as `Proprietary`.
{{% /note %}} {{% /note %}}
## authors ## authors
The authors of the package. **Required** The authors of the package. **Required**
This is a list of authors and should contain at least one author. Authors must b e in the form `name <email>`. This is a list of authors and should contain at least one author. Authors must b e in the form `name <email>`.
```toml
authors = [
"Sébastien Eustace <sebastien@eustace.io>",
]
```
## maintainers ## maintainers
The maintainers of the package. **Optional** The maintainers of the package. **Optional**
This is a list of maintainers and should be distinct from authors. Maintainers m ay contain an email and be in the form `name <email>`. This is a list of maintainers and should be distinct from authors. Maintainers m ay contain an email and be in the form `name <email>`.
```toml
maintainers = [
"John Smith <johnsmith@example.org>",
"Jane Smith <janesmith@example.org>",
]
```
## readme ## readme
The readme file of the package. **Optional** A path, or list of paths corresponding to the README file(s) of the package.
**Optional**
The file(s) can be of any format, but if you intend to publish to PyPI keep the
[recommendations for a PyPI-friendly README](
https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/) in
mind. README paths are implicitly relative to `pyproject.toml`.
The contents of the README file(s) are used to populate the [Description
field](https://packaging.python.org/en/latest/specifications/core-metadata/#desc
ription-optional)
of your distribution's metadata (similar to `long_description` in setuptools).
When multiple files are specified they are concatenated with newlines.
```toml
[tool.poetry]
# ...
readme = "README.md"
```
The file can be either `README.rst` or `README.md`. ```toml
[tool.poetry]
# ...
readme = ["docs/README1.md", "docs/README2.md"]
```
## homepage ## homepage
An URL to the website of the project. **Optional** An URL to the website of the project. **Optional**
```toml
homepage = "https://python-poetry.org/"
```
## repository ## repository
An URL to the repository of the project. **Optional** An URL to the repository of the project. **Optional**
```toml
repository = "https://github.com/python-poetry/poetry"
```
## documentation ## documentation
An URL to the documentation of the project. **Optional** An URL to the documentation of the project. **Optional**
```toml
documentation = "https://python-poetry.org/docs/"
```
## keywords ## keywords
A list of keywords (max: 5) that the package is related to. **Optional** A list of keywords that the package is related to. **Optional**
```toml
keywords = ["packaging", "poetry"]
```
## classifiers ## classifiers
A list of PyPI [trove classifiers](https://pypi.org/classifiers/) that describe the project. **Optional** A list of PyPI [trove classifiers](https://pypi.org/classifiers/) that describe the project. **Optional**
```toml ```toml
[tool.poetry] [tool.poetry]
# ... # ...
classifiers = [ classifiers = [
"Topic :: Software Development :: Build Tools", "Topic :: Software Development :: Build Tools",
skipping to change at line 166 skipping to change at line 239
another package named `extra_package`, you will need to specify `my_package` exp licitly: another package named `extra_package`, you will need to specify `my_package` exp licitly:
```toml ```toml
packages = [ packages = [
{ include = "my_package" }, { include = "my_package" },
{ include = "extra_package" }, { include = "extra_package" },
] ]
``` ```
{{% /note %}} {{% /note %}}
{{% note %}}
Poetry is clever enough to detect Python subpackages.
Thus, you only have to specify the directory where your root package resides.
{{% /note %}}
## include and exclude ## include and exclude
A list of patterns that will be included in the final package. A list of patterns that will be included in the final package.
You can explicitly specify to Poetry that a set of globs should be ignored or in cluded for the purposes of packaging. You can explicitly specify to Poetry that a set of globs should be ignored or in cluded for the purposes of packaging.
The globs specified in the exclude field identify a set of files that are not in cluded when a package is built. The globs specified in the exclude field identify a set of files that are not in cluded when a package is built.
If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (`.gitignore` for git for example). If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (`.gitignore` for git for example).
{{% note %}}
Explicitly declaring entries in `include` will negate VCS' ignore settings.
{{% /note %}}
```toml ```toml
[tool.poetry] [tool.poetry]
# ... # ...
include = ["CHANGELOG.md"] include = ["CHANGELOG.md"]
``` ```
You can also specify the formats for which these patterns have to be included, a
s shown here:
```toml
[tool.poetry]
# ...
include = [
{ path = "tests", format = "sdist" },
{ path = "for_wheel.txt", format = ["sdist", "wheel"] }
]
```
If no format is specified, it will default to include both `sdist` and `wheel`.
```toml ```toml
exclude = ["my_package/excluded.py"] exclude = ["my_package/excluded.py"]
``` ```
## `dependencies` and `dev-dependencies` ## dependencies and dependency groups
Poetry is configured to look for dependencies on [PyPi](https://pypi.org) by def ault. Poetry is configured to look for dependencies on [PyPI](https://pypi.org) by def ault.
Only the name and a version string are required in this case. Only the name and a version string are required in this case.
```toml ```toml
[tool.poetry.dependencies] [tool.poetry.dependencies]
requests = "^2.13.0" requests = "^2.13.0"
``` ```
If you want to use a private repository, you can add it to your `pyproject.toml` If you want to use a [private repository]({{< relref "repositories#using-a-priva
file, like so: te-repository" >}}),
you can add it to your `pyproject.toml` file, like so:
```toml ```toml
[[tool.poetry.source]] [[tool.poetry.source]]
name = 'private' name = "private"
url = 'http://example.com/simple' url = "http://example.com/simple"
```
If you have multiple repositories configured, you can explicitly tell poetry whe
re to look for a specific package:
```toml
[tool.poetry.dependencies]
requests = { version = "^2.13.0", source = "private" }
``` ```
{{% note %}} {{% note %}}
Be aware that declaring the python version for which your package Be aware that declaring the python version for which your package
is compatible is mandatory: is compatible is mandatory:
```toml ```toml
[tool.poetry.dependencies] [tool.poetry.dependencies]
python = "^3.6" python = "^3.7"
``` ```
{{% /note %}} {{% /note %}}
You can organize your dependencies in [groups]({{< relref "managing-dependencies
#dependency-groups" >}})
to manage them in a more granular way.
```toml
[tool.poetry.group.test.dependencies]
pytest = "*"
[tool.poetry.group.docs.dependencies]
mkdocs = "*"
```
See [Dependency groups]({{< relref "managing-dependencies#dependency-groups" >}}
) for a more in-depth look
at how to manage dependency groups and [Dependency specification]({{< relref "de
pendency-specification" >}})
for more information on other keys and specifying version ranges.
## `scripts` ## `scripts`
This section describes the scripts or executables that will be installed when in stalling the package This section describes the scripts or executables that will be installed when in stalling the package
```toml ```toml
[tool.poetry.scripts] [tool.poetry.scripts]
poetry = 'poetry.console:run' my_package_cli = 'my_package.console:run'
``` ```
Here, we will have the `poetry` script installed which will execute `console.run Here, we will have the `my_package_cli` script installed which will execute the
` in the `poetry` package. `run` function in the `console` module in the `my_package` package.
To specify a script that [depends on an extra](#extras), you may provide an entr
y as an inline table:
```toml
[tool.poetry.scripts]
devtest = { callable = "mypackage:test.run_tests", extras = ["test"] }
```
{{% note %}} {{% note %}}
When a script is added or updated, run `poetry install` to make them available i n the project's virtualenv. When a script is added or updated, run `poetry install` to make them available i n the project's virtualenv.
{{% /note %}} {{% /note %}}
## `extras` ## `extras`
Poetry supports extras to allow expression of: Poetry supports extras to allow expression of:
* optional dependencies, which enhance a package, but are not required; and * optional dependencies, which enhance a package, but are not required; and
skipping to change at line 245 skipping to change at line 371
```toml ```toml
[tool.poetry] [tool.poetry]
name = "awesome" name = "awesome"
[tool.poetry.dependencies] [tool.poetry.dependencies]
# These packages are mandatory and form the core of this package’s distribution. # These packages are mandatory and form the core of this package’s distribution.
mandatory = "^1.0" mandatory = "^1.0"
# A list of all of the optional dependencies, some of which are included in the # A list of all of the optional dependencies, some of which are included in the
# below `extras`. They can be opted into by apps. # below `extras`. They can be opted into by apps.
psycopg2 = { version = "^2.7", optional = true } psycopg2 = { version = "^2.9", optional = true }
mysqlclient = { version = "^1.3", optional = true } mysqlclient = { version = "^1.3", optional = true }
[tool.poetry.extras] [tool.poetry.extras]
mysql = ["mysqlclient"] mysql = ["mysqlclient"]
pgsql = ["psycopg2"] pgsql = ["psycopg2"]
databases = ["mysqlclient", "psycopg2"]
``` ```
When installing packages, you can specify extras by using the `-E|--extras` opti on: When installing packages with Poetry, you can specify extras by using the `-E|-- extras` option:
```bash ```bash
poetry install --extras "mysql pgsql" poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql poetry install -E mysql -E pgsql
``` ```
Or, you can install all extras with the `--all-extras` option:
```bash
poetry install --all-extras
```
When installing or specifying Poetry-built packages, the extras defined in this
section can be activated
as described in [PEP 508](https://www.python.org/dev/peps/pep-0508/#extras).
For example, when installing the package using `pip`, the dependencies required
by
the `databases` extra can be installed as shown below.
```bash
pip install awesome[databases]
```
{{% note %}}
The dependencies specified for each `extra` must already be defined as project d
ependencies.
Dependencies listed in [dependency groups]({{< relref "managing-dependencies#dep
endency-groups" >}}) cannot be specified as extras.
{{% /note %}}
## `plugins` ## `plugins`
Poetry supports arbitrary plugins which work similarly to Poetry supports arbitrary plugins which work similarly to
[setuptools entry points](http://setuptools.readthedocs.io/en/latest/setuptools. html). [setuptools entry points](http://setuptools.readthedocs.io/en/latest/setuptools. html).
To match the example in the setuptools documentation, you would use the followin g: To match the example in the setuptools documentation, you would use the followin g:
```toml ```toml
[tool.poetry.plugins] # Optional super table [tool.poetry.plugins] # Optional super table
[tool.poetry.plugins."blogtool.parsers"] [tool.poetry.plugins."blogtool.parsers"]
skipping to change at line 283 skipping to change at line 432
## `urls` ## `urls`
In addition to the basic urls (`homepage`, `repository` and `documentation`), yo u can specify In addition to the basic urls (`homepage`, `repository` and `documentation`), yo u can specify
any custom url in the `urls` section. any custom url in the `urls` section.
```toml ```toml
[tool.poetry.urls] [tool.poetry.urls]
"Bug Tracker" = "https://github.com/python-poetry/poetry/issues" "Bug Tracker" = "https://github.com/python-poetry/poetry/issues"
``` ```
If you publish you package on PyPI, they will appear in the `Project Links` sect ion. If you publish your package on PyPI, they will appear in the `Project Links` sec tion.
## Poetry and PEP-517 ## Poetry and PEP-517
[PEP-517](https://www.python.org/dev/peps/pep-0517/) introduces a standard way [PEP-517](https://www.python.org/dev/peps/pep-0517/) introduces a standard way
to define alternative build systems to build a Python project. to define alternative build systems to build a Python project.
Poetry is compliant with PEP-517, by providing a lightweight core library, Poetry is compliant with PEP-517, by providing a lightweight core library,
so if you use Poetry to manage your Python project you should reference so if you use Poetry to manage your Python project you should reference
it in the `build-system` section of the `pyproject.toml` file like so: it in the `build-system` section of the `pyproject.toml` file like so:
```toml ```toml
[build-system] [build-system]
requires = ["poetry_core>=1.0.0"] requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api" build-backend = "poetry.core.masonry.api"
``` ```
{{% note %}} {{% note %}}
When using the `new` or `init` command this section will be automatically added. When using the `new` or `init` command this section will be automatically added.
{{% /note %}} {{% /note %}}
{{% note %}} {{% note %}}
If your `pyproject.toml` file still references `poetry` directly as a build back end, If your `pyproject.toml` file still references `poetry` directly as a build back end,
you should update it to reference `poetry-core` instead. you should update it to reference `poetry-core` instead.
 End of changes. 29 change blocks. 
20 lines changed or deleted 180 lines changed or added
To the Text Files section of the poetry source changes report or the top of this page
Mainly generated by pkgdiff using rfcdiff
Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)