Currently the code in PyRIT should try to have a consistent style. A consistent coding style aids in efficient development of capabilities.
We use the Google Python Style Guide. For docstrings, there are rules for modules, classes, and functions.
While we can’t expect all documentation to be perfect from day 1, we’ll improve any docstring that we touch in a pull request to be compliant with this style guide.
The PyRIT codebase uses whitespace for organization / visual clues so developers can quickly scan and understand relation based on whitespace in addition to other features.
Deviations from any particular rule can occur depending on context and need.
Strict rules should be included in the pre-commit hooks. This is currently run as part of the build pipelines. If we want to enforce style, it’s best to do here.
Use explicit types and return values when possible
Comments are highly encouraged. We use docstrings under the function. The docstring format should align with Google guidelines .
Long line lengths are discouraged (>= ~120)
Large files are discouraged. If possible put one class per file or at least put only related classes in the same file. Large files should be broken up.
Fight indentation and scoping. Lots of scopes makes code more difficult to read and properly write. Use the following to fight indentation: early function exits, logic inversion/continue, exceptions (as appropriate), creating smaller functions, goto’s, etc.
Test code should adhere to these coding guidelines as well.
One empty line between related (in-class things)
Two empty lines between unrelated things (classes, global functions, etc)
One parameter per line
Spaces not tabs. Tab value must be 4 spaces
Test names should be test_foo test_bar, test_baz, etc.
In the case of type name conflicts, the desired type should be used in its fully-qualified (or disambiguating relatively-qualified) form: e.g.
pyrit.shared.fooNaming should follow typical Python naming. e.g. some_descriptive_name
PyRIT imports go last (after a newline)
Imports should go in alphabetical order
Public PyRIT imports¶
Use the shortest package that already exports a symbol. This keeps callers independent of implementation filenames:
from pyrit.analytics import analyze_results
from pyrit.executor.attack import AttackStrategy
from pyrit.models import MessageDo not import these from pyrit.analytics.result_analysis,
pyrit.executor.attack.core.attack_strategy, or pyrit.models.messages.message.
Keep distinct executor APIs such as pyrit.executor.attack and
pyrit.executor.workflow; do not flatten them into pyrit.executor.
Internal imports within the package owning the public export still use
absolute implementation-module paths to avoid circular imports. Ruff’s TID252
rejects relative imports so they cannot bypass public-import checks.
Helpers without a public export, such as
pyrit.common.net_utility.get_httpx_client, also keep their direct imports.
Package initializers and immutable Alembic revisions are excluded.
Tests follow the same public import convention so implementation file moves do not break public API tests. Tests of helpers without public exports still import them directly. Notebook code cells are checked independently because synchronization with paired Python files is not enforced.
The check-public-imports pre-commit hook uses existing _LAZY_EXPORTS declarations.
Local commits check changed files; CI checks all files. After changing public exports,
check all consumers, including unchanged files:
uv run pre-commit run check-public-imports --all-filesThe direct command uv run python -m build_scripts.check_public_imports also
checks all tracked Python files and notebooks when no filenames are supplied.
Ruff’s TID251 can ban fixed API
paths, but cannot infer public re-exports or exempt internal sibling imports
selectively. The export-aware hook avoids maintaining a second list of public APIs.
Mocking lazy exports¶
Patch the name where the consumer looks it up. For example, if the consumer imports inside a function:
from pyrit.score import find_objective_metrics_by_eval_hashpatch pyrit.score.find_objective_metrics_by_eval_hash, not
pyrit.score.scorer_evaluation.scorer_metrics_io.find_objective_metrics_by_eval_hash.
Lazy packages cache resolved exports. Patching only the implementation module can
either miss the cached function or cause the package to cache a mock after the patch
ends. Internal consumers that import the implementation module still need patches there.
For names imported at module scope, patch the consumer module’s bound name instead.