How quantco/polarify works
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