# quantco/polarify architecture

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

- Interactive diagram: https://gitdiagram.com/quantco/polarify
- Repository: https://github.com/quantco/polarify

## Overview

##### Project Type and Purpose
- This is an open-source Python library (plugin/tool) named **polarIFy**.
- Purpose: provide a decorator/CLI that parses Python functions containing `if`/`elif`/`else` logic and transpiles them into equivalent Polars expression chains (`pl.when(...).then(...).otherwise(...)`).
- Key users: Python developers writing data-transformation pipelines in [Polars](https://www.pola.rs/).

##### File Structure Analysis
Top-level:
- `.github/` – CI/CD workflows (build.yml, ci.yml), issue & PR templates, dependabot
- `LICENSE`, `README.md`, `.gitignore`, `.pre-commit-config.yaml` – project metadata & tooling
- `pixi.toml`, `pyproject.toml`, `pixi.lock` – build & package configuration (pixi, Poetry or PEP 517)
- `polarify/` – core library package
– `__init__.py` – exposes `polarify` decorator, `transform_func_to_new_source`
– `main.py` – entry-point, CLI definition (probably using `click` or `argparse`)
- `tests/` – unit tests covering parser, transformation logic, error handling

##### README Insights
- Describes decorator usage and examples of basic, nested, and multiple conditional transformations.
- Mentions under-the-hood AST parsing & visitor patterns.
- Shows distribution via pip, conda, pixi; CI badges.
- Limits scope: no loops, side-effects, walrus operator, etc.

##### Main Components
a. Developer Code
– Source functions decorated with `@polarify`
– Optionally invoked via CLI (script entry)
b. AST Processor
– Python’s `ast` module reads function definition
– AST visitor/writer transforms `If`, `Elif`, assignments into nested Polars expression nodes
c. Code Generator
– Generates new source code string (`transform_func_to_new_source`) or compiles in-memory function replacement
– Inserts `import polars as pl` where needed
d. Polars Library
– Receives the generated expressions at runtime when the function is called on a `pl.Expr`
e. Packaging & Distribution
– Build system (pixi, pyproject) → PyPI, conda-forge
– GitHub Actions for CI, release automation, dependency updates

##### Relationships & Interactions
- **Data Flow**:
Developer writes Python code → Decorator intercepts function object → AST Processor builds intermediate representation → Code Generator emits a new Python function → At runtime calls pass through Polars library → Polars execution engine executes expression on DataFrame.
- **Control Flow**:
CLI entry-point (`polarify` console script) can also wrap a file or function, outputting the transformed source.
- **Testing & CI**:
Unit tests import `polarify` and `transform_func_to_new_source`, verify correct transformation.
GitHub Actions run on PRs and on pushes to main, triggering lint, format, test suites, and releases.

##### Architectural Patterns & Design Principles
- **Decorator Pattern**: wraps user function, transparently replacing it with a transformed version.
- **Visitor Pattern**: traverses Python AST nodes, building Polars expression tree.
- **Single Responsibility**:
- `main.py`: CLI/bootstrap
- AST transformer: parse & transform
- Code generator: emit code
- Tests: validate each module
- **Separation of Concerns**: transformation logic isolated from packaging and CLI.

##### Technologies & Frameworks
- Python 3.10+ (AST enhancements, `match` support)
- Polars (`pl`) for expressions
- pixi (or Poetry) for local development scripts
- GitHub Actions for CI/CD
- pytest for unit testing

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Entities
    Developer(("Developer")):::external
    PolarsLib[(Polars Library)]:::external
    DataFrameEngine[(DataFrame Engine)]:::external
    PyPIConda[(PyPI / Conda Registry)]:::external

    %% Core Modules
    subgraph "Core Transformation Pipeline"
        direction TB
        Decorator["@polarify Decorator"]:::code
        ASTProcessor["AST Processor (Visitor)"]:::code
        CodeGenerator["Code Generator"]:::code
        GeneratedFunc["Generated Function"]:::code
    end

    %% CLI Module
    subgraph "CLI"
        direction TB
        CLI["polarify CLI (main.py)"]:::code
    end

    %% Testing
    subgraph "Testing (pytest)"
        direction TB
        UnitTests["Unit Tests"]:::code
    end

    %% CI/CD & Packaging
    subgraph "CI/CD & Distribution"
        direction TB
        GitHubActions[(GitHub Actions)]:::cicd
        Workflows["Workflows (.github/workflows)"]:::cicd
        Templates["GitHub Templates & Automation"]:::cicd
        Packaging["Build Config (pyproject.toml, pixi.toml, pixi.lock)"]:::cicd
        Registry[(Publish to Registries)]:::cicd
    end

    %% Legend
    subgraph "Legend"
        direction TB
        A["Rectangle = Module"]:::legend
        B[("( ) = External Service")]:::legend
        C["Cylinders = Registries/CI"]:::legend
    end

    %% Data Flow
    Developer -->|"writes function"| Decorator
    Decorator -->|"parse AST"| ASTProcessor
    ASTProcessor -->|"build Polars Expr Tree"| CodeGenerator
    CodeGenerator -->|"emit code"| GeneratedFunc
    GeneratedFunc -->|"invoke at runtime"| PolarsLib
    PolarsLib -->|"execute expression"| DataFrameEngine

    %% CLI Flow
    Developer -->|"runs CLI"| CLI
    CLI -->|"transforms file/function"| ASTProcessor

    %% Testing Flow
    UnitTests -->|"test decorator & transform"| Decorator
    UnitTests -->|"test AST parsing"| ASTProcessor
    UnitTests -->|"test code emission"| CodeGenerator

    %% CI/CD & Packaging Flow
    Workflows --> GitHubActions
    GitHubActions -->|"run tests & lint"| UnitTests
    GitHubActions -->|"build & release"| Registry
    Packaging --> Registry

    %% Publishing
    Registry --> PyPIConda

    %% Click Events
    click Decorator "https://github.com/quantco/polarify/blob/main/polarify/__init__.py"
    click ASTProcessor "https://github.com/quantco/polarify/blob/main/polarify/__init__.py"
    click CodeGenerator "https://github.com/quantco/polarify/blob/main/polarify/__init__.py"
    click GeneratedFunc "https://github.com/quantco/polarify/blob/main/polarify/__init__.py"
    click CLI "https://github.com/quantco/polarify/blob/main/polarify/main.py"
    click UnitTests "https://github.com/quantco/polarify/tree/main/tests/"
    click Workflows "https://github.com/quantco/polarify/blob/main/.github/workflows/build.yml"
    click Workflows "https://github.com/quantco/polarify/blob/main/.github/workflows/ci.yml"
    click Templates "https://github.com/quantco/polarify/blob/main/.github/release.yml"
    click Templates "https://github.com/quantco/polarify/blob/main/.github/dependabot.yml"
    click Templates "https://github.com/quantco/polarify/tree/main/.github/ISSUE_TEMPLATE/"
    click Templates "https://github.com/quantco/polarify/blob/main/.github/PULL_REQUEST_TEMPLATE.md"
    click Templates "https://github.com/quantco/polarify/tree/main/.github/CODEOWNERS"
    click Packaging "https://github.com/quantco/polarify/blob/main/pyproject.toml"
    click Packaging "https://github.com/quantco/polarify/blob/main/pixi.toml"
    click Packaging "https://github.com/quantco/polarify/blob/main/pixi.lock"

    %% Styles
    classDef code fill:#cfe2f3,stroke:#084298,color:#084298
    classDef external fill:#d1e7dd,stroke:#0f5132,color:#0f5132,stroke-dasharray: 5 5
    classDef cicd fill:#f8d7da,stroke:#842029,color:#842029
    classDef legend fill:#fff3cd,stroke:#664d03,color:#664d03,stroke-dasharray: 2 2
```
