Code Generation

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:

   python scripts/generate_inits.py
   

3. Generate test scaffold:

   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