Configuration¶
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 = Florian.Wilhelm@blue-yonder.com
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", "wheel"]
build-backend = "setuptools.build_meta"
[tool.setuptools_scm]
# See configuration details in 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/Preferences/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 = john.joe@gmail.com
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).