pythonpython-packagingpyproject.tomltoml

Can I add custom data to a pyproject.toml file

I am using the toml package to read my pyproject.toml file. I want to add custom data which in this case I will read in my docs/conf.py file. When I try and add a custom section I get errors and warnings from Even Better TOML extension in Vs Code stating that my custom data is no allowed.

Example TOML section in pyproject.toml

[custom.metadata]
docs_name = "GUI Automation for windows"
docs_author = "myname"
docs_copyright = "2023"
docs_url= "https://someurl.readthedocs.io/en/latest/"

So, my question is: Is there a valid way of adding custom data to a pyproject.toml file?

Solution

  • Use a [tool.*] table.

    Quoting PEP 518:

    The [tool] table is where any tool related to your Python project, not just build tools, can have users specify configuration data as long as they use a sub-table within [tool], e.g. the flit tool would store its configuration in [tool.flit].

    Any tools that interpret pyproject.toml files will expect the [tool] sub-tables to contain arbitrary, tool-specific metadata. You should not have any issues populating a custom subtable with whatever project metadata you need.

    In your case, something like this should work warning-free:

    [tool.my_distribution_name]
docs_name = "GUI Automation for windows"
docs_author = "myname"
docs_copyright = "2023"
docs_url= "https://someurl.readthedocs.io/en/latest/"

    Creating your own custom table is not permitted, since PEP 518 reserves all top-level tables in pyproject.toml:

    Tables not specified in this PEP are reserved for future use by other PEPs.