Release of PyScaffold v4

It has been a long journey since PyScaffold v3 was released and a lot of things happened in the Python community especially regarding the packaging ecosystem… but before we start, for the newcomers.

Why PyScaffold and what is it?

PyScaffold is the tool of choice for bootstrapping high-quality Python packages, ready to be shared on PyPI and installable via pip. It is easy to use and encourages the adoption of the best tools and practices of the Python ecosystem, helping you and your team to stay sane, happy, and productive. The best part? It is stable and has been used by thousands of developers for over half a decade!

PyScaffold was created in 2014 and therefore is stable and battle-tested, but yet constantly evolving to support its users’ needs and the latest standards of the Python community.

With PyScaffold you can jump-start your Python development with an incredibly smart project template, perfected throughout years of serious usage, that promotes the best practices in the Python ecosystem and ships with a ready-to-use configuration for all the tools needed by the vast majority of Python developers.

If you are still not convinced, have a look at these other reasons and the extensive list of PyScaffold’s features. And if you are curious, check out our demo project, or install PyScaffold and type putup -h to get started.

On the Road to Version 4

We saw emerging a huge effort to standardize the build process and metadata with PEP 517 and PEP 518, a tendency to avoid pkg_resources(in favor of native namespaces with PEP 420, importlib.resources, and importlib.metadata), and of course the deprecation of Python’s version 2. Moreover, having Python 3.6 as the lowest version officially supported by Python’s core team, changed the way developers write their code: a bunch of new features are now available, allowing us to be more expressive and succinct (don’t tell me you don’t like f-strings).

As a result, the PyScaffold team decided to expand our previous ideas for improvements and also to incorporate these changes within the ecosystem into a new, super cool, version of PyScaffold. So here I am, proud to officially announce the final release of PyScaffold v4 — now available in PyPI 🥳🎉

The complete list of changes introduced in this version is available on the official website together with a more detailed description of all the features, but I will try to summarise below some highlights of this release.

New Defaults

As a response to PEP 517 and PEP 518, PyScaffold v4 will automatically generate a pyproject.toml in the root of your repository. As a consequence, most of the tools in Python’s build ecosystem will assume the distribution package should be built in isolation (think of it as creating a virtual environment just for running python setup.py). In general, this change should reduce the chances of things going wrong and improve reproducibility, but it can also mean that you need to adapt a little bit your workflow.

To ease this transition, we are including by default a tox.ini in the root of your project, pre-configured with a lot of common tasks. If you have tox installed on your machine, you will be able to run:

tox -e docs     # build your documentation
tox -e build    # build your package distribution
tox -e publish  # uploads to test.pypi.org by default
tox -e publish -- --repository pypi  # release to PyPI
tox -av         # ist all the tasks available

This is meant to be a replacement for deprecated setup.py commands such as:

python setup.py docs
python setup.py tests
# etc ...

We also are recommending using pip install . and pip install -e . instead of python setup.py install and python setup.py develop. In the future, it is very likely that running setup.pydirectly will be deprecated by setuptools, so we might as well start to get used to an interface that is unlikely to change.

Experimental and Exciting Features

Interactive Mode

Have you ever tried to use a CLI tool for the first time, or after a long period without using it, and faced a situation that forced you to go back and forth between typing your command and reading the --help text? It is usually not a great experience, especially when you have many options…

A few programs try to solve this problem by providing something called “interactive mode”, which, most of the time, corresponds to a bunch of questions being prompted at the terminal. While this method is fine and familiar for most developers, it can get very tiring if… If the tool asks you more than 7 questions… and, it is going to be mildly annoying. Choosing by accident the wrong option in the last question? Well, then you are going to reply to the same questions all over again…

Thus, we are trying something different in v4. When you activate the interactive mode with the -i or --interactive flags, PyScaffold will open your favorite text editor (the one you specify with the EDITOR environment variable), with an “editable version” of the --help text. A bit unusual right? But don’t worry, it works very similarly to an interactive rebase with git, i.e.: you can comment options out by preceding the line with a # symbol, edit the values for the options (as shown in the example below), save and close the file then just wait for PyScaffold to run. This is how it looks:

myproject
    # path where to generate/update project


# --name myproject
    # (or alternatively: -n)
    # installable name (as in `pip install`/PyPI, default: basename 
    # of PROJECT_PATH)


# --package myproject
    # (or alternatively: -p)
    # package name (as in `import`, default: NAME)


 --description 'Add a short description here!'
    # (or alternatively: -d)
    # package description

# etc ...

Dynamically adapting to your Workflow

One of the nice things about PyScaffold is that you can mix and match many tools according to your workflow. For example, if you like to run some quick tasks like linting or formatting the code before committing your changes, just add --pre-commit when generating your project with putup and PyScaffold will configure your project to use pre-commit.

In v4, we took that to a new level. Now you can dynamically update your project to include the supported tools, so you can gradually evolve and adapt your workflow.

Consider, for example, you have a project generated by PyScaffold if at any point you decide to start testing it in Cirrus CI, just cd into your project root folder and run:

putup . --update --cirrus

Saving your favorite Configuration

We all have favorites, right? And I guess after a while using PyScaffold you might tend to repeat a series of flags to express your preferences (like --pre-commit, --license GPL-3.0, etc…). With v4 you can avoid retyping those options by saving a default configuration.

For example, if you create a new project by running:

putup myproject --pre-commit --cirrus --licence GPL-3.0 \
      --save-config

The next time you create a project with putup, the --pre-commit, --cirrus, and--license GPL-3.0 options will be automatically applied, without the need of typing it again.

We hope PyScaffold users will find v4 even easier to work with than v3. We also invite everyone to have a look at the official extensions in our GitHub organization, and if you are a bit more courageous, to have a look at our extensions guide.

In this release, we offer a packaging experience up to date with the latest best practices and standardization in the Python ecosystem, while maintaining the best backward compatibility possible. That is the spirit we plan to bring forward in the next releases.

I hope you all stay productive and have fun! 😉

Anderson Bravalheri & Florian Wilhelm

Feedback & Resources

• Issues and bugs: https://github.com/pyscaffold/pyscaffold/issues
• Discussion, suggestions, questions: https://github.com/pyscaffold/pyscaffold/discussions
• Documentation: https://pyscaffold.org/