Code Quality Standards#

Acoular requires a high standard of code quality, and we test if these requirements are met via Continuous Integration (CI) with GitHub Actions.

Currently, three main checks are performed on the code:

  1. Linting and Formatting: The code must be correctly formatted and free of linting errors.

  2. Documentation Build: The documentation must be buildable without errors.

  3. Testing: The unit and regression tests must pass without errors.

We recommend running these checks before submitting a pull request. This can be done locally or on a GitHub runner. The latter is possible by using the workflow_dispatch event from the desired branch holding the changes. To do this, go to the Actions tab in the forked GitHub repository, select the Tests workflow and press the Run workflow button.

Linting and Formatting#

Acoular primarily follows the coding style of PEP8. We use ruff for linting and formatting.

Before merging, the source code must be correctly formatted and free of linting errors. You can check your code locally by running the following commands:

To check for errors and linting violations, run:

$ uv run ruff check

and to check for correct code formatting, run:

$ uv run ruff format --check

To check for errors and linting violations, run:

$ ruff check

and to check for correct code formatting, run:

$ ruff format --check

To check for errors and linting violations, run:

$ ruff check

and to check for correct code formatting, run:

$ ruff format --check

To check for errors and linting violations, run:

$ ruff check

and to check for correct code formatting, run:

$ ruff format --check

In case there are any reported errors, you can either fix them manually or try to let ruff fix them for you by running:

To check for errors and linting violations and apply autofixes, run:

$ uv run ruff check --fix

and to format the code, run:

$ uv run ruff format

To check for errors and linting violations and apply autofixes, run:

$ ruff check --fix

and to format the code, run:

$ ruff format

To check for errors and linting violations and apply autofixes, run:

$ ruff check --fix

and to format the code, run:

$ ruff format

To check for errors and linting violations and apply autofixes, run:

$ ruff check --fix

and to format the code, run:

$ ruff format

The ruff configuration can be found in:

.ruff.toml (click to expand)
# Exclude a variety of commonly ignored directories.
src = ["acoular"]
exclude = ["tests/unsupported", "docs/source", ".git"]
line-length = 120

[lint]
select = [
        "F", # pyflakes
        "C","E","R", "W",  # pylint (including pycodestyle)
        "C90", "I", "N","D", "UP",
        "YTT", "ASYNC", "ASYNC1", "BLE", "B", "A", "COM", # flake8 plugins
        "C4", "DTZ","T10","EM", "FA", "ISC", "ICN", # flake8 plugins
        "LOG", "G", "INP", "PIE", "T20", "PYI", "PT", "RSE", # flake8 plugins
        "RET", "SLF", "SLOT", "SIM", "TID", "TCH", "INT", "ARG", "TD", # flake8 plugins
        "C901" # others
        ]

ignore = [
    "C901", # do we want to measure code complexity -> TBD
    "COM812", # conflict with ruff formatter
    "ISC001", # conflict with ruff formatter
    # D
    "D401", # first line should be in imperative mood -> TBD
    # Others
    "T20", # will be fixed when logging is implemented
    "SLF001", # should be fixed with issue: #225
]

[lint.flake8-import-conventions]
banned-from  = ["numba", "numpy", "scipy.linalg"]
[lint.flake8-import-conventions.aliases]
acoular = "ac"
numba = "nb"
numpy = "np"
"scipy.linalg" = "spla"
"matplotlib.pyplot" = "plt"

[lint.pycodestyle]
ignore-overlong-task-comments = true
max-doc-length = 100

[lint.pydocstyle]
convention = "numpy"  # Accepts: "google", "numpy", or "pep257".

[format]
quote-style = "single"
docstring-code-format = true
docstring-code-line-length = 120

[lint.per-file-ignores]
"!acoular/*" = ["D"]
"acoular/__init__.py" = ["F401"]
"acoular/demo/__init__.py" = ["F401"]
"acoular/tools/__init__.py" = ["F401"]
"acoular/aiaa/__init__.py" = ["F401"]
"acoular/environments.py" = ["N806"]
"acoular/fastFuncs.py" = ["N802", "N803", "N806", "N999"] # allow different naming convention
"acoular/fbeamform.py" = ["N806", "B023"]
"acoular/sources.py" = ["N806"]
"acoular/tools/helpers.py" = ["D205"]
"acoular/tprocess.py" = ["N806"]
"tests/cases/*" = ["N802"]
"examples/*" = ["A001", "B007", "D4", "E4", "E701", "F4", "UP036", "SIM108", "SLF001", "INP001"]

Documentation Compilation#

The package documentation is provided under acoular/docs/source. This directory contains the index.rst file, which is the root document embedding several other subdocuments (sub-pages).

You can check that the documentation can be compiled without errors locally by running:

$ uv run make -C docs html

$ make -C docs html

$ make -C docs html

$ make -C docs html

Testing#

Acoular provides several tests to ensure the correct functionality of the package at different Python versions. The tests are located in the acoular/tests directory.

To run the tests locally, execute the following command from within the acoular directory:

$ uv run pytest

$ pytest

$ pytest

$ pytest