Hygiene

Data cleaning and validation: docstring generation, code quality.

Docstring generation

Preview missing docstrings without modifying source files:

python -m siege_utilities.hygiene.generate_docstrings --path .

Apply the additions explicitly after reviewing the preview:

python -m siege_utilities.hygiene.generate_docstrings --path . --write

--apply is an alias for --write; --dry-run explicitly selects the default preview mode. Python callers must pass dry_run=False to process_python_file or main to write files. This replaces the previous write-by-default behavior.

The generator inserts docstring lines into public synchronous and asynchronous functions, preserving existing comments, formatting, encoding, and line endings. One-line suites are skipped with a warning because adding docstring lines would require reformatting their existing source. Existing docstrings are left intact. Directory exclusions match whole path components, including build, dist, caches, .git, and Django migrations directories. Names such as distributed, redistricting, and builds remain eligible.

Generated templates use signature information without importing target modules. Examples carry # doctest: +SKIP because names may not be package exports and calls may require external resources. Review the descriptions for domain-specific meaning before committing them.

Hygiene utilities for maintaining siege_utilities package.

This module provides tools for package maintenance including: - Documentation generation and management

For release management, use scripts/release_manager.py directly.

siege_utilities.hygiene.generate_docstrings(base_path=None, dry_run=True)

Process all Python files under base_path to add missing docstrings.

Parameters:

• base_path – Directory to search (defaults to the current directory).

• dry_run – Report changes without writing by default. Set False to apply.

Raises:

FileNotFoundError – If no Python files are found under base_path.

Submodules

Auto-generate docstrings for functions missing them in siege_utilities. Part of the hygiene maintenance toolkit.

siege_utilities.hygiene.generate_docstrings.analyze_function_signature(func)

Describe the signature of a callable or a parsed function definition.

siege_utilities.hygiene.generate_docstrings.categorize_function(func_name)

Categorize function based on name patterns.

siege_utilities.hygiene.generate_docstrings.generate_docstring_template(func_name, func_obj=None)

Generate a comprehensive docstring template.

class siege_utilities.hygiene.generate_docstrings.DocstringAdder

Bases: NodeTransformer

Add function docstrings to an AST and record source insertion points.

__init__(module_name='unknown', source=None)

visit_FunctionDef(node)

Add a docstring to an undocumented public function when insertion is safe.

visit_AsyncFunctionDef(node)

Apply the same docstring handling to asynchronous functions.

siege_utilities.hygiene.generate_docstrings.process_python_file(file_path, dry_run=True)

Process a single Python file to add missing docstrings.

Parameters:

• file_path – Python file to process.

• dry_run – Report changes without writing by default. Set False to apply.

Only docstring lines are inserted; existing source bytes are preserved. Inline suites are skipped with a warning because they require reformatting.

Raises:

• SyntaxError – If the file has invalid Python syntax.

• OSError – If the file cannot be read or written.

siege_utilities.hygiene.generate_docstrings.find_python_files(base_path)

Find Python files, excluding initializers, build/cache directories and migrations.

siege_utilities.hygiene.generate_docstrings.main(base_path=None, dry_run=True)

Process all Python files under base_path to add missing docstrings.

Parameters:

• base_path – Directory to search (defaults to the current directory).

• dry_run – Report changes without writing by default. Set False to apply.

Raises:

FileNotFoundError – If no Python files are found under base_path.

siege_utilities.hygiene.generate_docstrings.cli()

Command line interface.