Trouble with a packaging tutorial: Licence build issue

[Nordicus]

OS version

Ubuntu 20.04 LTS

Python version

3.12.8

Pip version

25.0

Guide link

https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives

Problem description

Trying to follow the guide as best as possible, but I run into an error when running python3 -m build for some backends but not others.
The error for setuptools is included below. Flit has a different error, also apparently related to the license and license-files fields.
Hatchling and PDM both build successfully.

If I comment out the license field only, I get the error that configuration error: `project` must not contain {'license-files'} properties and if I comment out both, then the contents of LICENSE appears to be included in the output. (adding 'example_package_[MY_UNAME]-0.0.1.dist-info/LICENSE' is not present if the LICENSE file is deleted).

My question is, why is the behaviour of each build system so different WRT including the license, and how do I know the correct way to specify the license for each individual build system? If I want to use setuptools specifically (it seems to be considered standard practice in my org) what is the "right" way to include a license?

Can the tutorial also be updated to reflect the fact that the body of the [project] section of pyproject.toml changes based on the build system used?

Error message

$python3 -m build
* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
  - setuptools>=61.0
* Getting build dependencies for sdist...
configuration error: `project.license` must be valid exactly by one definition (2 matches found):

    - keys:
        'file': {type: string}
      required: ['file']
    - keys:
        'text': {type: string}
      required: ['text']

DESCRIPTION:
    `Project license <https://peps.python.org/pep-0621/#license>`_.

GIVEN VALUE:
    "MIT"

OFFENDING RULE: 'oneOf'

DEFINITION:
    {
        "oneOf": [
            {
                "properties": {
                    "file": {
                        "type": "string",
                        "$$description": [
                            "Relative path to the file (UTF-8) which contains the license for the",
                            "project."
                        ]
                    }
                },
                "required": [
                    "file"
                ]
            },
            {
                "properties": {
                    "text": {
                        "type": "string",
                        "$$description": [
                            "The license of the project whose meaning is that of the",
                            "`License field from the core metadata",
                            "<https://packaging.python.org/specifications/core-metadata/#license>`_."
                        ]
                    }
                },
                "required": [
                    "text"
                ]
            }
        ]
    }
Traceback (most recent call last):
  File "[REDACTED_FILE_LOCATION]/.conda/envs/PackagingTutoral/lib/python3.12/site-packages/pyproject_hooks/_in_process/_in_process.py", line 389, in <module>
    main()
  File "[REDACTED_FILE_LOCATION]/.conda/envs/PackagingTutoral/lib/python3.12/site-packages/pyproject_hooks/_in_process/_in_process.py", line 373, in main
    json_out["return_val"] = hook(**hook_input["kwargs"])
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "[REDACTED_FILE_LOCATION]/.conda/envs/PackagingTutoral/lib/python3.12/site-packages/pyproject_hooks/_in_process/_in_process.py", line 317, in get_requires_for_build_sdist
    return hook(config_settings)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/build-env-_58y_gfp/lib/python3.12/site-packages/setuptools/build_meta.py", line 337, in get_requires_for_build_sdist
    return self._get_build_requires(config_settings, requirements=[])
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/build-env-_58y_gfp/lib/python3.12/site-packages/setuptools/build_meta.py", line 304, in _get_build_requires
    self.run_setup()
  File "/tmp/build-env-_58y_gfp/lib/python3.12/site-packages/setuptools/build_meta.py", line 320, in run_setup
    exec(code, locals())
  File "<string>", line 1, in <module>
  File "/tmp/build-env-_58y_gfp/lib/python3.12/site-packages/setuptools/__init__.py", line 117, in setup
    return distutils.core.setup(**attrs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/build-env-_58y_gfp/lib/python3.12/site-packages/setuptools/_distutils/core.py", line 160, in setup
    dist.parse_config_files()
  File "/tmp/build-env-_58y_gfp/lib/python3.12/site-packages/setuptools/dist.py", line 652, in parse_config_files
    pyprojecttoml.apply_configuration(self, filename, ignore_option_errors)
  File "/tmp/build-env-_58y_gfp/lib/python3.12/site-packages/setuptools/config/pyprojecttoml.py", line 72, in apply_configuration
    config = read_configuration(filepath, True, ignore_option_errors, dist)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/build-env-_58y_gfp/lib/python3.12/site-packages/setuptools/config/pyprojecttoml.py", line 140, in read_configuration
    validate(subset, filepath)
  File "/tmp/build-env-_58y_gfp/lib/python3.12/site-packages/setuptools/config/pyprojecttoml.py", line 61, in validate
    raise ValueError(f"{error}\n{summary}") from None
ValueError: invalid pyproject.toml config: `project.license`.
configuration error: `project.license` must be valid exactly by one definition (2 matches found):

    - keys:
        'file': {type: string}
      required: ['file']
    - keys:
        'text': {type: string}
      required: ['text']


ERROR Backend subprocess exited when trying to invoke get_requires_for_build_sdist

[henryiii]

The new license-files field was recently standardized and isn't handled in a standard way across backends yet. The license field is optional, and I'd recommend not setting it for now. It's only not optional if you set license-files. The current standard is to specify the license in your Trove Classifiers, and all backends should find LICENSE.* and copy those into the SDist/wheels. In the future, once all backends implement PEP 639 (license-files and string-valued license field in METADATA 2.4) properly, then you can use those two fields instead. Things like Pip, PyPI, and twine are only just now started to support METADATA 2.4. Setuptools is still stuck on something like METADATA 2.2 IIRC.

It looks like someone was a bit forward-thinking and updated the tutorial for PEP 639. Flit and setuptools have not added support yet.

[befeleme]

Hello,
Please review the updated page: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license
The diff of changes can be seen here: https://github.com/pypa/packaging.python.org/pull/1815/files

[cdce8p]

Hello, Please review the updated page: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license The diff of changes can be seen here: https://github.com/pypa/packaging.python.org/pull/1815/files

That page hasn't updated for me. I'd have suspected a caching issue but the PR was merged two days ago.

[befeleme]

Huh, it's true. @webknjaz - could you take a look? The cron jobs of packaging.python.org appear to have run successfully from commits containing the change.

[webknjaz]

The current standard is to specify the license in your Trove Classifiers

@henryiii just a nit: it's not a standard but rather a convention.

[webknjaz]

@befeleme apparently, the latest build got stuck: https://app.readthedocs.org/projects/python-packaging-user-guide/builds/27216162/.

FTR, GHA cron runs don't publish the docs. GHA only runs as a convenient check for whether it builds. RTD has their own build system that runs on pull_request and push events (on merge essentially).

[webknjaz]

Clicked Rebuild. It should be fine now: https://app.readthedocs.org/projects/python-packaging-user-guide/builds/27241778/.

[webknjaz]

That page hasn't updated for me. I'd have suspected a caching issue but the PR was merged two days ago.

Verified that the updated page has new text.

[zahlman]

Please note that Setuptools 77 adds support for the new standard.