finai-snowflake-transform 0.1.0__tar.gz

finai_snowflake_transform-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/

finai_snowflake_transform-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: finai-snowflake-transform
+Version: 0.1.0
+Summary: YAML-driven demo transformation for Snowpark and pandas on Snowflake
+Author: finai-data-analytics
+License-Expression: MIT
+Keywords: pandas,snowflake,snowpark,transform
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: snowflake
+Requires-Dist: snowflake-snowpark-python[modin]>=1.55.0; extra == 'snowflake'
+Description-Content-Type: text/markdown
+
+# finai-snowflake-transform
+
+A small public package used to verify that a PyPI release, including YAML files
+bundled inside it, can be installed and executed inside Snowflake through both
+Snowpark and pandas on Snowflake.
+
+## Transformation
+
+Parameters are read from a YAML file bundled in the package, so nothing depends
+on the working directory:
+
+```text
+TRANSFORMED_VALUE = fill_null(VALUE, null_fill) * scale + offset
+```
+
+| Config | scale | offset | null_fill |
+| --- | --- | --- | --- |
+| `defaults.yaml` | 2.0 | 1.0 | 0.0 |
+| `alternate.yaml` | 3.0 | -1.0 | 2.0 |
+
+## Install
+
+```bash
+pip install finai-snowflake-transform
+# with the Snowflake runtime extra
+pip install "finai-snowflake-transform[snowflake]"
+```
+
+## Use
+
+`ID` and `VALUE` are preserved and `TRANSFORMED_VALUE` is appended. Arithmetic
+stays native to the engine you pass in; the caller reads and writes tables.
+
+```python
+from finai_snowflake_transform import (
+    load_config,
+    transform_pandas_on_snowflake,
+    transform_snowpark,
+)
+
+load_config("defaults.yaml")
+# {'scale': 2.0, 'offset': 1.0, 'null_fill': 0.0}
+
+# pandas on Snowflake (also works with plain pandas)
+import modin.pandas as pd
+import snowflake.snowpark.modin.plugin  # noqa: F401
+
+out = transform_pandas_on_snowflake(pd.read_snowflake("MY_INPUT"), "defaults.yaml")
+
+# Snowpark
+out = transform_snowpark(session.table("MY_INPUT"), "alternate.yaml")
+```
+
+Invalid configuration names, non-mapping YAML, missing parameters, booleans and
+non-finite numbers all raise immediately with a message naming the config file.
+
+## License
+
+MIT

finai_snowflake_transform-0.1.0/README.md

@@ -0,0 +1,59 @@
+# finai-snowflake-transform
+
+A small public package used to verify that a PyPI release, including YAML files
+bundled inside it, can be installed and executed inside Snowflake through both
+Snowpark and pandas on Snowflake.
+
+## Transformation
+
+Parameters are read from a YAML file bundled in the package, so nothing depends
+on the working directory:
+
+```text
+TRANSFORMED_VALUE = fill_null(VALUE, null_fill) * scale + offset
+```
+
+| Config | scale | offset | null_fill |
+| --- | --- | --- | --- |
+| `defaults.yaml` | 2.0 | 1.0 | 0.0 |
+| `alternate.yaml` | 3.0 | -1.0 | 2.0 |
+
+## Install
+
+```bash
+pip install finai-snowflake-transform
+# with the Snowflake runtime extra
+pip install "finai-snowflake-transform[snowflake]"
+```
+
+## Use
+
+`ID` and `VALUE` are preserved and `TRANSFORMED_VALUE` is appended. Arithmetic
+stays native to the engine you pass in; the caller reads and writes tables.
+
+```python
+from finai_snowflake_transform import (
+    load_config,
+    transform_pandas_on_snowflake,
+    transform_snowpark,
+)
+
+load_config("defaults.yaml")
+# {'scale': 2.0, 'offset': 1.0, 'null_fill': 0.0}
+
+# pandas on Snowflake (also works with plain pandas)
+import modin.pandas as pd
+import snowflake.snowpark.modin.plugin  # noqa: F401
+
+out = transform_pandas_on_snowflake(pd.read_snowflake("MY_INPUT"), "defaults.yaml")
+
+# Snowpark
+out = transform_snowpark(session.table("MY_INPUT"), "alternate.yaml")
+```
+
+Invalid configuration names, non-mapping YAML, missing parameters, booleans and
+non-finite numbers all raise immediately with a message naming the config file.
+
+## License
+
+MIT

