Create simpler "readme =" under [project] instead of [project.readme] section?

[hugovk]

First, thanks for this really useful tool!

Summary

I found a potential bug in pyproject-fmt where it misplaces a [project.readme] section in pyproject.toml leading to an error.

It looks like pyproject-fmt wasn't expecting a [project.readme], and rather expected a readme = under [project], which it handles fine.

And the pyproject.toml was generated by ini2toml from a setup.cfg using -p setup.cfg, perhaps it could create the simpler readme = instead?

Feel free to close this if it's not a good idea!

Details

1. setup.cfg to pyproject.toml

Start with a minimal-ish setup.cfg with a Markdown README:

[metadata]
name = my-name
description = my-description
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/my/project
author = my-author
license = MIT

[options]
packages = find:
python_requires = >=3.7
package_dir = =src

[options.packages.find]
where = src

Convert to pyproject.toml and validate:

$ ini2toml setup.cfg -p setup.cfg -o pyproject.toml; validate-pyproject pyproject.toml
Valid file: pyproject.toml

Creates this pyproject.toml:

[build-system]
requires = ["setuptools>=61.2"]
build-backend = "setuptools.build_meta"

[project]
name = "my-name"
description = "my-description"
authors = [{name = "my-author"}]
license = {text = "MIT"}
urls = {Homepage = "https://github.com/my/project"}
requires-python = ">=3.7"
dynamic = ["version"]

[project.readme]
file = "README.md"
content-type = "text/markdown"

[tool.setuptools]
package-dir = {"" = "src"}
include-package-data = false

[tool.setuptools.packages.find]
where = ["src"]
namespaces = false

Note the README is in its own section:

[project.readme]
file = "README.md"
content-type = "text/markdown"

2. Format with pyproject-fmt

Running:

$ pyproject-fmt pyproject.toml > /dev/null; validate-pyproject pyproject.toml
Invalid file: pyproject.toml
[ERROR] `project` must contain ['version'] properties

Changes the pyproject.toml like this:

--- pyproject.toml

+++ pyproject.toml

@@ -1,19 +1,23 @@

 [build-system]
-requires = ["setuptools>=61.2"]
 build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools>=61.2",
+]

 [project]
-name = "my-name"
+name = "my_name"
 description = "my-description"
-authors = [{name = "my-author"}]
-license = {text = "MIT"}
-urls = {Homepage = "https://github.com/my/project"}
-requires-python = ">=3.7"
-dynamic = ["version"]
-
 [project.readme]
 file = "README.md"
 content-type = "text/markdown"
+
+license = {text = "MIT"}
+authors = [{name = "my-author"}]
+requires-python = ">=3.7"
+dynamic = [
+  "version",
+]
+urls = {Homepage = "https://github.com/my/project"}

 [tool.setuptools]
 package-dir = {"" = "src"}

To this pyproject.toml:

[build-system]
build-backend = "setuptools.build_meta"
requires = [
  "setuptools>=61.2",
]

[project]
name = "my_name"
description = "my-description"
[project.readme]
file = "README.md"
content-type = "text/markdown"

license = {text = "MIT"}
authors = [{name = "my-author"}]
requires-python = ">=3.7"
dynamic = [
  "version",
]
urls = {Homepage = "https://github.com/my/project"}


[tool.setuptools]
package-dir = {"" = "src"}
include-package-data = false

[tool.setuptools.packages.find]
where = ["src"]
namespaces = false

Note that pyproject-fmt inserts [project.readme] right in the middle of the [project] section:

[project]
name = "my_name"
description = "my-description"
[project.readme]
file = "README.md"
content-type = "text/markdown"

license = {text = "MIT"}
...

Alternatively

1. setup.cfg to pyproject.toml and edit

This is likely a pyproject-fmt bug, but if we re-generate pyproject.toml:

$ ini2toml setup.cfg -p setup.cfg -o pyproject.toml; validate-pyproject pyproject.toml
Valid file: pyproject.toml

But manually edit the generated pyproject.toml and simplify the readme config:

 [project]
 name = "my-name"
 description = "my-description"
+readme = "README.md"
 authors = [{name = "my-author"}]
 license = {text = "MIT"}
 urls = {Homepage = "https://github.com/my/project"}
 requires-python = ">=3.7"
 dynamic = ["version"]
 
-[project.readme]
-file = "README.md"
-content-type = "text/markdown"
-
 [tool.setuptools]
 package-dir = {"" = "src"}
 include-package-data = false

(Like pyproject-fmt itself does: https://github.com/tox-dev/pyproject-fmt/blob/e4e90cfa5f3731697673b34067796bbe7c9a8e07/pyproject.toml#L8)

2. Format with pyproject-fmt

This time pyproject-fmt doesn't break the file:

$ pyproject-fmt pyproject.toml > /dev/null; validate-pyproject pyproject.toml
Valid file: pyproject.toml

And makes valid edits:

diff --git a/pyproject.toml b/pyproject.toml
index 3188688..2f57876 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,19 +1,20 @@
 [build-system]
-requires = ["setuptools>=61.2"]
 build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools>=61.2",
+]
 
 [project]
-name = "my-name"
+name = "my_name"
 description = "my-description"
-authors = [{name = "my-author"}]
+readme = "README.md"
 license = {text = "MIT"}
-urls = {Homepage = "https://github.com/my/project"}
+authors = [{name = "my-author"}]
 requires-python = ">=3.7"
-dynamic = ["version"]
-
-[project.readme]
-file = "README.md"
-content-type = "text/markdown"
+dynamic = [
+  "version",
+]
+urls = {Homepage = "https://github.com/my/project"}
 
 [tool.setuptools]
 package-dir = {"" = "src"}

[abravalheri]

Hi @hugovk, thank you very much for the feedback.

In ini2toml I am trying to keep the transformation 1-to-1 as much as possible (at least for the time being) and avoid loss of information. There are quite a few things that might be redundant or that could be simplified, but they are kept because they were explicitly set on setup.cfg. This relationship between long_description and long_description_content_type is one of them.

The approach I have been following is to ensure that the generated TOML is syntactic correct and semantically equivalent. But since the combination of {TOML language/Core Metadata/PEP 621} has a lot of quirks, it is always possible that the user may want to tweak the outcome to their taste.

That said I would be very happy to consider a PR from the community targeting this aspect. Maybe introducing an opt-in flag like --simplified?