Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

3. Style Guide

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.

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 Message

Do 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-files

The 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_hash

patch 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.