Python Check Tool¶

The Python Check tool (python_check) is a dedicated Python code quality checker available as a first-class Amplifier tool. It combines formatting, linting, type checking, and stub detection into a single interface, giving you a comprehensive quality report for any Python code.

Unlike running individual tools manually through bash, python_check integrates multiple checkers and returns structured results that Amplifier can act on directly.

Operations¶

Check	Engine	What It Catches
format	ruff format	PEP 8 style violations, inconsistent formatting
lint	ruff lint	pycodestyle, pyflakes, isort, bugbear, comprehensions, and more
types	pyright	Static type errors, missing annotations, type mismatches
stubs	stub detection	TODOs, placeholders, `pass` stubs, incomplete implementations

Parameters¶

Parameter	Type	Required	Description
`paths`	list of strings	No*	File paths or directories to check
`content`	string	No*	Python code as a string to check
`fix`	bool	No	Auto-fix issues where possible (default: false, only works with paths)
`checks`	list of strings	No	Specific checks to run (default: all)

*One of paths or content must be provided.

Input Modes¶

Check files or directories:

{
  "paths": ["src/main.py"]
}

Check multiple paths:

{
  "paths": ["src/", "tests/test_main.py"]
}

Check a directory:

{
  "paths": ["src/"]
}

Check code directly:

{
  "content": "def foo():\n    x = 1\n    return x"
}

Selective Checks¶

Run only specific checkers by passing the checks parameter:

{
  "paths": ["src/"],
  "checks": ["lint", "types"]
}

Valid values: "format", "lint", "types", "stubs".

When omitted, all four checks run.

Auto-Fix¶

Enable automatic fixing for issues that have safe fixes:

{
  "paths": ["src/"],
  "fix": true
}

Auto-fix only works with the paths input mode (not content). It applies formatting corrections and safe lint fixes in place.

Return Values¶

The tool returns a structured result with four fields:

Field	Type	Description
`success`	bool	`true` if no errors found (warnings are acceptable)
`clean`	bool	`true` if no issues at all (no errors, no warnings)
`summary`	string	Human-readable summary of all findings
`issues`	list	Detailed list of individual issues

Issue Structure¶

Each item in the issues list contains:

Field	Type	Description
`file`	string	File path where the issue was found
`line`	int	Line number
`code`	string	Issue code (e.g., `E501`, `F841`, `reportMissingImports`)
`message`	string	Human-readable description
`severity`	string	`"error"` or `"warning"`

Interpreting Results¶

success=true,  clean=true   -> No issues at all
success=true,  clean=false  -> Warnings only, no errors
success=false, clean=false  -> Errors found, needs attention

Basic Usage¶

Conversation Format¶

When you ask Amplifier to check Python code quality, it uses python_check behind the scenes:

> Check src/auth.py for code quality issues

[Tool: python_check]
paths: ["src/auth.py"]

Result:
  success: true
  clean: false
  summary: "1 warning: unused import 'os' (F401) at line 3"
  issues: [{file: "src/auth.py", line: 3, code: "F401",
            message: "os imported but unused", severity: "warning"}]

Check an Entire Directory¶

> Run a full quality check on the src directory

[Tool: python_check]
paths: ["src/"]

Result:
  success: false
  clean: false
  summary: "3 errors, 2 warnings across 12 files"
  issues: [...]

Quick Lint Only¶

> Just lint check the utils module, skip type checking

[Tool: python_check]
paths: ["src/utils/"]
checks: ["lint"]

Auto-Fix Formatting¶

> Fix the formatting in my Python files

[Tool: python_check]
paths: ["src/"]
fix: true
checks: ["format"]

What Each Check Does¶

ruff format¶

Enforces consistent code formatting following PEP 8 conventions:

Indentation (4 spaces)
Line length limits
Blank line conventions
Trailing whitespace
Quote consistency
Trailing commas

ruff lint¶

Runs a comprehensive set of linting rules:

Rule Set	What It Catches
pycodestyle (E/W)	Style violations
pyflakes (F)	Unused imports, undefined names
isort (I)	Import ordering
flake8-bugbear (B)	Common bugs and design problems
flake8-comprehensions (C4)	Unnecessary list/dict/set comprehensions
Additional rules	Various best practice violations

pyright¶

Static type analysis that catches:

Missing or incorrect type annotations
Incompatible types in assignments and function calls
Missing imports and unresolved references
Incorrect use of Optional, Union, and other type constructs
Protocol and abstract method violations
Unreachable code detected through type narrowing

Stub Detection¶

Finds incomplete code that may indicate work in progress:

Functions with only pass or ... as body
TODO, FIXME, HACK comments
Placeholder return values
Incomplete implementations

Configuration¶

pyproject.toml Settings¶

Configure the Python Check tool's behavior in your project's pyproject.toml:

