pyproject.toml: specify description is one line

[henryiii]

See pypa/pyproject-metadata#30. This fills the Summary field, which must be a single line, so this should also be a single line. Historically, tools have done different things here. Setuptools removes anything after the first line. pyproject-metadata based backends (pdm-backend, scikit-build-core, and meson-python) join the lines into one line. The next version of scikit-build-core will error instead. Third party tools reading a config like this:

[project]
description = """Two
Line"""

Cannot know if the Summary will be "Two Line", "Two", or an error.

Enforcing this as one line also helps authors that put what should go into project.readme.text here instead.

There are three levels of response possible here, this PR is the middle one:

1. Just mention one line, pulled from the Summary field.
2. Mention that tools MAY error here. That's the current state of this PR. I think this will help validation tools (validate-pyproject and SchemaStore) make newlines a validation error.
3. Say tools MUST error. My favorite, I think it would help authors in the long run, but probably too late to do this.

---

📚 Documentation preview 📚: https://python-packaging-user-guide--1533.org.readthedocs.build/en/1533/

[chrysle]

Say tools MUST error. My favorite, I think it would help authors in the long run, but probably too late to do this.

I believe adding a ruff rule with an auto-fixing mechanism could be rewarding, and wouldn't pose a big problem concerning migration?

[edgarrmondragon]

Say tools MUST error. My favorite, I think it would help authors in the long run, but probably too late to do this.

I believe adding a ruff rule with an auto-fixing mechanism could be rewarding, and wouldn't pose a big problem concerning migration?

Would https://github.com/tox-dev/pyproject-fmt be a better place for such an auto-fix?

In fact it already strips whitespace from the description field: https://github.com/tox-dev/pyproject-fmt/blob/bb6005786f6624d72a66b7be876696a788ce7414/src/pyproject_fmt/formatter/project.py#L41-L42

[abravalheri]

Say tools MUST error. My favorite, I think it would help authors in the long run, but probably too late to do this.

When we tried to enforce one-line Summary in the core metadata, we got a very hard push back from the community (see the generalised commotion in pypa/setuptools#1390 and pypa/setuptools#2893). I don't think we are currently in a position that it will not bring disruption to the community if we try something similar again. (Enforcing on pyproject.toml might be different... but since historically we have already been told off by the community, I am not sure what would be the willingness of setuptools to try it).

The middle ground option sounds good.

[henryiii]

FYI, the problem was backward compatibility; people didn't want a project that used to build start to fail due to this. Failing a previously passing build is the problem, and there's not usually a way around it.¹ Projects that don't have a large user base absolutely can (and should in my opinion) error on this. It was only because older code supported it. It would have been nice if the pyproject.toml support had included it from the start, as there was no legacy at that time, but it is obviously too late. 0.2% of pyproject.tomls with a project.description field on PyPI have multiline descriptions, and all the ones I checked obviously didn't know it was supposed to be a single line, and would get chopped. All of them would like like knowing this, but zero of them would like this to cause their SDists to no longer be buildable into a wheel.

Ruff does not auto fix or even lint pyproject.toml. validate-pyproject lints pyproject.toml, and pyproject-fmt formats it. I think both places² would be good places to check for this. I think pyproject-fmt should automatically remove newlines, maybe making them escaped newlines.

Footnotes

1. Scikit-build-core actually does have a way around it; the minimum-version field is used to handle this. But no other build backend has this built in that I'm aware of. ↩

2. I think validate-pyproject is used internally by setuptools, so that might be a problem adding a regex here to protect against newlines? ↩

[chrysle]

Ruff does not auto fix or even lint pyproject.toml.

Hmm, I checked the docs and there was one certain RUF200 rule which sounded promising... However doing this in pyproject-fmt also makes sense to me, while setuptools, as you mentioned invokes validate-pyproject; I personally see fixing a build error like this as a small maintenance task that can be done on the side, and especially large projects should have pyproject.toml linting configured – but I trust you can estimate the overall downside better.

[edgarrmondragon]

Ruff does not auto fix or even lint pyproject.toml.

Hmm, I checked the docs and there was one certain RUF200 rule which sounded promising... However doing this in pyproject-fmt also makes sense to me, while setuptools, as you mentioned invokes validate-pyproject; I personally see fixing a build error like this as a small maintenance task that can be done on the side, and especially large projects should have pyproject.toml linting configured – but I trust you can estimate the overall downside better.

Latest pyproject-fmt now formats description into a one line string.

[chrysle]

Latest pyproject-fmt now formats description into a one line string.

Great, thanks for the initiative!

[chrysle]

Thanks!