# thombashi/subprocrunner architecture

> Architecture diagram of the GitHub repository thombashi/subprocrunner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thombashi/subprocrunner
- Repository: https://github.com/thombashi/subprocrunner

## Overview

##### Project type and purpose
- This is a Python wrapper library around the standard subprocess module, providing a higher-level API (SubprocessRunner), retry logic (Retry), command discovery (Which), error handling, and optional logging.

##### File structure
- Top‐level package: subprocrunner/
- _subprocess_runner.py → core runner implementation
- retry.py → Retry policy object
- _which.py → command lookup (Which)
- error.py → custom exceptions
- _logger/ → pluggable logger backend (real or null)
- Entry points: setup.py, pyproject.toml
- Tests and examples demonstrate usage but are not part of the runtime architecture.

##### README for insights
- Key components: SubprocessRunner API, Retry, Which, CalledProcessError, dry_run, history
- Dependencies: Python subprocess, optional loguru

##### Main components
a. Client application (user code)
b. Public API module (subprocrunner package)
- SubprocessRunner
- Retry
- Which
c. Internal modules
- _subprocess_runner.py
- retry.py
- _which.py
- error.py
- _logger/_logger.py and _null_logger.py
d. External services & libs
- Python subprocess stdlib
- OS shell/commands
- Optional loguru logger

##### Relationships & data flows
- Client calls SubprocessRunner(…)
- SubprocessRunner.run()
→ consults Retry (if provided)
→ invokes Python subprocess API via _subprocess_runner
→ captures stdout/stderr/returncode
→ may log via logger backend → either loguru or NullLogger
→ on error and check=True or raise_for_returncode(), throws CalledProcessError
- Which.is_exist() / abspath()
→ uses shutil.which or custom _which logic

##### Architectural patterns
- Facade: SubprocessRunner provides simplified interface over subprocess.
- Strategy: pluggable Retry policy.
- Adapter: Which adapts OS command lookup.
- Null Object: NullLogger vs real logger.

##### Elements
- Clear component names and package paths (e.g., subprocrunner._subprocess_runner)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Application"]:::external

    subgraph "Public API"
        Init["subprocrunner/__init__.py"]:::public
        SR["SubprocessRunner"]:::public
        RetryAPI["Retry Policy"]:::public
        WhichAPI["Which"]:::public
        ErrorsAPI["CalledProcessError & Errors"]:::public
        Typing["Type Definitions"]:::public
        Version["Version Metadata"]:::public
    end

    subgraph "Internal Modules"
        SSRunner["_subprocess_runner.py"]:::internal
        RetryImpl["retry.py"]:::internal
        WhichImpl["_which.py"]:::internal
        ErrorMod["error.py"]:::internal
        RealLogger["_logger/_logger.py"]:::internal
        NullLogger["_logger/_null_logger.py"]:::internal
    end

    subgraph "External Dependencies"
        PySub["Python subprocess stdlib"]:::external
        OS["OS shell/commands"]:::external
        Loguru["loguru (optional)"]:::external
    end

    Client -->|"imports / uses"| Init
    Client -->|"calls .run()"| SR
    SR -->|"uses"| RetryAPI
    SR -->|"invokes"| SSRunner
    SSRunner -->|"calls"| PySub
    PySub -->|"executes"| OS
    SR -->|"logs via"| RealLogger
    SR -->|"or via"| NullLogger
    RealLogger -->|"optional backend"| Loguru
    SR -->|"raises on error"| ErrorsAPI

    Client -->|"calls .is_exist() / .abspath()"| WhichAPI
    WhichAPI -->|"adapts"| WhichImpl
    WhichImpl -->|"checks"| OS

    classDef public fill:#b8e986,stroke:#4a7c00,color:#000
    classDef internal fill:#bae1ff,stroke:#117fcc,color:#000
    classDef external fill:#e0e0e0,stroke:#666,color:#000

    click SR "https://github.com/thombashi/subprocrunner/blob/master/subprocrunner/_subprocess_runner.py"
    click RetryAPI "https://github.com/thombashi/subprocrunner/blob/master/subprocrunner/retry.py"
    click WhichAPI "https://github.com/thombashi/subprocrunner/blob/master/subprocrunner/_which.py"
    click ErrorsAPI "https://github.com/thombashi/subprocrunner/blob/master/subprocrunner/error.py"
    click RealLogger "https://github.com/thombashi/subprocrunner/blob/master/subprocrunner/_logger/_logger.py"
    click NullLogger "https://github.com/thombashi/subprocrunner/blob/master/subprocrunner/_logger/_null_logger.py"
    click Init "https://github.com/thombashi/subprocrunner/blob/master/subprocrunner/__init__.py"
    click Typing "https://github.com/thombashi/subprocrunner/blob/master/subprocrunner/typing.py"
    click Version "https://github.com/thombashi/subprocrunner/blob/master/subprocrunner/__version__.py"
```
