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 my_project 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.

Let’s start:

  1. Change into the parent folder of my_project and type:

    putup my_project --force --no-skeleton -p my_package

    in order to deploy the new project structure in your repository.

  2. Now change into my_project and 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 tests or a documentation folder other than docs.

  3. Use git status to check for untracked files and add them with git add.

  4. Eventually, use git difftool to check all overwritten files for changes that need to be transferred. Most important is that all configuration that you may have done in setup.py by passing parameters to setup(...) need to be moved to setup.cfg. You will figure that out quite easily by putting your old setup.py and the new setup.cfg template 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.py file provided by PyScaffold. The only exceptions are if your project uses compiled resources, e.g. Cython.

  5. In order to check that everything works, run pip install . and tox -e build (or python setup.py sdist). If those two commands don’t work, check pyproject.toml, setup.cfg, setup.py as well as your package under src again. Were all modules moved correctly? Is there maybe some __init__.py file missing? Be aware that projects containing a pyproject.toml file 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.toml and 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 html and pytest (or preferably their tox equivalents) to check that Sphinx and PyTest run correctly.