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 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 in your machine, you will be able to run:

tox -e docs  # to build your documentation
tox -e build  # to build your package distribution
tox -e publish  # to test your project uploads correctly in test.pypi.org
tox -e publish -- --repository pypi  # to release your package to PyPI
tox -av  # to list 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.py directly 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 the tool asks you more than 7 questions... and choosing by accident the wrong option in the last question, well, then you are going to hate having 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 favourite 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 interactive rebases with git, i.e. you can comment options out by preceding the line with an # 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 favourite configuration

We all have favourites, 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, --licence 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 --licence GPL-3.0 options will be automatically applied, without the need of typing it again.

We hope PyScaffold users will find v4 easier to work with. We also invite everyone to have a look at the official extensions in our GitHub organisation, 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 standardisation 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! 😉

What is PyScaffold?

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!

Why PyScaffold?

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 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 on these other reasons and the extensive list of PyScaffold's features. And if you are curious, checkout our demo project, or install PyScaffold and type putup -h to get started.

Feedback

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

abravalheri/PyScffold v4 Release Notes.md