# google/latexify_py architecture

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

- Interactive diagram: https://gitdiagram.com/google/latexify_py
- Repository: https://github.com/google/latexify_py

## Overview

##### Project type and purpose
- Project name: **latexify-py**
- Purpose: A Python library that compiles Python source code or AST into LaTeX expressions. Also provides IPython wrappers for pretty-printing in notebooks.
- Type: **Open-source tooling/library**, not a web or client/server app.

##### File structure
- Top-level files & dirs:
- `pyproject.toml` – build/system config
- `src/latexify` – main Python package
- `src/integration_tests` – end-to-end tests
- `docs/` – user/developer documentation
- `examples/` – usage examples (Jupyter notebook)
- CI configs (`.github/workflows/*`), linting (`checks.sh`), CONTRIBUTING.md etc.
- Inside `src/latexify`:
- `parser.py` – parse Python source to AST
- `analyzers.py` – inspect AST to identify expressions, functions, control flow
- `transformers/` – AST transformers (e.g., expand functions, simplify assignments)
- `codegen/` – modules that map transformed AST nodes to LaTeX snippets
- `frontend.py` & `generate_latex.py` – public entry points / CLI interfaces
- `ipython_wrappers.py` – Notebook integration
- `config.py`, `exceptions.py` – support modules
- Testing strategy:
- Unit tests alongside each module (`*_test.py`)
- Integration tests in `src/integration_tests`

##### README for additional insights
- Confirms rule-based system on Python’s built-in `ast` package
- No external services or databases—pure in-process library
- Mentions IPython / Jupyter integration scope

a. Main components:
- **User Input**: Python source code or AST object
- **Parser**: `parser.py`
- **Analyzer**: `analyzers.py`
- **Transformers**: modules under `transformers/`
- **Code Generator**: modules under `codegen/`
- **Frontend / CLI**: `generate_latex.py`
- **IPython Wrapper**: `ipython_wrappers.py`
- **Tests & CI**: `unit tests`, `integration tests`, GitHub Workflows
- **External Dependencies**: Python `ast`, IPython, PyPI publish
b. Relationships/interactions:
- User → Frontend → Parser → (AST) → Analyzer → (annotated AST) → Transformers (chain) → (simplified AST) → Codegen → LaTeX string → Frontend outputs to console or notebook (via IPython wrapper)
- Tests call Frontend or each module to validate behavior; CI orchestrates test suite and publishing
c. Architectural patterns & principles:
- **Pipeline pattern**: linear data flow from parsing to code generation
- **Rule-based dispatch**: analyzers and codegen use rule tables (e.g., `expression_rules.py`)
- **Modularity**: clear separation of concerns (parsing vs analyzing vs transforming vs generating)
- **Test-driven development**: module-level tests mirror source structure
d. Key technologies/frameworks:
- Python 3.9+
- Standard `ast` module
- `pytest` (implied by test naming)
- IPython / Jupyter for notebook integration
- GitHub Actions for CI

