(dev-guide)=
# 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](https://python-poetry.org/docs/pyproject/) rather than [pip](https://pypi.org/project/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:
```bash
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:

```bash
cd ursa
poetry install --with dev
```

## Code style

Ursa uses [isort](https://pycqa.github.io/isort/) and [black](https://black.readthedocs.io/en/stable/) for formatting and [flake8](https://flake8.pycqa.org/en/latest/) 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](https://poethepoet.natn.io/) scripts are available for reference. Run `poe help` for the up-to-date list.

```bash
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.

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