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 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 with:

    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, or if you need to specify entry_points.

  5. In order to check that everything works, run python setup.py install and python setup.py sdist. If those two commands don’t work, check setup.cfg, setup.py as well as your package under src again. Where all modules moved correctly? Is there maybe some __init__.py file missing? After these basic commands, try also to run python setup.py docs and python setup.py test to check that Sphinx and PyTest runs correctly.