Developer Documentation

Developer Documentation#

To set up pytopotoolbox for development, first make sure you have set up Git, fork the repository on GitHub then use git clone https://github.com/$YOUR_USERNAME/pytopotoolbox to download your fork of the repository, where you have replaced $YOUR_USERNAME with your GitHub username.

To ensure you have a development environment that is consistent with other developers and with our continuous integration and testing setup, it is a good idea to set up a virtual environment in Python. You can then install the developer environment by running

pip install -r requirements.txt .

within the top-level directory of the repository.

Now you can make changes within pytopotoolbox. To rebuild pytopotoolbox after making changes, you’ll need to run

pip install .

You can run the tests with

python -m pytest

and the linter and type checks with

pylint --rcfile=pyproject.toml src/topotoolbox
mypy --ignore-missing-imports src/topotoolbox

It is a good idea to run the linter and type checks before making a pull request to pytopotoolbox, because failing lints or type checks will cause a test failure that must be fixed before your contribution can be accepted.

If you run into problems setting up development environment on any platform, please open an issue. While we test TopoToolbox extensively on different platforms, we only develop on a few, so feedback on how we can make this process as smooth as possible is greatly appreciated.

Development environment on Windows#

pytopotoolbox requires C/C++ files to be compiled. If you are developing on Windows, there are a few extra steps to ensure that you have access to the Windows C/C++ toolchain.

  1. Install the Developer Command Prompt for VS 2022.

    • Scroll down to ‘All Downloads’

    • open ‘Tools for Visual Studio’

    • download ‘Build Tools for Visual Studio 2022’

    • install it while including the ‘Desktop development with C++’ workload

  2. To ensure the compiler is working with 64-bit architecture, that is necessary for python, open ‘x64 Native Tools Command Prompt for VS 2022’ instead of the ‘Developer Command Prompt’ that defaults to 32-bit architecture.

  3. In the opened command prompt, navigate to the pytopotoolbox directory and follow the instructions above for installing the development environment.

If you are using Anaconda, you will still need to install the Build Tools for Visual Studio 2022 as above, but then you should be able to build pytopotoolbox with pip from the Anaconda Prompt.

If you receive errors like:

CMake Error: CMAKE_GENERATOR was set but the specified generator doesn't exist. Using CMake default.

You may need to either set it to the correct value with set CMAKE_GENERATOR=Visual Studio 17 2022 or unset it completely with set CMAKE_GENERATOR=.

Making a release of pytopotoolbox#

To release a new version of pytopotoolbox:

  1. Increase the version number in pyproject.toml depending on whether this is a patch, minor or major release.

  2. Manually draft a release on GitHub. Create a new tag matching the version number in pyproject.toml

  3. Publish the release. This will trigger our release workflow, which will build and upload binary wheels to the GitHub release and to PyPi.