##### Additional details to capture
- Call out the `config.py` for global settings
- Exception handling via `exceptions.py`
- How new rules plug into `expression_rules.py` and `algorithmic_codegen.py`

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Points
    subgraph "Entry Points"
        FP["frontend.py"]:::entry
        GL["generate_latex.py"]:::entry
    end

    %% Core Pipeline
    subgraph "Core Pipeline"
        P["parser.py"]:::runtime
        A["analyzers.py"]:::runtime
        AU["ast_utils.py"]:::runtime
        subgraph "Transformers"
            AR["assignment_reducer.py"]:::runtime
            AA["aug_assign_replacer.py"]:::runtime
            DR["docstring_remover.py"]:::runtime
            FE["function_expander.py"]:::runtime
            IR["identifier_replacer.py"]:::runtime
            PT["prefix_trimmer.py"]:::runtime
        end
        subgraph "Code Generator"
            EC["expression_codegen.py"]:::runtime
            FC["function_codegen.py"]:::runtime
            AC["algorithmic_codegen.py"]:::runtime
            IC["identifier_converter.py"]:::runtime
            LTX["latex.py"]:::runtime
            ER["expression_rules.py"]:::runtime
            CU["codegen_utils.py"]:::runtime
        end
    end

    %% Integration
    subgraph "IPython Integration"
        IP["ipython_wrappers.py"]:::entry
    end

    %% Config & Exceptions
    subgraph "Config & Exceptions"
        CFG["config.py"]:::runtime
        EXC["exceptions.py"]:::runtime
    end

    %% Tests & CI
    subgraph "Tests & CI"
        subgraph "Unit Tests"
            UT1["*_test.py"]:::test
        end
        subgraph "Integration Tests"
            IT1["algorithmic_style_test.py"]:::test
            IT2["function_expansion_test.py"]:::test
            IT3["regression_test.py"]:::test
            IU["integration_utils.py"]:::test
        end
        subgraph "CI / Release"
            CIWF["ci.yml"]:::test
            RW["release.yml"]:::test
        end
    end

    %% Documentation & Examples
    subgraph "Docs & Examples"
        Docs["docs/"]:::doc
        Ex["latexify_examples.ipynb"]:::doc
    end

    %% Build & Config Files
    subgraph "Build & Config Files"
        PP["pyproject.toml"]:::doc
        SC["checks.sh"]:::doc
        CM["CONTRIBUTING.md"]:::doc
        RM["README.md"]:::doc
    end

    %% External Dependencies
    subgraph "External Dependencies"
        ASTMOD["Python ast"]:::external
        IPYM["IPython"]:::external
        PYPI["PyPI"]:::external
    end

    %% Data Flow
    FP -->|"calls"| P
    GL -->|"calls"| P
    P -->|"generates AST"| A
    A -->|"annotated AST"| AU
    AU -->|"passes AST"| AR
    AR -->|"transformed AST"| AA
    AA -->|"transformed AST"| DR
    DR -->|"transformed AST"| FE
    FE -->|"transformed AST"| IR
    IR -->|"transformed AST"| PT
    PT -->|"simplified AST"| EC
    EC -->|"LaTeX snippets"| LTX
    FC -->|"LaTeX snippets"| LTX
    AC -->|"LaTeX snippets"| LTX
    IC -->|"LaTeX snippets"| LTX
    LTX -->|"LaTeX string"| GL
    LTX -->|"LaTeX in notebook"| IP

    %% Testing & CI Flows
    UT1 -->|"tests modules"| FP
    UT1 -->|"tests modules"| P
    IT1 -->|"end-to-end"| GL
    IT2 -->|"end-to-end"| GL
    IT3 -->|"end-to-end"| GL
    IU -->|"end-to-end"| GL
    CIWF -->|"runs"| UT1
    CIWF -->|"runs"| IT1
    CIWF -->|"runs"| IT2
    CIWF -->|"runs"| IT3
    CIWF -->|"runs"| IU
    RW -->|"publishes"| PYPI

    %% External Links
    P -->|"uses"| ASTMOD
    IP -->|"uses"| IPYM

    %% Click Events
    click FP "https://github.com/google/latexify_py/blob/main/src/latexify/frontend.py"
    click GL "https://github.com/google/latexify_py/blob/main/src/latexify/generate_latex.py"
    click P "https://github.com/google/latexify_py/blob/main/src/latexify/parser.py"
    click A "https://github.com/google/latexify_py/blob/main/src/latexify/analyzers.py"
    click AU "https://github.com/google/latexify_py/blob/main/src/latexify/ast_utils.py"
    click AR "https://github.com/google/latexify_py/blob/main/src/latexify/transformers/assignment_reducer.py"
    click AA "https://github.com/google/latexify_py/blob/main/src/latexify/transformers/aug_assign_replacer.py"
    click DR "https://github.com/google/latexify_py/blob/main/src/latexify/transformers/docstring_remover.py"
    click FE "https://github.com/google/latexify_py/blob/main/src/latexify/transformers/function_expander.py"
    click IR "https://github.com/google/latexify_py/blob/main/src/latexify/transformers/identifier_replacer.py"
    click PT "https://github.com/google/latexify_py/blob/main/src/latexify/transformers/prefix_trimmer.py"
    click EC "https://github.com/google/latexify_py/blob/main/src/latexify/codegen/expression_codegen.py"
    click FC "https://github.com/google/latexify_py/blob/main/src/latexify/codegen/function_codegen.py"
    click AC "https://github.com/google/latexify_py/blob/main/src/latexify/codegen/algorithmic_codegen.py"
    click IC "https://github.com/google/latexify_py/blob/main/src/latexify/codegen/identifier_converter.py"
    click LTX "https://github.com/google/latexify_py/blob/main/src/latexify/codegen/latex.py"
    click ER "https://github.com/google/latexify_py/blob/main/src/latexify/codegen/expression_rules.py"
    click CU "https://github.com/google/latexify_py/blob/main/src/latexify/codegen/codegen_utils.py"
    click IP "https://github.com/google/latexify_py/blob/main/src/latexify/ipython_wrappers.py"
    click CFG "https://github.com/google/latexify_py/blob/main/src/latexify/config.py"
    click EXC "https://github.com/google/latexify_py/blob/main/src/latexify/exceptions.py"
    click IT1 "https://github.com/google/latexify_py/blob/main/src/integration_tests/algorithmic_style_test.py"
    click IT2 "https://github.com/google/latexify_py/blob/main/src/integration_tests/function_expansion_test.py"
    click IT3 "https://github.com/google/latexify_py/blob/main/src/integration_tests/regression_test.py"
    click IU "https://github.com/google/latexify_py/blob/main/src/integration_tests/integration_utils.py"
    click CIWF "https://github.com/google/latexify_py/blob/main/.github/workflows/ci.yml"
    click RW "https://github.com/google/latexify_py/blob/main/.github/workflows/release.yml"
    click Docs "https://github.com/google/latexify_py/tree/main/docs/"
    click Ex "https://github.com/google/latexify_py/blob/main/examples/latexify_examples.ipynb"
    click PP "https://github.com/google/latexify_py/blob/main/pyproject.toml"
    click SC "https://github.com/google/latexify_py/blob/main/checks.sh"
    click CM "https://github.com/google/latexify_py/blob/main/CONTRIBUTING.md"
    click RM "https://github.com/google/latexify_py/blob/main/README.md"

    %% Styles
    classDef entry fill:#9f6,stroke:#333,stroke-width:1px
    classDef runtime fill:#6cf,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
    classDef test fill:#ccc,stroke:#333,stroke-width:1px
    classDef doc fill:#cfc,stroke:#333,stroke-width:1px
```
