# pyblish/pyblish-base architecture

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

- Interactive diagram: https://gitdiagram.com/pyblish/pyblish-base
- Repository: https://github.com/pyblish/pyblish-base

## Overview

##### Project type and purpose
- Pyblish-base is a Python library/framework: a modular, plugin-driven validation and publishing engine for creative pipelines.
- Its primary purpose is to provide a core API and plugin system. Other “pyblish-*” projects (e.g., integration with Maya or QML) build on top of this base.

##### File structure
- Top-level:
- setup.py, setup.cfg – packaging
- docs/ – Sphinx documentation
- pyblish/ – core package
- tests/ – unit and plugin compatibility tests
- run_testsuite.py, run_coverage.py – testing utilities
- Within pyblish/:
- __main__.py, cli.py – command-line entrypoints
- api.py – core API definitions (Context, Instance, etc.)
- logic.py – orchestration of plugin execution
- plugin.py – Plugin base class, discovery & registration
- lib.py, util.py, compat.py, error.py – supporting utilities
- version.py – package version
- plugins/ – example built-in plugins (collectors, validators)
- vendor/ – third-party vendored code

##### README for additional insights
- Confirms this is the “primary API” project.
- Mentions integration points (pyblish-maya, pyblish-qml) as external modules.
- Test-driven, collaborative, creative-pipeline focus.

a. Main components
- CLI Layer
– __main__.py, cli.py
- Core API & Engine
– api.py (data models: Context, Instance, Plugin)
– logic.py (pipeline orchestration)
- Plugin System
– plugin.py (base Plugin class, discovery)
– pyblish/plugins (built-in plugins)
– External Plugins (e.g., pyblish-maya)
- Utilities & Compatibility
– util.py, lib.py, compat.py
- Testing
– tests/ (unit tests, legacy pre-1.1, pre-1.3 compatibility)
- Documentation
– docs/ (Sphinx)
- Packaging & CI
– setup.py, .travis.yml, appveyor.yml, coveragerc, etc.

b. Relationships & data flows
1. User invokes CLI
→ Entry point (__main__.py) parses arguments
→ CLI module builds initial Context
2. Engine (logic.py) receives Context
→ Discovers plugins via plugin.py
→ Applies pipeline stages in order (collect → validate → extract → conform, etc.)
→ Each Plugin receives Context and modifies it or its Instances
3. Upon completion, results are reported back to CLI
4. Utilities modules support versioning, error handling, compat shims
5. Tests drive coverage and verify compatibility across releases

c. Architectural patterns & principles
- Plugin (inversion of control) pattern – core engine invokes user-provided plugins
- Pipeline / chain of responsibility – sequential stages that transform/validate data
- Separation of concerns – distinct layers (CLI, core API, plugin discovery, plugin code)

