alexander/lalib
1
0
Fork 0
Code Issues Pull requests Releases Activity Actions
lalib/README.md

171 lines
6.4 KiB
Markdown
Raw Permalink Normal View History

Add README file - describe the project's goals - contributions are welcome - mention the GitFlow branching model
2024-09-10 01:02:32 +02:00
# A Python library to study linear algebra
The goal of the `lalib` project is to create
a library written in pure [Python](https://docs.python.org/3/)
(incl. the [standard library](https://docs.python.org/3/library/index.html))
and thereby learn about
[linear algebra](https://en.wikipedia.org/wiki/Linear_algebra)
by reading and writing code.
Run `poetry publish` on GitHub actions
2024-09-10 03:22:52 +02:00
[![PyPI: Package version](https://img.shields.io/pypi/v/lalib?color=blue)](https://pypi.org/project/lalib/)
[![PyPI: Supported Python versions](https://img.shields.io/pypi/pyversions/lalib)](https://pypi.org/project/lalib/)
[![PyPI: Number of monthly downloads](https://img.shields.io/pypi/dm/lalib)](https://pypistats.org/packages/lalib)
Integrate readthedocs.io We publish the docs to readthedocs.io
2024-09-10 03:11:59 +02:00
[![Documentation: Status](https://readthedocs.org/projects/lalib/badge/?version=latest)](https://lalib.readthedocs.io/en/latest/?badge=latest)
Run `nox -s test` on GitHub actions
2024-09-10 02:50:06 +02:00
[![Test suite: Status](https://github.com/webartifex/lalib/actions/workflows/tests.yml/badge.svg)](https://github.com/webartifex/lalib/actions/workflows/tests.yml)
Integrate codecov.io We publish the test coverage reporting to codecov.io
2024-09-10 03:10:26 +02:00
[![Test coverage: codecov](https://codecov.io/github/webartifex/lalib/graph/badge.svg?token=J4LWOMVP0R)](https://codecov.io/github/webartifex/lalib)
Set up code formatting tools - auto-format code with: + autoflake => * remove unused imports and variables * remove duplicate dict keys * expand star imports + black => enforce an uncompromising code style + isort => enforce a consistent import style compliant with Google's Python style guide - add nox session "format" to run these tools
2024-09-10 01:27:34 +02:00
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
Set up code linting tools - use flake8 as the main linting tool with the following plug-ins: + flake8-annotations + flake8-bandit + flake8-black + flake8-broken-line + flake8-bugbear + flake8-commas + flake8-comprehensions + flake8-debugger + flake8-docstrings + flake8-eradicate + flake8-isort + flake8-quotes + flake8-string-format + flake8-pyproject + pep8-naming + pydoclint - use mypy for static type checking - use ruff for linting for future compatibility - add nox session "lint" to run these tools - add `ruff check --fix ...` in nox session "format" - lint all source files => no errors found
2024-09-10 01:33:54 +02:00
[![Type checking: mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
[![Code linting: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
Set up code formatting tools - auto-format code with: + autoflake => * remove unused imports and variables * remove duplicate dict keys * expand star imports + black => enforce an uncompromising code style + isort => enforce a consistent import style compliant with Google's Python style guide - add nox session "format" to run these tools
2024-09-10 01:27:34 +02:00
Run `poetry publish` on GitHub actions
2024-09-10 03:22:52 +02:00
## Installation
This project is published on [PyPI](https://pypi.org/project/lalib/).
To install it, open any Python prompt and type:
`pip install lalib`
You may want to do so
within a [virtual environment](https://docs.python.org/3/library/venv.html)
or a [Jupyter notebook](https://docs.jupyter.org/en/latest/#what-is-a-notebook).
Add README file - describe the project's goals - contributions are welcome - mention the GitFlow branching model
2024-09-10 01:02:32 +02:00
## 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](https://github.com/webartifex/lalib/issues).
All contributions become open-source themselves, under the
[MIT license](https://github.com/webartifex/lalib/blob/main/LICENSE.txt).
Initialize the project - describe how a local develop environment can be set up - we use poetry to manage the project => add pyproject.toml and poetry.lock files - add a package for the source code => "src" layout structure to ensure that pytest runs the tests against a packaged version installed in a virtual environment and not the *.py files in the project directory (Source: https://hynek.me/articles/testing-packaging/) - ignore poetry's artifacts in git
2024-09-10 01:15:36 +02:00
### 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](https://github.com/webartifex/lalib/blob/main/pyproject.toml) file
and are managed with [poetry](https://python-poetry.org/docs/)
which needs to be installed as well.
`poetry` also creates and manages a
[virtual environment](https://docs.python.org/3/tutorial/venv.html)
with the develop tools,
and pins their exact installation versions in the
[poetry.lock](https://github.com/webartifex/lalib/blob/main/poetry.lock) file.
To replicate the project maintainer's develop environment, run:
`poetry install`
Set up nox as the task runner - base configuration for all nox sessions to come - add infos about nox in the README file - ignore [py]cache folders in git
2024-09-10 01:21:37 +02:00
### Maintenance Tasks
We use [nox](https://nox.thea.codes/en/stable/) to run
the test suite and other maintenance tasks during development
in isolated environments.
`nox` is similar to the popular [tox](https://tox.readthedocs.io/en/latest/).
It is configured in the
[noxfile.py](https://github.com/webartifex/lalib/blob/main/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`
Set up a test suite - use pytest as the test suite and measure test coverage with coverage.py - add package for the test suite under tests/ - add nox session "test" to run the test suite for all supported Python versions - use flake8 to lint pytest for consistent style
2024-09-10 01:38:26 +02:00
This includes running the test suite for the project's main Python version
Make Python 3.13 the new default
2024-10-16 01:32:14 +02:00
(i.e., [3.13](https://devguide.python.org/versions/)).
Set up a test suite - use pytest as the test suite and measure test coverage with coverage.py - add package for the test suite under tests/ - add nox session "test" to run the test suite for all supported Python versions - use flake8 to lint pytest for consistent style
2024-09-10 01:38:26 +02:00
Set up nox as the task runner - base configuration for all nox sessions to come - add infos about nox in the README file - ignore [py]cache folders in git
2024-09-10 01:21:37 +02:00
Set up code linting tools - use flake8 as the main linting tool with the following plug-ins: + flake8-annotations + flake8-bandit + flake8-black + flake8-broken-line + flake8-bugbear + flake8-commas + flake8-comprehensions + flake8-debugger + flake8-docstrings + flake8-eradicate + flake8-isort + flake8-quotes + flake8-string-format + flake8-pyproject + pep8-naming + pydoclint - use mypy for static type checking - use ruff for linting for future compatibility - add nox session "lint" to run these tools - add `ruff check --fix ...` in nox session "format" - lint all source files => no errors found
2024-09-10 01:33:54 +02:00
#### Code Formatting & Linting
Set up code formatting tools - auto-format code with: + autoflake => * remove unused imports and variables * remove duplicate dict keys * expand star imports + black => enforce an uncompromising code style + isort => enforce a consistent import style compliant with Google's Python style guide - add nox session "format" to run these tools
2024-09-10 01:27:34 +02:00
Set up code linting tools - use flake8 as the main linting tool with the following plug-ins: + flake8-annotations + flake8-bandit + flake8-black + flake8-broken-line + flake8-bugbear + flake8-commas + flake8-comprehensions + flake8-debugger + flake8-docstrings + flake8-eradicate + flake8-isort + flake8-quotes + flake8-string-format + flake8-pyproject + pep8-naming + pydoclint - use mypy for static type checking - use ruff for linting for future compatibility - add nox session "lint" to run these tools - add `ruff check --fix ...` in nox session "format" - lint all source files => no errors found
2024-09-10 01:33:54 +02:00
We follow [Google's Python style guide](https://google.github.io/styleguide/pyguide.html)
and include [type hints](https://docs.python.org/3/library/typing.html)
where possible.
Set up code formatting tools - auto-format code with: + autoflake => * remove unused imports and variables * remove duplicate dict keys * expand star imports + black => enforce an uncompromising code style + isort => enforce a consistent import style compliant with Google's Python style guide - add nox session "format" to run these tools
2024-09-10 01:27:34 +02:00
During development,
Set up code linting tools - use flake8 as the main linting tool with the following plug-ins: + flake8-annotations + flake8-bandit + flake8-black + flake8-broken-line + flake8-bugbear + flake8-commas + flake8-comprehensions + flake8-debugger + flake8-docstrings + flake8-eradicate + flake8-isort + flake8-quotes + flake8-string-format + flake8-pyproject + pep8-naming + pydoclint - use mypy for static type checking - use ruff for linting for future compatibility - add nox session "lint" to run these tools - add `ruff check --fix ...` in nox session "format" - lint all source files => no errors found
2024-09-10 01:33:54 +02:00
`nox -s format` and `nox -s lint` may be helpful.
Both can be speed up by re-using a previously created environment
Set up code formatting tools - auto-format code with: + autoflake => * remove unused imports and variables * remove duplicate dict keys * expand star imports + black => enforce an uncompromising code style + isort => enforce a consistent import style compliant with Google's Python style guide - add nox session "format" to run these tools
2024-09-10 01:27:34 +02:00
with the `-R` flag.
Set up code linting tools - use flake8 as the main linting tool with the following plug-ins: + flake8-annotations + flake8-bandit + flake8-black + flake8-broken-line + flake8-bugbear + flake8-commas + flake8-comprehensions + flake8-debugger + flake8-docstrings + flake8-eradicate + flake8-isort + flake8-quotes + flake8-string-format + flake8-pyproject + pep8-naming + pydoclint - use mypy for static type checking - use ruff for linting for future compatibility - add nox session "lint" to run these tools - add `ruff check --fix ...` in nox session "format" - lint all source files => no errors found
2024-09-10 01:33:54 +02:00
The first task formats all source code files with
Set up code formatting tools - auto-format code with: + autoflake => * remove unused imports and variables * remove duplicate dict keys * expand star imports + black => enforce an uncompromising code style + isort => enforce a consistent import style compliant with Google's Python style guide - add nox session "format" to run these tools
2024-09-10 01:27:34 +02:00
[autoflake](https://pypi.org/project/autoflake/),
[black](https://pypi.org/project/black/), and
[isort](https://pypi.org/project/isort/).
Set up code linting tools - use flake8 as the main linting tool with the following plug-ins: + flake8-annotations + flake8-bandit + flake8-black + flake8-broken-line + flake8-bugbear + flake8-commas + flake8-comprehensions + flake8-debugger + flake8-docstrings + flake8-eradicate + flake8-isort + flake8-quotes + flake8-string-format + flake8-pyproject + pep8-naming + pydoclint - use mypy for static type checking - use ruff for linting for future compatibility - add nox session "lint" to run these tools - add `ruff check --fix ...` in nox session "format" - lint all source files => no errors found
2024-09-10 01:33:54 +02:00
The second task lints all source code files with
[flake8](https://pypi.org/project/flake8/),
[mypy](https://pypi.org/project/mypy/), and
[ruff](https://pypi.org/project/ruff/).
`flake8` is configured with a couple of plug-ins.
Set up pre-commit hooks - add pre-commit hooks: + run `nox -s lint` on staged *.py files + run common pre-commit hooks for validations that could not be achieved with tools in the develop environment so easily - add pre-merge hook: + run `nox -s _pre-commit-test-hook` before merges * ignores the paths to staged files passed in by the pre-commit framework * runs all test cases instead
2024-09-10 02:32:56 +02:00
You may want to install the [pre-commit](https://pre-commit.com/) hooks
that come with the project:
`nox -s pre-commit-install`
Then, the linting and testing occurs automatically before every commit.
Set up code formatting tools - auto-format code with: + autoflake => * remove unused imports and variables * remove duplicate dict keys * expand star imports + black => enforce an uncompromising code style + isort => enforce a consistent import style compliant with Google's Python style guide - add nox session "format" to run these tools
2024-09-10 01:27:34 +02:00
Set up a test suite - use pytest as the test suite and measure test coverage with coverage.py - add package for the test suite under tests/ - add nox session "test" to run the test suite for all supported Python versions - use flake8 to lint pytest for consistent style
2024-09-10 01:38:26 +02:00
#### Test Suite
We use [pytest](https://docs.pytest.org/en/stable/)
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`
Add README file - describe the project's goals - contributions are welcome - mention the GitFlow branching model
2024-09-10 01:02:32 +02:00
### Branching Strategy
The branches in this repository follow the
[GitFlow](https://nvie.com/posts/a-successful-git-branching-model/) model.
Feature branches are rebased onto
the [develop](https://github.com/webartifex/lalib/tree/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`.
Add `__version__` identifier - `lalib.__version__` is dynamically assigned - the format is "x.y.z[.dev0|aN|bN|rcN|.postM]" where x, y, z, M, and N are non-negative integers + x, y, and z model the "major", "minor", and "patch" parts of semantic versioning (See: https://semver.org/#semantic-versioning-200) + M is a single digit and N either 1 or 2 => This complies with (a strict subset of) PEP440 - add unit tests for the `__version__` identifier
2024-09-10 01:45:47 +02:00
#### Versioning
The version identifiers adhere to a subset of the rules in
[PEP440](https://peps.python.org/pep-0440/) and
follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
Run `poetry publish` on GitHub actions
2024-09-10 03:22:52 +02:00
So, releases to [PyPI](https://pypi.org/project/lalib/#history)
Add `__version__` identifier - `lalib.__version__` is dynamically assigned - the format is "x.y.z[.dev0|aN|bN|rcN|.postM]" where x, y, z, M, and N are non-negative integers + x, y, and z model the "major", "minor", and "patch" parts of semantic versioning (See: https://semver.org/#semantic-versioning-200) + M is a single digit and N either 1 or 2 => This complies with (a strict subset of) PEP440 - add unit tests for the `__version__` identifier
2024-09-10 01:45:47 +02:00
come in the popular `major.minor.patch` format.
The specific rules for this project are explained
[here](https://github.com/webartifex/lalib/blob/main/tests/test_version.py).
Prepare release v0.4.2
2024-09-10 03:39:30 +02:00
## Releases
### v0.4.2, 2024-09-10
- This release provides no functionality
- Its purpose is to (re-)claim the
[lalib](https://pypi.org/project/lalib/) name on PyPI
- We can *not* start with **v0.1.0**
because we already used this when learning to use PyPI years back
Reference in a new issue Copy permalink