Usage & Examples¶
Quickstart¶
A single command is all you need to quickly start coding like a Python rockstar, skipping all the difficult and tedious bits:
putup my_project
This will create a new folder called my_project
containing a
perfect project template with everything you need for getting things done.
Checkout out this demo project, which was set up using Pyscaffold.
Tip
Added in version 4.0: We are trying out a brand new interactive mode that makes it
even easier to use PyScaffold in its full potential.
If you want to give it a shot, use the --interactive
, or simply -i
option.
The interactive command equivalent to the previous example is:
putup -i my_project
.
You can cd
into your new project and interact with it from the
command line after creating (or activating) an isolated
development environment (with virtualenv, conda or your preferred tool),
and performing the usual editable install:
pip install -e .
… all set and ready to go! Try the following in a Python shell:
>>> from my_project.skeleton import fib
>>> fib(10)
55
Or if you are concerned about performing package maintainer tasks, make sure to have tox installed and see what we have prepared for you out of the box:
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
The following figure demonstrates the usage of putup
with the new experimental
interactive mode for setting up a simple project.
It uses the –cirrus flag to add CI support (via Cirrus CI), and
tox to run automated project tasks like building a package file for
distribution (or publishing).

Type putup -h
to learn about other things PyScaffold can do for your project,
and if you are not convinced yet, have a look on these reasons to use PyScaffold.
There is also a video tutorial on how to develop a command-line application with the help of PyScaffold.
Notes¶
PyScaffold’s project template makes use of a dedicated
src
folder to store all the package files meant for distribution (additional files like tests and documentation are kept in their own separated folders). You can find some comments and useful links about this design decision in our FAQ.The
pip install -e .
command installs your project in editable mode, making it available in import statements as any other Python module. It might fail if your have an old version of Python’s package manager and tooling in your current environment. Please make sure you are using the intended environment (either a virtual environment [recommended] or the default installation of Python in the operating system) and try to update them withpython -m pip install -U pip setuptools
.If you are using a virtual environment, please remember to re-activate it every time you close your shell, otherwise you will not be able to import your project in the REPL. To check if you have already activated it you can run
which python
on Linux and OSX,where python
on the classical Windows command prompt, orGet-Command python
on PowerShell.
Examples¶
Just a few examples to get you an idea of how easy PyScaffold is to use:
putup my_little_project
The simplest way of using PyScaffold. A directory
my_little_project
is created with a Python package named exactly the same. The MIT license will be used.putup -i my_little_project
If you are unsure on how to use PyScaffold, or keep typing
putup --help
all the time, the experimental--interactive
(or simply-i
), is your best friend. It will open your default text editor with a file containing examples and explanations on how to useputup
(think of it as an “editable”--help
text, once the file is saved and closed all the values you leave there are processed by PyScaffold). You might find some familiarities in the way this option works withgit rebase -i
, including the capacity of choosing a different text editor by setting theEDITOR
(orVISUAL
) environment variable in your terminal.putup skynet -l GPL-3.0-only -d "Finally, the ultimate AI!" -u https://sky.net
This will create a project and package named skynet licensed under the GPL3. The description inside
setup.cfg
is directly set to “Finally, the ultimate AI!” and the homepage tohttps://sky.net
.putup Scikit-Gravity -p skgravity -l BSD-3-Clause
This will create a project named Scikit-Gravity but the package will be named skgravity with license new-BSD [1].
putup youtub --django --pre-commit -d "Ultimate video site for hot tub fans"
This will create a web project and package named youtub that also includes the files created by Django’s
django-admin
[2]. The description insetup.cfg
will be set and a file.pre-commit-config.yaml
is created with a default setup for pre-commit.putup thoroughly_tested --cirrus
This will create a project and package thoroughly_tested with files
tox.ini
and.cirrus.yml
for tox and Cirrus CI.putup my_zope_subpackage --name my-zope-subpackage --namespace zope --package subpackage
This will create a project under the
my_zope_subpackage
directory with the installation name ofmy-zope-subpackage
(this is the name used by pip and PyPI), but with the following corresponding import statement:from zope import subpackage # zope is the namespace and subpackage is the package name
To be honest, there is really only the Zope project that comes to my mind which is using this exotic feature of Python’s packaging system. Chances are high, that you will never ever need a namespace package in your life. To learn more about namespaces in the Python ecosystem, check PEP 420.
Package Configuration¶
Projects set up with PyScaffold rely on setuptools, and therefore can be
easily configured/customised via setup.cfg
. Check out the example below:
# Docs on setup.cfg:
# http://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files
[metadata]
name = my_project
description = A test project that was set up with PyScaffold
author = Florian Wilhelm
author_email = [email protected]
license = MIT
url = https://...
long_description = file: README.rst
platforms = any
classifiers =
Development Status :: 5 - Production/Stable
Topic :: Utilities
Programming Language :: Python
Programming Language :: Python :: 3
Environment :: Console
Intended Audience :: Developers
License :: OSI Approved :: MIT License
Operating System :: POSIX :: Linux
Operating System :: Unix
Operating System :: MacOS
Operating System :: Microsoft :: Windows
[options]
zip_safe = False
packages = find_namespace:
python_requires = >=3.6
include_package_data = True
package_dir =
=src
# Add here dependencies of your project (semicolon/line-separated)
install_requires =
pandas
scikit-learn
[options.packages.find]
where = src
exclude =
tests
[options.extras_require]
# Add here additional requirements for extra features, like:
# pdf = ReportLab>=1.2; RXP
# rest = docutils>=0.3; pack ==1.1, ==1.3
all = django; cookiecutter
# Add here test requirements (semicolon/line-separated)
testing =
pytest
pytest-cov
[options.entry_points]
# Add here console scripts like:
# console_scripts =
# script_name = ${package}.module:function
# For example:
# console_scripts =
# fibonacci = ${package}.skeleton:run
# And any other entry points, for example:
# pyscaffold.cli =
# awesome = pyscaffoldext.awesome.extension:AwesomeExtension
[tool:pytest]
# Options for py.test:
# Specify command line options as you would do when invoking py.test directly.
# e.g. --cov-report html (or xml) for html/xml output or --junitxml junit.xml
# in order to write a coverage file that can be read by Jenkins.
addopts =
--cov my_project --cov-report term-missing
--verbose
norecursedirs =
dist
build
.tox
testpaths = tests
markers =
slow: mark tests as slow (deselect with '-m "not slow"')
[bdist_wheel]
universal = 1
[devpi:upload]
# Options for the devpi: PyPI server and packaging tool
# VCS export must be deactivated since we are using setuptools-scm
no_vcs = 1
formats =
sdist
bdist_wheel
[flake8]
# Some sane defaults for the code style checker flake8
max_line_length = 88
extend_ignore = E203, W503
# ^ Black-compatible
# E203 and W503 have edge cases handled by black
exclude =
.tox
build
dist
.eggs
docs/conf.py
[pyscaffold]
# PyScaffold's parameters when the project was created.
# This will be used when updating. Do not change!
version = 4.0
package = my_package
extensions =
namespace
namespace = ns1.ns2
You might also want to have a look on pyproject.toml for specifying dependencies required during the build:
[build-system]
# AVOID CHANGING REQUIRES: IT WILL BE UPDATED BY PYSCAFFOLD!
requires = ["setuptools>=46.1.0", "setuptools_scm[toml]>=5"]
build-backend = "setuptools.build_meta"
[tool.setuptools_scm]
# For smarter version schemes and other configuration options,
# check out https://github.com/pypa/setuptools_scm
version_scheme = "no-guess-dev"
Please note PyScaffold will add some internal information to setup.cfg
,
we do that to make updates a little smarter.
Note
To avoid splitting the configuration and build parameters among several
files, PyScaffold uses the same file as setuptools (setup.cfg
).
Storing configuration in pyproject.toml is not supported.
In the future, if the default build metadata location changes (as proposed
by PEP 621), PyScaffold will follow the same pattern.
PyScaffold’s Own Configuration¶
PyScaffold also allows you to save your favourite configuration to a file that
will be automatically read every time you run putup
, this way you can avoid
always retyping the same command line options.
The locations of the configuration files vary slightly across platforms, but in general the following rule applies:
Linux:
$XDG_CONFIG_HOME/pyscaffold/default.cfg
with fallback to~/.config/pyscaffold/default.cfg
OSX:
~/Library/Application Support/pyscaffold/default.cfg
Windows(≥7):
%APPDATA%\pyscaffold\pyscaffold\default.cfg
The file format resembles the setup.cfg
generated automatically by
PyScaffold, but with only the metadata
and pyscaffold
sections, for
example:
[metadata]
author = John Doe
author-email = [email protected]
license = MPL-2.0
[pyscaffold]
extensions =
cirrus
pre-commit
With this file in place, typing only:
$ putup myproj
will have the same effect as if you had typed:
$ putup --license MPL-2.0 --cirrus --pre-commit myproj
Note
For the time being, only the following options are allowed in the config file:
metadata section:
author
,author-email
andlicense
pyscaffold section:
extensions
(and associated opts)
Options associated with extensions are the ones prefixed by an extension name.
To prevent PyScaffold from reading an existing config file, you can pass the
--no-config
option in the CLI. You can also save the given options when
creating a new project with the --save-config
option. Finally, to read the
configurations from a location other then the default, use the --config PATH
option. See putup --help
for more details.
Warning
Experimental Feature - We are still evaluating how this new and exciting feature will work, so its API (including file format and name) is not considered stable and might change between minor versions. As previously stated, if the configuration file for setuptools changes (e.g. with PEP 621), PyScaffold will follow that and change its own configuration.
This means that in future versions, PyScaffold will likely adopt a more pyproject.toml-style configuration (and as a consequence the file name and extension might change).