Is there a reason to have both tox.ini and setup.cfg in a python project?

Question

I have just scaffolded a python project using PyScaffold. One thing that has caught my attention was the fact that the scaffolding generated both setup.cfg and tox.ini files. If my understanding is correct, if I were to use tox using the tox command, it would just look at the tox.ini file and ignore setup.cfg and setup.py altogether.

With this being the case, here is my question: is there a reason to keep both of them in the project, or would just using tox.ini or setup.cfg be enough? And if I have to keep both of them in my project, is there an easy way so both of them use the same configurations (e.g. configurations for running flake8 for linting) without me having to type those configurations in both setup.cfg and tox.ini?

Answer 1

Let's go through this step by step.

PyScaffold is a tool which tries to ease the setup of a new Python project.

What even is a Python project?

At the very heart a single executable Python file is enough.

If you want to make the project being installable, you need configuration file for the build system.

While a lot has changed over time, still setup.py is the most prominent one. At some point in time it was figured out, that it may be not such a great idea that the build configuration file could execute arbitrary code, so setup.cfg was invented, where you can define e.g. the projects name and dependencies in a ini-style format. Meanwhile, another format was invented, the pyproject.toml file.

So basically, to build your project you need one of those:

• setup.py
• setup.py and setup.cfg (the former only calls the latter)
• pyproject.toml

Usually you want to write tests for your project. You could use the builtin unittest testrunner to run your tests, or nowadays many projects use pytest. pytest can be configured with a pytest.ini.

Tests usually need some dependencies, e.g. pytest itself and maybe some other test helpers. They need to be installed at some time.

And here comes tox into play. Amongst many other features, like e.g. running your tests against different Python versions, tox can both install your project and your test requirements and execute the tests. tox usually comes with a tox.ini file.

Oh, and what about linting? You want to have easy to read code and follow the Python guidelines (e.g. PEP 8), so you usually use a tool like flake8 - which also comes with its own configuration file, namely .flake8.

Ok, now we have many tools and many configuration files, but that's not all. As not everybody likes so many configuration files, some of the tools support to be configured with other tools's configuration file.

e.g. you can configure flake8 both in a setup.cfg and a tox.ini, see https://flake8.pycqa.org/en/latest/user/configuration.html

You can also configure tox via setup.cfg or pyproject.toml, see https://tox.readthedocs.io/en/latest/config.html#configuration-discovery

And one important thing to know: You only need to configure your tool once, not in all those files.

So, technically, you do not need all those files, and it is up to you what you think is an easy to read and easy to manage setup for your project.

At a past Python Ireland meetup I gave a 5 minute lightning talk about how this is all confusing and what solution I came up with:

https://youtu.be/8iqhNbDHC-c