# soxhub/openpyxl architecture

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

- Interactive diagram: https://gitdiagram.com/soxhub/openpyxl
- Repository: https://github.com/soxhub/openpyxl

## Overview

##### Project type and purpose
- Type: A standalone, full-featured Python library (not a web or mobile app).
- Purpose: Read, manipulate and write Microsoft Office Open XML spreadsheets (xlsx/xlsm/xltx/xltm) entirely in Python. It provides a high-level API (Workbook, Worksheet, Cell…) plus low-level XML, packaging and rendering services to produce a valid .xlsx file or parse an existing one.

##### File structure
- Top-level directories and files
– setup.py, setup.cfg, requirements.txt, tox.ini, pytest.ini: Build, packaging and CI configuration.
– openpyxl/: The entire implementation lives here, structured into subpackages by feature.
– doc/: User and developer documentation (Sphinx) including tutorials and API reference.
– tests (embedded under each subpackage and conftest.py at root): Unit and integration tests.
- Key subpackages inside openpyxl/
– workbook, worksheet, cell: Core data model classes (Workbook, Worksheet, Cell, RichText).
– reader, writer: File I/O layers that parse XML and produce XML.
– xml: Shared XML utility functions and constants.
– packaging: ZIP-container abstraction (part, relationships, manifest).
– chart, chartsheet, drawing: Domain features for charts and drawings.
– formatting, styles: Styling and formatting rule engines.
– formula, filters, comments, pivot: Advanced spreadsheet features.
– descriptors: Meta-programming layer for attribute serialization.
– utils, compat: Utility functions and compatibility shims.
- Patterns and architecture
– Layered architecture: Public API → Data Model → Service layers (reader/writer/xml) → Infrastructure (packaging, stdlib zip).
– Serialization/deserialization pattern: Each data object is serialisable via descriptors and reader/writer engines.

##### README for additional insights
- Confirms that openpyxl is a pure-Python library for OOXML spreadsheets.
- Mentions optional dependency on defusedxml for XML-attacks mitigation.
- Sample code shows the public-facing API (Workbook, Worksheet, save).

##### Elements
– load_workbook → Reader → Data Model → Public API
– Workbook.save → Writer → Packaging → .xlsx file
– Another for feature modules (Charts, Drawing, Formatting)
– A separate style for external dependencies (defusedxml) and for tests/docs

