A Python library to study linear algebra

The goal of the lalib project is to create a library written in pure Python (incl. the standard library) and thereby learn about linear algebra by reading and writing code.

Contributing & Development

This project is open for any kind of contribution, be it by writing code for new features or bugfixes, or by raising issues. All contributions become open-source themselves, under the MIT license.

Local Develop Environment

In order to play with the lalib codebase, you need to set up a develop environment on your own computer.

First, get your own copy of this repository:

git clone git@github.com:webartifex/lalib.git

While lalib comes without any dependencies except core Python and the standard library for the user, we assume a couple of packages and tools be installed to ensure code quality during development. These can be viewed in the pyproject.toml file and are managed with poetry which needs to be installed as well. poetry also creates and manages a virtual environment with the develop tools, and pins their exact installation versions in the poetry.lock file.

To replicate the project maintainer's develop environment, run:

poetry install

Maintenance Tasks

We use nox to run the test suite and other maintenance tasks during development in isolated environments. nox is similar to the popular tox. It is configured in the noxfile.py file. nox is assumed to be installed as well and is therefore not a project dependency.

To list all available tasks, called sessions in nox, simply run:

nox --list or nox -l for short

To execute all default tasks, simply invoke:

nox

This includes running the test suite for the project's main Python version (i.e., 3.12).

Code Formatting & Linting

We follow Google's Python style guide and include type hints where possible.

During development, nox -s format and nox -s lint may be helpful. Both can be speed up by re-using a previously created environment with the -R flag.

The first task formats all source code files with autoflake, black, and isort.

The second task lints all source code files with flake8, mypy, and ruff. flake8 is configured with a couple of plug-ins.

Test Suite

We use pytest to obtain confidence in the correctness of lalib. To run the tests for all supported Python versions in isolated (and perfectly reproducable) environments, invoke:

nox -s test

Branching Strategy

The branches in this repository follow the GitFlow model. Feature branches are rebased onto the develop branch before being merged. Whereas a rebase makes a simple fast-forward merge possible, all merges are made with explicit and empty merge commits. This ensures that past branches remain visible in the logs, for example, with git log --graph.

Versioning

The version identifiers adhere to a subset of the rules in PEP440 and follow Semantic Versioning. So, releases to PyPI come in the popular major.minor.patch format. The specific rules for this project are explained here.