ABE Python Development¶

Overview¶

ABE uses Python for microarchitecture tools (see FIFO Depth Tool and Packet Quantization Calculator) and RAD DV. This document describes the static analysis tools that help maintain code quality.

Audience: ABE contributors

Tools:

isort - Organize imports
black - Format code
pylint - Lint for errors and style
mypy - Type check

Getting Started¶

Set Up and Install the Environment¶

make py-venv-all
source .venv/bin/activate
make py-install-all

Run Example¶

make PY_SRCS=ALL py-static-fix

See FAQ for more usage examples.

Examine Outputs¶

Outputs appear at the console.

Explore Relevant Directory Layout¶

.
├── mk
│   ├── 00-vars.mk
│   ├── 20-python.mk
├── isort.cfg
├── mypy.ini
├── pyproject.toml

Makefiles¶

Makefiles are in directory mk. See Makefiles section for details.

Common flags come from 00-vars.mk.
Python commands are in 20-python.mk.

Common commands:

make py-help

Organize Imports with isort ¶

isort automatically sorts and organizes Python import statements. It groups imports into sections (standard library, third-party, local) and sorts them alphabetically for consistency.

isort Commands¶

Check import organization without modifying files:

make PY_SRCS=<files> py-isort-check

Fix import organization:

make PY_SRCS=<files> py-isort-fix

The format commands also include isort:

make PY_SRCS=<files> py-format-check  # includes isort check
make PY_SRCS=<files> py-format-fix    # includes isort fix

isort Configuration¶

Configured in .isort.cfg and pyproject.toml under [tool.isort].

Format with black ¶

black is a Python code formatter that automatically formats code to a consistent style. It applies the same formatting rules everywhere, making code easier to read and review.

black Commands¶

Check code formatting without modifying files:

make PY_SRCS=<files> py-format-check

Fix code formatting:

make PY_SRCS=<files> py-format-fix

black Configuration¶

Configured in pyproject.toml under [tool.black].

Lint with pylint ¶

pylint analyzes Python code for errors and style issues. It finds bugs and potential problems before you run the code.

Commands¶

Run pylint on specified files:

make PY_SRCS=<files> py-lint

Configuration¶

Configured in pyproject.toml under [tool.pylint] and via command-line flags in mk/00-vars.mk.

Type Check with mypy ¶

mypy is a static type checker for Python. It checks type annotations without running the code and finds type-related bugs early.

mypy Commands¶

Run mypy type checking on specified files:

make PY_SRCS=<files> py-typecheck

mypy Configuration¶

Configured in mypy.ini.
The typings directory contains necessary type stubs for imports.

FAQ¶

Why doesn't ABE use the latest Python version?¶

ABE targets the latest Python version when dependencies support it.

What does `PY_SRCS=ALL` mean?¶

ALL runs tools on all Python files in the workspace tracked by git.

How do I run all static checks at once?¶

make PY_SRCS=ALL py-static-check  # check only
make PY_SRCS=ALL py-static-fix    # check and fix

Can I run tools on specific files?¶

Yes, set PY_SRCS to specific file patterns:

make PY_SRCS="src/abe/uarch/*.py" py-lint
make PY_SRCS="src/abe/rad/tools/dv.py" py-typecheck

References¶

Licensing¶

See the LICENSES directory at the repository root.