pyscaffold | 🛠 Python project template generator with batteries | Automation library

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

You generally should not name your packages or modules using dashes although you can. Since the import statement does not use quotes, using a dash is interpreted as using a minus sign, which will result in an illegal syntax during import if using the dash name.

There are ways around this, such as importing with underscores but installing via pip/searching pypi with dashes, but it is a needless inconsistency that can cause frustration. Generally the python approach is to be able to import modules as valid module objects whose variable name equals the actual module name. When naming projects, it is therefore better to use underscores instead of dashes.

That being said, pkg_resources seems to actually replace all non-alphanumeric and non-dot characters with dashes when resolving project names.

There are multiple ways to suppress warnings:

• using command-line arguments

To hide the warning completely use