[Refactor] Standardize CLI Examples for Testability and Maintenance

[Borda]

Search before asking

• I have searched the issues and discussions and found no similar feature request.

Feature Description

Summary

This issue tracks the refactoring of CLI scripts within the examples/ directory. Currently, many example scripts execute logic via loose procedural code or simple main blocks. The goal is to standardize these into callable functions to improve code hygiene and enable programmatic testing.

Proposed Changes

Refactor the example scripts (e.g., traffic_analysis, speed_estimation, tracking, etc.) to adhere to the following pattern:

1. Encapsulation: Move execution logic from the global scope/if __name__ block into a dedicated def main(args): function.
2. Return Values: Ensure the main() function returns essential metadata (e.g., detection counts, processing stats) rather than simply printing to stdout or exiting.

Impact

• Simplicity: Creates a uniform structure across all examples, making it easier for contributors to understand and modify different scripts.
• Maintainability: Decouples argument parsing from the core execution logic.
• Testability: This is the primary driver. By making main a function that returns data, we can implement integration tests that import the script, execute main(), and programmatically validate the returned metadata against expected results.

Related Open PRs

The following PRs implement these changes across various example scripts:

• examples/traffic_analysis: improve CLI argument handling #2059 (traffic_analysis)
• examples/tracking: improve CLI argument parsing #2058 (tracking)
• examples/time_in_zone: improve CLI argument handling #2057 (time_in_zone)
• examples/speed_estimation: improve CLI argument parsing #2056 (speed_estimation)
• examples/heatmap_and_track: improve CLI argument parsing #2055 (heatmap_and_track)
• examples/count_people_in_zone: resolve IoU threshold & improve CLI #2054 (count_people_in_zone)

Sample Usage for Testing

1. Script Refactoring Pattern (examples/your_script.py)

Instead of running logic globally, encapsulate it in main and return data.

# ... imports ...

def main(*args):
    # ... complex logic execution ...
    
    # ... calculation of results ...

    # Return metadata instead of just exiting/printing
    return {
        "status": "success",
        "metric_a": 123,
        "metric_b": 456
    }

if __name__ == "__main__":
    # ...

2. Test Implementation Pattern (tests/test_your_script.py)

Now you can import the function and validate the return dictionary programmatically.

import pytest
from argparse import Namespace
from examples.traffic_analysis import main as traffic_main

def test_traffic_analysis_runs_successfully():
    # 1. Mock the CLI arguments using a Namespace object
    #    This simulates passing flags like --source or --confidence
    mock_args = Namespace(
        source="tests/data/short_clip.mp4",
        target="tests/output/result.mp4",
        confidence=0.3,
        iou=0.5
    )

    # 2. Call the function directly
    #    No subprocess.run(), no parsing stdout text!
    result = traffic_main(mock_args)

    # 3. Assertions based on the Return Value
    assert result["status"] == "success"
    assert result["processed_frames"] > 0
    
    # We can even validate specific computer vision logic
    # e.g., we know the test video contains at least 1 car
    assert result["detections"]["car"] >= 1

Why this is better

• Speed: It runs in the same Python process; no overhead of creating new processes for every test.
• Precision: You check actual data (result["detections"]["car"] >= 1) rather than fragile string matching on logs (e.g., assert "Car detected" in stdout).
• Debugging: If the test fails, you get a full Python traceback pointing exactly to the line in the script that failed, rather than a generic "Process exited with code 1".

Are you willing to submit a PR?

• Yes I'd like to help by submitting a PR!