[tool.amplifier-python-dev]
enable_ruff_format = true
enable_ruff_lint = true
enable_pyright = true
enable_stub_check = true

Set any option to false to disable that checker globally for the project.

Auto-Checking Hook¶

The tool can run automatically whenever Python files are written or edited:

[tool.amplifier-python-dev.hook]
enabled = true
file_patterns = ["*.py"]
report_level = "warning"
auto_inject = true

Setting	Description
`enabled`	Activate automatic checking on file writes
`file_patterns`	Which files trigger the hook (glob patterns)
`report_level`	Minimum severity to report: `"error"` or `"warning"`
`auto_inject`	Automatically inject quality feedback into the conversation

When auto_inject is enabled, every write_file or edit_file operation on a *.py file triggers a lint and type check. Results appear inline, so issues are caught immediately rather than discovered later.

ruff Configuration¶

The tool respects your project's ruff configuration in pyproject.toml:

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "B", "C4"]
ignore = ["E501"]

[tool.ruff.format]
quote-style = "double"

Pyright Configuration¶

Pyright reads from pyrightconfig.json or pyproject.toml:

[tool.pyright]
typeCheckingMode = "basic"
pythonVersion = "3.11"
venvPath = "."
venv = ".venv"

Best Practices¶

Run Early, Run Often¶

Check code quality as you write, not at the end:

1. Write a new function
2. Run python_check on the file
3. Fix issues immediately
4. Continue development

The auto-checking hook automates this pattern entirely.

Use Selective Checks for Speed¶

When iterating quickly, run only the checks you need:

// Quick formatting check
{"paths": ["src/module.py"], "checks": ["format"]}

// Type checking only after refactoring
{"paths": ["src/"], "checks": ["types"]}

// Full check before committing
{"paths": ["src/", "tests/"]}

Fix Before Committing¶

Run a full check with auto-fix before creating commits:

> Fix formatting and check everything in src/

[Tool: python_check]
paths: ["src/"]
fix: true

// Then verify no remaining issues
[Tool: python_check]
paths: ["src/"]

Content Mode for Quick Validation¶

Use the content parameter to validate code snippets before writing them to files:

{
  "content": "from typing import Optional\n\ndef get_user(id: int) -> Optional[dict]:\n    if id < 0:\n        return None\n    return {'id': id, 'name': 'test'}\n"
}

This catches issues before they touch the filesystem.

Try It Yourself¶

1. Check a Single File¶

> Check my main module for code quality

Result: Runs all four checks and reports any issues

2. Fix Formatting¶

> Auto-fix formatting issues in the src directory

Result: Applies formatting fixes in place

3. Type Check Only¶

> Run type checking on tests/

Result: Reports only pyright type errors and warnings

4. Validate a Code Snippet¶

> Check this code for issues:
  def add(a, b):
      unused = 42
      return a + b

Result: Reports unused variable 'unused' (F841)

5. Full Project Quality Report¶

> Run a complete quality check across src/ and tests/

Result: Comprehensive report across all files with all checkers

Errors and Troubleshooting¶

ruff Not Found¶

Error: ruff command not available

Solution:
1. Install ruff: pip install ruff
2. Verify: ruff --version
3. Ensure it's on your PATH

Pyright Not Found¶

Error: pyright not available

Solution:
1. Install pyright: pip install pyright (or npm install -g pyright)
2. Verify: pyright --version
3. Check your virtual environment is active

Too Many False Positives¶

Problem: pyright reports errors for valid code

Solution:
1. Ensure your virtual environment is configured in pyrightconfig.json
2. Set typeCheckingMode to "basic" instead of "strict"
3. Add type stubs for third-party libraries: pip install types-requests

Hook Running Too Often¶

Problem: Auto-checking slows down rapid edits

Solution:
1. Set report_level to "error" to reduce noise
2. Narrow file_patterns to specific directories
3. Disable the hook temporarily for bulk operations

Content Mode Limitations¶

Problem: Type checking in content mode misses imports

Explanation: Content mode checks code in isolation.
Imports referencing project modules won't resolve.

Solution: Use paths mode for code that depends on project imports.
Content mode is best for self-contained snippets.

Integration with Other Tools¶

With git-ops¶

Run quality checks before committing:

1. python_check on changed files
2. Fix any issues
3. git-ops to commit clean code

With modular-builder¶

The builder agent uses python_check to validate its own output, catching issues before presenting code to you.

With the Auto-Checking Hook¶

When the hook is active, the quality feedback loop is automatic:

1. Agent writes Python file (write_file or edit_file)
2. Hook triggers python_check with lint + types
3. Issues appear inline in the conversation
4. Agent can fix them immediately

This creates a continuous quality gate without manual intervention.

Next Steps: - Learn about LSP (Code Intelligence) for semantic code navigation - Explore Bash for running tests and builds - See Filesystem for the file operations that trigger auto-checking