12

Context

So, I'm trying to create a new Python package following this tutorial: https://packaging.python.org/en/latest/tutorials/packaging-projects/

As the tutorial 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="author@example.com" },
]
description = "A small example package"

but when I created this file with poetry init, it created this structure:

[tool.poetry]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
  { name="Example Author", email="author@example.com" },
]
description = "A small example package"

The main difference between these two is the [project] instead of [tool.poetry] section header. I also see, that poetry can't do anything with the project, when there is no [tool.poetry] section in pyproject.toml

So my questions are:

  1. What are the differences between these two?

  2. Should I have only one or both at the same time in my pyproject.toml? And in case I should keep both, what should it contain?

  3. In case there should be only [tool.poetry], do I need to follow the same rules for the content and sub-sections as for [project]? So for example [project.urls] would be renamed to [tool.poetry.urls]?

  4. What is the best future-proof choice for publishing on PyPI? Or are there no difference?

  5. Is changing the [build-system] from poetry-core to setuptools a good idea? Or I should keep poetry-core?

sinoroc
  • 18,409
  • 2
  • 39
  • 70
toiletsandpaper
  • 139
  • 1
  • 6

2 Answers2

16

1. What are the differences between these 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. The most notable difference (the one you should keep an eye on) is regarding the notation for declaring the dependencies. This is where the divergence is the most critical.

2. Should I have only one or both at the same time in my pyproject.toml? And in case I should keep both, what should it contain?

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. In case there should be only [tool.poetry], do I need to follow the same rules for the content and sub-sections as for [project]? So for example [project.urls] would 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 the best future-proof choice for publishing on PyPI? Or are there no difference?

This is for you (and your team) to decide. One could argue that choosing a build back-end that follows the [project] standard is more future-proof, but it is only one criteria amongst many. The following tables compare some features one could take into account when making such a choice:

5. Is changing the [build-system] from poetry-core to setuptools 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.

sinoroc
  • 18,409
  • 2
  • 39
  • 70
  • Thank you for your well-written description. This is very helpful! Especially about `poetry` developer's plans about adding support of `[project]`. And for tool comparisons too – toiletsandpaper Feb 10 '23 at 12:42
1

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.

Corralien
  • 109,409
  • 8
  • 28
  • 52
  • So, if I switch `[build-system]` to `setuptools` - I need to use `[project]`, but if I switch to `poetry-core` - I need to use [tool.poetry]? So how can I use poetry as venv handler, but use `setuptools` as build backend? – toiletsandpaper Feb 10 '23 at 09:11
  • Why do you want to have 2 tools? poetry can do the job. – Corralien Feb 10 '23 at 09:14
  • Just curious about changing backend, ofc I can leave as `poetry-core`. I'm just trying to understand all aspects of `poetry` capabilities. Knowledge is power, as someone said :) – toiletsandpaper Feb 10 '23 at 09:18
  • 2
    It's a bad idea to mix package managers. Just one tool to handle `[build-system]` section. Setuptools is also able to use [dynamic directives](https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html#dynamic-metadata) under the section `[tool.setuptools.dynamic]` like version. – Corralien Feb 10 '23 at 09:36