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