Development

HAL uses poetry for dependency management and packaging. To work with an editable install it’s recommended that you setup poetry and install HAL in a virtual environment by doing

poetry install

Pip does not support editable installs with PEP-517 yet. That means that running pip install -e . will fail because poetry doesn’t use a setup.py file. As a workaround, you can use the create_setup.py file to generate a temporary setup.py file. To install HAL in editable mode without poetry, do

pip install --pre poetry
python create_setup.py
pip install -e .

Note that this will only install the production dependencies, not the development ones. You’ll need to install those manually (see pyproject.toml [tool.poetry.dev-dependencies]).

Style and type checking

This project uses the black code style with 88-character line lengths for code and docstrings. It is recommended that you run black on save. Imports must be sorted using isort. The GitHub test workflow checks all the Python file to make sure they comply with the black formatting.

Configuration files for flake8, isort, and black are provided and will be applied by most editors. For Visual Studio Code, the following project file is compatible with the project configuration:

{
    "python.formatting.provider": "black",
    "[python]" : {
        "editor.codeActionsOnSave": {
            "source.organizeImports": true
        },
        "editor.formatOnSave": true
    },
    "[markdown]": {
        "editor.wordWrapColumn": 88
    },
    "[restructuredtext]": {
        "editor.wordWrapColumn": 88
    },
    "editor.rulers": [88],
    "editor.wordWrapColumn": 88,
    "python.analysis.typeCheckingMode": "basic"
}

This assumes that the Python and Pylance extensions are installed.

This project uses type hints. Typing is enforced by the test workflow using pyright (in practice this means that if Pylance doesn’t produce any errors in basic mode, pyright shouldn’t).