##### Detail
- Major subpackage is represented so that future maintainers immediately see where to add new features.
- Flow of responsibility: who owns XML parsing, who constructs relationships, who renders drawing parts, and how the data model lives independently from file I/O.
- Don’t just list modules—show how they collaborate in both the load and save paths.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers and components

    %% User
    User["User Script"]:::external

    %% Public API Layer
    subgraph "Public API Layer"
        API["openpyxl/__init__.py"]:::core
    end

    %% Data Model Layer
    subgraph "Data Model Layer"
        DM_WB["Workbook\n(openpyxl/workbook/workbook.py)"]:::core
        DM_WS["Worksheet\n(openpyxl/worksheet/worksheet.py)"]:::core
        DM_Cell["Cell\n(openpyxl/cell/cell.py)"]:::core
    end

    %% Serialization Layer
    subgraph "Serialization Layer"
        Reader["Reader\n(openpyxl/reader/)"]:::core
        Writer["Writer\n(openpyxl/writer/)"]:::core
        XML["XML Helpers\n(openpyxl/xml/)"]:::core
        Desc["Descriptors\n(openpyxl/descriptors/)"]:::core
    end

    %% Packaging Layer
    subgraph "Packaging Layer"
        Pack["Packaging\n(openpyxl/packaging/)"]:::core
    end

    %% Feature Modules
    subgraph "Feature Modules"
        Charts["Charts\n(openpyxl/chart/)"]:::feature
        Chartsheet["Chart Sheets\n(openpyxl/chartsheet/)"]:::feature
        Drawing["Drawings\n(openpyxl/drawing/)"]:::feature
        Formatting["Formatting\n(openpyxl/formatting/)"]:::feature
        Styles["Styles\n(openpyxl/styles/)"]:::feature
        Formulas["Formulas\n(openpyxl/formula/)"]:::feature
        Comments["Comments\n(openpyxl/comments/)"]:::feature
        Pivot["Pivot Tables\n(openpyxl/pivot/)"]:::feature
    end

    %% Utilities & Compatibility
    subgraph "Utilities & Compatibility"
        Utils["Utilities\n(openpyxl/utils/)"]:::util
        Compat["Compatibility\n(openpyxl/compat/)"]:::util
    end

    %% External Dependency
    Defused["defusedxml"]:::external

    %% Docs & Tests
    Docs["Documentation\n(doc/)"]:::docs
    Tests["Tests\n(openpyxl/*/tests/)"]:::docs

    %% Data flow: Load
    User -->|"import & load_workbook"| API
    API -->|"calls Reader"| Reader
    Reader -->|"uses XML Helpers"| XML
    Reader -->|"parses XML via defusedxml"| Defused
    Reader -->|"deserializes via Descriptors"| Desc
    Desc -->|"constructs"| DM_WB
    Desc -->|"constructs"| DM_WS
    Desc -->|"constructs"| DM_Cell
    DM_* -->|"in-memory model"| API

    %% Data flow: Save
    API -->|"save()"| DM_WB
    DM_WB -->|"serialize via Descriptors"| Desc
    DM_WB -->|"passed to Writer"| Writer
    Writer -->|"generates XML via XML Helpers"| XML
    Writer -->|"packages parts"| Pack
    Pack -->|".xlsx file"| User

    %% Feature integration
    Charts -->|hooks into Descriptors| Desc
    Chartsheet -->|hooks into Descriptors| Desc
    Drawing -->|hooks into Descriptors| Desc
    Formatting -->|hooks into Descriptors| Desc
    Styles -->|hooks into Descriptors| Desc
    Formulas -->|hooks into Descriptors| Desc
    Comments -->|hooks into Descriptors| Desc
    Pivot -->|hooks into Descriptors| Desc

    %% Utilities usage
    Utils -->|"supports all layers"| API
    Utils --> API
    Utils --> DM_WB
    Compat -->|"supports compatibility"| Reader
    Compat --> Writer

    %% Docs & Tests
    Docs -.-> API
    Docs -.-> DM_WB
    Tests -.-> DM_WS
    Tests -.-> Charts

    %% Click events
    click API "https://github.com/soxhub/openpyxl/blob/master/openpyxl/__init__.py"
    click DM_WB "https://github.com/soxhub/openpyxl/blob/master/openpyxl/workbook/workbook.py"
    click DM_WS "https://github.com/soxhub/openpyxl/blob/master/openpyxl/worksheet/worksheet.py"
    click DM_Cell "https://github.com/soxhub/openpyxl/blob/master/openpyxl/cell/cell.py"
    click Reader "https://github.com/soxhub/openpyxl/tree/master/openpyxl/reader/"
    click Writer "https://github.com/soxhub/openpyxl/tree/master/openpyxl/writer/"
    click XML "https://github.com/soxhub/openpyxl/tree/master/openpyxl/xml/"
    click Desc "https://github.com/soxhub/openpyxl/tree/master/openpyxl/descriptors/"
    click Pack "https://github.com/soxhub/openpyxl/tree/master/openpyxl/packaging/"
    click Charts "https://github.com/soxhub/openpyxl/tree/master/openpyxl/chart/"
    click Chartsheet "https://github.com/soxhub/openpyxl/tree/master/openpyxl/chartsheet/"
    click Drawing "https://github.com/soxhub/openpyxl/tree/master/openpyxl/drawing/"
    click Formatting "https://github.com/soxhub/openpyxl/tree/master/openpyxl/formatting/"
    click Styles "https://github.com/soxhub/openpyxl/tree/master/openpyxl/styles/"
    click Formulas "https://github.com/soxhub/openpyxl/tree/master/openpyxl/formula/"
    click Comments "https://github.com/soxhub/openpyxl/tree/master/openpyxl/comments/"
    click Pivot "https://github.com/soxhub/openpyxl/tree/master/openpyxl/pivot/"
    click Utils "https://github.com/soxhub/openpyxl/tree/master/openpyxl/utils/"
    click Compat "https://github.com/soxhub/openpyxl/tree/master/openpyxl/compat/"
    click Docs "https://github.com/soxhub/openpyxl/tree/master/doc/"

    %% Styles
    classDef core fill:#D6EFFF,stroke:#0366D6,stroke-width:1px
    classDef feature fill:#DFFFE0,stroke:#228B22,stroke-width:1px
    classDef util fill:#FFF5CC,stroke:#DAA520,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#666666,stroke-width:1px,stroke-dasharray: 2 2
    classDef docs fill:#FFE5EC,stroke:#DB1374,stroke-width:1px
```
