Code Generation Tools

When to use: When creating new modules, updating exports, or scaffolding tests.

generate_inits.py

Purpose: Auto-generate __init__.py files with proper __all__ exports.

Use when:

• •Adding new public functions/classes to a module
• •Creating a new package
• •Cleaning up exports after refactoring

Usage:

python scripts/generate_inits.py

How it works:

1. •Scans Python modules for public names (classes, functions, constants)
2. •Generates __init__.py with __all__ listing public exports
3. •Uses config from scripts/configs/generate_inits_config.yml

What it exports:

• •Top-level classes and functions (not private _*)
• •Module-level constants (ALL_CAPS)
• •Filters out banned exports per config

Decision rule: After adding public functions to a module, run this to update exports.

generate_tests.py

Purpose: Generate test scaffolds with smart assertions and proper fixtures.

Use when:

• •Adding tests for a new module
• •Creating test structure for existing code
• •Getting a head start on test implementation

Usage:

# Generate tests for a module
python scripts/generate_tests.py nomarr.services.domain.tagging_svc --output tests/unit/services/test_tagging_svc.py

# Preview without writing
python scripts/generate_tests.py nomarr.components.ml.ml_embed_comp --preview

# Specify layer for auto-fixture selection
python scripts/generate_tests.py nomarr.workflows.processing.process_file_wf --layer workflows

Generated tests include:

• •Proper pytest structure
• •Fixtures for layer-appropriate mocks (DB, config, ML backends)
• •Test functions for each public method
• •Type-appropriate assertions

Workflow: Adding a New Module

1. •

   Create the module with your functions/classes

2. •

   Update exports:

   bash

   python scripts/generate_inits.py
   

3. •

   Generate test scaffold:

   bash

   python scripts/generate_tests.py nomarr.components.new_comp --output tests/unit/components/test_new_comp.py --preview
   
   # If preview looks good:
   python scripts/generate_tests.py nomarr.components.new_comp --output tests/unit/components/test_new_comp.py
   

4. •

   Fill in test implementations

Workflow: After Refactoring Exports

# After adding/removing public functions:
python scripts/generate_inits.py

# Review changes:
git diff nomarr/*/__init__.py

Configuration

generate_inits_config.yml

Located at scripts/configs/generate_inits_config.yml:

# Packages to scan
packages:
  - nomarr.services
  - nomarr.workflows
  - nomarr.components
  - nomarr.persistence
  - nomarr.helpers

# Names to never export
banned_exports:
  - TYPE_CHECKING
  - annotations

Key Rules

• •Run generate_inits.py after adding public symbols — keeps exports consistent
• •Use --preview before writing test files — verify structure is correct
• •Generated tests are scaffolds — you still need to fill in assertions and edge cases