Skip to content

How to get started? How to contribute?

Remember to keep things as simple, as minimal and as usable as possible (see the Suckless philosophy).

Code of conduct

See the Python Code Quality Authority’s Code of Conduct.



The versioning system used for this project is Git (via the GitLab Git server), which is a free and open source distributed version control system.

You can install Git, and learn more about it, by following its official documentation.

Note: When committing with Git, while working on the SARAR project, whenever possible please refer to the issue you are working on (e.g. add see #42 at the end of your commit if you are working on issue number 42).

Python 3

The programming language used to develop SARAR is Python.

If you are discovering Python: you can follow the Getting Started guide, in order to install it and learn more about it.

If you are wondering what is the "Python philosophy" of doing things in this project, then I suggest you read this excellent series of articles.


The Python package/environment manager used for this project is poetry.

You can install poetry, and learn more about it, by following its [official documentation]((

For example, here is how I installed it:

  • First, define a poetry home:

    $ vi $HOME/.bashrc # or ~/.zshrc or ~/.zshenv or wherever
        > ...
      + >
      + > # PYTHON POETRY
      + > export POETRY_HOME="${XDG_DATA_HOME:-${HOME/.local/share}}/poetry"
      + > export PATH="$POETRY_HOME/bin:$PATH"
    $ source $HOME/.bashrc # or ~/.zshrc or ~/.zshenv or wherever

  • Then install it, without automatically modifying your path:

    $ curl -sSL >
    $ python --no-modify-path

  • Now, make sure poetry is up to date:

    $ poetry self update
    $ poetry --version

  • Optionally, you might want to create a virtual environment per project inside the project's root directory. If so, the virtual environment will be created and expected in a folder named .venv:

    $ poetry config true

  • If you want to uninstall poetry:

    $ python --uninstall

How to install, update and run

  • Installing the project and all its development dependencies is quite simple:

    $ git clone
    $ cd sarar
    $ poetry install

  • Updating it is even more easy:

    $ git pull

  • Running it just requires to execute the following:

    $ poetry run sarar

  • E.g. if you want to run the check-deck command:

    $ poetry run sarar check-deck -d /path/to/deck.deck

Coding style

In order to save time and mental energy for more important matters, black is the tool used in this project to format Python code.

black enforces formatting that conforms to PEP 8 which is a very sane style guide for Python (and a very interesting reading).

Here are some resources in order to integrate black to your IDE:


The linters used for this project are flake8 and pylint, because they are well supported by black (see black compatible configurations).

  • flake8 is a popular lint wrapper for python. Under the hood, it runs three other tools and combines their results:

  • pylint is also a popular linter for python (now it even is the default python linter in VS Code). Under the hood, it runs those tools to combine their results:

    • astroid for a base representation of python source code
    • isort for imports management
    • mccabe for checking complexity

Here are some resources in order to integrate flake8 to your IDE:

Here are some resources in order to integrate pylint to your IDE:


If you encounter tough errors during your developments, do not hesitate to use the Python debugger.

If you want to check your PYTHONPATH you can use some of those commands:

$ poetry run python -m site
$ poetry run bash -c "echo $PATH"
$ poetry run python -c "import sys, pprint; pprint.pprint(sys.path)"


The test framework used for this project is pytest.

pytest has already been installed in your virtual environment when running $ poetry install, you can learn more about it by reading its official documentation.

When adding, changing or removing some code to the SARAR project, make sure to update the tests accordingly. And of course: make sure the tests are successful!

So, before pushing any new code, please check the results of the following tests:

$ poetry run pytest # run tests
$ poetry run pytest -vv -r a # run tests with better looking output
$ poetry run pytest --black  # check black formatting
$ poetry run pytest --flake8 # check flake8 linter
$ poetry run pytest --pylint # check pylint linter
$ poetry run pytest --cov=sarar/ # check code coverage
$ poetry run pytest --pydocstyle # check doctrings
$ poetry run vulture ./sarar ./tests # check no dead code
You can also test all at once with this one-liner:
$ poetry run pytest -vv -r a --black --flake8 --pylint --pydocstyle --cov=sarar/
$ poetry run vulture ./sarar ./tests # check no dead code

SARAR uses the click module in order to create some command line interfaces, here is how to create tests against click-based apps:

Also, you can check the code coverage with the following command:

$ poetry run pytest --cov=sarar --cov-report html

This will generate the ./htmlcov folder. You can open it in your browser, e.g. with Firefox: $ firefox ./htmlcov/index.html, and check your coverage.

This will also generate a .coverage file used to create the coverage badge. For your information, you can create/update the coverage badge with the following command:

$ poetry run coverage-badge -o .coverage.svg

But you don't need to manually run the previous command, since it's already in the project's CI.


When adding, changing or removing some code to the SARAR project, make sure to update accordingly the associated docstring and the documentation folder (docs at the root of the project). Feel free to create, update or delete any file, and eventually reference it from the README.

Markdown documentation

When documenting in the README or the docs folder, please respect the markdown syntax in order to get nice and pleasant files to read.

The docs folder is also the root directory for MkDocs to work, MkDocs is a documentation oriented site generator: it will build a static HTML site from the markdown file and will allow to format the documentation in a very nice way.

So, once you are done editing, please build the documentation and serve it, in order to check it:

$ poetry run mkdocs serve -f .mkdocs.yaml
    > ...
    > Serving on
    > ...
Now just open in a web browser and make sure the rendering of your modifications is OK.

In another console, in order to make sure your documentation does not contains any broken link, you can run the following:

$ poetry run linkchecker --check-extern --ignore-url= --ignore-url=https://fonts --ignore-url= --no-robots

Note that the static HTML site build by MkDocs is hosted on readthedocs, so after pushing your markdown modifications readthedocs will serve them here.

Docstring documentation

The source code of this project follows the PEP 257 Docstring conventions, in order to get a standardize structure of docstrings (i.e. what docstrings should contain, not what markup syntax should be used).

PEP 257 can be checked with:

$ poetry run pytest -vv -r a --pydocstyle

The target markup syntax for formatting docstrings is the one recommended by the PEP 287 reStructuredText Docstring Format, i.e. reStructuredText plaintext markup syntax. For a quick overview: see this example, or this one, or this one.

Please, when adding or changing some source code, make sure to create or update associated docstring(s).

Help documentation / Command documentation

The documentation of this project contains a little specificity: the Markdown docs in the commands folder (e.g. the check-deck doc) are parsed by SARAR when printing help information in the command line (e.g. $ sarar check-deck --help).

This trick is possible thanks to the doc_to_help(...) function in So when creating or modifying a command doc, please check the Markdown rendering and the associated -h, --help option output (e.g. $ poetry run sarar check-deck --help).

Do not hesitate to change the doc_to_help(...) function according to your needs.


The target format for the help documentation and the command documentation is to be like a man page. Take inspiration from $ man man or $ man git.


You can check all the dependency tree of SARAR by running $ poetry show --tree, a short description for the top level dependencies will also be printed.

An other way to quickly check the top dependencies of SARAR is to read the ./pyproject.toml file.


See how to use GNU licenses for your own software. In particular, don't forget to include the copyright notice at the top of each new source file you would include.

Release checklist

When a new version of SARAR is about to be released, make sure that:

  • the milestone of the new release has been completed and closed (all associated issues must have been done and closed). The next one has been created.

  • the dependencies have been updated

    $ poetry update

  • all the tests are passing (with 100% of tests coverage and no dead code)

    $ poetry run pytest -v -r a --black --flake8 --pylint --cov=sarar/ -vv
    $ poetry run vulture ./sarar ./tests # check no dead code

  • TODO: the size badge has been updated (TODO: run this into CI, not here manually)

    $ SIZE=$(du -c --exclude=TODO --exclude=TODO | tail -1 | awk '{print $1}')
    $ curl$SIZE-informational -o .size.svg

  • the documentation has been updated and is looking nice

    $ poetry run mkdocs serve -f .mkdocs.yaml
    $ poetry run linkchecker --check-extern --ignore-url= --ignore-url=https://fonts --ignore-url= --no-robots

  • the change log has been updated

  • the project layout has been updated

  • the __version__ variable in has been updated

  • the locally build version is running without problems:

    $ poetry build
    $ cd tests
    $ python -m venv .test_venv
    $ . ./.test_venv/bin/activate
    $ pip install --upgrade pip
    $ pip install ../dist/sarar-0.1.0.tar.gz
    $ sarar
    $ # now check your developments
    $ deactivate
    $ rm -r .test_venv

  • the poetry version has been updated (see here for more details, note that you can print the current version with $ poetry version):

    • in case of a major version bump: $ poetry version major (e.g. 1.3.0 -> 2.0.0)
    • in case of a minor version bump: $ poetry version minor (e.g. 2.1.4 -> 2.2.0)
    • in case of a patch version bump: $ poetry version patch (e.g. 4.1.1 -> 4.1.2)
  • the new poetry version has been published to PyPi: $ poetry publish --build

  • the git tag version has been created, e.g. create a tag for the current commit to version 1.2.3:

    $ git tag 1.2.3 -m "bump version to 1.2.3"
    $ git push origin 1.2.3

  • the readthedocs version associated to the previous git tag has been activated (see

  • the GitLab release has been created, e.g. to create a new release through the GitLab UI:

    • On the left sidebar, select Deployments -> Releases -> New release.
    • Select the associated tag name.
    • Set release title to the tag name.
    • Select the associated milestone.
    • Set the release notes to the associated CHANGELOG section.

      ##### Changelog

    • Add links

      • Add URL:, Link title: SARAR x.y.z PyPi files, Type: Package
      • Add URL:, Link title: SARAR x.y.z PyPi, Type: Other
      • Add URL:, Link title: SARAR x.y.z documentation, Type: Documentation
    • E.g. release 0.1