model2data 1.3.1__tar.gz → 1.4.0__tar.gz

{model2data-1.3.1/model2data.egg-info → model2data-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model2data
-Version: 1.3.1
+Version: 1.4.0
 Summary: Generate analytics-ready datasets from DBML models
 Author: JB Analytica
 License-Expression: MIT
@@ -85,7 +85,10 @@ access required.
 - **Relationship-preserving.** Foreign keys resolve to real parent rows; tables are generated in
   dependency order.
 - **Deterministic.** Pass `--seed` and the same schema always produces the same data — safe to
-  commit fixtures, safe to diff across CI runs.
+  commit fixtures, safe to diff across CI runs. Add `--as-of` to pin the date the data is anchored
+  on, and the run reproduces on any later day rather than only on the day it first ran.
+- **Re-rollable one table at a time.** `--table-seed orders=7` regenerates a single table and
+  leaves every other table byte-identical, so you can keep the four tables that look right.
 - **A real dbt project, not just CSVs.** Seeds, staging models that `ref()` them, schema tests,
   and a ready-to-use profile — the thing you'd otherwise spend an afternoon scaffolding by hand.
   A single `dbt build` loads, transforms, and tests the whole thing.
@@ -136,6 +139,18 @@ model2data --file examples/ecommerce.dbml --rows 200 --seed 42
 
 This creates a `dbt_ecommerce/` folder with your data and dbt setup.
 
+`--seed` reproduces a run's numbers, but dates and timestamps are generated relative to the
+current date, so the same seed drifts once the day turns over. `--as-of` pins the date they're
+anchored on, and the whole dataset reproduces on any later day — which is what makes a generated
+fixture safe to commit. If one table comes out wrong and the rest looks right, `--table-seed`
+re-rolls just that table, leaving every other table's seed CSV byte-identical. `--locale` picks
+the country every generated person and address comes from:
+
+```bash
+model2data --file examples/ecommerce.dbml --rows 200 --seed 42 \
+  --as-of 2026-01-31 --table-seed orders=7 --locale nl_BE
+```
+
 Run dbt to load, transform, and test the data:
 
 ```bash
@@ -274,7 +289,6 @@ wants to pick them up as a contribution:
   parsed schema shape.
 - Example mart-layer models on top of staging (the generated `dbt_project.yml` carries a
   ready-to-uncomment `marts` schema/materialization config for this).
-- Locale-aware generation (`--locale`) for non-English/US synthetic data.
 
 See [CONTRIBUTING.md](https://github.com/JB-Analytica/model2data/blob/main/CONTRIBUTING.md) if you'd like to work on any of these.
 

{model2data-1.3.1 → model2data-1.4.0}/README.md

@@ -44,7 +44,10 @@ access required.
 - **Relationship-preserving.** Foreign keys resolve to real parent rows; tables are generated in
   dependency order.
 - **Deterministic.** Pass `--seed` and the same schema always produces the same data — safe to
-  commit fixtures, safe to diff across CI runs.
+  commit fixtures, safe to diff across CI runs. Add `--as-of` to pin the date the data is anchored
+  on, and the run reproduces on any later day rather than only on the day it first ran.
+- **Re-rollable one table at a time.** `--table-seed orders=7` regenerates a single table and
+  leaves every other table byte-identical, so you can keep the four tables that look right.
 - **A real dbt project, not just CSVs.** Seeds, staging models that `ref()` them, schema tests,
   and a ready-to-use profile — the thing you'd otherwise spend an afternoon scaffolding by hand.
   A single `dbt build` loads, transforms, and tests the whole thing.
@@ -138,6 +141,30 @@ model2data --file examples/ecommerce.dbml --rows 200 --seed 42 \
   --rows-for customers=50 --rows-for order_items=5000
 ```
 
+`--seed` reproduces a run's numbers, but dates and timestamps are generated relative to the
+current date, so the same seed drifts once the day turns over. `--as-of` pins the date they're
+anchored on, and the whole dataset reproduces on any later day — which is what makes a generated
+fixture safe to commit:
+
+```bash
+model2data --file examples/ecommerce.dbml --rows 200 --seed 42 --as-of 2026-01-31
+```
+
+If one table comes out wrong and the rest looks right, `--table-seed` re-rolls just that table.
+Every other table's seed CSV stays byte-identical, and children of the re-rolled table still
+reference rows that exist, so there's nothing to re-check but the table you asked to change:
+
+```bash
+model2data --file examples/ecommerce.dbml --rows 200 --seed 42 --table-seed orders=7
+```
+
+`--locale` picks the country every generated person and address comes from (`en_US` by default);
+it's a per-run setting, so a table can't end up holding one Belgian and one American address:
+
+```bash
+model2data --file examples/ecommerce.dbml --rows 200 --seed 42 --locale nl_BE
+```
+
 Run dbt to load, transform, and test the data:
 
 ```bash
@@ -277,7 +304,6 @@ wants to pick them up as a contribution:
   parsed schema shape.
 - Example mart-layer models on top of staging (the generated `dbt_project.yml` carries a
   ready-to-uncomment `marts` schema/materialization config for this).
-- Locale-aware generation (`--locale`) for non-English/US synthetic data.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) if you'd like to work on any of these.
 

{model2data-1.3.1 → model2data-1.4.0}/README_PYPI.md

@@ -41,7 +41,10 @@ access required.
 - **Relationship-preserving.** Foreign keys resolve to real parent rows; tables are generated in
   dependency order.
 - **Deterministic.** Pass `--seed` and the same schema always produces the same data — safe to
-  commit fixtures, safe to diff across CI runs.
+  commit fixtures, safe to diff across CI runs. Add `--as-of` to pin the date the data is anchored
+  on, and the run reproduces on any later day rather than only on the day it first ran.
+- **Re-rollable one table at a time.** `--table-seed orders=7` regenerates a single table and
+  leaves every other table byte-identical, so you can keep the four tables that look right.
 - **A real dbt project, not just CSVs.** Seeds, staging models that `ref()` them, schema tests,
   and a ready-to-use profile — the thing you'd otherwise spend an afternoon scaffolding by hand.
   A single `dbt build` loads, transforms, and tests the whole thing.
@@ -92,6 +95,18 @@ model2data --file examples/ecommerce.dbml --rows 200 --seed 42
 
 This creates a `dbt_ecommerce/` folder with your data and dbt setup.
 
+`--seed` reproduces a run's numbers, but dates and timestamps are generated relative to the
+current date, so the same seed drifts once the day turns over. `--as-of` pins the date they're
+anchored on, and the whole dataset reproduces on any later day — which is what makes a generated
+fixture safe to commit. If one table comes out wrong and the rest looks right, `--table-seed`
+re-rolls just that table, leaving every other table's seed CSV byte-identical. `--locale` picks
+the country every generated person and address comes from:
+
+```bash
+model2data --file examples/ecommerce.dbml --rows 200 --seed 42 \
+  --as-of 2026-01-31 --table-seed orders=7 --locale nl_BE
+```
+
 Run dbt to load, transform, and test the data:
 
 ```bash
@@ -230,7 +245,6 @@ wants to pick them up as a contribution:
   parsed schema shape.
 - Example mart-layer models on top of staging (the generated `dbt_project.yml` carries a
   ready-to-uncomment `marts` schema/materialization config for this).
-- Locale-aware generation (`--locale`) for non-English/US synthetic data.
 
 See [CONTRIBUTING.md](https://github.com/JB-Analytica/model2data/blob/main/CONTRIBUTING.md) if you'd like to work on any of these.
 

{model2data-1.3.1 → model2data-1.4.0}/model2data/cli.py

@@ -1,5 +1,6 @@
 import random
 import shutil
+from datetime import datetime
 from pathlib import Path
 from typing import Optional
 
@@ -75,6 +76,43 @@ def _parse_row_overrides(
     return overrides
 
 
+def _parse_table_seeds(
+    raw: Optional[list[str]],
+    tables: dict,
+) -> dict[str, int]:
+    """Turn repeated `--table-seed TABLE=N` values into a {table: seed} mapping.
+
+    Same shape and the same loud failure on an unknown name as `--rows-for`:
+    the whole point of naming a table here is to change that table, so a typo
+    would otherwise produce a run in which nothing moved and nothing was said.
+    """
+    if not isinstance(raw, (list, tuple)):
+        return {}
+
+    table_seeds: dict[str, int] = {}
+    for item in raw:
+        table_name, separator, value = item.partition("=")
+        table_name = table_name.strip()
+        if not separator or not table_name:
+            raise typer.BadParameter(f"Expected TABLE=N, got {item!r}.", param_hint="--table-seed")
+
+        try:
+            table_seed = int(value)
+        except ValueError:
+            raise typer.BadParameter(
+                f"Seed for {table_name!r} must be a whole number, got {value!r}.",
+                param_hint="--table-seed",
+            ) from None
+        if table_name not in tables:
+            known = ", ".join(sorted(tables)) or "none"
+            raise typer.BadParameter(
+                f"No table named {table_name!r} in this schema. Tables: {known}.",
+                param_hint="--table-seed",
+            )
+        table_seeds[table_name] = table_seed
+    return table_seeds
+
+
 app = typer.Typer(
     help=(
         "model2data: Generate analytics-ready datasets from DBML models.\n\n"
@@ -107,8 +145,11 @@ def main(
         min=10,
         help="Number of rows to generate per table.",
     ),
-    # noqa: B008 is only needed here (not on the other options) because a
-    # repeatable option must be annotated with a mutable `list` type.
+    # noqa: B008 is needed on some options and not others because ruff waves a
+    # call through in a default only when the annotation is one of the types it
+    # knows to be immutable. `str`, `int`, `bool` and `Path` are on that list;
+    # the `list` a repeatable option must be annotated with, and `datetime`,
+    # are not -- neither is actually mutated here.
     rows_for: Optional[list[str]] = typer.Option(  # noqa: B008
         None,
         "--rows-for",
@@ -126,6 +167,25 @@ def main(
             "Using the same seed will always produce identical datasets."
         ),
     ),
+    table_seed: Optional[list[str]] = typer.Option(  # noqa: B008
+        None,
+        "--table-seed",
+        metavar="TABLE=N",
+        help=(
+            "Re-roll one table without disturbing the others, keeping --seed for the rest.\n"
+            "Repeatable, e.g. --table-seed orders=7. Requires --seed."
+        ),
+    ),
+    as_of: Optional[datetime] = typer.Option(  # noqa: B008
+        None,
+        "--as-of",
+        formats=["%Y-%m-%d"],
+        metavar="YYYY-MM-DD",
+        help=(
+            "Date to anchor generated dates and timestamps on (default: today).\n"
+            "Pin it and a --seed run reproduces on any later day, not just the day it first ran."
+        ),
+    ),
     locale: Optional[str] = typer.Option(
         None,
         "--locale",
@@ -183,6 +243,14 @@ def main(
         Faker.seed(seed)
         typer.echo(f"🔁 Using deterministic seed: {seed}")
 
+    # Same reason as `_parse_row_overrides`'s isinstance guard: `main` is also
+    # called directly as a plain function, which leaves this holding its
+    # `OptionInfo` default rather than None. Anything that isn't a real
+    # datetime means "not supplied", i.e. anchor on today.
+    as_of = as_of if isinstance(as_of, datetime) else None
+    if as_of is not None:
+        typer.echo(f"📅 Anchoring generated dates on: {as_of.date()}")
+
     # -------------------------
     # Parse DBML (names untouched)
     # -------------------------
@@ -196,6 +264,16 @@ def main(
     # should not leave a half-scaffolded project behind for the next run to trip
     # over with a confusing "destination already exists".
     row_overrides = _parse_row_overrides(rows_for, tables)
+    table_seeds = _parse_table_seeds(table_seed, tables)
+    if table_seeds and seed is None:
+        raise typer.BadParameter(
+            "--table-seed re-rolls one table out of the run's seed, so there has to "
+            "be one. Add --seed.",
+            param_hint="--table-seed",
+        )
+    if table_seeds:
+        rolled = ", ".join(f"{name}={value}" for name, value in sorted(table_seeds.items()))
+        typer.echo(f"🎲 Re-rolling with a table seed of its own: {rolled}")
 
     project_name = normalize_identifier(name or file.stem)
     dest = Path.cwd() / f"dbt_{project_name}"
@@ -225,6 +303,8 @@ def main(
         seed=seed,
         row_overrides=row_overrides,
         locale=locale,
+        as_of=as_of,
+        table_seeds=table_seeds,
     )
 
     # -------------------------

{model2data-1.3.1 → model2data-1.4.0}/model2data/generate/core.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import random
 from collections import defaultdict, deque
 from collections.abc import Mapping
@@ -9,6 +10,7 @@ import pandas as pd
 from faker import Faker
 
 from model2data.generate.faker import (
+    AsOf,
     generate_column_values,
     release_row_pools,
     reset_duplicate_unique_columns,
@@ -68,6 +70,8 @@ def generate_data_from_dbml(
     seed: Optional[int] = None,
     row_overrides: Optional[Mapping[str, int]] = None,
     locale: Optional[str] = None,
+    as_of: AsOf = None,
+    table_seeds: Optional[Mapping[str, int]] = None,
 ) -> dict[str, pd.DataFrame]:
     """
     Generate synthetic datasets from parsed DBML definitions.
@@ -86,9 +90,28 @@ def generate_data_from_dbml(
     holding one Belgian and one American address is the incoherence the row
     pools exist to remove.
 
-    This function is deterministic if a seed is provided.
-    It performs no filesystem I/O and returns pandas DataFrames.
+    `as_of` is the date every generated date and timestamp is placed relative
+    to -- dates land in the two years up to it, timestamps in the year up to
+    midnight on it -- and defaults to today. Without it a seed reproduces only
+    for as long as the day lasts: the numbers come back identical and the dates
+    move, so a committed fixture churns and a saved project renders different
+    rows next month. Pass the day the run should look like it happened on and
+    the whole frame reproduces, on any later day.
+
+    `table_seeds` re-rolls individual tables without disturbing the rest. Each
+    table draws from its own RNG stream, derived from `(seed, table_name,
+    table_seeds[table_name])`, so bumping one table's entry changes that
+    table's rows and leaves every other table byte-identical. Children of a
+    re-rolled table keep pointing at rows that exist, because their foreign
+    keys are drawn from whatever their parent ended up holding. It needs a
+    `seed` to work off -- with none, every table is already different on every
+    run -- and unknown table names are an error rather than a silent no-op.
+
+    This function is deterministic if a seed is provided (and, with `as_of`,
+    on any day). It performs no filesystem I/O and returns pandas DataFrames.
     """
+    _validate_table_seeds(tables, table_seeds, seed)
+
     # Locale first, then the seed: switching locale builds a new Faker, and the
     # seed has to be the last word on the generator that actually runs.
     set_locale(locale)
@@ -118,6 +141,26 @@ def generate_data_from_dbml(
         table_def = tables[table_name]
         row_count = _determine_row_count(table_def.name, base_rows, row_overrides)
 
+        # Give this table its own RNG stream before a single value of it is
+        # drawn. One stream for the whole run meant re-rolling a table
+        # re-rolled everything generated after it too -- fine for a one-shot
+        # CLI run, useless for a "regenerate just this table" button, which is
+        # exactly the thing users ask for once they like four tables out of
+        # five. Same locale-then-seed order as the run-level seeding above.
+        if seed is not None:
+            stream_seed = _table_stream_seed(
+                seed, table_name, table_seeds.get(table_name) if table_seeds else None
+            )
+            random.seed(stream_seed)
+            Faker.seed(stream_seed)
+
+        # A table's identities are its own. `release_row_pools` below already
+        # drops the pool keyed by this table's name; this also drops the
+        # un-named bucket the composite-key repair shares, so nothing a
+        # previous table left behind can reach this one's rows and make its
+        # stream depend on what came before it.
+        reset_row_pools()
+
         data: dict[str, list] = {}
 
         # A composite *primary* key's member columns are frequently declared
@@ -166,11 +209,16 @@ def generate_data_from_dbml(
                 ensure_unique=ensure_unique,
                 force_not_null=column.name in composite_pk_columns,
                 table_name=table_name,
+                as_of=as_of,
             )
 
         df = pd.DataFrame(data)
-        df = _resolve_self_referencing_fks(df, table_def, table_name, fk_lookup, row_count)
-        df = _deduplicate_composite_keys(df, table_def, table_name, fk_lookup, generated)
+        df = _resolve_self_referencing_fks(
+            df, table_def, table_name, fk_lookup, row_count, as_of=as_of
+        )
+        df = _deduplicate_composite_keys(
+            df, table_def, table_name, fk_lookup, generated, as_of=as_of
+        )
 
         # -----------------------------------------------------
         # Second pass: attribute mirroring (non-FK refs)
@@ -250,6 +298,7 @@ def _deduplicate_composite_keys(
     fk_lookup: dict[tuple[str, str], tuple[str, str]],
     generated: dict[str, pd.DataFrame],
     max_attempts: int = 20,
+    as_of: AsOf = None,
 ) -> pd.DataFrame:
     """
     Regenerate colliding rows for any pk/unique composite key declared via an
@@ -300,7 +349,9 @@ def _deduplicate_composite_keys(
                     if col_name in fk_pools:
                         df.at[idx, col_name] = random.choice(fk_pools[col_name])
                     else:
-                        df.at[idx, col_name] = generate_column_values(col_def, row_count=1)[0]
+                        df.at[idx, col_name] = generate_column_values(
+                            col_def, row_count=1, as_of=as_of
+                        )[0]
                 combo = tuple(df.at[idx, c] for c in key_columns)
                 attempts += 1
             # Retry budget spent and still colliding: this row keeps a
@@ -325,6 +376,7 @@ def _resolve_self_referencing_fks(
     table_name: str,
     fk_lookup: dict[tuple[str, str], tuple[str, str]],
     row_count: int,
+    as_of: AsOf = None,
 ) -> pd.DataFrame:
     """
     Re-generate any FK column that references its own table (e.g. a
@@ -362,11 +414,56 @@ def _resolve_self_referencing_fks(
             ensure_unique=ensure_unique,
             force_not_null=column.name in composite_pk_columns,
             table_name=table_name,
+            as_of=as_of,
         )
 
     return df
 
 
+def _validate_table_seeds(
+    tables: dict[str, TableDef],
+    table_seeds: Optional[Mapping[str, int]],
+    seed: Optional[int],
+) -> None:
+    """Reject a `table_seeds` mapping that cannot do what it was asked to do.
+
+    Unlike `row_overrides`, which quietly ignores a name it does not know, an
+    unknown name here is always a mistake worth stopping for: the caller asked
+    for one table to be re-rolled and would otherwise get a run in which
+    nothing changed, with nothing said about why. The same goes for passing
+    `table_seeds` with no `seed` -- there is no stream to re-roll out of, and
+    every table is already different on every run.
+    """
+    if not table_seeds:
+        return
+
+    unknown = sorted(name for name in table_seeds if name not in tables)
+    if unknown:
+        known = ", ".join(sorted(tables)) or "none"
+        label = "No table named" if len(unknown) == 1 else "No tables named"
+        named = ", ".join(repr(name) for name in unknown)
+        raise ValueError(f"{label} {named} in this schema. Tables: {known}.")
+
+    if seed is None:
+        raise ValueError(
+            "table_seeds needs a seed to re-roll a table out of: without one every "
+            "table is already generated afresh on every run."
+        )
+
+
+def _table_stream_seed(seed: int, table_name: str, table_seed: Optional[int]) -> int:
+    """The RNG seed one table draws from, derived from the run seed and its name.
+
+    Hashed with blake2b rather than Python's built-in `hash()`, which is salted
+    per interpreter process for strings: a "deterministic" seed built on it
+    would reproduce only within a single run of the program, which is the one
+    place determinism was never in doubt.
+    """
+    payload = f"{seed}|{table_name}|{'' if table_seed is None else table_seed}"
+    digest = hashlib.blake2b(payload.encode("utf-8"), digest_size=8).digest()
+    return int.from_bytes(digest, "big")
+
+
 def _determine_row_count(
     table_name: str,
     base_rows: int,

{model2data-1.3.1 → model2data-1.4.0}/model2data/generate/faker.py

@@ -5,7 +5,7 @@ import re
 import unicodedata
 import uuid
 from dataclasses import dataclass
-from datetime import datetime, timedelta
+from datetime import date, datetime, timedelta
 from typing import Callable, Optional, Union
 
 import pandas as pd
@@ -59,6 +59,47 @@ def set_locale(locale: Optional[str]) -> None:
     _address_state.clear()
 
 
+# ---------------------------------------------------------
+# Date anchor
+# ---------------------------------------------------------
+# Every generated date and timestamp is placed relative to a single anchor
+# date, which defaults to today. That default is what made a seeded run
+# reproduce only for as long as the day lasted: re-run tomorrow, the same seed
+# gave the same numbers and different dates, so a committed fixture churned and
+# a shared demo drifted. Callers that need a run to reproduce across days pass
+# `as_of` and pin the window instead.
+AsOf = Union[date, datetime, None]
+
+# How far back a `date` column's window reaches from the anchor.
+_DATE_WINDOW_YEARS = 2
+
+
+def _anchor_date(as_of: AsOf) -> date:
+    """The date a run generates relative to: `as_of`, or today when it is None.
+
+    A `datetime` is narrowed to its day, so a caller who has a timestamp to
+    hand does not have to remember that only the date part is used.
+    """
+    if as_of is None:
+        return date.today()
+    if isinstance(as_of, datetime):
+        return as_of.date()
+    return as_of
+
+
+def _years_before(anchor: date, years: int) -> date:
+    """`years` calendar years before `anchor`, moving 29 Feb back to 28 Feb.
+
+    Only 29 February has no counterpart in a non-leap year, and a whole run
+    failing on one day in four years is not a tradeoff worth taking for the
+    sake of an exact anniversary.
+    """
+    try:
+        return anchor.replace(year=anchor.year - years)
+    except ValueError:
+        return anchor.replace(year=anchor.year - years, month=2, day=28)
+
+
 # ---------------------------------------------------------
 # Per-row identities
 # ---------------------------------------------------------
@@ -471,11 +512,16 @@ def generate_column_values(
     ensure_unique: bool = False,
     force_not_null: bool = False,
     table_name: Optional[str] = None,
+    as_of: AsOf = None,
 ) -> list:
     """
     Generate synthetic values for a single column.
     Respects FKs, uniqueness, and optional min/max hints in column notes.
 
+    `as_of` is the date every generated date and timestamp is placed relative
+    to, defaulting to today. Pass it to make a seeded run reproduce on any
+    later day rather than only on the day it first ran.
+
     `force_not_null` lets a caller override the nullability pass below for a
     column whose *individual* settings don't carry `not null`/`pk` but is
     still never allowed to be null -- namely a composite primary key member
@@ -580,13 +626,20 @@ def generate_column_values(
     # Dates
     # -----------------------------------------------------
     elif "date" in base_type and "time" not in base_type:
-        values = [fake.date_between(start_date="-2y", end_date="today") for _ in range(row_count)]
+        # Explicit endpoints rather than Faker's "-2y"/"today" shorthand: those
+        # strings are resolved against `date.today()` inside Faker, which is
+        # precisely the hidden dependency on the wall clock `as_of` removes.
+        anchor = _anchor_date(as_of)
+        values = [
+            fake.date_between(start_date=_years_before(anchor, _DATE_WINDOW_YEARS), end_date=anchor)
+            for _ in range(row_count)
+        ]
 
     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 = [_random_datetime().isoformat(sep=" ") for _ in range(row_count)]
+        values = [_random_datetime(as_of=as_of).isoformat(sep=" ") for _ in range(row_count)]
 
     # -----------------------------------------------------
     # Untyped / generic string columns: honour a type that names
@@ -693,17 +746,19 @@ def _suffixed(value: str, counter: int) -> str:
     return f"{local}{counter}{at}{domain}"
 
 
-def _random_datetime(start_days: int = -365, end_days: int = 0) -> datetime:
-    """Pick a random timestamp in a window around today, to whole seconds.
+def _random_datetime(start_days: int = -365, end_days: int = 0, as_of: AsOf = None) -> datetime:
+    """Pick a random timestamp in a window around the anchor, to whole seconds.
 
-    The window is anchored to midnight rather than `datetime.now()`. The
-    random offset is a whole number of seconds, so anchoring on `now()` let
-    its sub-second component leak straight through into every generated
-    timestamp -- two runs with the same `--seed` produced values differing
-    only in their microseconds, which quietly broke the reproducibility
-    `--seed` exists to provide.
+    The window is anchored to midnight of `as_of` (today when it is None)
+    rather than to a `datetime.now()`. The random offset is a whole number of
+    seconds, so anchoring on `now()` let its sub-second component leak straight
+    through into every generated timestamp -- two runs with the same `--seed`
+    produced values differing only in their microseconds, which quietly broke
+    the reproducibility `--seed` exists to provide. Midnight of an explicit
+    `as_of` extends that reproducibility past the end of the day.
     """
-    midnight = datetime.now().replace(hour=0, minute=0, second=0, microsecond=0)
+    anchor = _anchor_date(as_of)
+    midnight = datetime(anchor.year, anchor.month, anchor.day)
     start = midnight + timedelta(days=start_days)
     end = midnight + timedelta(days=end_days)
     random_second = random.randint(0, int((end - start).total_seconds()))

{model2data-1.3.1 → model2data-1.4.0/model2data.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: model2data
-Version: 1.3.1
+Version: 1.4.0
 Summary: Generate analytics-ready datasets from DBML models
 Author: JB Analytica
 License-Expression: MIT
@@ -85,7 +85,10 @@ access required.
 - **Relationship-preserving.** Foreign keys resolve to real parent rows; tables are generated in
   dependency order.
 - **Deterministic.** Pass `--seed` and the same schema always produces the same data — safe to
-  commit fixtures, safe to diff across CI runs.
+  commit fixtures, safe to diff across CI runs. Add `--as-of` to pin the date the data is anchored
+  on, and the run reproduces on any later day rather than only on the day it first ran.
+- **Re-rollable one table at a time.** `--table-seed orders=7` regenerates a single table and
+  leaves every other table byte-identical, so you can keep the four tables that look right.
 - **A real dbt project, not just CSVs.** Seeds, staging models that `ref()` them, schema tests,
   and a ready-to-use profile — the thing you'd otherwise spend an afternoon scaffolding by hand.
   A single `dbt build` loads, transforms, and tests the whole thing.
@@ -136,6 +139,18 @@ model2data --file examples/ecommerce.dbml --rows 200 --seed 42
 
 This creates a `dbt_ecommerce/` folder with your data and dbt setup.
 
+`--seed` reproduces a run's numbers, but dates and timestamps are generated relative to the
+current date, so the same seed drifts once the day turns over. `--as-of` pins the date they're
+anchored on, and the whole dataset reproduces on any later day — which is what makes a generated
+fixture safe to commit. If one table comes out wrong and the rest looks right, `--table-seed`
+re-rolls just that table, leaving every other table's seed CSV byte-identical. `--locale` picks
+the country every generated person and address comes from:
+
+```bash
+model2data --file examples/ecommerce.dbml --rows 200 --seed 42 \
+  --as-of 2026-01-31 --table-seed orders=7 --locale nl_BE
+```
+
 Run dbt to load, transform, and test the data:
 
 ```bash
@@ -274,7 +289,6 @@ wants to pick them up as a contribution:
   parsed schema shape.
 - Example mart-layer models on top of staging (the generated `dbt_project.yml` carries a
   ready-to-uncomment `marts` schema/materialization config for this).
-- Locale-aware generation (`--locale`) for non-English/US synthetic data.
 
 See [CONTRIBUTING.md](https://github.com/JB-Analytica/model2data/blob/main/CONTRIBUTING.md) if you'd like to work on any of these.
 

{model2data-1.3.1 → model2data-1.4.0}/model2data.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ model2data/generate/faker.py
 model2data/generate/relationships.py
 model2data/parse/__init__.py
 model2data/parse/dbml.py
+tests/test_as_of_anchor.py
 tests/test_cli.py
 tests/test_coverage_gaps.py
 tests/test_dbml_parser.py
@@ -34,4 +35,5 @@ tests/test_dbt_tests.py
 tests/test_faker_name_inference.py
 tests/test_generation.py
 tests/test_release_stress.py
-tests/test_row_identity.py
+tests/test_row_identity.py
+tests/test_table_seeds.py

{model2data-1.3.1 → model2data-1.4.0}/pyproject.toml

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

model2data-1.4.0/tests/test_as_of_anchor.py

@@ -0,0 +1,139 @@
+"""A seed has to reproduce tomorrow, not only for the rest of today.
+
+Dates and timestamps were generated relative to the wall clock, so two runs of
+the same seed on different days agreed on every number and disagreed on every
+date. `as_of` pins the anchor instead, and these tests hold both halves of that:
+an explicit anchor survives the day changing underneath it, and the default
+still follows today.
+"""
+
+from datetime import date, datetime, timedelta
+
+import pytest
+
+import model2data.generate.faker as faker_module
+from model2data.generate.core import generate_data_from_dbml
+from model2data.generate.faker import _anchor_date, _years_before
+from model2data.parse.dbml import ColumnDef, TableDef
+
+ANCHOR = date(2024, 3, 15)
+
+
+def _dated_table() -> dict[str, TableDef]:
+    return {
+        "events": TableDef(
+            name="events",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("happened_on", "date", {"not null"}),
+                ColumnDef("created_at", "timestamp", {"not null"}),
+            ],
+        )
+    }
+
+
+def _freeze_today(monkeypatch: pytest.MonkeyPatch, today: date) -> None:
+    """Move the day the process thinks it is, the way the calendar would.
+
+    `date.today()` is the only clock generation reads, so replacing it with a
+    subclass that answers a fixed day is enough to run "tomorrow" inside a
+    single test.
+    """
+
+    class _FrozenDate(date):
+        @classmethod
+        def today(cls) -> date:
+            return today
+
+    monkeypatch.setattr(faker_module, "date", _FrozenDate)
+
+
+def _frames(**kwargs) -> dict:
+    return generate_data_from_dbml(_dated_table(), [], base_rows=30, seed=7, **kwargs)
+
+
+class TestAnchorHelpers:
+    def test_none_means_today(self, monkeypatch: pytest.MonkeyPatch):
+        _freeze_today(monkeypatch, date(2031, 8, 9))
+        assert _anchor_date(None) == date(2031, 8, 9)
+
+    def test_a_date_is_used_as_given(self):
+        assert _anchor_date(ANCHOR) == ANCHOR
+
+    def test_a_datetime_is_narrowed_to_its_day(self):
+        assert _anchor_date(datetime(2024, 3, 15, 23, 59, 59)) == ANCHOR
+
+    def test_two_years_back_is_the_same_day_of_the_year(self):
+        assert _years_before(date(2024, 3, 15), 2) == date(2022, 3, 15)
+
+    def test_the_29th_of_february_lands_on_the_28th(self):
+        """The one day of the year with no counterpart two years earlier."""
+        assert _years_before(date(2024, 2, 29), 2) == date(2022, 2, 28)
+
+
+class TestSeededRunsReproduceAcrossDays:
+    def test_an_explicit_anchor_survives_the_day_changing(self, monkeypatch: pytest.MonkeyPatch):
+        _freeze_today(monkeypatch, date(2024, 3, 15))
+        first = _frames(as_of=ANCHOR)["events"]
+
+        _freeze_today(monkeypatch, date(2026, 11, 2))
+        second = _frames(as_of=ANCHOR)["events"]
+
+        assert first.equals(second)
+
+    def test_without_an_anchor_the_dates_move_with_the_calendar(
+        self, monkeypatch: pytest.MonkeyPatch
+    ):
+        """The behaviour `as_of` exists to opt out of, pinned so it stays opt-out."""
+        _freeze_today(monkeypatch, date(2024, 3, 15))
+        first = _frames()["events"]
+
+        _freeze_today(monkeypatch, date(2026, 11, 2))
+        second = _frames()["events"]
+
+        assert not first["happened_on"].equals(second["happened_on"])
+        # Same stream, so the numbers underneath the dates are untouched.
+        assert first["id"].equals(second["id"])
+
+
+class TestTheWindowMoves:
+    def test_dates_fall_in_the_two_years_up_to_the_anchor(self):
+        dates = _frames(as_of=ANCHOR)["events"]["happened_on"]
+
+        assert dates.min() >= date(2022, 3, 15)
+        assert dates.max() <= ANCHOR
+
+    def test_a_different_anchor_shifts_the_window(self):
+        earlier = _frames(as_of=date(2019, 1, 1))["events"]["happened_on"]
+        later = _frames(as_of=ANCHOR)["events"]["happened_on"]
+
+        assert earlier.max() <= date(2019, 1, 1)
+        assert later.min() >= date(2022, 3, 15)
+        assert earlier.max() < later.min()
+
+    def test_timestamps_fall_in_the_year_up_to_midnight_on_the_anchor(self):
+        stamps = [
+            datetime.fromisoformat(value) for value in _frames(as_of=ANCHOR)["events"]["created_at"]
+        ]
+        midnight = datetime(2024, 3, 15)
+
+        assert min(stamps) >= midnight - timedelta(days=365)
+        assert max(stamps) <= midnight
+        # Midnight, not `now()`: no sub-second component to churn a CSV.
+        assert all(stamp.microsecond == 0 for stamp in stamps)
+
+    def test_a_datetime_anchor_is_read_as_its_day(self):
+        from_date = _frames(as_of=ANCHOR)["events"]
+        from_datetime = _frames(as_of=datetime(2024, 3, 15, 16, 30, 45))["events"]
+
+        assert from_date.equals(from_datetime)
+
+
+class TestTheDefaultIsUnchanged:
+    def test_no_anchor_still_means_today(self, monkeypatch: pytest.MonkeyPatch):
+        _freeze_today(monkeypatch, date(2024, 3, 15))
+
+        implicit = _frames()["events"]
+        explicit = _frames(as_of=ANCHOR)["events"]
+
+        assert implicit.equals(explicit)

{model2data-1.3.1 → model2data-1.4.0}/tests/test_cli.py

@@ -1,6 +1,7 @@
 """Direct tests of CLI main function for proper coverage."""
 
 import os
+import re
 
 import pandas as pd
 from typer.testing import CliRunner
@@ -9,6 +10,14 @@ from model2data.cli import app
 
 runner = CliRunner()
 
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def _plain(output: str) -> str:
+    """Typer's error box is coloured on CI, which splits `--flag` into styled
+    pieces; strip the escapes before looking for an option name in it."""
+    return _ANSI.sub("", output)
+
 
 def test_cli_basic_generation(tmp_path):
     """Test basic CLI generation with direct invocation."""
@@ -832,3 +841,89 @@ def test_cli_rows_for_rejects_malformed_values(tmp_path):
     assert "Expected TABLE=N" in _run_rows_for(tmp_path, "--rows-for", "users").output
     assert "whole number" in _run_rows_for(tmp_path, "--rows-for", "users=lots").output
     assert "at least 1" in _run_rows_for(tmp_path, "--rows-for", "users=0").output
+
+
+# Same two tables as ROWS_FOR_SCHEMA, plus the date and timestamp columns
+# --as-of has anything to say about.
+DATED_SCHEMA = """
+Table users {
+    id int [pk]
+    email email [unique]
+    signed_up date [not null]
+}
+Table orders {
+    id int [pk]
+    user_id int [not null]
+    placed_at timestamp [not null]
+}
+Ref: orders.user_id > users.id
+"""
+
+
+def _run_shop(tmp_path, name, *extra_args):
+    """Generate the dated users/orders schema under a chosen project name."""
+    dbml_file = tmp_path / "shop.dbml"
+    dbml_file.write_text(DATED_SCHEMA)
+    cwd = os.getcwd()
+    os.chdir(tmp_path)
+    try:
+        return runner.invoke(
+            app,
+            ["--file", str(dbml_file), "--rows", "30", "--name", name, *extra_args],
+        )
+    finally:
+        os.chdir(cwd)
+
+
+def test_cli_as_of_anchors_generated_dates(tmp_path):
+    result = _run_shop(tmp_path, "anchored", "--seed", "42", "--as-of", "2024-03-15")
+    assert result.exit_code == 0, result.output
+    assert "Anchoring generated dates on: 2024-03-15" in result.output
+
+    orders = pd.read_csv(tmp_path / "dbt_anchored" / "seeds" / "raw" / "orders.csv")
+    placed = pd.to_datetime(orders["placed_at"].dropna())
+    assert placed.max() <= pd.Timestamp("2024-03-15")
+    assert placed.min() >= pd.Timestamp("2024-03-15") - pd.Timedelta(days=365)
+
+
+def test_cli_as_of_rejects_a_date_it_cannot_read(tmp_path):
+    result = _run_shop(tmp_path, "bad_date", "--as-of", "the 15th")
+    assert result.exit_code != 0
+    assert "--as-of" in _plain(result.output)
+
+
+def test_cli_table_seed_re_rolls_only_that_table(tmp_path):
+    common = ("--seed", "42", "--as-of", "2024-03-15")
+    assert _run_shop(tmp_path, "before", *common).exit_code == 0
+    result = _run_shop(tmp_path, "after", *common, "--table-seed", "orders=7")
+    assert result.exit_code == 0, result.output
+    assert "Re-rolling with a table seed of its own: orders=7" in result.output
+
+    def seed_csv(project, table):
+        return (tmp_path / f"dbt_{project}" / "seeds" / "raw" / f"{table}.csv").read_text()
+
+    assert seed_csv("before", "users") == seed_csv("after", "users")
+    assert seed_csv("before", "orders") != seed_csv("after", "orders")
+
+
+def test_cli_table_seed_needs_a_seed_to_re_roll_out_of(tmp_path):
+    result = _run_shop(tmp_path, "no_seed", "--table-seed", "orders=7")
+    assert result.exit_code != 0
+    assert "--seed" in _plain(result.output)
+
+
+def test_cli_table_seed_rejects_an_unknown_table(tmp_path):
+    result = _run_shop(tmp_path, "typo", "--seed", "1", "--table-seed", "ordres=7")
+    assert result.exit_code != 0
+    assert "No table named 'ordres'" in result.output
+
+
+def test_cli_table_seed_rejects_malformed_values(tmp_path):
+    assert (
+        "Expected TABLE=N"
+        in _run_shop(tmp_path, "m1", "--seed", "1", "--table-seed", "orders").output
+    )
+    assert (
+        "whole number"
+        in _run_shop(tmp_path, "m2", "--seed", "1", "--table-seed", "orders=x").output
+    )

model2data-1.4.0/tests/test_table_seeds.py

@@ -0,0 +1,225 @@
+"""Re-rolling one table must leave the others exactly where they were.
+
+One RNG stream for the whole run meant a table's values depended on every table
+generated before it, so "I like these customers, give me different orders" was
+not a thing that could be asked. Each table now draws from its own stream,
+derived from the run seed and its own name. These tests hold the property that
+buys: change one table's entry in `table_seeds` and only that table -- plus the
+foreign keys that have to follow it -- moves.
+"""
+
+import pandas as pd
+import pytest
+from pandas.testing import assert_frame_equal
+
+from model2data.generate.core import _table_stream_seed, generate_data_from_dbml
+from model2data.parse.dbml import ColumnDef, TableDef
+
+# customers <- orders <- order_items, plus a products table connected to
+# nothing, so the suite covers a parent, a middle table, a grandchild and a
+# bystander in one schema.
+REFS = [
+    {
+        "source_table": "orders",
+        "source_column": "customer_id",
+        "target_table": "customers",
+        "target_column": "id",
+    },
+    {
+        "source_table": "order_items",
+        "source_column": "order_id",
+        "target_table": "orders",
+        "target_column": "id",
+    },
+]
+
+
+def _schema() -> dict[str, TableDef]:
+    return {
+        "customers": TableDef(
+            name="customers",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("email", "varchar", {"not null"}),
+            ],
+        ),
+        "orders": TableDef(
+            name="orders",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("customer_id", "int", {"not null"}),
+                ColumnDef("total", "numeric", {"not null"}),
+            ],
+        ),
+        "order_items": TableDef(
+            name="order_items",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("order_id", "int", {"not null"}),
+                ColumnDef("quantity", "int", {"not null"}),
+            ],
+        ),
+        "products": TableDef(
+            name="products",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("title", "varchar", {"not null"}),
+            ],
+        ),
+    }
+
+
+def _generate(**kwargs) -> dict[str, pd.DataFrame]:
+    return generate_data_from_dbml(_schema(), REFS, base_rows=40, seed=11, **kwargs)
+
+
+class TestReRollingOneTable:
+    def test_only_the_named_table_and_its_descendants_move(self):
+        baseline = _generate()
+        rolled = _generate(table_seeds={"orders": 7})
+
+        assert not rolled["orders"].equals(baseline["orders"]), (
+            "the whole point of the override is that this table changes"
+        )
+        assert_frame_equal(rolled["customers"], baseline["customers"])
+        assert_frame_equal(rolled["products"], baseline["products"])
+
+    def test_a_child_of_an_untouched_table_is_byte_identical(self):
+        """Re-rolling `products` reaches nothing: `orders` and its child stay put.
+
+        `order_items` is the interesting one -- it is two hops downstream of a
+        table nobody touched, and under a single shared stream it would have
+        moved anyway simply for being generated later in the run.
+        """
+        baseline = _generate()
+        rolled = _generate(table_seeds={"products": 5})
+
+        assert not rolled["products"].equals(baseline["products"])
+        assert_frame_equal(rolled["customers"], baseline["customers"])
+        assert_frame_equal(rolled["orders"], baseline["orders"])
+        assert_frame_equal(rolled["order_items"], baseline["order_items"])
+
+    def test_a_childs_own_columns_survive_its_parent_being_re_rolled(self):
+        """Only the FK column of a child may follow its parent."""
+        baseline = _generate()
+        rolled = _generate(table_seeds={"orders": 7})
+
+        assert_frame_equal(
+            rolled["order_items"].drop(columns=["order_id"]),
+            baseline["order_items"].drop(columns=["order_id"]),
+        )
+
+    def test_referential_integrity_holds_against_the_new_parent(self):
+        rolled = _generate(table_seeds={"orders": 7})
+
+        assert set(rolled["orders"]["customer_id"]) <= set(rolled["customers"]["id"])
+        assert set(rolled["order_items"]["order_id"]) <= set(rolled["orders"]["id"])
+
+    def test_the_old_parent_rows_are_genuinely_gone(self):
+        """A child that still pointed at the pre-roll ids would be dangling."""
+        baseline = _generate()
+        rolled = _generate(table_seeds={"orders": 7})
+
+        stale = set(baseline["orders"]["id"]) - set(rolled["orders"]["id"])
+        assert stale, "the re-rolled parent has to hand out at least some new ids"
+        assert not set(rolled["order_items"]["order_id"]) & stale
+
+    def test_two_tables_can_be_re_rolled_at_once(self):
+        baseline = _generate()
+        rolled = _generate(table_seeds={"customers": 2, "products": 5})
+
+        assert not rolled["customers"].equals(baseline["customers"])
+        assert not rolled["products"].equals(baseline["products"])
+
+    def test_re_rolling_is_itself_reproducible(self):
+        first = _generate(table_seeds={"orders": 7})
+        second = _generate(table_seeds={"orders": 7})
+
+        for name in first:
+            assert_frame_equal(first[name], second[name])
+
+    def test_a_different_override_value_gives_a_different_table(self):
+        seven = _generate(table_seeds={"orders": 7})
+        eight = _generate(table_seeds={"orders": 8})
+
+        assert not seven["orders"].equals(eight["orders"])
+        assert_frame_equal(seven["customers"], eight["customers"])
+
+    def test_an_empty_mapping_changes_nothing(self):
+        assert_frame_equal(_generate(table_seeds={})["orders"], _generate()["orders"])
+
+
+class TestValidation:
+    def test_an_unknown_table_name_is_an_error(self):
+        with pytest.raises(ValueError, match="No table named 'ordres'"):
+            _generate(table_seeds={"ordres": 7})
+
+    def test_the_message_lists_the_tables_that_do_exist(self):
+        with pytest.raises(ValueError, match="customers, order_items, orders, products"):
+            _generate(table_seeds={"nope": 1})
+
+    def test_several_unknown_names_are_reported_together(self):
+        with pytest.raises(ValueError, match="No tables named 'a', 'b'"):
+            _generate(table_seeds={"b": 1, "a": 2})
+
+    def test_it_needs_a_seed_to_re_roll_out_of(self):
+        with pytest.raises(ValueError, match="table_seeds needs a seed"):
+            generate_data_from_dbml(
+                _schema(), REFS, base_rows=10, seed=None, table_seeds={"orders": 7}
+            )
+
+    def test_no_seed_and_no_overrides_is_still_fine(self):
+        frames = generate_data_from_dbml(_schema(), REFS, base_rows=10, seed=None)
+
+        assert len(frames["orders"]) == 10
+
+    def test_validation_runs_before_anything_is_generated(self):
+        """A typo should not cost a full generation pass first."""
+        with pytest.raises(ValueError):
+            generate_data_from_dbml(
+                _schema(), REFS, base_rows=2_000_000, seed=1, table_seeds={"typo": 1}
+            )
+
+
+class TestTheDerivedSeed:
+    def test_it_is_stable_across_processes(self):
+        """Pinned literally: `hash()` is salted per process and would not be."""
+        assert _table_stream_seed(11, "orders", None) == 11237587294246756286
+        assert _table_stream_seed(11, "orders", 7) == 9635424189123890928
+
+    def test_each_table_gets_a_different_stream(self):
+        assert _table_stream_seed(11, "orders", None) != _table_stream_seed(11, "customers", None)
+
+    def test_each_run_seed_gets_a_different_stream(self):
+        assert _table_stream_seed(11, "orders", None) != _table_stream_seed(12, "orders", None)
+
+    def test_no_override_is_not_the_same_as_an_override_of_zero(self):
+        assert _table_stream_seed(11, "orders", None) != _table_stream_seed(11, "orders", 0)
+
+
+class TestOtherOptionsStillCompose:
+    def test_row_counts_are_untouched_by_a_re_roll(self):
+        rolled = _generate(row_overrides={"orders": 120}, table_seeds={"orders": 7})
+
+        assert len(rolled["orders"]) == 120
+        assert len(rolled["customers"]) == 40
+
+    def test_a_pinned_anchor_and_a_re_roll_work_together(self):
+        from datetime import date
+
+        tables = {
+            "events": TableDef(
+                name="events",
+                columns=[
+                    ColumnDef("id", "int", {"pk"}),
+                    ColumnDef("happened_on", "date", {"not null"}),
+                ],
+            )
+        }
+        kwargs = {"base_rows": 20, "seed": 4, "as_of": date(2024, 3, 15)}
+
+        first = generate_data_from_dbml(tables, [], table_seeds={"events": 1}, **kwargs)["events"]
+        second = generate_data_from_dbml(tables, [], table_seeds={"events": 1}, **kwargs)["events"]
+
+        assert_frame_equal(first, second)
+        assert first["happened_on"].max() <= date(2024, 3, 15)