Updating from Previous Versions¶
When updating a project generated with the same major version of PyScaffold
putup --update should be enough to get you going.
However updating from previous major versions of PyScaffold will probably
require some manual adjustments. The following sections describe how to update
from one major version into the following one.
Before updating make sure to commit all the pending changes in your
repository. If something does not work exactly how you expected after the
update, please revise the changes using a
diff and perform the necessary
Updates from PyScaffold 2 to PyScaffold 3¶
Since the overall structure of a project set up with PyScaffold 2 differs quite
much from a project generated with PyScaffold 3 it is not possible to just use
--update parameter. Still with some manual efforts an update from
a scaffold generated with PyScaffold 2 to PyScaffold 3’s scaffold is quite easy.
Assume the name of our project is
old_project with a package called
old_package and no namespaces then just:
make sure your worktree is not dirty, i.e. commit all your changes,
putup old_project --force --no-skeleton -p old_packageto generate the new structure inplace and
cdinto your project,
git mv old_package/* src/old_package/ --forceyour old package over to the new
git statusand add untracked files from the new structure,
git difftoolto check all overwritten files, especially
setup.cfg, and transfer custom configurations from the old structure to the new,
python setup.py test sdistworks and commit your changes.
Updates from PyScaffold 3 to PyScaffold 4¶
Most of the time, updating from PyScaffold 3 should be completely automatic. However, since in version 4 we have adopted Python’s new standards for packaging (PEP 517/PEP 518), you might find the new build process incompatible.
If that is the case, you might want to try reverting to the legacy behaviour and preventing the build tools from using isolated builds (PEP 517). That can be easily done by deleting the pyproject.toml file from your package root.
You will need, though, to manually follow a few extra steps to make sure everything works:
Remove PyScaffold from your build dependencies (
setup.cfg) and add setuptools_scm.
The use of
setup_requiresis discouraged. When updating to v4 PyScaffold will remove this field automatically and transfer the dependencies to the
pyproject.toml :: build-system.requiresfield, which means you may need to manually place them back when deleting
pyproject.toml. Alternatively you can ditch
setup_requirescompletely and rely on other tools like tox or make to build your project with the correct dependencies in place inside a virtual environment. This have the advantage of increasing reproducibility. With tox you can specify a
buildtestenv with the skip_install option and the required build time dependencies listed in
Migrate any configuration options for tools that might be using
pyproject.tomlto alternative files. For example if you have
coverageconfigurations in your
pyproject.toml, you might want to rewrite them in the .isort.cfg and .coveragerc files respectively.
Please open an issue with PyScaffold so we understand with kind of backward incompatibilities PEP 517 and PEP 518 might be causing and try to help. Similarly you might also consider opening an issue with setuptools.
For the time being you can use the transitional
option, when running
putup, but have in mind that this option will
be removed in future versions of PyScaffold.
PyScaffold 4 also adopts the PEP 420 scheme for implicit namespaces and will automatically migrate existing packages. This is incompatible with the previously adopted pkg_resources methodology. Fortunately, this will not affect you if you are not using namespaces, but in the case you are, installing a new PEP 420-compliant package in an environment that already contains other packages with the same namespace but that use the pkg_resources methodology, will likely result in errors (please check the official packaging namespace packages guides for more information).
To solve this problem you will need to either migrate the existing
packages to PEP 420 or revert some specific configurations in
after the update. In particular
packages = find_namespace: should
be converted back to
packages = find: in the
[options] section (use
git difftool to help you with that).
If using Sphinx for the documentation, you can also remove the
--implicit-namespaces option in the
cmd_line_template variable in the
Existing regular Python files (or other directories containing Python files)
that do not belong to the package distribution but are placed inside the
src folder (such as example files not meant to be packaged), can cause
problems when building your package.
Please move these files if necessary to their own separated folders (e.g.
docs folder or a new
examples folder in the root of the
repository), or revert back to the pkg_resources implementation. Just
have in mind that PyScaffold, considers the
src directory to be
exclusively dedicated to store files meant to be distributed, and will rely
on that assumption on its future versions and updates.
PyScaffold uses 3 numbers for its version:
MAJOR.MINOR.PATCH(when the numbers on the right are missing, just assume them as being 0), so PyScaffold 3.1.2 has the same major version as PyScaffold 3.3.1, but not PyScaffold 4.