Where to get started with pyproject.toml?

Hey all,

I have toi create a new Python package so I thought, for once, I’d try to be doing the right thing and use the new pyproject.toml as well introduced by Brett in https://snarky.ca/what-the-heck-is-pyproject-toml/

But I goty confused quickly unfortunately. It seems no official documentation exists yet around pyproject.toml and the PEPs aren’t user docs. It appears Pypa and the Python docs both continue talking about using setup.py.

I was wondering if there was a place I wasn’t aware of perhaps? Or maybe some help to document it if I can find the time, but then where to start?



The post you linked contains the three lines you need in pyproject.toml. Use setup.py for everything else like you used to.

If you’re looking to adapt the three-file set-up (a three-line pyproject.toml, a setup.py shim, and setup.cfg) as suggested in Brett’s post, here’s documentation on how to write setup.cfg: https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files

Hello Tzu-ping,

Thanks for the feedback.

So as I understand you, pyproject.toml is only meant to declare the build configuration and we still need setup.py/cfg for defining what’s inside the built package, right?

Correct. To be pedantic, setup.py and/or setup.cfg is needed for defining what’s inside the built package if you choose to use setuptools. But most people use setuptools anyway.

1 Like

Well, you an also use a tool that takes care of that for you, such as poetry: https://python-poetry.org/

That still needs further clarification:

We now have 3 files (pyproject.toml, setup.py, setup.cfg) instead of just 1 (setup.py). That sounds like a huge progress! Ha? :roll_eyes:

That can’t be the appropriate answer. There must be a better way!

1 Like

Forgive me if what I’m going to write feels like ranting; I’ve had this discussion with many people and have many thoughts on this topic.

The number of files does not correlate to “goodness”. Each configuration file is a signal to people reading your repository (including your future self) what tools the project uses. You see webpack.config.js and you know a project uses Webpack, not (say) Gulp; pytest.ini for pytest as the designated test runner, noxfile.py for Nox, etc. Each of the three files in this set-up signals different aspects of your project’s tooling. pyproject.toml means this is a Python project. setup.cfg means it is using setuptools for packaging. setup.py means it also uses setuptools during development (note that you don’t need this file if you don’t call python setup.py directly; pip recognise setup.cfg and can run it independently). Can we use only one file? Absolutely. But I’d prefer not doing that, personally.

I do regnoise that a lot of people don’t agree with my preference. And that’s OK, since it’s just a subjective preference. But on the other hand, it is also important to recognise the reasoning behind the preference to multiple configuration files. What a better way means depends on the people who use the tools (and remember, project maintainers are usually the most involved users of the project itself!), and it doesn’t help to complain when you and the tool designers disagree.

If you absolutely can’t stand this “clutter” (as some of my friends put it), there are other tools that may fit your preference. Poetry (mentioned above) and Flit are both alternatives to setuptools, and both of them only use pyproject.toml as the One Configuration File. (There is also discussion to add pyproject.toml support to setuptools as well, but don’t hold your breath waiting for it.) But regardless of the tool you choose, it’s only natural to sometimes disagree with the design. We all learn to live with the differences.

1 Like

Personally, it doesn’t really pain me we have many files but it does that the explanation for them is either buried deep into the docs somewhere or not transparent at all.

It was more a documentation issue for my side than an infrastructure issue.

1 Like