# brianpugh/cyclopts architecture

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

- Interactive diagram: https://gitdiagram.com/brianpugh/cyclopts
- Repository: https://github.com/brianpugh/cyclopts

## Overview

##### Project Type and Purpose
- Cyclopts is an open-source Python library that provides a modern, extensible CLI framework.
- It offers an intuitive API for defining commands, advanced type-hinting support (built-ins, Unions, Literals, Pydantic, dataclasses, attrs), automatic help generation, and customizable parsing/validation.

##### High-Level Component Analysis
- Core Library (“cyclopts” package)
- core.py             – App class and run() entry point
- argument.py, token.py, parameter.py, field_info.py – Argument & parameter models
- bind.py, _convert.py, validators/ – Parsing, converting, validating
- help.py             – Help-page generation
- config/             – Config file (& env var) loaders: JSON, TOML, YAML
- annotations.py, protocols.py, utils.py – Support modules
- Documentation (docs/)
- Sphinx sources, extensions, theming for ReadTheDocs
- Testing (tests/)
- pytest test suites for modules, end-to-end apps, CI code coverage
- CI/CD ( .github/workflows )
- tests.yaml → run pytest + codecov
- deploy.yaml → publish to PyPI
- Packaging (pyproject.toml)
- Defines metadata, build backend, dependencies

##### Relationships & Data Flow
- User (CLI) → invokes “run()” or App()
↓
- Core: parse sys.argv → tokenize input (token.py)
↓
- Bind & Convert: map tokens to function parameters (bind.py → _convert.py → validators/)
↓
- Call target function (core.App) → capture return/exit codes
↓
- Help generation (help.py) triggered on “--help” or error
- Config loaders optionally hook into parameter resolution via environment or config files

##### Architectural Patterns & Design Principles
- Modular separation of concerns: parsing, conversion, validation, help rendering, config loading
- Extension points via protocols and registries (annotations.py, group_extractors.py)
- Dependency injection-style design: users supply converter/validator overrides
- Pluggable config backends (common/env/json/toml/yaml)

## Diagram (Mermaid)

```mermaid
graph TB
    %% User
    UserCLI["User CLI"] 

    %% Core Library
    subgraph "Core Library"
        direction TB
        AppEntry["App.run() Entry"]:::core
        subgraph "Models"
            direction TB
            Argument["Argument Model"]:::core
            Token["Token Model"]:::core
            Parameter["Parameter Model"]:::core
            FieldInfo["Field Info"]:::core
        end
        Parser["Parser (tokenize sys.argv)"]:::core
        Binder["Binder"]:::core
        Converter["Converter"]:::core
        Validators["Validators"]:::core
        Executor["Executor (call target fn)"]:::core
        HelpGen["Help Generator"]:::core
        subgraph "Config Loader"
            direction TB
            CommonConfig["Common Config"]:::ext
            EnvConfig["Env Loader"]:::ext
            JSONConfig["JSON Loader"]:::ext
            TOMLConfig["TOML Loader"]:::ext
            YAMLConfig["YAML Loader"]:::ext
        end
    end

    %% Extensions & Support
    subgraph "Extensions & Support"
        direction TB
        Annotations["Annotations & Registries"]:::ext
        Protocols["Protocols"]:::ext
        Utils["Utilities"]:::ext
        GroupExt["Group Extractors"]:::ext
        GroupCore["Core Group"]:::ext
        Types["Type Registry"]:::ext
        Exceptions["Exception Handling"]:::ext
        EnvVar["Env-var Support"]:::ext
        EditHelper["Edit Helper"]:::ext
    end

    %% User Script
    UserCode["User Script"] 

    %% Documentation
    subgraph "Documentation"
        direction TB
        Sphinx["Sphinx Sources"]:::docs
        ReadTheDocs["ReadTheDocs"]:::docs
    end

    %% CI/CD & Distribution
    subgraph "CI/CD & Distribution"
        direction TB
        GitHub["GitHub Actions"]:::cicd
        TestsCI["Run Tests & Coverage"]:::cicd
        Codecov["Codecov Reports"]:::cicd
        DeployCI["Build & Publish PyPI"]:::cicd
        PyPI["PyPI Registry"]:::cicd
        Packaging["pyproject.toml"]:::cicd
    end

    %% Flows
    UserCLI --> AppEntry
    AppEntry --> Parser
    Parser --> Binder
    Binder --> Converter
    Converter --> Validators
    Validators --> Executor
    Executor --> UserCode

    Parser --> HelpGen
    Validators --> HelpGen

    ConfigLoader --> Binder

    UserCode -.->|imports & config hooks| ConfigLoader
    Annotations -.-> Converter
    Protocols -.-> Converter
    Utils -.-> Parser
    GroupExt -.-> Validators
    GroupCore -.-> Validators
    Types -.-> Converter
    Exceptions -.-> Executor
    EnvVar -.-> Binder
    EditHelper -.-> Executor

    Sphinx --> ReadTheDocs

    GitHub --> TestsCI
    TestsCI --> Codecov
    GitHub --> DeployCI
    DeployCI --> PyPI
    GitHub --> Packaging

    %% Click Events
    click AppEntry "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/core.py"
    click Argument "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/argument.py"
    click Token "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/token.py"
    click Parameter "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/parameter.py"
    click FieldInfo "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/field_info.py"
    click Binder "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/bind.py"
    click Converter "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/_convert.py"
    click Validators "https://github.com/brianpugh/cyclopts/tree/main/cyclopts/validators/"
    click HelpGen "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/help.py"
    click CommonConfig "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/config/_common.py"
    click EnvConfig "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/config/_env.py"
    click JSONConfig "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/config/_json.py"
    click TOMLConfig "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/config/_toml.py"
    click YAMLConfig "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/config/_yaml.py"
    click Annotations "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/annotations.py"
    click Protocols "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/protocols.py"
    click Utils "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/utils.py"
    click GroupExt "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/group_extractors.py"
    click GroupCore "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/group.py"
    click Types "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/types.py"
    click Exceptions "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/exceptions.py"
    click EnvVar "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/_env_var.py"
    click EditHelper "https://github.com/brianpugh/cyclopts/blob/main/cyclopts/_edit.py"
    click Sphinx "https://github.com/brianpugh/cyclopts/tree/main/docs/"
    click TestsCI "https://github.com/brianpugh/cyclopts/blob/main/.github/workflows/tests.yaml"
    click DeployCI "https://github.com/brianpugh/cyclopts/blob/main/.github/workflows/deploy.yaml"
    click Packaging "https://github.com/brianpugh/cyclopts/blob/main/pyproject.toml"

    %% Styles
    classDef core fill:#cce5ff,stroke:#3399ff
    classDef ext fill:#d4edda,stroke:#28a745
    classDef cicd fill:#ffe5cc,stroke:#ff9933
    classDef docs fill:#e5ccff,stroke:#9933ff
```
