# gaogaotiantian/objprint architecture

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

- Interactive diagram: https://gitdiagram.com/gaogaotiantian/objprint
- Repository: https://github.com/gaogaotiantian/objprint

## Overview

##### Project type and purpose
- This is a Python library (“objprint”) published on PyPI.
- Its purpose is to provide functions (`op`, `objstr`, `objjson`) and a decorator (`@add_objprint`) for printing or serializing arbitrary Python objects in a human-readable or JSON format, with configurable depth, colorization, and custom formatter plugins.

##### File structure
- Top-level:
- CI/workflow configs (`.github/workflows/`)
- Project metadata (`pyproject.toml`, `Makefile`, `LICENSE`, `README.md`)
- Development requirements (`requirements-dev.txt`)
- Source root: `src/objprint/`
- Core modules under `src/objprint/`:
- `objprint.py` – main entrypoints (`op`, `objstr`, `objjson`)
- `decorator.py` – implementation of `@add_objprint` decorator
- `frame_analyzer.py` – captures call site info (filename, line number)
- `executing/` subpackage – execution-context utilities for runtime introspection
- `_exceptions.py`, `_position_node_finder.py` – helper code for `executing`
- Tests under `tests/` validate each feature and module.

##### Key architecture insights from README
- Uses a global/configurable registry of type formatters (plugin pattern)
- Separation between formatting to string vs. building a JSON-serializable structure
- Decorator pattern to inject `__str__` dynamically
- Optional features toggled via global or per-call config

##### Main components
a. Entrypoint Layer
- `op()` / `objstr()` / `objjson()` functions (in `objprint.py`)
- `install()` to expose `op()` globally
b. Core Engine
- Formatter Registry (maps Python types → formatter functions)
- Format Dispatcher (selects built-in vs. custom formatter via MRO)
- Object Inspector / Walker (reflects attributes based on regex filters)
- JSON Converter (builds dict/list primitives)
c. Extension Layer
- `@add_objprint` decorator (in `decorator.py`), which wraps class’s `__str__`/`__repr__` to call core engine
d. Utility Modules
- `frame_analyzer` & `executing` subpackage (capture call site for `line_number=True`)
- Config Module (global vs. per-call settings)
e. External Interfaces
- Standard Python `print()` and `json.dumps()` (the library integrates with them)

##### Component interactions and data flows
- User calls `op(my_obj, indent=4, format="json")` → Entrypoint Layer
- Entrypoint reads/merges global & local Config → Config Module
- Core Engine queries Formatter Registry for `type(my_obj)` → Formatter Dispatcher
- If format="json", routes to JSON Converter; else, routes to Inspector & String Builder
- Inspector may call `frame_analyzer` if `line_number=True`
- Colorization applied last by `color_util` if enabled
- Decorator usage: at import time, `@add_objprint` injects calls to Core Engine

##### Architectural patterns and design principles
- Layered architecture: Entrypoint → Engine → Utility modules
- Plugin/Registry pattern for type formatters (extensibility)
- Decorator pattern to augment user classes
- Use of Python’s MRO for formatter resolution
- Strict isolation of test suite in `tests/`

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entrypoint Layer (API)"
        API["op()/objstr()/objjson()/install()"]:::api
    end

    subgraph "Core Engine"
        Config["Config Module"]:::core
        Registry["Formatter Registry & Dispatch"]:::core
        JSONConv["JSON Converter"]:::core
        Inspector["Object Inspector/Walker"]:::core
    end

    subgraph "Utilities"
        Color["color_util"]:::util
        Frame["frame_analyzer"]:::util
        subgraph "executing (exec context)"
            Exec["executing.py"]:::util
            ExcEx["_exceptions.py"]:::util
            PosFinder["_position_node_finder.py"]:::util
        end
    end

    subgraph "Extension Layer"
        Decorator["@add_objprint"]:::ext
    end

    subgraph "External Interfaces"
        Print["Python print()"]:::external
        JsonD["json.dumps()"]:::external
    end

    subgraph "Tests"
        T1["test_objprint.py"]:::test
        T2["test_objstr.py"]:::test
        T3["test_objjson.py"]:::test
        T4["test_decorator.py"]:::test
        T5["test_config.py"]:::test
        T6["test_basic.py"]:::test
        T7["objtest.py"]:::test
    end

    API -->|"config settings"| Config
    Config -->|"type lookup request"| Registry
    Registry -->|"determine formatter"| Inspector
    Registry -->|"determine formatter"| JSONConv
    Inspector -->|"inspect attributes"| Frame
    Frame -->|"use execution context"| Exec
    Frame --> ExcEx
    Frame --> PosFinder
    Inspector -->|"intermediate output"| Color
    JSONConv -->|"json structure"| JsonD
    Color -->|"colored string"| Print
    Decorator -->|"wraps class __str__/__repr__"| API

    T1 --> API
    T2 --> API
    T3 --> API
    T4 --> Decorator
    T5 --> Config
    T6 --> API
    T7 --> Registry

    classDef api fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef core fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef util fill:#FFF9C4,stroke:#333,stroke-width:1px
    classDef ext fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef test fill:#F8BBD0,stroke:#333,stroke-width:1px

    click API "https://github.com/gaogaotiantian/objprint/blob/master/src/objprint/objprint.py"
    click Decorator "https://github.com/gaogaotiantian/objprint/blob/master/src/objprint/decorator.py"
    click Registry "https://github.com/gaogaotiantian/objprint/blob/master/src/objprint/objprint.py"
    click JSONConv "https://github.com/gaogaotiantian/objprint/blob/master/src/objprint/objprint.py"
    click Color "https://github.com/gaogaotiantian/objprint/blob/master/src/objprint/color_util.py"
    click Frame "https://github.com/gaogaotiantian/objprint/blob/master/src/objprint/frame_analyzer.py"
    click Exec "https://github.com/gaogaotiantian/objprint/blob/master/src/objprint/executing/executing.py"
    click ExcEx "https://github.com/gaogaotiantian/objprint/blob/master/src/objprint/executing/_exceptions.py"
    click PosFinder "https://github.com/gaogaotiantian/objprint/blob/master/src/objprint/executing/_position_node_finder.py"
    click T1 "https://github.com/gaogaotiantian/objprint/blob/master/tests/test_objprint.py"
    click T2 "https://github.com/gaogaotiantian/objprint/blob/master/tests/test_objstr.py"
    click T3 "https://github.com/gaogaotiantian/objprint/blob/master/tests/test_objjson.py"
    click T4 "https://github.com/gaogaotiantian/objprint/blob/master/tests/test_decorator.py"
    click T5 "https://github.com/gaogaotiantian/objprint/blob/master/tests/test_config.py"
    click T6 "https://github.com/gaogaotiantian/objprint/blob/master/tests/test_basic.py"
    click T7 "https://github.com/gaogaotiantian/objprint/blob/master/tests/objtest.py"
```
