Updating from Previous Versions#
When updating a project generated with the same major version of PyScaffold
[1], running 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.
Tip
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
corrections.
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
the --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,
run
putup old_project --force --no-skeleton -p old_package
to generate the new structure inplace andcd
into your project,move with
git mv old_package/* src/old_package/ --force
your old package over to the newsrc
directory,check
git status
and add untracked files from the new structure,use
git difftool
to check all overwritten files, especiallysetup.cfg
, and transfer custom configurations from the old structure to the new,check if
python setup.py test sdist
works 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_requires
insetup.cfg
) and add setuptools-scm.Note
The use of
setup_requires
is discouraged. When updating to v4 PyScaffold will remove this field automatically and transfer the dependencies to thepyproject.toml :: build-system.requires
field, which means you may need to manually place them back when deletingpyproject.toml
. Alternatively you can ditchsetup_requires
completely 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 abuild
testenv with the skip_install option and the required build time dependencies listed indeps
.Migrate any configuration options for tools that might be using
pyproject.toml
to alternative files. For example if you haveisort
andcoverage
configurations in yourpyproject.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.
Warning
For the time being you can use the transitional --no-pyproject
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 setup.cfg
after the update. In particular packages = find_namespace:
should
be converted back to packages = find:
in the [options]
section (use
a 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
docs/conf.py
file.
Tip
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.
the 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.