d. Key technologies & frameworks
- Python 3 (and 2) – language
- setuptools – packaging (setup.py)
- Sphinx – docs (docs/)
- pytest/unittest – tests
- CI: Travis CI, AppVeyor, Coveralls

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and main flow
    subgraph "User Invocation"
        CLI["CLI Layer"]:::cli
    end
    CLI -->|"parses args"| Engine["Core Engine"]:::core

    subgraph "Core Engine"
        subgraph "Plugin Discovery" 
            Discovery["plugin.py – discovery"]:::core
        end
        subgraph "Pipeline Orchestration"
            Orchestrator["logic.py – pipeline runner"]:::core
        end
        subgraph "Reporting"
            Reporting["Reporting Results"]:::core
        end
    end

    Engine --> Discovery
    Engine --> Orchestrator
    Engine --> Reporting

    subgraph "Core API Models"
        Context["api.py – Context, Instance"]:::model
        PluginBase["plugin.py – Plugin class"]:::model
    end

    Discovery --> PluginBase
    Orchestrator --> Context
    Orchestrator --> PluginBase

    subgraph "Built-in Plugins"
        BuiltInDir["pyblish/plugins/"]:::plugin
        CPDate["collect_current_date.py"]:::plugin
        CPUser["collect_current_user.py"]:::plugin
        CPWD["collect_current_working_directory.py"]:::plugin
    end

    BuiltInDir --> CPDate
    BuiltInDir --> CPUser
    BuiltInDir --> CPWD
    Discovery --> BuiltInDir
    CPDate --> Orchestrator
    CPUser --> Orchestrator
    CPWD --> Orchestrator

    subgraph "External Plugins"
        ExtMaya["pyblish-maya"]:::external
        ExtQML["pyblish-qml"]:::external
    end

    Discovery --> ExtMaya
    Discovery --> ExtQML
    ExtMaya --> Orchestrator
    ExtQML --> Orchestrator

    subgraph "Utilities & Compatibility"
        Util["util.py"]:::util
        Lib["lib.py"]:::util
        Compat["compat.py"]:::util
        Error["error.py"]:::util
        Version["version.py"]:::util
    end

    Engine <--> Util
    Engine <--> Lib
    Engine <--> Compat
    Engine <--> Error
    Engine <--> Version

    subgraph "Vendored Code"
        VendorDir["pyblish/vendor/"]:::vendor
    end
    Engine --> VendorDir

    %% Side components
    subgraph "Documentation"
        DocsDir["docs/"]:::docs
    end

    subgraph "Testing"
        TestsRoot["tests/"]:::test
    end

    subgraph "CI & Packaging"
        SetupPy["setup.py"]:::ci
        Travis[".travis.yml"]:::ci
        AppVeyor["appveyor.yml"]:::ci
        CoverCfg[".coveragerc"]:::ci
        RunCov["run_coverage.py"]:::ci
        RunTests["run_testsuite.py"]:::ci
    end

    CLI --> TestsRoot
    Engine --> TestsRoot
    CLI --> SetupPy
    Engine --> SetupPy
    DocsDir --> Travis
    TestsRoot --> Travis
    SetupPy --> Travis
    CoverCfg --> Travis
    AppVeyor --> TestsRoot

    %% Click Events
    click CLI "https://github.com/pyblish/pyblish-base/blob/master/pyblish/__main__.py"
    click CLI "https://github.com/pyblish/pyblish-base/blob/master/pyblish/cli.py"
    click main_py "https://github.com/pyblish/pyblish-base/blob/master/pyblish/main.py"
    click Context "https://github.com/pyblish/pyblish-base/blob/master/pyblish/api.py"
    click Orchestrator "https://github.com/pyblish/pyblish-base/blob/master/pyblish/logic.py"
    click Discovery "https://github.com/pyblish/pyblish-base/blob/master/pyblish/plugin.py"
    click BuiltInDir "https://github.com/pyblish/pyblish-base/tree/master/pyblish/plugins/"
    click CPDate "https://github.com/pyblish/pyblish-base/blob/master/pyblish/plugins/collect_current_date.py"
    click CPUser "https://github.com/pyblish/pyblish-base/blob/master/pyblish/plugins/collect_current_user.py"
    click CPWD "https://github.com/pyblish/pyblish-base/blob/master/pyblish/plugins/collect_current_working_directory.py"
    click Util "https://github.com/pyblish/pyblish-base/blob/master/pyblish/util.py"
    click Lib "https://github.com/pyblish/pyblish-base/blob/master/pyblish/lib.py"
    click Compat "https://github.com/pyblish/pyblish-base/blob/master/pyblish/compat.py"
    click Error "https://github.com/pyblish/pyblish-base/blob/master/pyblish/error.py"
    click Version "https://github.com/pyblish/pyblish-base/blob/master/pyblish/version.py"
    click VendorDir "https://github.com/pyblish/pyblish-base/tree/master/pyblish/vendor/"
    click TestsRoot "https://github.com/pyblish/pyblish-base/tree/master/tests/"
    click DocsDir "https://github.com/pyblish/pyblish-base/tree/master/docs/"
    click SetupPy "https://github.com/pyblish/pyblish-base/blob/master/setup.py"
    click Travis "https://github.com/pyblish/pyblish-base/blob/master/.travis.yml"
    click AppVeyor "https://github.com/pyblish/pyblish-base/blob/master/appveyor.yml"
    click CoverCfg "https://github.com/pyblish/pyblish-base/blob/master/.coveragerc"
    click RunCov "https://github.com/pyblish/pyblish-base/blob/master/run_coverage.py"
    click RunTests "https://github.com/pyblish/pyblish-base/blob/master/run_testsuite.py"

    %% Styles
    classDef cli fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef core fill:#80B3FF,stroke:#333,stroke-width:1px;
    classDef model fill:#B3E6B3,stroke:#333,stroke-width:1px;
    classDef plugin fill:#A3FFA3,stroke:#333,stroke-width:1px;
    classDef external fill:#FFC1C1,stroke:#333,stroke-width:1px;
    classDef util fill:#D1B3FF,stroke:#333,stroke-width:1px;
    classDef vendor fill:#CCCCCC,stroke:#333,stroke-width:1px;
    classDef docs fill:#E6E6E6,stroke:#333,stroke-width:1px;
    classDef test fill:#FF9999,stroke:#333,stroke-width:1px;
    classDef ci fill:#FFFF99,stroke:#333,stroke-width:1px;
```
