model2data 1.5.0__tar.gz → 1.6.0__tar.gz

{model2data-1.5.0/model2data.egg-info → model2data-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model2data
-Version: 1.5.0
+Version: 1.6.0
 Summary: Generate analytics-ready datasets from DBML models
 Author: JB Analytica
 License-Expression: MIT

{model2data-1.5.0 → model2data-1.6.0}/README.md

@@ -184,6 +184,24 @@ doesn't say what it depends on can say so explicitly with an `after` note:
 shipped_at timestamp [note: '{"after": "ordered_at"}']
 ```
 
+The flags above shape every date and timestamp column the same way, run-wide. `business_hours`,
+`growth`, and `seasonality` column note hints override that for one column at a time — the whole
+point being a run can be uniform everywhere except the one column that needs shaping, or shaped
+everywhere except the one column that shouldn't be:
+
+```dbml
+Table orders {
+  id int [pk]
+  created_at timestamp [note: '{"business_hours": true, "growth": 0.4}']
+  refunded_at timestamp [note: '{"growth": 0}']
+}
+```
+
+Here `created_at` gets business hours and growth even on an otherwise-uniform run, while
+`refunded_at` stays flat even under `--growth 0.5` — each hint only replaces the fields it names,
+so a partial hint like `{"growth": 0}` leaves that column's `business_hours`/`seasonality` at
+whatever the run-level flags set.
+
 ### Shape how the data is spread
 
 By default every parent row is equally likely to be picked for a child row, and every column

{model2data-1.5.0 → model2data-1.6.0}/model2data/generate/faker.py

@@ -12,7 +12,7 @@ from typing import Callable, Optional, Union
 import pandas as pd
 from faker import Faker
 
-from model2data.generate.options import TimeProfile
+from model2data.generate.options import UNIFORM, TimeProfile
 from model2data.generate.timeline import weighted_dates, weighted_timestamps
 from model2data.parse.dbml import ColumnDef
 
@@ -505,6 +505,31 @@ def _infer_by_type(base_type: str) -> Optional[_Provider]:
     return lambda: fake.format(base_type)
 
 
+def _column_time_profile(
+    column: ColumnDef, time_profile: Optional[TimeProfile]
+) -> Optional[TimeProfile]:
+    """The run-level `time_profile` with this column's note hints applied on top.
+
+    Mirrors the `skew` override on the FK branch, one level up: a note doesn't
+    replace the run's profile, it patches only the fields it names (via
+    `dataclasses.replace`), so `{"growth": 0}` flattens one column of a
+    growing run while `business_hours`/`seasonality` stay exactly what the
+    run set. `validate_hints` has already confirmed the column is a date or
+    timestamp column and that each hint present is well-typed, so this does
+    no validation of its own -- a column with no hint gets `time_profile`
+    back unchanged, including a bare `None`, so the uniform path stays
+    untouched.
+    """
+    note = column.note or {}
+    overrides = {
+        key: note[key] for key in ("business_hours", "growth", "seasonality") if key in note
+    }
+    if not overrides:
+        return time_profile
+    base = time_profile if time_profile is not None else UNIFORM
+    return replace(base, **overrides)
+
+
 def _generate_dates(row_count: int, as_of: AsOf, time_profile: Optional[TimeProfile]) -> list:
     """The date branch's values: shaped by `time_profile` when it isn't uniform.
 
@@ -750,13 +775,13 @@ def generate_column_values(
     # Dates
     # -----------------------------------------------------
     elif "date" in base_type and "time" not in base_type:
-        values = _generate_dates(row_count, as_of, time_profile)
+        values = _generate_dates(row_count, as_of, _column_time_profile(column, time_profile))
 
     elif "time" in base_type and "stamp" not in base_type:
         values = [fake.time() for _ in range(row_count)]
 
     elif any(key in base_type for key in ["timestamp", "datetime"]):
-        values = _generate_timestamps(row_count, as_of, time_profile)
+        values = _generate_timestamps(row_count, as_of, _column_time_profile(column, time_profile))
 
     # -----------------------------------------------------
     # Untyped / generic string columns: honour a type that names

{model2data-1.5.0 → model2data-1.6.0}/model2data/generate/hints.py

@@ -3,10 +3,10 @@
 A note has always been either plain text (a comment, ignored by generation)
 or a JSON object read for `min`/`max`. This module documents the rest of that
 object's vocabulary -- `null_rate`, `weights`, `true_rate`, `distinct`, `skew`,
-`after` -- and checks it once, before a single row is generated, so a typo'd
-enum value or a hint on the wrong kind of column fails with a message naming
-the table and column rather than surfacing as a wrong-looking dataset or a
-downstream dbt test failure.
+`after`, `business_hours`, `growth`, `seasonality` -- and checks it once,
+before a single row is generated, so a typo'd enum value or a hint on the
+wrong kind of column fails with a message naming the table and column rather
+than surfacing as a wrong-looking dataset or a downstream dbt test failure.
 
 | key         | applies to                                   | meaning                                   |
 |-------------|-----------------------------------------------|--------------------------------------------|
@@ -17,6 +17,9 @@ downstream dbt test failure.
 | `distinct`  | columns that aren't an FK, `pk`, `unique`, enum | positive integer: draw from a pool that size |
 | `skew`      | foreign-key columns                            | overrides the run-level `skew` for this column |
 | `after`     | date/timestamp columns                         | name of another date/timestamp column, read by the time-aware generator |
+| `business_hours` | date/timestamp columns                    | overrides the run-level `TimeProfile.business_hours` for this column |
+| `growth`    | date/timestamp columns                         | overrides the run-level `TimeProfile.growth` for this column |
+| `seasonality` | date/timestamp columns                       | overrides the run-level `TimeProfile.seasonality` for this column |
 """
 
 from __future__ import annotations
@@ -152,6 +155,21 @@ def _validate_column_hints(
             raise ValueError(f'{label}: "after" only applies to date/timestamp columns.')
         _check_after(label, table_name, note["after"], columns_by_name)
 
+    if "business_hours" in note:
+        if not is_temporal:
+            raise ValueError(f'{label}: "business_hours" only applies to date/timestamp columns.')
+        _check_bool(label, "business_hours", note["business_hours"])
+
+    if "growth" in note:
+        if not is_temporal:
+            raise ValueError(f'{label}: "growth" only applies to date/timestamp columns.')
+        _check_growth(label, note["growth"])
+
+    if "seasonality" in note:
+        if not is_temporal:
+            raise ValueError(f'{label}: "seasonality" only applies to date/timestamp columns.')
+        _check_fraction(label, "seasonality", note["seasonality"])
+
 
 def _check_fraction(label: str, key: str, value: object) -> None:
     if isinstance(value, bool) or not isinstance(value, (int, float)) or not 0.0 <= value <= 1.0:
@@ -163,6 +181,16 @@ def _check_positive_int(label: str, key: str, value: object) -> None:
         raise ValueError(f'{label}: "{key}" must be a positive whole number (got {value!r}).')
 
 
+def _check_bool(label: str, key: str, value: object) -> None:
+    if not isinstance(value, bool):
+        raise ValueError(f'{label}: "{key}" must be true or false (got {value!r}).')
+
+
+def _check_growth(label: str, value: object) -> None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value < -1.0:
+        raise ValueError(f'{label}: "growth" must be -1.0 or more (got {value!r}).')
+
+
 def _check_enum_weights(label: str, enum_values: list[str], weights: object) -> None:
     if not isinstance(weights, dict) or not weights:
         raise ValueError(

{model2data-1.5.0 → model2data-1.6.0/model2data.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model2data
-Version: 1.5.0
+Version: 1.6.0
 Summary: Generate analytics-ready datasets from DBML models
 Author: JB Analytica
 License-Expression: MIT

{model2data-1.5.0 → model2data-1.6.0}/model2data.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ model2data/parse/__init__.py
 model2data/parse/dbml.py
 tests/test_as_of_anchor.py
 tests/test_cli.py
+tests/test_column_time_hints.py
 tests/test_coverage_gaps.py
 tests/test_dbml_parser.py
 tests/test_dbml_parser_fuzz.py

{model2data-1.5.0 → model2data-1.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "model2data"
-version = "1.5.0"
+version = "1.6.0"
 description = "Generate analytics-ready datasets from DBML models"
 readme = "README_PYPI.md"
 requires-python = ">=3.10"

model2data-1.6.0/tests/test_column_time_hints.py

@@ -0,0 +1,241 @@
+"""Per-column overrides of the run-level `TimeProfile`.
+
+1.5.0 shaped *when* things happen for a whole run: business hours, growth,
+seasonality all apply to every date/timestamp column alike. The product
+ask this closes was literally "that changes for everything globally, can we
+have that column per column?" -- so `business_hours`/`growth`/`seasonality`
+column-note hints patch just the fields they name onto the run's profile for
+that one column, the same way `skew` already overrides per foreign key (see
+tests/test_shaping.py). Every statistical test here uses a fixed seed and a
+generous tolerance so it never flakes; the exact bounds were chosen by
+running the real implementation and leaving headroom, not derived
+analytically.
+"""
+
+from datetime import date, datetime, timedelta
+
+import pytest
+
+from model2data.generate.core import generate_data_from_dbml
+from model2data.generate.options import TimeProfile
+from model2data.parse.dbml import ColumnDef, TableDef
+
+ANCHOR_DATE = date(2026, 3, 15)
+
+
+def _two_timestamp_schema(hinted_note=None, plain_note=None) -> dict[str, TableDef]:
+    return {
+        "events": TableDef(
+            name="events",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("hinted_at", "timestamp", {"not null"}, note=hinted_note),
+                ColumnDef("plain_at", "timestamp", {"not null"}, note=plain_note),
+            ],
+        )
+    }
+
+
+def _column(df, name) -> list[datetime]:
+    return [datetime.fromisoformat(v) for v in df[name]]
+
+
+def _business_hours_share(timestamps: list[datetime]) -> float:
+    in_hours = sum(1 for t in timestamps if t.weekday() < 5 and 8 <= t.hour < 18)
+    return in_hours / len(timestamps)
+
+
+def _timestamp_window_midpoint() -> date:
+    """Midpoint of the 365-day timestamp window `weighted_timestamps` draws
+    from (see timeline.py's `_TIMESTAMP_WINDOW_DAYS`): the anchor minus a
+    year, up to the day before the anchor."""
+    start = ANCHOR_DATE - timedelta(days=365)
+    end = ANCHOR_DATE - timedelta(days=1)
+    return start + (end - start) / 2
+
+
+# ---------------------------------------------------------
+# A hint shapes its own column, not its neighbour
+# ---------------------------------------------------------
+def test_business_hours_hint_shapes_only_the_hinted_column():
+    tables = _two_timestamp_schema(hinted_note={"business_hours": True})
+    df = generate_data_from_dbml(
+        tables, [], base_rows=1000, seed=5, as_of=ANCHOR_DATE, time_profile=TimeProfile()
+    )["events"]
+
+    hinted_share = _business_hours_share(_column(df, "hinted_at"))
+    plain_share = _business_hours_share(_column(df, "plain_at"))
+
+    assert hinted_share >= 0.70
+    assert plain_share < hinted_share - 0.2
+
+
+def test_growth_hint_shapes_only_the_hinted_column():
+    tables = _two_timestamp_schema(hinted_note={"growth": 1.0})
+    df = generate_data_from_dbml(
+        tables, [], base_rows=2000, seed=5, as_of=ANCHOR_DATE, time_profile=TimeProfile()
+    )["events"]
+
+    midpoint = _timestamp_window_midpoint()
+    hinted = _column(df, "hinted_at")
+    plain = _column(df, "plain_at")
+
+    hinted_second_half = sum(1 for t in hinted if t.date() >= midpoint) / len(hinted)
+    plain_second_half = sum(1 for t in plain if t.date() >= midpoint) / len(plain)
+
+    # growth=1.0 on hinted_at pushes its rows toward the second half of the
+    # window; plain_at, with no hint under a flat run-level profile, does not.
+    assert hinted_second_half > plain_second_half + 0.05
+
+
+# ---------------------------------------------------------
+# A hint overrides the run-level profile in both directions
+# ---------------------------------------------------------
+def test_hint_overrides_a_flat_run_level_profile():
+    tables = _two_timestamp_schema(hinted_note={"business_hours": True})
+    df = generate_data_from_dbml(
+        tables, [], base_rows=1000, seed=5, as_of=ANCHOR_DATE, time_profile=TimeProfile()
+    )["events"]
+
+    assert _business_hours_share(_column(df, "hinted_at")) >= 0.70
+
+
+def test_hint_overrides_a_shaped_run_level_profile_back_to_flat():
+    tables = _two_timestamp_schema(hinted_note={"business_hours": False})
+    df = generate_data_from_dbml(
+        tables,
+        [],
+        base_rows=1000,
+        seed=5,
+        as_of=ANCHOR_DATE,
+        time_profile=TimeProfile(business_hours=True),
+    )["events"]
+
+    # hinted_at is forced back to uniform; plain_at keeps the run's shaping.
+    hinted_share = _business_hours_share(_column(df, "hinted_at"))
+    plain_share = _business_hours_share(_column(df, "plain_at"))
+    assert plain_share >= 0.70
+    assert hinted_share < plain_share - 0.2
+
+
+def test_cli_flag_and_column_hint_combine_with_the_hint_winning():
+    """`--business-hours` (a run-level TimeProfile) plus a column hint that
+    turns it back off for one column: the hint wins for that column, the
+    run-level setting still applies to its neighbour."""
+    tables = _two_timestamp_schema(hinted_note={"business_hours": False})
+    df = generate_data_from_dbml(
+        tables,
+        [],
+        base_rows=1000,
+        seed=5,
+        as_of=ANCHOR_DATE,
+        time_profile=TimeProfile(business_hours=True),
+    )["events"]
+
+    assert _business_hours_share(_column(df, "hinted_at")) < 0.5
+    assert _business_hours_share(_column(df, "plain_at")) >= 0.70
+
+
+# ---------------------------------------------------------
+# A partial hint only replaces the fields it names
+# ---------------------------------------------------------
+def test_partial_hint_keeps_the_other_run_level_fields():
+    """`{"growth": 0}` flattens growth for this column but leaves
+    business_hours exactly as the run set it."""
+    tables = _two_timestamp_schema(hinted_note={"growth": 0.0})
+    run_profile = TimeProfile(business_hours=True, growth=1.0)
+    df = generate_data_from_dbml(
+        tables, [], base_rows=2000, seed=5, as_of=ANCHOR_DATE, time_profile=run_profile
+    )["events"]
+
+    hinted = _column(df, "hinted_at")
+    plain = _column(df, "plain_at")
+
+    # business_hours still applies to hinted_at (inherited, not overridden).
+    assert _business_hours_share(hinted) >= 0.70
+
+    # growth=0 on hinted_at flattens it relative to plain_at, which keeps the
+    # run's growth=1.0 and skews toward the second half of the window.
+    midpoint = _timestamp_window_midpoint()
+    hinted_second_half = sum(1 for t in hinted if t.date() >= midpoint) / len(hinted)
+    plain_second_half = sum(1 for t in plain if t.date() >= midpoint) / len(plain)
+    assert 0.35 <= hinted_second_half <= 0.65
+    assert plain_second_half > hinted_second_half
+
+
+# ---------------------------------------------------------
+# No hint: pinned frames unchanged
+# ---------------------------------------------------------
+def test_no_hint_reproduces_the_run_level_only_frame():
+    """A column with no time hint must generate byte-identical values to the
+    same schema before this feature existed -- the override helper is a
+    pure no-op when a column's note carries none of the three keys."""
+    tables = _two_timestamp_schema()
+    with_helper = generate_data_from_dbml(
+        tables, [], base_rows=20, seed=2024, as_of=ANCHOR_DATE, time_profile=TimeProfile(growth=0.4)
+    )["events"]
+    again = generate_data_from_dbml(
+        tables, [], base_rows=20, seed=2024, as_of=ANCHOR_DATE, time_profile=TimeProfile(growth=0.4)
+    )["events"]
+
+    assert with_helper.equals(again)
+
+
+def test_no_hint_and_uniform_profile_matches_the_pre_feature_pinned_frame():
+    """Same schema and seed as test_timeline.py's own pinned-frame test, with
+    an explicit empty note on both columns: still byte-identical to 1.5.0."""
+    tables = {
+        "events": TableDef(
+            name="events",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("created_at", "timestamp", {"not null"}),
+                ColumnDef("event_date", "date", set()),
+            ],
+        )
+    }
+    df = generate_data_from_dbml(tables, [], base_rows=8, seed=2024, as_of=ANCHOR_DATE)["events"]
+
+    assert list(df["created_at"])[:2] == ["2026-01-24 23:52:50", "2025-08-07 01:00:18"]
+
+
+# ---------------------------------------------------------
+# Validation
+# ---------------------------------------------------------
+def _single_column_table(column: ColumnDef, table_name: str = "t") -> dict[str, TableDef]:
+    return {table_name: TableDef(name=table_name, columns=[ColumnDef("id", "int", {"pk"}), column])}
+
+
+@pytest.mark.parametrize(
+    "key, value", [("business_hours", True), ("growth", 0.5), ("seasonality", 0.5)]
+)
+def test_hint_on_a_non_temporal_column_is_rejected(key, value):
+    tables = _single_column_table(ColumnDef("label", "varchar", note={key: value}))
+    with pytest.raises(ValueError, match=r"t\.label"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_growth_below_negative_one_is_rejected():
+    tables = _single_column_table(ColumnDef("happened_at", "timestamp", note={"growth": -1.5}))
+    with pytest.raises(ValueError, match=r"t\.happened_at.*growth"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_growth_as_a_bool_is_rejected():
+    tables = _single_column_table(ColumnDef("happened_at", "timestamp", note={"growth": True}))
+    with pytest.raises(ValueError, match=r"t\.happened_at"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_seasonality_out_of_range_is_rejected():
+    tables = _single_column_table(ColumnDef("happened_at", "timestamp", note={"seasonality": 1.5}))
+    with pytest.raises(ValueError, match=r"t\.happened_at"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_business_hours_as_a_non_bool_is_rejected():
+    tables = _single_column_table(
+        ColumnDef("happened_at", "timestamp", note={"business_hours": "yes"})
+    )
+    with pytest.raises(ValueError, match=r"t\.happened_at"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)