finai_snowflake_transform-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "finai-snowflake-transform"
+version = "0.1.0"
+description = "YAML-driven demo transformation for Snowpark and pandas on Snowflake"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "finai-data-analytics" }]
+keywords = ["snowflake", "snowpark", "pandas", "transform"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pandas>=2.0",
+    "numpy>=1.24",
+    "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+snowflake = ["snowflake-snowpark-python[modin]>=1.55.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/finai_snowflake_transform"]
+
+[tool.hatch.build.targets.sdist]
+# Explicit allowlist so nothing from the surrounding repository can leak in.
+include = [
+    "src/finai_snowflake_transform",
+    "tests",
+    "README.md",
+    "pyproject.toml",
+]
+# Hatchling otherwise pulls the surrounding repository's ignore file into the sdist.
+exclude = [".gitignore"]

finai_snowflake_transform-0.1.0/src/finai_snowflake_transform/__init__.py

@@ -0,0 +1,24 @@
+"""Public API for ``finai-snowflake-transform``."""
+
+from finai_snowflake_transform.transforms import (
+    DEFAULT_CONFIG,
+    OUTPUT_COLUMN,
+    REQUIRED_KEYS,
+    VALUE_COLUMN,
+    load_config,
+    transform_pandas_on_snowflake,
+    transform_snowpark,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_CONFIG",
+    "OUTPUT_COLUMN",
+    "REQUIRED_KEYS",
+    "VALUE_COLUMN",
+    "__version__",
+    "load_config",
+    "transform_pandas_on_snowflake",
+    "transform_snowpark",
+]

finai_snowflake_transform-0.1.0/src/finai_snowflake_transform/alternate.yaml

@@ -0,0 +1,5 @@
+# Alternate transformation parameters, used to prove the YAML drives the result.
+# TRANSFORMED_VALUE = fill_null(VALUE, null_fill) * scale + offset
+scale: 3.0
+offset: -1.0
+null_fill: 2.0

finai_snowflake_transform-0.1.0/src/finai_snowflake_transform/defaults.yaml

@@ -0,0 +1,5 @@
+# Default transformation parameters.
+# TRANSFORMED_VALUE = fill_null(VALUE, null_fill) * scale + offset
+scale: 2.0
+offset: 1.0
+null_fill: 0.0

finai_snowflake_transform-0.1.0/src/finai_snowflake_transform/transforms.py

@@ -0,0 +1,98 @@
+"""YAML-driven transformations for Snowpark and pandas on Snowflake.
+
+The transformation is ``TRANSFORMED_VALUE = fill_null(VALUE, null_fill) * scale
++ offset``. Parameters come from a YAML file bundled inside this package, so the
+same code works locally, in a stored procedure, or in a UDF without depending on
+the working directory.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from typing import Any
+
+import numpy as np
+import yaml
+
+__all__ = [
+    "DEFAULT_CONFIG",
+    "OUTPUT_COLUMN",
+    "REQUIRED_KEYS",
+    "VALUE_COLUMN",
+    "load_config",
+    "transform_pandas_on_snowflake",
+    "transform_snowpark",
+]
+
+DEFAULT_CONFIG = "defaults.yaml"
+REQUIRED_KEYS = ("scale", "offset", "null_fill")
+VALUE_COLUMN = "VALUE"
+OUTPUT_COLUMN = "TRANSFORMED_VALUE"
+
+
+def _read_resource(config_name: str) -> str:
+    """Read a YAML file bundled in this package, rejecting unsafe names."""
+    if not isinstance(config_name, str) or not config_name.strip():
+        raise ValueError("config_name must be a non-empty string")
+    if config_name != config_name.strip():
+        raise ValueError(f"config_name must not be padded with whitespace: {config_name!r}")
+    if config_name.startswith(".") or "/" in config_name or "\\" in config_name:
+        raise ValueError(f"config_name must be a bare bundled file name: {config_name!r}")
+    if not config_name.endswith((".yaml", ".yml")):
+        raise ValueError(f"config_name must end with .yaml or .yml: {config_name!r}")
+
+    resource = resources.files(__package__).joinpath(config_name)
+    if not resource.is_file():
+        raise FileNotFoundError(f"bundled config not found in {__package__}: {config_name!r}")
+    return resource.read_text(encoding="utf-8")
+
+
+def _validate_config(raw: Any, source: str = "<mapping>") -> dict[str, float]:
+    """Validate a parsed config mapping and coerce its values to finite floats."""
+    if not isinstance(raw, dict):
+        raise ValueError(f"{source}: config must be a YAML mapping, got {type(raw).__name__}")
+
+    missing = [key for key in REQUIRED_KEYS if key not in raw]
+    if missing:
+        raise ValueError(f"{source}: missing required parameter(s): {', '.join(missing)}")
+
+    config: dict[str, float] = {}
+    for key in REQUIRED_KEYS:
+        value = raw[key]
+        # bool is a subclass of int, so it has to be rejected before the numeric check.
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise TypeError(f"{source}: {key} must be a real number, got {type(value).__name__}")
+        number = float(value)
+        if not np.isfinite(number):
+            raise ValueError(f"{source}: {key} must be finite, got {value!r}")
+        config[key] = number
+    return config
+
+
+def load_config(config_name: str = DEFAULT_CONFIG) -> dict[str, float]:
+    """Load and validate a bundled YAML config into ``{scale, offset, null_fill}``."""
+    text = _read_resource(config_name)
+    try:
+        raw = yaml.safe_load(text)
+    except yaml.YAMLError as exc:  # pragma: no cover - bundled configs are valid
+        raise ValueError(f"{config_name}: invalid YAML: {exc}") from exc
+    return _validate_config(raw, source=config_name)
+
+
+def transform_pandas_on_snowflake(df, config_name: str = DEFAULT_CONFIG):
+    """Add ``TRANSFORMED_VALUE`` to a Snowpark pandas (or pandas) DataFrame."""
+    config = load_config(config_name)
+    transformed = df[VALUE_COLUMN].fillna(config["null_fill"]) * config["scale"] + config["offset"]
+    return df.assign(**{OUTPUT_COLUMN: transformed})
+
+
+def transform_snowpark(df, config_name: str = DEFAULT_CONFIG):
+    """Add ``TRANSFORMED_VALUE`` to a Snowpark DataFrame using Snowpark expressions."""
+    from snowflake.snowpark.functions import coalesce, col, lit
+
+    config = load_config(config_name)
+    return df.with_column(
+        OUTPUT_COLUMN,
+        coalesce(col(VALUE_COLUMN), lit(config["null_fill"])) * lit(config["scale"])
+        + lit(config["offset"]),
+    )

finai_snowflake_transform-0.1.0/tests/test_transform.py

@@ -0,0 +1,104 @@
+"""Local checks for the bundled-YAML transformation.
+
+Expected values are written out by hand from the MVP spec, not recomputed with
+the package, so a change in the transformation is caught rather than mirrored.
+"""
+
+from __future__ import annotations
+
+import math
+
+import pandas as pd
+import pytest
+
+from finai_snowflake_transform import (
+    __version__,
+    load_config,
+    transform_pandas_on_snowflake,
+)
+from finai_snowflake_transform.transforms import _validate_config
+
+IDS = [1, 2, 3, 4]
+VALUES = [-2.0, 0.0, 3.5, None]
+EXPECTED = {
+    "defaults.yaml": [-3.0, 1.0, 8.0, 1.0],
+    "alternate.yaml": [-7.0, -1.0, 9.5, 5.0],
+}
+
+
+def make_input() -> pd.DataFrame:
+    return pd.DataFrame({"ID": IDS, "VALUE": VALUES})
+
+
+def test_version() -> None:
+    assert __version__ == "0.1.0"
+
+
+def test_bundled_configs_load_from_the_installed_package() -> None:
+    assert load_config("defaults.yaml") == {"scale": 2.0, "offset": 1.0, "null_fill": 0.0}
+    assert load_config("alternate.yaml") == {"scale": 3.0, "offset": -1.0, "null_fill": 2.0}
+    assert load_config() == load_config("defaults.yaml")
+
+
+@pytest.mark.parametrize("config_name", sorted(EXPECTED))
+def test_transform_matches_independent_expectations(config_name: str) -> None:
+    result = transform_pandas_on_snowflake(make_input(), config_name)
+
+    assert list(result.columns) == ["ID", "VALUE", "TRANSFORMED_VALUE"]
+    assert list(result["ID"]) == IDS
+    assert result["VALUE"].isna().tolist() == [False, False, False, True]
+    assert result["TRANSFORMED_VALUE"].tolist() == pytest.approx(EXPECTED[config_name])
+
+
+def test_input_frame_is_not_mutated() -> None:
+    df = make_input()
+    transform_pandas_on_snowflake(df)
+    assert list(df.columns) == ["ID", "VALUE"]
+
+
+@pytest.mark.parametrize(
+    "config_name",
+    ["missing.yaml", "defaults.json", "", "  ", "../defaults.yaml", "sub/defaults.yaml", ".defaults.yaml", None, 3],
+)
+def test_invalid_config_names_are_rejected(config_name: object) -> None:
+    with pytest.raises((ValueError, FileNotFoundError)):
+        load_config(config_name)  # type: ignore[arg-type]
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        None,
+        [1, 2, 3],
+        "scale: 2.0",
+        {"scale": 2.0, "offset": 1.0},
+        {"scale": True, "offset": 1.0, "null_fill": 0.0},
+        {"scale": "2.0", "offset": 1.0, "null_fill": 0.0},
+        {"scale": None, "offset": 1.0, "null_fill": 0.0},
+        {"scale": math.nan, "offset": 1.0, "null_fill": 0.0},
+        {"scale": math.inf, "offset": 1.0, "null_fill": 0.0},
+    ],
+)
+def test_invalid_config_payloads_are_rejected(raw: object) -> None:
+    with pytest.raises((ValueError, TypeError)):
+        _validate_config(raw, source="unit")
+
+
+def demo() -> None:
+    """Runnable self-check: ``python tests/test_transform.py``."""
+    for config_name, expected in EXPECTED.items():
+        got = transform_pandas_on_snowflake(make_input(), config_name)["TRANSFORMED_VALUE"].tolist()
+        assert all(math.isclose(a, b) for a, b in zip(got, expected, strict=True)), (config_name, got)
+        print(f"{config_name}: {got} == {expected}")
+    for bad in ("missing.yaml", "../defaults.yaml"):
+        try:
+            load_config(bad)
+        except (ValueError, FileNotFoundError) as exc:
+            print(f"rejected {bad!r}: {exc}")
+        else:  # pragma: no cover
+            raise AssertionError(f"{bad!r} should have been rejected")
+    print("OK")
+
+
+if __name__ == "__main__":
+    demo()