checks

checks

Base classes for implementing checks in panoptipy.

Classes

Name	Description
Check	Base class for all checks.
CheckResult	Result of a single code quality check.
CheckStatus	Status of a check run.
DocstringCheck	Check to ensure documentation included via docstrings in Python codebase.
HasTestsCheck	A check that identifies test files and test functions without executing code.
LargeFilesCheck	A check that identifies large files in version control that exceed a specified size threshold.
PrivateKeyCheck	A security check that scans files for private key patterns.
PydoclintCheck	A check implementation to validate docstring compatibility with type signatures using pydoclint.
PyprojectTomlValidateCheck	A check class that validates the pyproject.toml file format and schema.
ReadmeCheck	A check that verifies the existence and content of a README file.
RuffFormatCheck	A check class that verifies code formatting using ruff format.
RuffLintingCheck	A Check implementation that performs linting using the Ruff linter.

Check

checks.Check(self, check_id, description)

Base class for all checks.

Attributes

Name	Description
category	Category this check belongs to.

Methods

Name	Description
run	Run this check against a codebase.

run

checks.Check.run(codebase)

Run this check against a codebase.

CheckResult

checks.CheckResult(
    self,
    check_id,
    status,
    message,
    repo_path=None,
    details=None,
)

Result of a single code quality check.

CheckStatus

checks.CheckStatus()

Status of a check run.

DocstringCheck

checks.DocstringCheck(self)

Check to ensure documentation included via docstrings in Python codebase.

This class implements a check that verifies the presence of docstrings for all public functions and classes in a Python codebase, excluding test files and test-related items. The check considers an item “public” if it doesn’t start with an underscore, and identifies test-related items through various common naming patterns.

Attributes

Name	Type	Description
check_id	str	Identifier for this check, set to “docstrings”
description	str	Human-readable description of what this check does

HasTestsCheck

checks.HasTestsCheck(self)

A check that identifies test files and test functions without executing code.

This check searches for test files following standard Python testing conventions (test_.py or _test.py) and identifies test functions using AST parsing. It counts and reports test functions that follow these patterns:

Functions prefixed with ‘test_’
Methods prefixed with ‘test_’ inside classes prefixed with ‘Test’
Static and class methods prefixed with ‘test_’ inside test classes

The check provides a count of all identified test items without executing any code.

Attributes

Name	Type	Description
check_id	str	Identifier for this check, set to “has_tests”
description	str	Description of what this check does

LargeFilesCheck

checks.LargeFilesCheck(self, config=None)

A check that identifies large files in version control that exceed a specified size threshold.

This check examines all tracked files in the repository and reports those that are larger than the configured maximum size. This helps identify potentially problematic large files that could bloat the repository or data that have been added to version control by mistake.

Attributes

Name	Type	Description
max_size_kb	int	Maximum allowed file size in kilobytes. Defaults to 500KB if not specified.
check_id	str	Unique identifier for this check (“large_files”)

PrivateKeyCheck

checks.PrivateKeyCheck(self, additional_patterns=None)

A security check that scans files for private key patterns.

This class implements a security check to detect private keys in version-controlled files by looking for common private key header patterns. It helps prevent accidental exposure of sensitive credentials in source code repositories.

Attributes

Name	Type	Description
BLACKLIST	List[bytes]	Default list of byte patterns indicating private keys
blacklist	List[bytes]	Instance copy of BLACKLIST that can be extended

Parameters

Name	Type	Description	Default
additional_patterns	Optional[List[bytes]]	Additional patterns to check. These patterns will be added to the default BLACKLIST. Defaults to None.	`None`

PydoclintCheck

checks.PydoclintCheck(self)

A check implementation to validate docstring compatibility with type signatures using pydoclint.

This class extends the base Check class to verify that docstrings in Python files match their corresponding type signatures. It uses the pydoclint tool to perform the validation.

The check will: 1. Find all Python files in version control 2. Filter files to only those containing both docstrings and type annotations 3. Run pydoclint on the filtered files 4. Report any mismatches between docstrings and type signatures

Attributes

Name	Type	Description
check_id	str	Identifier for this check, set to “pydoclint”
description	str	Description of what this check does

PyprojectTomlValidateCheck

checks.PyprojectTomlValidateCheck(self)

A check class that validates the pyproject.toml file format and schema.

This check validates both the TOML syntax and the schema of pyproject.toml using the validate-pyproject API. It verifies that the file exists in the codebase root directory and contains valid configuration.

Attributes

Name	Type	Description
check_id	str	Identifier for this check, set to “pydoclint”
description	str	Description of what this check does

ReadmeCheck

checks.ReadmeCheck(self, config=None)

A check that verifies the existence and content of a README file.

This check searches for README files in common formats (md, rst, txt) in the repository root and verifies that they contain sufficient content. A README is considered “empty” if it contains fewer than a configurable number of non-whitespace characters.

Attributes

Name	Type	Description
check_id	str	Identifier for this check, set to “readme”
description	str	Description of what this check does
min_content_length	int	Minimum content length (in characters) for a README to be considered non-empty

RuffFormatCheck

checks.RuffFormatCheck(self)

A check class that verifies code formatting using ruff format.

This class implements a check to ensure that code follows formatting according to ruff format standards. It runs the ‘ruff format –check’ command on the codebase and reports any formatting inconsistencies.

Attributes

Name	Type	Description
check_id	str	Identifier for this check, set to “ruff_format”
description	str	Description of what this check does

RuffLintingCheck

checks.RuffLintingCheck(self)

A Check implementation that performs linting using the Ruff linter.

This class runs the Ruff linter on a codebase to identify code style and quality issues.

Attributes

Name	Type	Description
check_id	str	Unique identifier “ruff_linting” for this check
description	str	Human readable description of what this check does