Migration to PyScaffold#
Migrating your existing project to PyScaffold is in most cases quite easy and requires
only a few steps. We assume your project resides in the Git repository
and includes a package directory
my_package with your Python modules.
Since you surely don’t want to lose your Git history, we will just deploy a new scaffold in the same repository and move as well as change some files. But before you start, please make sure that your working tree is not dirty, i.e. all changes are committed and all important files are under version control.
Change into the parent folder of
putup my_project --force --no-skeleton -p my_package
in order to deploy the new project structure in your repository.
Now change into
my_projectand move your old package folder into
src(if your existing project does not follow a src layout yet):
git mv my_package/* src/my_package/
Use the same technique if your project has a test folder other than
testsor a documentation folder other than
git statusto check for untracked files and add them with
git difftoolto check all overwritten files for changes that need to be transferred. Most important is that all configuration that you may have done in
setup.pyby passing parameters to
setup(...)need to be moved to
setup.cfg. You will figure that out quite easily by putting your old
setup.pyand the new
setup.cfgtemplate side by side. Checkout the documentation of setuptools for more information about this conversion. In most cases you will not need to make changes to the new
setup.pyfile provided by PyScaffold. The only exceptions are if your project uses compiled resources, e.g. Cython.
If you have any pre-existing git tag in your repository history, you will need to ensure that the latest tag is compatible with setuptools-scm. You can do that by running
python -m setuptools_scm(after installing it in your environment). If the command succeeds you are good to go.
Please note that some specific tag formats can be problematic. Check our Best Practices and Common Errors with Version Numbers for a workaround for this problem.
In order to check that everything works, run
pip install .and
tox -e build(or
python -m build --wheelafter installing
build). If those two commands don’t work, check
setup.pyas well as your package under
srcagain. Were all modules moved correctly? Is there maybe some
__init__.pyfile missing? Be aware that projects containing a
pyproject.tomlfile will build in a different, and sometimes non backwards compatible, way. If that is your case, you can try to keep the legacy behaviour by deleting
pyproject.tomland building the distributions exclusively with
setup.py. Please see our updating guide for some extra steps you might want to execute manually. Finally, try also to run
make -C docs htmland
pytest(or preferably their
toxequivalents) to check that Sphinx and PyTest run correctly.