ltc-code 0.1.0__py3-none-any.whl

ltc_code/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from ltc-code!")

ltc_code/polars_dates.py

@@ -0,0 +1,167 @@
+"""Utilities for parsing mixed-format string dates with Polars.
+
+`parse_date_column(...)` returns expressions that can be used directly inside
+`with_columns(*...)`.
+
+`apply_parse_date_column(...)` is a small eager wrapper around those
+expressions that prints diagnostics and conditionally keeps or drops the
+parse-failure flag column.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+import polars as pl
+
+
+DEFAULT_DATE_FORMATS: tuple[str, ...] = (
+    "%Y-%m-%d",
+    "%Y/%m/%d",
+    "%m/%d/%Y",
+    "%m-%d-%Y",
+    "%b %d, %Y",
+    "%d-%b-%Y",
+)
+
+
+def _coalesced_date_expr(column: str, formats: Sequence[str]) -> pl.Expr:
+    """Build one Date expression that tries each format in order."""
+
+    source = pl.col(column).cast(pl.String)
+    return pl.coalesce(
+        [
+            source.str.strptime(pl.Date, format=fmt, strict=False)
+            for fmt in formats
+        ]
+    )
+
+
+def _collect_if_lazy(frame: pl.DataFrame | pl.LazyFrame) -> pl.DataFrame:
+    """Collect a LazyFrame, or pass through an eager DataFrame unchanged."""
+
+    if isinstance(frame, pl.LazyFrame):
+        return frame.collect()
+    return frame
+
+
+def parse_date_column(
+    column: str,
+    *,
+    output_column: str | None = None,
+    formats: Sequence[str] = DEFAULT_DATE_FORMATS,
+    flag_column: str | None = None,
+) -> list[pl.Expr]:
+    """Return Polars expressions for mixed-format date parsing.
+
+    This helper is designed for direct use inside `with_columns(*...)`.
+    It always returns:
+    1. the parsed `Date` column
+    2. an integer flag column where `1` means the parsed date is null
+
+    The richer behavior requested by the user (printing diagnostics and
+    dropping the flag when only null inputs failed) lives in
+    `apply_parse_date_column(...)`, which needs access to the full DataFrame.
+    """
+
+    output_column = output_column or column
+    flag_column = flag_column or f"{output_column}_parse_failed"
+
+    parsed_expr = _coalesced_date_expr(column, formats)
+
+    return [
+        parsed_expr.alias(output_column),
+        parsed_expr.is_null().cast(pl.Int8).alias(flag_column),
+    ]
+
+
+def apply_parse_date_column(
+    df: pl.DataFrame | pl.LazyFrame,
+    column: str,
+    *,
+    output_column: str | None = None,
+    formats: Sequence[str] = DEFAULT_DATE_FORMATS,
+    flag_column: str | None = None,
+    sample_size: int = 5,
+) -> pl.DataFrame | pl.LazyFrame:
+    """Parse one date column on an eager or lazy frame.
+
+    The return type matches the input type. Diagnostics are printed in either
+    case. For lazy inputs, the function collects only the small summary queries
+    needed for reporting and deciding whether to keep the failure flag column.
+    """
+
+    output_column = output_column or column
+    flag_column = flag_column or f"{output_column}_parse_failed"
+
+    temp_raw_column = f"__{output_column}_raw_input"
+    temp_flag_column = f"__{output_column}_parse_failed_tmp"
+    temp_null_column = f"__{output_column}_input_was_null_tmp"
+
+    working = df.with_columns(
+        pl.col(column).cast(pl.String).alias(temp_raw_column),
+        *parse_date_column(
+            column,
+            output_column=output_column,
+            formats=formats,
+            flag_column=temp_flag_column,
+        ),
+        pl.col(column).is_null().alias(temp_null_column),
+    )
+
+    summary = _collect_if_lazy(
+        working.select(
+        pl.len().alias("n_rows"),
+        pl.col(output_column).is_not_null().sum().alias("n_parsed_successfully"),
+        pl.col(temp_null_column).sum().alias("n_failed_because_null"),
+        (
+            (pl.col(temp_flag_column) == 1) & (~pl.col(temp_null_column))
+        ).sum().alias("n_failed_because_invalid_non_null"),
+        )
+    ).row(0, named=True)
+
+    n_rows = int(summary["n_rows"])
+    n_parsed_successfully = int(summary["n_parsed_successfully"])
+    n_failed_because_null = int(summary["n_failed_because_null"])
+    n_failed_because_invalid_non_null = int(
+        summary["n_failed_because_invalid_non_null"]
+    )
+
+    print(
+        f"[parse_date_column] '{column}' -> '{output_column}' "
+        f"across {n_rows} rows"
+    )
+    print(f"  parsed successfully: {n_parsed_successfully}")
+    print(f"  failed because original value was null: {n_failed_because_null}")
+    print(
+        "  failed because original value was a non-null invalid date string: "
+        f"{n_failed_because_invalid_non_null}"
+    )
+
+    if n_failed_because_invalid_non_null > 0:
+        invalid_values = _collect_if_lazy(
+            working.filter(
+                (pl.col(temp_flag_column) == 1) & pl.col(temp_raw_column).is_not_null()
+            ).select(pl.col(temp_raw_column).alias("invalid_value"))
+        )
+
+        n_unique_invalid = int(
+            invalid_values.select(pl.col("invalid_value").n_unique()).item()
+        )
+        invalid_examples = (
+            invalid_values.unique()
+            .sort("invalid_value")
+            .head(sample_size)
+            .get_column("invalid_value")
+            .to_list()
+        )
+
+        print(f"  unique invalid values: {n_unique_invalid}")
+        print(f"  example invalid values: {invalid_examples}")
+
+        return working.with_columns(
+            pl.col(temp_flag_column).cast(pl.Int8).alias(flag_column)
+        ).drop([temp_raw_column, temp_flag_column, temp_null_column])
+
+    print("  no non-null invalid strings detected, so the failure flag was dropped")
+    return working.drop([temp_raw_column, temp_flag_column, temp_null_column])

ltc_code-0.1.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.3
+Name: ltc-code
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+

ltc_code-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+ltc_code/__init__.py,sha256=oVeqiMp3EZkL8L2aIdNzn2HjrmB8D06qj46J1b5VjRI,54
+ltc_code/polars_dates.py,sha256=5S6R4fRBig0SdtZ6X2x7NvJEAfS6akVH0pA_Ryd7Z4U,5487
+ltc_code-0.1.0.dist-info/WHEEL,sha256=f5fWSvWsg5Knq5GWa6t1nJIug0Tqo69GqAWD_9LbBKw,81
+ltc_code-0.1.0.dist-info/entry_points.txt,sha256=qgoFyxqsnABOyOi-uLHQAfOk6CwMndlwAhTpbe68Rpw,44
+ltc_code-0.1.0.dist-info/METADATA,sha256=Evsq-aF0XNBzznwltDT7cFpKthYu5uIs8qFtksIUJyo,152
+ltc_code-0.1.0.dist-info/RECORD,,

ltc_code-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.16
+Root-Is-Purelib: true
+Tag: py3-none-any

ltc_code-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ltc-code = ltc_code:main
+