pinky-core 0.1.0.dev3__tar.gz → 0.1.0.dev4__tar.gz

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/.github/workflows/ci.yml

@@ -33,7 +33,10 @@ jobs:
         uses: j178/prek-action@v2
 
       - name: Install dependencies
-        run: pip install -e ".[validate,address,dev]"
+        # All optional extras, not just validate/address/dev — omitting xml/schedule/lint
+        # silently skips their test files at collection time (pytest.importorskip on the
+        # missing package), deflating the coverage number without ever failing CI.
+        run: pip install -e ".[validate,address,schedule,xml,lint,dev]"
 
       - name: Tests
         run: pytest

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pinky-core
-Version: 0.1.0.dev3
+Version: 0.1.0.dev4
 Summary: Shared Python utilities for Snowflake development
 Project-URL: Homepage, https://github.com/pinky-and-co/pinky-core
 Project-URL: Repository, https://github.com/pinky-and-co/pinky-core
@@ -198,6 +198,7 @@ pinky-core/
 │   ├── test_fmt.py
 │   ├── test_html.py
 │   ├── test_lint.py
+│   ├── test_public_api.py
 │   ├── test_schedule.py
 │   ├── test_security.py
 │   ├── test_sql.py

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/README.md

@@ -125,6 +125,7 @@ pinky-core/
 │   ├── test_fmt.py
 │   ├── test_html.py
 │   ├── test_lint.py
+│   ├── test_public_api.py
 │   ├── test_schedule.py
 │   ├── test_security.py
 │   ├── test_sql.py

pinky_core-0.1.0.dev4/docs/explanation/2-features.md

