Support PEP 639 license metadata

[dunossauro]

What is the problem or limitation you are having?

When we already have a pyproject.toml file created, if it follows PEP 639, we encounter an issue when creating a package with briefcase.

Examples:

pyproject.toml file:

[project]
name = "Example"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
# license = {file = "LICENSE", text = 'BSD'} # PEP 621 format
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "httpx (>=0.28.1,<0.29.0)",
]
# PEP 639 format
license = 'BSD'
license-files = ["LICEN[CS]E*"]

# ...
[tool.briefcase]
project_name = "Example"
bundle = "com.example"
version = "0.1.0"

[tool.briefcase.app.example]
formal_name = "Example"
sources = ['example']

Briefcase create command:

briefcase create

*************************************************************************
** WARNING: License Definition for the Project is Deprecated           **
*************************************************************************

    Briefcase now uses PEP 621 format for license definitions.

    Previously, the name of the license was assigned to the 'license'
    field in pyproject.toml. For PEP 621, the name of the license is
    assigned to 'license.text' or the name of the file containing the
    license is assigned to 'license.file'.

    The current configuration for the Project has a 'license' field
    that is specified as a string:

        license = "BSD"

    To use the PEP 621 format (and to remove this warning), specify that
    the LICENSE file contains the license for the Project:

        license.file = "LICENSE"

*************************************************************************

Some links:
PEP 639: https://peps.python.org/pep-0639/
PyPA recommendations for defining the license field: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license
pyproject specification by PyPA: https://packaging.python.org/en/latest/specifications/pyproject-toml/#license

Describe the solution you'd like

Support for both PEPs?

Describe alternatives you've considered

Currently, I am using fields defined from PEP 261

Additional context

No response

[freakboy3742]

Thanks for the suggestion. Briefcase tries wherever possible to adhere to current Python packaging best practices. Our migration to PEP 621 is a work in progress (see #1219 and #1235); PEP 639 support is another thing to add to the list.

Ironically, we moved away from a bare license field as part of PEP621 support just months before PEP 639 was approved. Looks like we can roll back some of those changes, and put in warnings about the license.file format.

[NMertsch]

With beeware/briefcase-template#200, briefcase new will create new projects using PEP 639 license metadata. However, briefcase create, briefcase convert and possibly other commands must continue to work with pre-PEP 639 projects.

There are situations where this is trivial (i.e. issue a warning, convert the metadata to PEP 639 while parsing pyproject.toml):

• license = "[SPDX license expression]" (pre-PEP 621)
• license.text = "[SPDX license expression]" (PEP 621)
• license.text = "[nonSPDX license expression]", with the license identifiers used by briefcase before Align license terminology with SPDX License List #2272 (PEP 621)
• license.file = "LICENSE" where we can infer the SPDX identifier from the license file content (PEP 621)

But what do we do with these situations?

• license = "[non-SPDX expression]" (pre-PEP 621)
• license.text = "[non-SPDX expression]", with unknown license identifiers (PEP 621)
• license.file = "LICENSE" where we can't infer the SPDX identifier from the license file content (PEP 621)

We could issue a warning and keep the original metadata format (which is deprecated by PEP 621/639). And after some grace period, raise an error and only accept PEP 639 metadata?

I'm not familiar with the Beeware user base and typical use cases, so I can't guess how large the impact on users would actually be.

[freakboy3742]

But what do we do with these situations?

• license = "[non-SPDX expression]" (pre-PEP 621)

This case is currently coerced into license.file = "LICENSE", regardless of whether that file actually exists; the linux packaging step will then fail because there is no file with that name.

I don't think anything in the PEP 639 transition needs to change; the only addition being that we need to differentiate from the PEP639 case based on whether license-files is defined, and update the existing warning message to provide the new suggestion for PEP 639 transition.

If we need to provide a value to ensure that license always exists, something like LicenseRef-Unknown seems like a reasonable "valid under SPDX so it won't explode" value.

• license.text = "[non-SPDX expression]", with unknown license identifiers (PEP 621)

My expectation is that this won't be a common case - anyone coming to this via Briefcase will have either license = '...' or license.files = 'xxx' configurations.

My suggestion would be to take a similar approach to the previous example - use license = "LicenseRef-Unknown", use license-files = ["LICENSE"] (even though this file may not exist), and raise a warning that the license format requires an update. Briefcase will then raise an error when the LICENSE file doesn't exist.

• license.file = "LICENSE" where we can't infer the SPDX identifier from the license file content (PEP 621)

As with the first case, I'd suggest using license = "LicenseRef-Unknown", and raising a warning that a valid SPDX value needs to be provided.

Also - I discovered that packaging has an SPDX validator built-in:

>>> from packaging.licenses import canonicalize_license_expression
>>> canonicalize_license_expression("BSD-3-Clause")
'BSD-3-Clause'
>>> canonicalize_license_expression("New BSD")
Traceback (most recent call last):
  File "<python-input-4>", line 1, in <module>
    canonicalize_license_expression("New BSD")
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^
  File "/Users/rkm/projects/pyspamsum/venv/lib/python3.13/site-packages/packaging/licenses/__init__.py", line 106, in canonicalize_license_expression
    raise InvalidLicenseExpression(message) from None
packaging.licenses.InvalidLicenseExpression: Invalid license expression: 'New BSD'

If we've got any content that we're unsure if it might be a valid SPDX identifier, this seems to provide a straightforward way to validate.

Also - it's worth noting that moving to PEP 639 also gives us a chance to fix #1829, because we now have a way to populate license fields that aren't file-based.