Design — pinky-core

Update date : 2026-05-25 16:31

Architecture decisions, constraints, and trade-offs for pinky-core.

Placement in the suite

pinky-core belongs in this kit because it has zero runtime dependencies beyond the standard library and optional pure-Python packages. The rule: if a module requires a live Snowflake connection or external credentials, it does not belong here — it belongs in pinky-snowpark or pinky-connect.

This constraint is what makes pinky-core importable everywhere: CI pipelines, local scripts, Streamlit apps, UDF handlers inside Snowflake.

Import constraint — no top-level Snowpark

Pure utility modules (fmt.py, security.py, validate.py, …) must not import Snowpark at the module level. The reason: importing Snowpark without a session raises or adds startup cost in contexts that don't need it (CI, local dev, plain Python scripts).

The pattern for modules that optionally use Snowpark:

# In snowpark.py — lazy import inside the function body
def stage_write(session, path: str) -> None:
    import snowflake.snowpark as snowpark  # only loaded when called
    ...

# For type hints only — no runtime cost
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    import snowflake.snowpark as snowpark

Module boundaries

Each .py file = one concern. No cross-imports between peer modules. The __init__.py re-exports everything — callers use from pinky_core import format_date, not from pinky_core.fmt import format_date.

Distribution

pinky-core is published as a standard Python package (src/ layout, pyproject.toml). For Snowflake UDFs and SPs, it is uploaded as a .zip to a stage via pinky_core.packages. The same package runs inside and outside Snowflake without modification.

What is deliberately out of scope

Snowpark session management → pinky-snowpark
Streamlit components → pinky-streamlit
External API calls (HTTP, Workday, INSEE) → pinky-connect
Airflow operators → pinky-airflow
Anything that requires credentials at import time