Developer guide

Use the developer installation if you anticipate modifying the source code or building the ursa documentation locally.

Install with developer tools

The primary difference between the standard installation instructions and the developer installation instructions is the use of poetry rather than pip to manage the installation. This results in installation of the optional developer tools used to build the documentation, format the code, and check for lint.

To install using poetry, execute the following:

conda create -n ursa-env -c conda-forge python=3.11 python-graphviz ffmpeg
conda activate ursa-env
pip install poetry

Then, activate the conda environment and install ursa:

cd ursa
poetry install --with dev

Code style

Ursa uses isort and black for formatting and flake8 to check for lint. Before submitting a pull request, ensure that the code is formatted and lint is removed.

Useful developer functions

Once ursa is installed, the following poe scripts are available for reference. Run poe help for the up-to-date list.

Configured tasks:
  audit                 Checks package dependencies for security issues
  update                Deletes poetry.lock and reinstalls the project
  test                  Runs the tests and reports missing coverage
  coverage              Prints the coverage report for the tests
  format                Applies black and isort to ursa and its tests
  lint                  Requires ursa and its tests to be properly formatted
  checkpretty           Runs 'poe format' and 'poe lint' in sequence
  docs                  Runs docs

Functions for snakefile development

If one is modifying the snakefile, the following functions may be of use. All are intended to be called from within a project folder.

ursa reset snakefile # copy the standard snakefile from ursa/initialize/assets into the project folder.