# astanin/python-tabulate architecture

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

- Interactive diagram: https://gitdiagram.com/astanin/python-tabulate
- Repository: https://github.com/astanin/python-tabulate

## Overview

##### Main Components
a. User Layer
- Python Client Code (import tabulate; call tabulate(...))
- CLI Tool (`tabulate` executable)
b. Core Library
- API entrypoint (tabulate.py, `def tabulate(...)`)
- Data Normalizer / Type Detector (handles lists, dicts, numpy arrays, pandas.DataFrame, dataclasses, etc.)
- Table Model (rows × columns matrix)
- Alignment & Formatting Engine (decimal alignment, numeric parsing, multi-line support)
- Formatter Registry (mapping tablefmt names to formatter classes/modules)
c. Formatters (one per output format)
- Plain, Simple, Grid, GitHub, HTML, LaTeX, etc.
- Each formatter module knows how to render a Table Model into a string or HTML.
d. Output Layer
- Return string to caller (Python)
- Write to stdout/file (CLI wrapper)
e. Optional / External Services
- wcwidth library (for wide-char support)
- NumPy, Pandas (if installed)

##### Interactions & Data Flows
1. User → (import/CLI) → API Entrypoint
2. Entrypoint
- Parses arguments (if CLI)
- Calls Data Normalizer ⇒ constructs internal Table Model
3. Table Model → Alignment & Formatting Engine
4. Formatting Engine → Formatter Registry → Specific Formatter
5. Formatter → renders output string
6. API returns string (or CLI prints to stdout / writes to file)

##### Architectural Patterns
- Modular design: clear separation of concerns (normalization, formatting, output)
- Strategy pattern: each `tablefmt` is a strategy/formatter class implementing a common interface
- Plug-in / registry: formatters registered by name in a central map
- Adapter pattern: external types (NumPy, pandas, dataclass, dict) are adapted to the same Table Model
- Optional chaining: features (wide-char via wcwidth, extra backends) are only activated if detected

##### Relevant Technologies & Configuration
- Python 3.7+ library
- pyproject.toml for packaging (PEP 517/518)
- tox.ini for multi-env testing
- pytest for test suite under test/
- GitHub Actions workflows (.github/workflows) for CI (lint, test matrix)
- benchmark scripts under benchmark/

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        User["Python Client Code"]:::user
        CLI["CLI Tool"]:::user
    end

    %% Core Library
    subgraph "Core Library"
        API["API Entrypoint"]:::code
        Normalizer["Data Normalizer / Type Detector"]:::code
        Model["Table Model"]:::code
        Engine["Alignment & Formatting Engine"]:::code
        Registry["Formatter Registry"]:::code
    end

    %% Formatters
    subgraph "Formatters"
        Plain["Plain Formatter"]:::code
        Grid["Grid Formatter"]:::code
        GitHub["GitHub Formatter"]:::code
        HTML["HTML Formatter"]:::code
        LaTeX["LaTeX Formatter"]:::code
        %% ... other formatters ...
    end

    %% Output Layer
    subgraph "Output Layer"
        Return["Return String to Caller"]:::code
        Print["Print to stdout/file"]:::code
    end

    %% External Dependencies
    subgraph "External / Optional"
        WC["wcwidth"]:::external
        NumPy["NumPy Adapter"]:::external
        Pandas["Pandas Adapter"]:::external
    end

    %% Packaging & CI
    subgraph "Packaging & CI"
        ConfigPKG["pyproject.toml & MANIFEST.in"]:::config
        CI1[".github/workflows/lint.yml"]:::config
        CI2[".github/workflows/tabulate.yml"]:::config
        Tests["Test Suite (test/)"]:::test
        Benchmark["Benchmark (benchmark/)"]:::config
        Tox["tox.ini"]:::config
    end

    %% Data Flows
    User -->|"imports / calls"| API
    CLI -->|"executes entry point"| API
    API -->|"normalizes data"| Normalizer
    Normalizer -->|"builds model"| Model
    Model -->|"formats & aligns"| Engine
    Engine -->|"selects formatter"| Registry
    Registry -->|"renders via"| Plain
    Registry -->|"renders via"| Grid
    Registry -->|"renders via"| GitHub
    Registry -->|"renders via"| HTML
    Registry -->|"renders via"| LaTeX
    Plain -->|"output string"| Return
    Grid --> Return
    GitHub --> Return
    HTML --> Return
    LaTeX --> Return
    Return --> Print

    %% Optional chaining
    Normalizer -.-> WC
    Normalizer -.-> NumPy
    Normalizer -.-> Pandas

    %% Packaging & CI Flows
    API -.-> ConfigPKG
    CLI -.-> Tests
    Tests -.-> CI1
    Tests -.-> CI2
    Benchmark -.-> ConfigPKG
    CI1 -.-> Tox
    CI2 -.-> Tox

    %% Click Events
    click User "https://github.com/astanin/python-tabulate/blob/master/tabulate/__init__.py"
    click CLI "https://github.com/astanin/python-tabulate/blob/master/test/test_cli.py"
    click API "https://github.com/astanin/python-tabulate/blob/master/tabulate/__init__.py"
    click Normalizer "https://github.com/astanin/python-tabulate/blob/master/tabulate/__init__.py"
    click Model "https://github.com/astanin/python-tabulate/blob/master/tabulate/__init__.py"
    click Engine "https://github.com/astanin/python-tabulate/blob/master/tabulate/__init__.py"
    click Registry "https://github.com/astanin/python-tabulate/blob/master/tabulate/__init__.py"
    click ConfigPKG "https://github.com/astanin/python-tabulate/blob/master/pyproject.toml"
    click ConfigPKG "https://github.com/astanin/python-tabulate/blob/master/MANIFEST.in"
    click CI1 "https://github.com/astanin/python-tabulate/blob/master/.github/workflows/lint.yml"
    click CI2 "https://github.com/astanin/python-tabulate/blob/master/.github/workflows/tabulate.yml"
    click Tests "https://github.com/astanin/python-tabulate/tree/master/test/"
    click Benchmark "https://github.com/astanin/python-tabulate/blob/master/benchmark/benchmark.py"
    click Benchmark "https://github.com/astanin/python-tabulate/blob/master/benchmark/requirements.txt"
    click Tox "https://github.com/astanin/python-tabulate/blob/master/tox.ini"

    %% Styles
    classDef user fill:#E3F2FD,stroke:#2196F3,color:#0D47A1,stroke-width:1px;
    classDef code fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20,stroke-width:1px;
    classDef external fill:#FFF3E0,stroke:#FF9800,color:#E65100,stroke-width:1px,stroke-dasharray: 5 5;
    classDef config fill:#F3E5F5,stroke:#9C27B0,color:#4A148C,stroke-width:1px;
    classDef test fill:#FFEBEE,stroke:#F44336,color:#B71C1C,stroke-width:1px,stroke-dasharray: 2 2;
```
