Python Ultimate

Quick Start

Coding Standards

Type Hints

T | None

Optional[T]

def process(data: str, limit: int | None = None) -> list[str]: ...

TYPE_CHECKING

String Formatting

.format()

%

Code Size Limits

Docstrings

Prohibited Patterns

• TYPE_CHECKING

  guards

• os.path

  (use

  pathlib.Path

  )

• Optional[T]

  (use

  T | None

  )

• # noqa

  comments

• sys.path

  manipulation
• Defensive

  try/except ImportError

  for required dependencies (see references/imports-optional-dependencies.md)
• Vague or wide parameter/return types with hidden

  isinstance

  /

  hasattr

  checks and

  None

  -as-error returns (see references/coding-standards.md)

Naming Conventions

Files and Directories

_file

output_file

config_file

_dir

cache_dir

output_dir

_path

data_path

• Bare generic names:

  path

  ,

  file

  ,

  folder

  ,

  dir

  ,

  directory

  ,

  output

  ,

  input

  ,

  source

  ,

  target

  ,

  dest

• Prefix instead of suffix:

  dir_output

  ,

  file_config

• Missing suffix:

  results

  ,

  data

  ,

  config

  (ambiguous)

Test Naming

• Files:

  test_<module>.py

• Classes:

  Test<DataProcessor>

  (PascalCase with Test prefix)
• Methods:

  test_<description>

  (snake_case with test_ prefix)

Automated Validation

# Check a variable name
uv run assets/check_path_naming.py output_file
# Output: is_file

# Scan for violations
uv run assets/check_path_naming.py --check-files src/

CLI Development

Framework Selection

Key Patterns

• Parameter validation with type hints
• Rich output formatting
• Environment variable integration
• Exit codes for error states

Linter Rules

Covered Rules

_

None

tempfile

numpy.random

secrets

Typer Exception

Annotated

Testing

Quick Commands

uv run pytest -v --tb=short
uv run pytest --cov=src --cov-report=term-missing

Key Practices

• Co-located tests:

  <module>_test.py

  alongside implementation
• 90%+ coverage target
• Fixtures in

  conftest.py

• Parameterized testing for multiple inputs

• unittest.mock

  for external dependencies

TDD Cycle

Debugging

Iron Law

4-Phase Process

1. Root Cause — Reproduce, isolate, trace data flow
2. Pattern Analysis — Identify state changes, timing issues
3. Hypothesis — Form testable prediction
4. Implementation — Minimal fix, verify with test

Red Flags

• "Let me just try changing X"
• Fixing symptoms without understanding cause
• Multiple failed fix attempts

Refactoring

Workflow

1. Find — Grep for target pattern
2. Replace — Edit with

   replace_all

   for bulk changes
3. Verify — Run tests, check for regressions

Code Transfer

Code Review

Workflow

Key Principles

• No performative agreement
• Push back with technical reasoning
• Verify feedback before implementing
• Evaluate: is the suggestion correct?

Auditing

Dimensions

1. Architecture — Structure, modularity, dependencies
2. Quality — Readability, complexity, duplication
3. Security — Input validation, secrets, injection
4. Performance — Bottlenecks, memory, I/O
5. Testing — Coverage, quality, edge cases
6. Maintainability — Documentation, technical debt

Severity Ratings

Documentation

Workflow

Sections

Mermaid Diagrams

Planning

When to Use

Structure

Project Setup

Key Tools

• uv for dependency management
• src layout for packages
• pyproject.toml for configuration

Import Order

1. Standard library
2. Third-party
3. Local (absolute imports)

File Analysis

Tools

• stat

  for metadata

• wc

  for line counts
• Grep for pattern searching
• Glob for file discovery

Type Checking Alternatives

TYPE_CHECKING

Alternatives

1. Extract shared types to dedicated modules
2. Use protocols for structural typing
3. Forward references (string literals)
4. Local imports (last resort)

Bulk Operations

• Bulk operations (10+ files)
• Complex multi-step workflows
• Iterative processing across many files
• User mentions efficiency/performance

1. Analyze locally — Use metadata operations (file counts, grep patterns)
2. Process locally — Execute all transformations in Python
3. Return summary — Report counts, not full data

# Bulk refactor across 50 files
from pathlib import Path
import re

files = list(Path('.').glob('**/*.py'))
modified = 0

for f in files:
    content = f.read_text()
    new_content = re.sub(r'old_pattern', 'new_pattern', content)
    if new_content != content:
        f.write_text(new_content)
        modified += 1

result = {'files_scanned': len(files), 'files_modified': modified}

# Code audit metadata extraction
from pathlib import Path
import ast

files = list(Path('src').glob('**/*.py'))
complexity_issues = []

for f in files:
    tree = ast.parse(f.read_text())
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            # Calculate simple complexity metric
            nested = sum(1 for n in ast.walk(node) if isinstance(n, (ast.If, ast.For, ast.While)))
            if nested > 10:
                complexity_issues.append({'file': str(f), 'function': node.name, 'complexity': nested})

result = {'files_audited': len(files), 'high_complexity': len(complexity_issues)}

• ✅ Return summaries, not full data
• ✅ Batch operations where possible
• ✅ Use

  pathlib.Path

  for file operations
• ✅ Handle errors gracefully, return error counts
• ❌ Don't read full source into context when metadata suffices
• ❌ Don't process files one-by-one interactively

Reference Files

references/

coding-standards.md

cli-development.md

linter-rules.md

testing.md

type-checking.md

debugging.md

refactoring.md

code-review.md

auditing.md

documentation.md

planning.md

file-analysis.md

project-setup.md

verification.md

imports-optional-dependencies.md