@@ -0,0 +1,44 @@
+---
+title: Features
+---
+# Features — pinky-core
+*Update date : 2026-07-12 10:37*
+
+Feature list ordered by priority. `stable` = in production. `planned` = not yet built, order = priority.
+
+---
+
+## Stable
+
+| Module | Description | Status |
+|--------|-------------|--------|
+| `fmt.py` | Formatters: dates/periods, numbers (compact/duration/fraction/trend/stars/boolean), string case (UPPER_SNAKE/camelCase/slug), text/city normalization, ISO3→ISO2, header dedup, FR/AFNOR address parsing | stable |
+| `validate.py` | Input validation: SIRET/SIREN, IBAN/BIC, TVA EU, NIR, email, phone | stable |
+| `security.py` | Filepath and SQL-identifier sanitisation — guards against injection in dynamically built DDL | stable |
+| `sql.py` | SQL parsing helpers powered by sqlglot: statement kind, table-ref extraction, query resolution, statement splitting | stable |
+| `html.py` | HTML templating engine — emails, reports, mini-sites, Outlook-safe | stable |
+| `xml.py` | XPath helpers, namespace-aware parsing, safe attribute extraction | stable |
+| `files.py` | S3/MFT filename pattern normalisation — `detect_file_pattern`, `FileDetection` | stable |
+| `schedule.py` | French public holidays, business-day helpers, cron human-readable formatting, Airflow-timetable predicates (month/week/fiscal-quarter, eve-of-holiday) | stable |
+| `lint.py` | Optional lint/format delegation (sqlfluff/ruff/yamllint/detect-secrets) — consumed by pinky-provider for the secret-scan deploy gate and SQL pre-flight | stable |
+| `warnings.py` | `PinkyDeprecationWarning` — deprecated pinky APIs and UDFs. No consumer wired yet (destined for pinky-provider's registry `status: deprecated`) | stable |
+| `finance/fec.py` | FEC parser (Fichier des Écritures Comptables, arrêté A47 A-1) — `parse_fec`/`check_fec_balance`, positional column reading, dual format tolerance (delimiter/date/decimal/amount schema), mojibake repair | stable |
+
+---
+
+## Planned
+
+Ordered by priority — closest to implementation first.
+
+### finance/ — extend beyond FEC
+
+Same lineage as `finance/fec.py` (real FR accounting/payroll file formats) — no current consumer card, kept for the likely follow-on employer-migration need.
+
+- `finance/dsn.py` — Déclaration Sociale Nominative parser (INSEE/Net-Entreprises)
+- `finance/sepa.py` — SEPA pain.001 / pain.008 XML builders (credit transfers, direct debits)
+- `finance/ofx.py` — bank statement parsers (OFX/QFX for reconciliation)
+
+### finance/ — FEC validator as CLI
+
+`python -m pinky_core.finance.fec validate file.txt` — thin CLI wrapper around the already-built
+`parse_fec`/`check_fec_balance`. Gated on `pinky-tools` CLI integration (chantier 0002), not speculative.

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/docs/reference/generated/coverage_badge.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 50.56%"><title>coverage: 50.56%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#ea7233"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">50.56%</text><text x="865" y="150" fill-opacity=".3" textLength="430">50.56%</text></g><text x="865" y="140" textLength="430">50.56%</text></g></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 84.34%"><title>coverage: 84.34%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#67ac09"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">84.34%</text><text x="865" y="150" fill-opacity=".3" textLength="430">84.34%</text></g><text x="865" y="140" textLength="430">84.34%</text></g></g></svg>

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/docs/reference/generated/interrogate_badge.svg

@@ -1,10 +1,10 @@
 <svg width="140" height="20" viewBox="0 0 140 20" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
-    <title>interrogate: 65.9%</title>
+    <title>interrogate: 100%</title>
     <g transform="matrix(1,0,0,1,22,0)">
         <g id="backgrounds" transform="matrix(1.32789,0,0,1,-22.3892,0)">
             <rect x="0" y="0" width="71" height="20" style="fill:rgb(85,85,85);"/>
         </g>
-        <rect x="71" y="0" width="47" height="20" data-interrogate="color" style="fill:#dfb317"/>
+        <rect x="71" y="0" width="47" height="20" data-interrogate="color" style="fill:#4c1"/>
         <g transform="matrix(1.19746,0,0,1,-22.3744,-4.85723e-16)">
             <rect x="0" y="0" width="118" height="20" style="fill:url(#_Linear1);"/>
         </g>
@@ -12,8 +12,8 @@
     <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110">
         <text x="590" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="610">interrogate</text>
         <text x="590" y="140" transform="scale(.1)" textLength="610">interrogate</text>
-        <text x="1160" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370" data-interrogate="result">65.9%</text>
-        <text x="1160" y="140" transform="scale(.1)" textLength="370" data-interrogate="result">65.9%</text>
+        <text x="1160" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="330" data-interrogate="result">100%</text>
+        <text x="1160" y="140" transform="scale(.1)" textLength="330" data-interrogate="result">100%</text>
     </g>
     <g id="logo-shadow" serif:id="logo shadow" transform="matrix(0.854876,0,0,0.854876,-6.73514,1.732)">
         <g transform="matrix(0.299012,0,0,0.299012,9.70229,-6.68582)">

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pinky-core"
-version = "0.1.0.dev3"
+version = "0.1.0.dev4"
 description = "Shared Python utilities for Snowflake development"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -105,13 +105,21 @@ follow_imports  = "skip"
 
 # ── Interrogate ───────────────────────────────────────────────────────────────
 [tool.interrogate]
-ignore-init-method = true
-ignore-magic       = true
-ignore-module      = true
-ignore-private     = true
-fail-under         = 60
-paths              = ["src/"]
-generate-badge     = "docs/reference/generated/"
+ignore-init-method  = true
+ignore-magic        = true
+ignore-module       = true
+ignore-private      = true
+# --ignore-private only covers dunder-prefixed (__foo) names; this codebase's actual
+# private-helper convention is single-underscore (_foo) — that's --ignore-semiprivate.
+# Without it, every internal helper (xml.py's _parse_path, fmt.py's _parse_fr, …) counted
+# against docstring coverage, deflating the real number from ~98% to ~66%.
+ignore-semiprivate  = true
+# Real coverage is ~97.6% now that ignore-semiprivate is set (was capped at 60 to not
+# block interrogate's initial rollout). Threshold left with headroom below current, not
+# pinned to 97.6, so incidental drift doesn't fail CI on unrelated PRs.
+fail-under          = 95
+paths               = ["src/"]
+generate-badge      = "docs/reference/generated/"
 
 # ── Darglint ─────────────────────────────────────────────────────────────────
 [tool.darglint]

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/scripts/hooks/generate-docs

@@ -14,6 +14,15 @@
 #      manual `setup.py --all` — gating on staged src/ files missed exactly that edit.
 #   2. SVG quality badges (interrogate/coverage/noqa/hooks) — unchanged from check-docs-up-to-date,
 #      still gated on staged src/ or .pre-commit-config.yaml (more expensive: coverage xml + genbadge).
+#
+# Coverage badge reliability fix (2026-07-12): the old version trusted a pre-existing
+# .cache/coverage/.coverage file — silently stale for a month on pinky-core (nobody's commit
+# happened to run a full, correctly-instrumented `pytest` right before hitting this hook) with
+# no failure, no warning, nothing. It now runs the test suite itself, every time, and prints a
+# visible warning instead of silently no-op'ing when pytest or genbadge aren't available. Uses
+# `coverage run -m pytest --no-cov` (not pytest-cov's own instrumentation) — editable-install
+# path setups (multiple repos' src/ on sys.path at once) can make pytest-cov silently measure
+# nothing ("module-not-measured") with no visible error; wrapping externally sidesteps that.
 # =============================================================================
 
 # 1. Repo-local docs (README sections + docs/index.md) — always, idempotent.
@@ -35,10 +44,18 @@ fi
 if [ "$SRC_STAGED" -gt 0 ]; then
     git add docs/reference/generated/interrogate_badge.svg 2>/dev/null
 
-    if [ -f ".cache/coverage/.coverage" ] && command -v genbadge > /dev/null 2>&1; then
-        coverage xml --data-file=.cache/coverage/.coverage -o .cache/coverage/coverage.xml > /dev/null 2>&1
-        genbadge coverage -i .cache/coverage/coverage.xml -o docs/reference/generated/coverage_badge.svg > /dev/null 2>&1
-        git add docs/reference/generated/coverage_badge.svg 2>/dev/null
+    mkdir -p .cache/coverage
+    COV_LOG=$(mktemp)
+    if python -m coverage run -m pytest -q --no-cov > "$COV_LOG" 2>&1; then
+        python -m coverage xml -o .cache/coverage/coverage.xml > /dev/null 2>&1
+        if command -v genbadge > /dev/null 2>&1; then
+            genbadge coverage -i .cache/coverage/coverage.xml -o docs/reference/generated/coverage_badge.svg > /dev/null 2>&1
+            git add docs/reference/generated/coverage_badge.svg 2>/dev/null
+        else
+            echo "⚠ coverage_badge.svg not regenerated: 'genbadge' not installed — pip install -e '.[dev]'" >&2
+        fi
+    else
+        echo "⚠ coverage_badge.svg not regenerated: test run failed, see $COV_LOG" >&2
     fi
 
     python scripts/hooks/generate_ci_badges.py --noqa > /dev/null 2>&1

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/src/pinky_core/__init__.py

@@ -9,6 +9,8 @@ files     File pattern normalization for S3 and MFT path analysis.
 finance   French accounting file formats (FEC parser).
 fmt       Pure formatting helpers (text, dates, numbers, FR addresses).
 html      HTML templating engine (emails, reports, mini-sites) — Outlook-safe.
+lint      Delegated tooling for pinky-provider's SQL/secret pre-flight — accessed
+          via ``pinky_core.lint`` directly, never top-level.
 schedule  Business-day calendar (FR) and cron utilities for SPs and DAGs.
 security  Path and identifier sanitisation for safe dynamic SQL.
 sql       SQL parsing helpers powered by sqlglot (Snowflake dialect).
@@ -46,6 +48,7 @@ from pinky_core.finance.fec import (
 from pinky_core.fmt import (
     AddressComponents,
     AfnorAddress,
+    NumType,
     deduplicate_headers,
     format_boolean,
     format_date,
@@ -61,6 +64,7 @@ from pinky_core.fmt import (
     normalize_text,
     parse_address,
     period_to_date,
+    slugify,
     to_camel_case,
     to_upper_snake_case,
 )
@@ -79,10 +83,18 @@ from pinky_core.html import (
 from pinky_core.schedule import (
     business_days_between,
     cron_to_human,
+    days_until_end_of_month,
+    first_business_day_of_month,
+    fiscal_quarter,
     is_business_day,
+    is_eve_of_holiday,
+    is_even_week,
     is_in_schedule,
+    is_odd_week,
+    last_business_day_of_month,
     next_business_day,
     next_schedule,
+    nth_business_day_of_month,
     public_holidays_fr,
 )
 
@@ -94,6 +106,7 @@ from pinky_core.security import (
 
 # sql — pure SQL parsing, always available
 from pinky_core.sql import (
+    extract_table_refs,
     resolve_query,
     split_sql_statements,
     statement_kind,
@@ -137,6 +150,7 @@ __all__ = [
     # fmt
     "AddressComponents",
     "AfnorAddress",
+    "NumType",
     "deduplicate_headers",
     "iso3_to_iso2",
     "normalize_city_fr",
@@ -152,6 +166,7 @@ __all__ = [
     "format_trend",
     "parse_address",
     "period_to_date",
+    "slugify",
     "to_camel_case",
     "to_upper_snake_case",
     # html
@@ -166,6 +181,14 @@ __all__ = [
     "is_business_day",
     "next_business_day",
     "business_days_between",
+    "is_eve_of_holiday",
+    "last_business_day_of_month",
+    "first_business_day_of_month",
+    "nth_business_day_of_month",
+    "is_even_week",
+    "is_odd_week",
+    "fiscal_quarter",
+    "days_until_end_of_month",
     "cron_to_human",
     "next_schedule",
     "is_in_schedule",
@@ -173,6 +196,7 @@ __all__ = [
     "safe_filepath",
     "validate_identifier",
     # sql
+    "extract_table_refs",
     "resolve_query",
     "split_sql_statements",
     "statement_kind",

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/src/pinky_core/finance/fec.py

@@ -90,6 +90,8 @@ class FecAmountSchema(StrEnum):
 
 
 class FecSens(StrEnum):
+    """Debit/credit sign, as used by the ``Sens`` column of the ``Montant``/``Sens`` amount schema."""
+
     DEBIT = "D"
     CREDIT = "C"
 
@@ -186,6 +188,13 @@ class FecParseResult(BaseModel):
 
     @property
     def is_valid(self) -> bool:
+        """Whether every row parsed without error.
+
+        Does not check debit/credit balance — see :func:`check_fec_balance` for that.
+
+        Returns:
+            True if ``errors`` is empty.
+        """
         return not self.errors
 
 

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/src/pinky_core/fmt.py

@@ -13,6 +13,7 @@ import math
 import re
 from dataclasses import dataclass
 from datetime import date, datetime
+from typing import Literal
 
 # =============================================================================
 # Dates
@@ -99,7 +100,10 @@ def period_to_date(period: str) -> date:
 # =============================================================================
 
 
-def format_number(num: float | int | None, num_type: str = "count") -> str:
+NumType = Literal["count", "amount", "percent", "percent_decimal"]
+
+
+def format_number(num: float | int | None, num_type: NumType = "count") -> str:
     """Format a number using compact notation (K, M).
 
     Args:
@@ -297,6 +301,29 @@ def to_upper_snake_case(name: str) -> str:
     return name.strip("_").upper()
 
 
+def slugify(text: str) -> str:
+    """Convert a string to a URL-safe slug (lowercase, ASCII, hyphens).
+
+    Uses ``unidecode`` to transliterate accented and non-ASCII characters,
+    then collapses any run of non-alphanumeric characters to a single ``-``.
+
+    Examples:
+        "Résidence de l'Étoile" -> "residence-de-l-etoile"
+        "NAF 2025\\nsous-classes" -> "naf-2025-sous-classes"
+
+    Args:
+        text: String to convert.
+
+    Returns:
+        Lowercase ASCII slug with hyphens, no leading/trailing hyphen.
+    """
+    from unidecode import unidecode
+
+    text = unidecode(text)
+    text = re.sub(r"[^a-zA-Z0-9]+", "-", text)
+    return text.strip("-").lower()
+
+
 def to_camel_case(name: str) -> str:
     """Convert UPPER_SNAKE_CASE or snake_case to camelCase.
 

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/src/pinky_core/security.py

@@ -13,16 +13,17 @@ import re
 
 
 def safe_filepath(filepath: str) -> str:
-    """Validate and sanitize a file path for use in a Snowflake REMOVE statement.
+    """Validate a file path for use in a Snowflake REMOVE statement.
 
-    Rejects paths containing special characters or ``..`` segments, and escapes
-    single quotes to prevent SQL injection in dynamically built DDL.
+    Rejects paths containing special characters (including single quotes) or
+    ``..`` segments to prevent SQL injection and path traversal in dynamically
+    built DDL.
 
     Args:
         filepath: Relative path to validate (e.g. ``"folder/file.csv"``).
 
     Returns:
-        Sanitized path with single quotes doubled.
+        The unchanged path if valid.
 
     Raises:
         ValueError: If the path contains disallowed characters or ``..``.

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/src/pinky_core/sql.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 import re
 
 import sqlglot
-from sqlglot import ErrorLevel
+from sqlglot import ErrorLevel, exp
 
 
 def statement_kind(statement: str) -> str:
@@ -93,7 +93,53 @@ def resolve_query(template: str, refs: dict[str, str]) -> str:
     for key, value in refs.items():
         if not _SAFE_REF_PATTERN.match(value):
             raise ValueError(f"Unsafe table reference for {{{key}}}: {value!r}")
-    return template.format(**refs)
+    try:
+        return template.format(**refs)
+    except KeyError as e:
+        raise ValueError(f"Template placeholder {e} has no matching key in refs") from e
+
+
+def extract_table_refs(query: str) -> list[str]:
+    """Extract fully-qualified table references from a SQL query.
+
+    Motivation: a View/Dynamic Table resource's body (``AS <query>`` or ``REFRESH USING (<dml>)``)
+    implicitly depends on every table it reads from — this walks the AST to recover that dependency
+    set instead of asking the manifest author to declare it by hand.
+
+    Uses sqlglot (Snowflake dialect). Excludes CTE aliases (``WITH x AS (...)`` — a local name, not a
+    real table) and any bare, unqualified identifier: a legitimate cross-resource reference is always
+    at least ``SCHEMA.TABLE`` (pinky-provider's FQN convention, ``DATABASE.SCHEMA.NAME``), so a bare
+    name is either a CTE already filtered out, or a DML self-reference placeholder (e.g. ``SELF`` in a
+    dynamic table's ``REFRESH USING (INSERT INTO SELF ...)``) — never a real dependency.
+
+    Args:
+        query: A single SQL statement without trailing ``;``.
+
+    Returns:
+        Sorted, deduplicated list of fully-qualified table references (``DB.SCHEMA.TABLE`` or
+        ``SCHEMA.TABLE``) — a dependency set, not a trace of the query, so it sorts rather than
+        preserving AST-traversal order (which does not match source order). Unparseable or empty
+        input → ``[]``.
+    """
+    try:
+        tree = sqlglot.parse_one(
+            query.strip(),
+            dialect="snowflake",
+            error_level=ErrorLevel.IGNORE,
+        )
+    except Exception:
+        return []
+    if tree is None:
+        return []
+
+    cte_names = {cte.alias for cte in tree.find_all(exp.CTE)}
+    refs: set[str] = set()
+    for table in tree.find_all(exp.Table):
+        parts = [p for p in (table.catalog, table.db, table.name) if p]
+        if len(parts) < 2 or parts[-1] in cte_names:
+            continue
+        refs.add(".".join(parts))
+    return sorted(refs)
 
 
 def split_sql_statements(sql: str) -> list[str]:

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/src/pinky_core/xml.py

@@ -48,7 +48,7 @@ from typing import Any
 # Snowflake VARIANT: dict node, text scalar, or None
 Variant = Any
 # XPath step: (kind, tag_or_attr, predicates)
-Step = tuple[str, str | None, list[str]]
+_Step = tuple[str, str | None, list[str]]
 
 # ---------------------------------------------------------------------------
 # Public UDF handler
@@ -115,7 +115,7 @@ def xml_path_str(xml_string: str | None, path: str | None) -> Variant:
         # namespace:: axis tuple, bytearray, memoryview, or other non-element
         # XPath result — not a serialisable scalar
         return None
-    except Exception:
+    except Exception:  # UDF handler: malformed XML / invalid XPath → None, never raise
         return None
 
 
@@ -134,8 +134,8 @@ def _evaluate(node: Variant, path: str) -> Variant:
     return current
 
 
-def _parse_path(path: str) -> list[Step]:
-    result: list[Step] = []
+def _parse_path(path: str) -> list[_Step]:
+    result: list[_Step] = []
     i = 0
     n = len(path)
     while i < n:
@@ -183,7 +183,7 @@ def _read_bracket(path: str, start: int) -> tuple[str, int]:
     return s.strip(), j + 1
 
 
-def _read_step_token(path: str, start: int) -> tuple[Step | None, int]:
+def _read_step_token(path: str, start: int) -> tuple[_Step | None, int]:
     i = start
     n = len(path)
     token = ""
@@ -247,7 +247,7 @@ def _deep_find_all(node: Variant, tag: str) -> list[Variant]:
 # ---------------------------------------------------------------------------
 
 
-def _execute(node: Variant, step: Step) -> Variant:
+def _execute(node: Variant, step: _Step) -> Variant:
     if not isinstance(node, dict):
         return None
     kind, tag, preds = step

{pinky_core-0.1.0.dev3 → pinky_core-0.1.0.dev4}/tests/test_fmt.py

@@ -11,6 +11,7 @@ from pinky_core.fmt import (
     normalize_city_fr,
     normalize_text,
     parse_address,
+    slugify,
     to_camel_case,
     to_upper_snake_case,
 )
@@ -162,6 +163,23 @@ def test_to_camel_case():
     assert to_camel_case("phone") == "phone"
 
 
+# ── slugify ───────────────────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "inp, expected",
+    [
+        ("Résidence de l'Étoile", "residence-de-l-etoile"),
+        ("NAF 2025\nsous-classes", "naf-2025-sous-classes"),
+        ("  Multiple   spaces  ", "multiple-spaces"),
+        ("Ñoño", "nono"),
+        ("already-a-slug", "already-a-slug"),
+    ],
+)
+def test_slugify(inp, expected):
+    assert slugify(inp) == expected
+
+
 # ── deduplicate_headers ───────────────────────────────────────────────────────
 
 

pinky_core-0.1.0.dev4/tests/test_public_api.py

@@ -0,0 +1,69 @@
+"""Regression test: every public name a module defines must be re-exported from
+``pinky_core`` (the top-level package) and listed in ``pinky_core.__all__``.
+
+Guards against the drift caught in the V1 stability pass: `schedule.py`'s 8
+timetable predicates (PR #10) were defined and tested but never wired into the
+package `__init__.py`, so `from pinky_core import is_even_week` raised
+`ImportError` despite the module advertising them. Covers every submodule
+re-exported from `pinky_core/__init__.py`.
+"""
+
+import inspect
+
+import pinky_core
+from pinky_core import (
+    files,
+    fmt,
+    html,
+    schedule,
+    security,
+    sql,
+    validate,
+    warnings,
+    xml,
+)
+from pinky_core.finance import fec
+
+_PACKAGE_MODULES = [
+    fec,
+    files,
+    fmt,
+    html,
+    schedule,
+    security,
+    sql,
+    validate,
+    warnings,
+    xml,
+]
+# NOTE: pinky_core.lint is intentionally excluded — it is delegated tooling for
+# pinky-provider's SQL/secret pre-flight (ADR-0024), not a consumer-facing API.
+# Its symbols are never re-exported at the top level.
+
+
+def _public_names(module: object) -> set[str]:
+    return {
+        name
+        for name, member in vars(module).items()
+        if not name.startswith("_")
+        and inspect.getmodule(member) is module
+        and (inspect.isfunction(member) or inspect.isclass(member))
+    }
+
+
+def test_every_module_public_name_is_reexported_at_package_level() -> None:
+    missing = {}
+    for module in _PACKAGE_MODULES:
+        gap = _public_names(module) - set(pinky_core.__all__)
+        if gap:
+            missing[module.__name__] = sorted(gap)
+    assert not missing, f"names defined but not re-exported from pinky_core: {missing}"
+
+
+def test_every_module_public_name_is_importable_from_package() -> None:
+    for module in _PACKAGE_MODULES:
+        for name in _public_names(module):
+            assert hasattr(pinky_core, name), (
+                f"{module.__name__}.{name} is public but `from pinky_core import "
+                f"{name}` would fail"
+            )

pinky_core-0.1.0.dev4/tests/test_sql.py

@@ -0,0 +1,170 @@
+"""Tests for pinky_core.sql — pure Python, no external deps."""
+
+import pytest
+
+from pinky_core.sql import (
+    extract_table_refs,
+    resolve_query,
+    split_sql_statements,
+    statement_kind,
+)
+
+# ── statement_kind ────────────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    ("stmt", "kind"),
+    [
+        ("SELECT 1", "select"),
+        (
+            "WITH c AS (SELECT 1) SELECT * FROM c",
+            "select",
+        ),  # CTE → top node is the SELECT
+        ("SELECT 1 UNION SELECT 2", "union"),
+        ("INSERT INTO SELF SELECT 1", "insert"),
+        (
+            "MERGE INTO SELF USING s ON a = b WHEN MATCHED THEN UPDATE SET x = 1",
+            "merge",
+        ),
+        ("UPDATE t SET x = 1", "update"),
+        ("DELETE FROM t", "delete"),
+        ("CREATE TABLE t (id INT)", "create"),
+        ("DROP TABLE t", "drop"),
+        ("CALL my_proc()", "command"),
+    ],
+)
+def test_statement_kind(stmt, kind):
+    assert statement_kind(stmt) == kind
+
+
+def test_statement_kind_unknown_on_empty():
+    assert statement_kind("") == "unknown"
+    assert statement_kind("   ") == "unknown"
+
+
+def test_single_statement():
+    assert split_sql_statements("SELECT 1") == ["SELECT 1"]
+
+
+def test_trailing_semicolon():
+    assert split_sql_statements("SELECT 1;") == ["SELECT 1"]
+
+
+def test_multiple_statements():
+    sql = "SELECT 1; SELECT 2; SELECT 3"
+    assert split_sql_statements(sql) == ["SELECT 1", "SELECT 2", "SELECT 3"]
+
+
+def test_strips_inline_comments():
+    sql = "SELECT 1 -- this is a comment\n; SELECT 2"
+    stmts = split_sql_statements(sql)
+    assert len(stmts) == 2
+    assert "comment" not in stmts[0]
+
+
+def test_strips_block_comments():
+    sql = "/* header */ SELECT 1; /* footer */ SELECT 2"
+    stmts = split_sql_statements(sql)
+    assert stmts == ["SELECT 1", "SELECT 2"]
+
+
+def test_semicolon_inside_string_ignored():
+    sql = "SELECT 'a;b' AS col; SELECT 2"
+    stmts = split_sql_statements(sql)
+    assert len(stmts) == 2
+    assert stmts[0] == "SELECT 'a;b' AS col"
+
+
+def test_empty_input():
+    assert split_sql_statements("") == []
+    assert split_sql_statements("   ") == []
+
+
+def test_only_comments():
+    assert split_sql_statements("-- just a comment") == []
+
+
+# ── extract_table_refs ────────────────────────────────────────────────────────
+
+
+def test_extract_table_refs_simple():
+    assert extract_table_refs("SELECT * FROM DB.SCH.COMPANIES") == ["DB.SCH.COMPANIES"]
+
+
+def test_extract_table_refs_joins():
+    sql = """
+        SELECT c.siren, e.name
+        FROM DB.SCH.COMPANIES c
+        JOIN DB.SCH.ESTABLISHMENTS e ON e.siren = c.siren
+        LEFT JOIN OTHER_SCH.CONTACTS ct ON ct.siren = c.siren
+    """
+    assert extract_table_refs(sql) == [
+        "DB.SCH.COMPANIES",
+        "DB.SCH.ESTABLISHMENTS",
+        "OTHER_SCH.CONTACTS",
+    ]
+
+
+def test_extract_table_refs_excludes_ctes():
+    sql = """
+        WITH recent AS (SELECT * FROM DB.SCH.COMPANIES WHERE created_at > 1)
+        SELECT * FROM recent JOIN DB.SCH.ESTABLISHMENTS e ON 1 = 1
+    """
+    assert extract_table_refs(sql) == ["DB.SCH.COMPANIES", "DB.SCH.ESTABLISHMENTS"]
+
+
+def test_extract_table_refs_excludes_bare_identifiers():
+    # unqualified names are never a real pinky FQN (SCHEMA.TABLE minimum) — e.g. the
+    # dynamic-table DML self-reference placeholder `INSERT INTO SELF ...`
+    sql = "INSERT INTO SELF SELECT * FROM DB.SCH.SRC"
+    assert extract_table_refs(sql) == ["DB.SCH.SRC"]
+
+
+def test_extract_table_refs_dedupes_and_sorts():
+    sql = "SELECT * FROM DB.SCH.B b JOIN DB.SCH.A a1 ON 1 = 1 JOIN DB.SCH.A a2 ON 1 = 1"
+    assert extract_table_refs(sql) == ["DB.SCH.A", "DB.SCH.B"]
+
+
+def test_extract_table_refs_no_tables():
+    assert extract_table_refs("SELECT 1") == []
+
+
+def test_extract_table_refs_unparseable():
+    assert extract_table_refs("not valid sql (((") == []
+
+
+def test_extract_table_refs_empty():
+    assert extract_table_refs("") == []
+
+
+# ── resolve_query ─────────────────────────────────────────────────────────────
+
+
+def test_resolve_query_simple_substitution():
+    tpl = "SELECT * FROM {companies} WHERE 1 = 1"
+    result = resolve_query(tpl, {"companies": "DB.SCH.COMPANIES"})
+    assert result == "SELECT * FROM DB.SCH.COMPANIES WHERE 1 = 1"
+
+
+def test_resolve_query_multiple_refs():
+    tpl = "SELECT * FROM {a} JOIN {b} ON 1 = 1"
+    result = resolve_query(tpl, {"a": "DB.S.A", "b": "DB.S.B"})
+    assert result == "SELECT * FROM DB.S.A JOIN DB.S.B ON 1 = 1"
+
+
+def test_resolve_query_iceberg_scan():
+    tpl = "SELECT * FROM {src}"
+    result = resolve_query(tpl, {"src": "iceberg_scan('s3://bucket/path/')"})
+    assert "iceberg_scan" in result
+
+
+def test_resolve_query_rejects_unsafe_ref():
+    tpl = "SELECT * FROM {t}"
+    with pytest.raises(ValueError, match="Unsafe table reference"):
+        resolve_query(tpl, {"t": "DB.T; DROP TABLE X--"})
+
+
+def test_resolve_query_missing_key():
+    tpl = "SELECT * FROM {companies} JOIN {establishments} ON 1 = 1"
+    with pytest.raises(ValueError, match="Template placeholder"):
+        resolve_query(tpl, {"companies": "DB.SCH.C"})

pinky_core-0.1.0.dev3/docs/explanation/2-features.md

@@ -1,74 +0,0 @@
----
-title: Features
----
-# Features — pinky-core
-*Update date : 2026-07-12 05:44*
-
-Feature list ordered by priority. `stable` = in production. `planned` = not yet built, order = priority.
-
----
-
-## Stable
-
-| Module | Description | Status |
-|--------|-------------|--------|
-| `fmt.py` | String/value formatters: snake_case, truncate, normalize whitespace, FR/AFNOR address, ISO3→ISO2 | stable |
-| `validate.py` | Input validation: SIRET/SIREN, IBAN/BIC, TVA EU, NIR, email, phone | stable |
-| `security.py` | Secret masking, PII detection, zero-width space injection/detection | stable |
-| `sql.py` | SQL parsing helpers powered by sqlglot: statement kind, query resolution, statement splitting | stable |
-| `html.py` | HTML templating engine — emails, reports, mini-sites, Outlook-safe | stable |
-| `xml.py` | XPath helpers, namespace-aware parsing, safe attribute extraction | stable |
-| `files.py` | S3/MFT filename pattern normalisation — `detect_file_pattern`, `FileDetection` | stable |
-| `schedule.py` | French public holidays, business-day helpers, cron human-readable formatting, Airflow-timetable predicates (month/week/fiscal-quarter, eve-of-holiday) | stable |
-
----
-
-## Planned
-
-Ordered by priority — closest to implementation first.
-
-### finance/fec.py — FEC parser
-
-New submodule `pinky_core/finance/fec.py`. Pure Python, no Snowflake connection.
-Parses FEC files (tab-separated, ISO-8859-1) into typed `FecRow` dataclass rows.
-Validates DEBIT == CREDIT and mandatory column presence.
-
-### schedule.py — additional calendar support
-
-- `public_holidays_be(year)` / `public_holidays_uk(year)` — expand beyond FR
-- `business_days_until_end_of_month(d)` — look-ahead for SLA calculations
-- `nth_last_business_day_of_month(d, n)` — countdown from month end (e.g. J-2)
-- Holiday calendar as injectable parameter — custom frozenset for non-standard calendars
-
-### finance/ — extend beyond FEC
-
-- `finance/dsn.py` — Déclaration Sociale Nominative parser (INSEE/Net-Entreprises)
-- `finance/sepa.py` — SEPA pain.001 / pain.008 XML builders (credit transfers, direct debits)
-- `finance/ofx.py` — bank statement parsers (OFX/QFX for reconciliation)
-
-### sql_custom.py — query builder extensions
-
-- `build_merge()` — MERGE INTO stubs from a key/value column dict
-- `paginate_query(sql, page_size, offset)` — LIMIT/OFFSET wrapper for cursor-based pagination
-
-### validate.py — additional validators
-
-- `is_luhn(s)` — Luhn algorithm for generic checksums not already covered
-
-### schedule.py — cron expression builder
-
-Inverse of `cron_to_human`: build a 5-field cron string from structured parameters.
-Council-validate before implementing — may already be covered by existing tools.
-
-### fmt.py — slugify
-
-`slugify(text) -> str` — converts any string to a URL-safe slug (lowercase, ASCII, hyphens).
-Use cases: Snowflake object keys, URL segments, file/schema name generation.
-
-### fmt.py — locale-aware formatters
-
-French locale (espace insécable, virgule décimale). Low priority: rendering mostly happens at Streamlit level.
-
-### finance/ — FEC validator as CLI
-
-`python -m pinky_core.finance.fec validate file.txt` — depends on `snowflake-tools` CLI integration.

pinky_core-0.1.0.dev3/tests/test_sql.py

@@ -1,82 +0,0 @@
-"""Tests for pinky_core.sql — pure Python, no external deps."""
-
-import pytest
-
-from pinky_core.sql import (
-    split_sql_statements,
-    statement_kind,
-)
-
-# ── statement_kind ────────────────────────────────────────────────────────────
-
-
-@pytest.mark.parametrize(
-    ("stmt", "kind"),
-    [
-        ("SELECT 1", "select"),
-        (
-            "WITH c AS (SELECT 1) SELECT * FROM c",
-            "select",
-        ),  # CTE → top node is the SELECT
-        ("SELECT 1 UNION SELECT 2", "union"),
-        ("INSERT INTO SELF SELECT 1", "insert"),
-        (
-            "MERGE INTO SELF USING s ON a = b WHEN MATCHED THEN UPDATE SET x = 1",
-            "merge",
-        ),
-        ("UPDATE t SET x = 1", "update"),
-        ("DELETE FROM t", "delete"),
-        ("CREATE TABLE t (id INT)", "create"),
-        ("DROP TABLE t", "drop"),
-        ("CALL my_proc()", "command"),
-    ],
-)
-def test_statement_kind(stmt, kind):
-    assert statement_kind(stmt) == kind
-
-
-def test_statement_kind_unknown_on_empty():
-    assert statement_kind("") == "unknown"
-    assert statement_kind("   ") == "unknown"
-
-
-def test_single_statement():
-    assert split_sql_statements("SELECT 1") == ["SELECT 1"]
-
-
-def test_trailing_semicolon():
-    assert split_sql_statements("SELECT 1;") == ["SELECT 1"]
-
-
-def test_multiple_statements():
-    sql = "SELECT 1; SELECT 2; SELECT 3"
-    assert split_sql_statements(sql) == ["SELECT 1", "SELECT 2", "SELECT 3"]
-
-
-def test_strips_inline_comments():
-    sql = "SELECT 1 -- this is a comment\n; SELECT 2"
-    stmts = split_sql_statements(sql)
-    assert len(stmts) == 2
-    assert "comment" not in stmts[0]
-
-
-def test_strips_block_comments():
-    sql = "/* header */ SELECT 1; /* footer */ SELECT 2"
-    stmts = split_sql_statements(sql)
-    assert stmts == ["SELECT 1", "SELECT 2"]
-
-
-def test_semicolon_inside_string_ignored():
-    sql = "SELECT 'a;b' AS col; SELECT 2"
-    stmts = split_sql_statements(sql)
-    assert len(stmts) == 2
-    assert stmts[0] == "SELECT 'a;b' AS col"
-
-
-def test_empty_input():
-    assert split_sql_statements("") == []
-    assert split_sql_statements("   ") == []
-
-
-def test_only_comments():
-    assert split_sql_statements("-- just a comment") == []