Developer Guide for Inspeqtor

Getting Started

This guide provides the necessary steps and commands for developing the Inspeqtor package. We use the uv package manager for dependency management and various tools for testing, linting, and documentation.

How to contribute?

First of all, thank you for interested in contributing to inspeqtor 😊

By contributing your work to this repository, you agree to license it in perpetuity under the terms described in LICENSE.md. You are also asserting that the work is your own, and that you have the right to license it to us.

If you wish to integrate our work into your own projects, please follow the attribution guidelines in LICENSE.md.

We use git for our library developement. The following steps will guide you to setup everthing necessary for developement. If you encount any problem, please do not hesitate to reach out to us by creating github issue at our github repository.

Clone the project from remote to your local machine and cd into the directory.

git clone https://github.com/PorametPat/inspeqtor.git && cd inspeqtor

We recommend using uv for environment and dependencies manangement. To learn more about uv, please see their official documentation. You can create the virtual environment along with installing dependencies using the following commands. Use the appropiate command corresponding to what you want to do, e.g., docs for documentation contribution.

Minimaldevdocs

Minimal requirement

uv sync

With developement dependencies

uv sync --group dev

With documentation dependencies

uv sync --group docs

After modification, please use the following command to check the code quality to make the development life cycle faster. Note that we also use workflow to run the automate test, but it take a longer time than local testing.

Using pre-commit hooks

uv run pre-commit run --all-files

Or using script, we may need to make the script executable first by using

chmod +x ./bin/check.bash

then execute it using,

Using script

./bin/check.bash

Please read the following for more details.

Project Setup

The following is the instruction used for project initialization.

Creating a New Project

Create a library project

uv init inspeqtor --lib

Create an application project

uv init inspeqtor

Setting Up a Virtual Environment

Create a virtual environment with Python 3.12

uv venv [name] --python 3.12

If using a custom name for your virtual environment, set these environment variables:

Set environment variable for custom venv name

export UV_PROJECT_ENVIRONMENT=[name]

Set VIRTUAL_ENV environment variable

export VIRTUAL_ENV=[name]

Installing the Package

Install the package in development mode

uv add . --editable --dev

Install Jupyter integration

uv add ipykernel --dev

Intall dependency in optional docs group

uv add mkdocs-marimo --optional docs

Syncing dependencies

Install all optional dependencies

uv sync --all-extras

Development Workflow

The project uses several tools for development:

pytest for testing
ruff for linting and formatting
pyright for type checking
pre-commit for git hooks
tuna for import profiling

Testing

Basic test run

uv run pytest tests/ -v

Test experimental module with detailed output

uv run pytest tests/. -vv --durations=0

Test with specific Python version

uv run --python 3.12 --with '.[test]' pytest tests/.

Test docstrings

uv run -m doctest src/inspeqtor/v1/utils.py

Test with live logging

uv run -m doctest src/inspeqtor/v1/utils.py --log-cli-level=INFO

Code Quality

Run linting with Ruff

uvx ruff check .

Check code formatting

uvx ruff format --check .

Run type checking with Pyright

uv run pyright .

Run pre-commit hooks

uv run pre-commit run --all-files

Documentation

MkDocs Setup

We use MkDocs Material and pymdown-extensions for documentation generation. Follow the Real Python tutorial for detailed setup instructions.

Serve documentation locally

uv run mkdocs serve

If an error "cairosvg" Python module is installed, but it crashed with: occur, please check this link for more details of how to solve it. Otherwise, if you are using macOS and the issue persist after more than one resolved, the following command line might be useful:

export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib

After execution of the above command, please run serve again.

The following command will deploy the document to the github page. However, since we are using mike for documentaion versioning please see command in Versioning for deployment instead.

Deploy to GitHub Pages using mkdocs

mkdocs gh-deploy

Versioning

Note

The versioning process should be automated. But we document the process here for explanation.

We use mike to manage documentation versioning. See the following references for more details:

Here are the commands related to the versioning.

To list all of the versions of the documentation use

uv run mike list

After making change, and you want to change the documentation's version, use the following command to update the version number and set the aliases to latest. In the below snippet, we use version of 0.2,

uv run mike deploy --push --update-aliases 0.2 latest

To make the defualt version of the documentation to latest use

uv run mike set-default --push latest

If you want to simply update the documentation with the current version (e.g. 0.1) use,

uv run mike deploy --push 0.1

Note that the --push option will push the change to gh-pages branch directly. Furthermore, mike will deploy the documentation built from the latest branch of the main branch.

Performance Profiling

Generate import profile

uv run python -X importtime profile.py > import.log

Visualize import profile

uvx tuna import.log

CI/CD

For setting up GitHub Actions for CI/CD, refer to this tutorial.

This guide covers the essential commands and workflows for developing the Inspeqtor package. For more detailed information about specific components, refer to the respective documentation.