Frequently Asked Questions¶
In case you have a general question that is not answered here, consider submitting a new issue.
Why would I use PyScaffold instead of Cookiecutter?
PyScaffold is focused on a good out-of-the-box experience for developing distributable Python packages (exclusively). The idea is to standardize the structure of Python packages. Thus, PyScaffold sticks to
“There should be one– and preferably only one –obvious way to do it.”
from the Zen of Python. The long-term goal is that PyScaffold becomes for Python what Cargo is for Rust. Still, with the help of PyScaffold’s extension system customizing a project scaffold is possible.
Cookiecutter on the other hand is a really flexible templating tool that allows you to define own templates according to your needs. Although some standard templates are provided that will give you quite similar results as PyScaffold, the overall goal of the project is quite different.
Does my project depend on PyScaffold when I use it to set my project up?
The short answer is no if you later distribute your project in the recommended wheel format. The longer answer is that only during development PyScaffold is needed as a setup dependency. That means if someone clones your repository and runs
setuptoolschecks for the
setup_requiresargument which includes PyScaffold and installs PyScaffold automatically as egg file into
.eggsif PyScaffold is not yet installed. This mechanism is provided by
setuptoolsand definitely beyond the scope of this answer. The same applies for the deprecated source distribution (
sdist) but not for a binary distribution (
bdist). Anyways, the recommend way is nowadays a binary wheel distribution (
bdist_wheel) which will not depend on PyScaffold at all.
Why does PyScaffold 3 have a
srcfolder which holds the actual Python package?
This avoids quite many problems compared to the case when the actual Python package resides in the same folder as
setup.py. A nice blog post by Ionel gives a thorough explanation why this is so. In a nutshell, the most severe problem comes from the fact that Python imports a package by first looking at the current working directory and then into the
PYTHONPATHenvironment variable. If your current working directory is the root of your project directory you are thus not testing the installation of your package but the local package directly. Eventually, this always leads to huge confusion (“But the unit tests ran perfectly on my machine!”).
Can I use PyScaffold 3 to develop a Python package that is Python 2 & 3 compatible?
Python 3 is actually only needed for the
putupcommand and whenever you use
setup.py. This means that with PyScaffold 3 you have to use Python 3 during the development of your package for practical reasons. If you develop the package using six you can still make it Python 2 & 3 compatible by creating a universal
bdist_wheelpackage. This package can then be installed and run from Python 2 and 3.
How can I get rid of PyScaffold when my project was set up using it?
First of all, I would really love to understand why you want to remove it and what you don’t like about it. You can create an issue for that or just text me on Twitter. To answer the question, it’s actually really simple. Within
setup.pyjust remove the
use_pyscaffoldargument from the
setup()call which will deactivate all of PyScaffold’s functionality that goes beyond what is provided by
setuptools. In practice, following things will no longer work:
python setup.py --versionand the dynamic versioning according to the git tags when creating distributions, just put e.g.
version = 0.1in the
python setup.py testand
python setup.py doctest, just use
python setup.py docsfor building your Sphinx documentation, just enter the
docsfolder and type
That’s already everything you gonna lose. Not that much. You will still benefit from:
- the smart project layout,
- the declarative configuration with
setup.cfgwhich comes from
- some sane defaults in Sphinx’
.gitignorewith some nice defaults and other dot files depending on the flags used when running
- some sane defaults for py.test.
For further cleanups, feel free to remove
setup.cfgas well as the complete