How to create a new repository with the template

First install cookiecutter

$ task install
$ source .venv/bin/activate

To create a new project my-test and push it to github based on this template, run the following from the directory where the project should reside:

$ task create-repo
repository_name [repository-name]: my-test
module_name [my_test]:
$ cd my-test
$ git init --initial-branch=main
$ git add .
$ git commit -m "Add files generated from template"
$ git remote add origin git@github.com:mightypirate1/my-test.git
$ git branch cookiecutter-template
$ git push -u origin main cookiecutter-template

It is recommended, although probably not necessary, that you now exit your current virtual environment by running

$ deactivate

Go into the source of your new repository and run

$ task develop

This creates a virtual environment in your repository and installs your repository as a module, solving dependency issues automatically.

Guidance while coding

Ensure that you always have the virtual environment activated (even in your editor if it has such functionality) by running

$ source .venv/bin/activate

while standing in the source of your repository. Otherwise, you will have problems with importing from the repository and running task commands.

When you are done editing, do the following in this order:

1. Run task reformat until the command does not suggest any improvements (If you have syntax errors, they must be fixed first).
2. Run task lint and fix all errors it is complaining about. A small subset of all errors can be fixed automatically using task lint-fix (see Tooling/Usage for details).
3. If you have tests, run task test and fix failing tests if there are any.

Tooling

The template provides numerous tools to simplify the development process:

• venv for handling the environment
• setuptools for installation and dependency handling
• black for formatting
• ruff for linting
• ty for typechecking
• pytest for testing
• coverage for analyzing test coverage While you can use these tools manually, the intended way of running them is via task commands.

Usage

venv and setuptools

There are a two main ways of using these:

For development:

$ task develop  # runs `task venv` then installs the code as a package (editable mode) inside of it
$ source .venv/bin/activate  # activates the virtual environment

For installation:

$ task venv  # creates an empty virtual environment
$ source .venv/bin/activate  # activates the virtual environment
$ task install  # installs the code as a package in the virtual environment

Linting, typechecking and formatting

Reformatting (may take a couple of runs):

$ task reformat  # applies standard formatting using ruff (I, W) and black

Linting and typechecking:

$ task lint  # runs ruff, black check, and ty

Some errors that ruff finds can be fixed by the linter:

$ task lint-fix  # runs ruff with `--fix-only`

A (possibly) non-exhaustive list of all errors that can be fixed via task lint-fix is:

• Unused imports
• Incorrect order of importing
• Upgrading of old typing syntax

Testing and coverage

$ task test  # runs pytest on the tests/ folder

$ task coverage  # analyzes the test coverage on a file-by-file level

Configuration

Most tools are configured in pyproject.toml.

Dependencies are handled in pyproject.toml under [project.optional-dependencies] for dev requirements (used by task develop) and [project.dependencies] for module requirements (used by task install).