What's difference between [tool.poetry] and [project] in pyproject.toml?
Question:
Context
So, I’m trying to create a new python package following this guideline: https://packaging.python.org/en/latest/tutorials/packaging-projects/
As a guideline says – in my pyproject.toml I should have this structure:
[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
{ name="Example Author", email="[email protected]" },
]
description = "A small example package"
but, when I’ve created this file with poetry init I have this structure:
[tool.poetry]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
{ name="Example Author", email="[email protected]" },
]
description = "A small example package"
The main difference between this two is project and tool.poetry headers for sections.
I also see, that poetry can’t do anything with project, when there is no [tool.poetry] in pyproject.toml
So my questions is:
- What the difference between this two?
- Should I have only one or both at the same time in my
pyproject.toml? And what should contain what if I should keep both?
- If there should be only
[tool.poetry] – so I need to follow same rules for [project] sections naming? So [project.urls] will be renamed to [tool.poetry.urls]?
- What is best for future publishing on PyPI? Or there is no difference?
- Is changing
[build-system] from poetry-core to setuptools is a good idea? Or I should keep poetry-core?
Answers:
The [project] section is mandatory in pyproject.toml. If the entry is missing, the build tool (defined in [build-system] section) have to add it dynamically. I guess that’s exactly what poetry does.
From the documentation:
The keys defined in this specification MUST be in a table named [project] in pyproject.toml. No tools may add keys to this table which are not defined by this specification. For tools wishing to store their own settings in pyproject.toml, they may use the [tool] table as defined in the build dependency declaration specification. The lack of a [project] table implicitly means the build back-end will dynamically provide all keys.
So you don’t need the [project] while you are using poetry. If you change the build system, you must convert your pyproject.toml to be PEP 621 compliant.
1. What the difference between this two?
The [project] section is standardized (also known as PEP-621). But Poetry is older than the creation of this standard, so it started by using its own section [tool.poetry]. Poetry is planning to add support for the standardized [project] (see python-poetry/poetry/issues/3332 and python-poetry/roadmap/issues/3), but it takes time.
The differences between the two are quite small, they are basically different notations for the same package metadata.
2. Should I have only one or both at the same time in my pyproject.toml? And what should contain what if I should keep both?
You should have only one. You have to choose a build back-end. If your build back-end is poetry-core then you need the [tool.poetry] section. If you choose a build back-end that requires [project] (which is the case of setuptools), then that is what you should have.
3. If there should be only [tool.poetry] – so I need to follow same rules for [project] sections naming? So [project.urls] will be renamed to [tool.poetry.urls]?
This is not exactly one-to-one equivalent, there are some differences. Follow Poetry‘s documentation if you use Poetry. Or the [project] specification if you use something else (setuptools, etc.).
4. What is best for future publishing on PyPI? Or there is no difference?
There is not much difference. You could argue that choosing a build back-end that follows the [project] standard is better, but really it is not what you should base your choice on. There are many other criteria you should base your choice on.
For example:
- https://sinoroc.gitlab.io/kb/python/packaging_tools_comparisons.html#development-workflow-tools
- https://sinoroc.gitlab.io/kb/python/packaging_tools_comparisons.html#build-back-ends
5. Is changing [build-system] from poetry-core to setuptools is a good idea? Or I should keep poetry-core?
Poetry the "development workflow tool" does not allow using any other build back-end than poetry-core. So if you want to keep using Poetry for your project, you have no choice but to keep using poetry-core as build back-end.
Context
So, I’m trying to create a new python package following this guideline: https://packaging.python.org/en/latest/tutorials/packaging-projects/
As a guideline says – in my pyproject.toml I should have this structure:
[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
{ name="Example Author", email="[email protected]" },
]
description = "A small example package"
but, when I’ve created this file with poetry init I have this structure:
[tool.poetry]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
{ name="Example Author", email="[email protected]" },
]
description = "A small example package"
The main difference between this two is project and tool.poetry headers for sections.
I also see, that poetry can’t do anything with project, when there is no [tool.poetry] in pyproject.toml
So my questions is:
- What the difference between this two?
- Should I have only one or both at the same time in my
pyproject.toml? And what should contain what if I should keep both? - If there should be only
[tool.poetry]– so I need to follow same rules for[project]sections naming? So[project.urls]will be renamed to[tool.poetry.urls]? - What is best for future publishing on PyPI? Or there is no difference?
- Is changing
[build-system]frompoetry-coretosetuptoolsis a good idea? Or I should keeppoetry-core?
The [project] section is mandatory in pyproject.toml. If the entry is missing, the build tool (defined in [build-system] section) have to add it dynamically. I guess that’s exactly what poetry does.
From the documentation:
The keys defined in this specification MUST be in a table named [project] in pyproject.toml. No tools may add keys to this table which are not defined by this specification. For tools wishing to store their own settings in pyproject.toml, they may use the [tool] table as defined in the build dependency declaration specification. The lack of a [project] table implicitly means the build back-end will dynamically provide all keys.
So you don’t need the [project] while you are using poetry. If you change the build system, you must convert your pyproject.toml to be PEP 621 compliant.
1. What the difference between this two?
The [project] section is standardized (also known as PEP-621). But Poetry is older than the creation of this standard, so it started by using its own section [tool.poetry]. Poetry is planning to add support for the standardized [project] (see python-poetry/poetry/issues/3332 and python-poetry/roadmap/issues/3), but it takes time.
The differences between the two are quite small, they are basically different notations for the same package metadata.
2. Should I have only one or both at the same time in my pyproject.toml? And what should contain what if I should keep both?
You should have only one. You have to choose a build back-end. If your build back-end is poetry-core then you need the [tool.poetry] section. If you choose a build back-end that requires [project] (which is the case of setuptools), then that is what you should have.
3. If there should be only [tool.poetry] – so I need to follow same rules for [project] sections naming? So [project.urls] will be renamed to [tool.poetry.urls]?
This is not exactly one-to-one equivalent, there are some differences. Follow Poetry‘s documentation if you use Poetry. Or the [project] specification if you use something else (setuptools, etc.).
4. What is best for future publishing on PyPI? Or there is no difference?
There is not much difference. You could argue that choosing a build back-end that follows the [project] standard is better, but really it is not what you should base your choice on. There are many other criteria you should base your choice on.
For example:
- https://sinoroc.gitlab.io/kb/python/packaging_tools_comparisons.html#development-workflow-tools
- https://sinoroc.gitlab.io/kb/python/packaging_tools_comparisons.html#build-back-ends
5. Is changing [build-system] from poetry-core to setuptools is a good idea? Or I should keep poetry-core?
Poetry the "development workflow tool" does not allow using any other build back-end than poetry-core. So if you want to keep using Poetry for your project, you have no choice but to keep using poetry-core as build back-end.