model2data 1.6.0__tar.gz → 1.7.1__tar.gz

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

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

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

@@ -159,7 +159,10 @@ model2data --file examples/ecommerce.dbml --rows 200 --seed 42 --table-seed orde
 ```
 
 `--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:
+it's a per-run setting, so a table can't end up holding one Belgian and one American address. A
+`country` column that sits beside a `city`/`street`/`state`/`postcode` column always agrees with
+that place; a `country` column with none of those beside it isn't describing anyone's address, so
+it reads as an international mix instead, with the locale's own country the most common:
 
 ```bash
 model2data --file examples/ecommerce.dbml --rows 200 --seed 42 --locale nl_BE
@@ -232,6 +235,26 @@ non-null rows a boolean column comes back `true`. `null_rate` replaces the colum
 fraction outright. `distinct` draws the column's values from a fixed-size pool instead of a fresh
 value per row — a `shipping_city` most warehouses only ever see a handful of.
 
+### Shape a number's distribution
+
+`min`/`max` alone only ever drew uniformly between them. A `distribution` note hint on an
+integer or decimal column picks a different shape instead:
+
+```dbml
+Table orders {
+  id int [pk]
+  total_amount numeric [note: '{"distribution": "lognormal", "median": 80, "spread": 0.6, "min": 5}']
+}
+```
+
+`normal` takes `mean` (the centre) and `stddev` (the spread); `lognormal` takes `median` (the
+typical value) and `spread` (how heavy the tail is — 0.3 is mild, 1.0 is heavy); `exponential`
+takes `mean` (the average). Any left unset default to the midpoint of the column's effective
+`min`/`max` (or `stddev` = range / 6, `spread` = 0.5). `min`/`max` still clip the result — a
+`normal` centred near an edge redraws a bounded number of times before clamping, so it never
+loops forever and never crosses the bound. Leaving `distribution` out, or setting it to
+`"uniform"`, is exactly today's behaviour.
+
 Run dbt to load, transform, and test the data:
 
 ```bash

{model2data-1.6.0 → model2data-1.7.1}/model2data/generate/core.py

@@ -15,6 +15,7 @@ from model2data.generate.faker import (
     release_row_pools,
     reset_duplicate_unique_columns,
     reset_row_pools,
+    resolve_address_pool_field,
     set_locale,
 )
 from model2data.generate.hints import validate_hints
@@ -201,6 +202,12 @@ def generate_data_from_dbml(
             for column_name in key.get("columns") or []
         }
 
+        # A table's own shape, worked out before a single value is drawn: does
+        # this table have a `country` column with no `city`/`street`/`state`/
+        # `postcode` beside it to keep coherent with. See
+        # _lone_country_columns.
+        lone_country_columns = _lone_country_columns(table_def)
+
         # -----------------------
         # First pass: columns + FKs
         # -----------------------
@@ -230,6 +237,7 @@ def generate_data_from_dbml(
                 as_of=as_of,
                 time_profile=profile,
                 skew=skew,
+                lone_country=column.name in lone_country_columns,
             )
 
         df = pd.DataFrame(data)
@@ -303,6 +311,31 @@ def generate_data_from_dbml(
 # ---------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------
+def _lone_country_columns(table_def: TableDef) -> set[str]:
+    """Names of this table's *lone* country columns.
+
+    A `country` column reads as the locale's own country on every row when it
+    sits beside a `city`/`street`/`state`/`postcode` column -- together they
+    describe one place, and the country has to agree with the rest of it.
+    Alone, repeating that same country on every row reads as a single-country
+    customer base rather than an international one, so
+    `generate_column_values` draws it from a home-heavy mix instead (see
+    `faker._HOME_COUNTRY_SHARE`). `country` columns don't count as company
+    for each other -- only a *different* address-pool field does.
+    """
+    address_fields = {
+        column.name: field
+        for column in table_def.columns
+        for field in [resolve_address_pool_field(column)]
+        if field is not None
+    }
+    country_columns = {name for name, field in address_fields.items() if field == "country"}
+    if not country_columns:
+        return set()
+    has_place_column = any(field != "country" for field in address_fields.values())
+    return set() if has_place_column else country_columns
+
+
 def _coerce_integer_dtypes(df: pd.DataFrame, table_def: TableDef) -> pd.DataFrame:
     """
     Cast int/bigint/smallint-typed columns to pandas' nullable "Int64" dtype.

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

@@ -505,6 +505,42 @@ def _infer_by_type(base_type: str) -> Optional[_Provider]:
     return lambda: fake.format(base_type)
 
 
+def resolve_address_pool_field(column: ColumnDef) -> Optional[str]:
+    """The address-pool field (`street`, `full`, `city`, `state`, `postcode`,
+    `country`) this column would draw from, if any -- else None.
+
+    Same declared-type-then-name precedence `generate_column_values`'s own
+    untyped-column branch uses (`_infer_by_type` before `_infer_by_name`),
+    narrowed to the address pool. Exposed for `generate.core` to tell a
+    *lone* country column -- the only address-pool-shaped column in its
+    table -- from one that sits beside a `city`/`street`/`state`/`postcode`
+    column, before a single value of the table has been generated.
+
+    Restricted to columns that would actually reach that branch: an enum
+    column, or one whose type is a structured (int/date/uuid/...) type, never
+    gets there in `generate_column_values` -- and `_infer_by_type` probes an
+    unrecognized type by actually calling it (`fake.format(base_type)`), so
+    running it over a `date` or `int` column here would consume real draws
+    from the shared RNG and shift every value generated after it, breaking
+    reproducibility for reasons invisible to whoever hits it.
+    """
+    if column.enum_values or not is_free_text_type(column.data_type):
+        return None
+    base_type = column.data_type.lower().split("(")[0].strip()
+    generator = _infer_by_type(base_type) or _infer_by_name(column.name)
+    if isinstance(generator, _FromRow) and generator.pool == "address":
+        return generator.field
+    return None
+
+
+# A lone country column (see resolve_address_pool_field's caller) mixes the
+# locale's own country in with the rest of the world rather than repeating it
+# on every row. 0.6 is a default, not a claim about any real market -- a
+# business selling internationally still has a home market, and most of its
+# rows are plausibly it, but "most" is not "all".
+_HOME_COUNTRY_SHARE = 0.6
+
+
 def _column_time_profile(
     column: ColumnDef, time_profile: Optional[TimeProfile]
 ) -> Optional[TimeProfile]:
@@ -580,6 +616,7 @@ def generate_column_values(
     as_of: AsOf = None,
     time_profile: Optional[TimeProfile] = None,
     skew: float = 0.0,
+    lone_country: bool = False,
 ) -> list:
     """
     Generate synthetic values for a single column.
@@ -591,6 +628,16 @@ def generate_column_values(
     every path that draws a value -- the main pass, the self-referencing FK
     repair, the composite-key retry -- draws it the same way.
 
+    `lone_country` tells the address-pool branch this column is the *only*
+    address-shaped column in its table (see
+    `generate.core._lone_country_columns`). A `country` column that sits
+    beside a `city`/`street`/`state`/`postcode` column still reads that
+    place's own country, byte-identical to earlier releases; a lone one
+    instead draws a home-heavy mix of the locale's country and the wider
+    world, since "Belgium" on every row of a customers table with no other
+    address column reads as a single-country customer base rather than an
+    international one.
+
     `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.
@@ -629,6 +676,7 @@ def generate_column_values(
             as_of=as_of,
             time_profile=time_profile,
             skew=skew,
+            lone_country=lone_country,
         )
         values = random.choices(pool, k=row_count)
         if not force_not_null and "not null" not in column.settings and "pk" not in column.settings:
@@ -665,6 +713,13 @@ def generate_column_values(
     if column.note:
         min_val = column.note.get("min")
         max_val = column.note.get("max")
+    # The note's own min/max, before either numeric branch fills in its
+    # branch-specific default -- these are the only bounds a distribution
+    # hint clips against (see `_clipped_distribution_draw`). A column with no
+    # explicit min/max draws from an unclipped distribution even though the
+    # branch below still has an implicit default range for the *parameters*.
+    explicit_min, explicit_max = min_val, max_val
+    distribution = column_note.get("distribution", "uniform")
 
     if fk_series is not None and not fk_series.empty:
         # A plain branch of the same if/elif chain (rather than an early
@@ -722,7 +777,22 @@ def generate_column_values(
         if max_val is None:
             max_val = 100
 
-        if ensure_unique:
+        if distribution != "uniform":
+            # A shaped column never needs the row_count-sized value space
+            # random.sample relies on below, so it always draws one value at
+            # a time -- unique or not -- and leans on _deduplicate the same
+            # way every other non-uniform-fast-path branch does.
+            params = _distribution_params(distribution, min_val, max_val, column_note)
+
+            def generator() -> int:
+                return round(
+                    _clipped_distribution_draw(distribution, params, explicit_min, explicit_max)
+                )
+
+            values = [generator() for _ in range(row_count)]
+            if ensure_unique:
+                values = _deduplicate(values, generator, column_name=unique_label)
+        elif ensure_unique:
             if not had_explicit_range:
                 # No user-specified range: widen the default so there's
                 # always enough headroom for `row_count` unique PK values.
@@ -753,13 +823,27 @@ def generate_column_values(
             min_val = 0
         if max_val is None:
             max_val = 10_000
-        values = [round(random.uniform(min_val, max_val), 2) for _ in range(row_count)]
-        if ensure_unique:
-            values = _deduplicate(
-                values,
-                lambda: round(random.uniform(min_val, max_val), 2),
-                column_name=unique_label,
-            )
+
+        if distribution != "uniform":
+            params = _distribution_params(distribution, min_val, max_val, column_note)
+
+            def generator() -> float:
+                return round(
+                    _clipped_distribution_draw(distribution, params, explicit_min, explicit_max),
+                    2,
+                )
+
+            values = [generator() for _ in range(row_count)]
+            if ensure_unique:
+                values = _deduplicate(values, generator, column_name=unique_label)
+        else:
+            values = [round(random.uniform(min_val, max_val), 2) for _ in range(row_count)]
+            if ensure_unique:
+                values = _deduplicate(
+                    values,
+                    lambda: round(random.uniform(min_val, max_val), 2),
+                    column_name=unique_label,
+                )
 
     # -----------------------------------------------------
     # Booleans
@@ -791,8 +875,18 @@ def generate_column_values(
     else:
         generator = _infer_by_type(base_type) or _infer_by_name(column.name)
         if isinstance(generator, _FromRow):
-            rows = _row_pool(generator.pool, table_name, row_count)
-            values = [getattr(rows[index], generator.field) for index in range(row_count)]
+            if lone_country and generator.pool == "address" and generator.field == "country":
+                # No sibling city/street/state/postcode column to keep this
+                # one coherent with, so it isn't "this row's place" at all --
+                # draw a home-heavy mix instead of repeating the locale's own
+                # country on every row.
+                values = [
+                    _country_name if random.random() < _HOME_COUNTRY_SHARE else fake.country()
+                    for _ in range(row_count)
+                ]
+            else:
+                rows = _row_pool(generator.pool, table_name, row_count)
+                values = [getattr(rows[index], generator.field) for index in range(row_count)]
             if ensure_unique:
                 values = _deduplicate_identity(values)
         elif generator is not None:
@@ -824,6 +918,78 @@ def generate_column_values(
 # ---------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------
+# How many times a clipped draw redraws before giving up and clamping. Kept
+# small and fixed rather than exposed as a hint: a normal whose mean sits
+# well inside its min/max rarely needs a redraw at all, and a distribution
+# whose parameters put most of its mass outside the bounds is a schema
+# mistake no retry count fixes -- clamping is the honest fallback either way.
+_MAX_DISTRIBUTION_REDRAWS = 20
+
+
+def _distribution_params(
+    distribution: str, effective_min: float, effective_max: float, note: dict
+) -> dict:
+    """Fill in whichever of mean/stddev/median/spread `note` leaves unset.
+
+    `effective_min`/`effective_max` are the note's own `min`/`max` when given,
+    else the calling branch's default range (0-100 for integers, 0-10,000 for
+    decimals) -- ordinary enough a midpoint to centre an unparameterized
+    distribution on.
+    """
+    midpoint = (effective_min + effective_max) / 2
+    if distribution == "normal":
+        return {
+            "mean": note.get("mean", midpoint),
+            "stddev": note.get("stddev", (effective_max - effective_min) / 6),
+        }
+    if distribution == "lognormal":
+        return {
+            "median": note.get("median", midpoint),
+            "spread": note.get("spread", 0.5),
+        }
+    # exponential: hints.py has already rejected anything else reaching here.
+    return {"mean": note.get("mean", midpoint)}
+
+
+def _draw_distribution_value(distribution: str, params: dict) -> float:
+    """One raw draw from `distribution`, unclipped and unrounded."""
+    if distribution == "normal":
+        return random.gauss(params["mean"], params["stddev"])
+    if distribution == "lognormal":
+        return random.lognormvariate(math.log(params["median"]), params["spread"])
+    return random.expovariate(1 / params["mean"])  # exponential
+
+
+def _clipped_distribution_draw(
+    distribution: str,
+    params: dict,
+    clip_min: Optional[float],
+    clip_max: Optional[float],
+) -> float:
+    """Draw from `distribution`, redrawing out-of-bounds values before clamping.
+
+    A normal centred well inside [min, max] almost never needs the clamp; one
+    centred near an edge (mean 120, min 0) would otherwise pile values up at
+    the boundary, so a bounded number of redraws is tried first and only a
+    value still out of bounds after all of them gets clamped -- which also
+    keeps this from looping forever when min and max leave no room at all.
+    `clip_min`/`clip_max` are the note's own bounds (`None` when the column
+    didn't set one), never the branch's implicit default range.
+    """
+    value = _draw_distribution_value(distribution, params)
+    attempts = 0
+    while attempts < _MAX_DISTRIBUTION_REDRAWS and (
+        (clip_min is not None and value < clip_min) or (clip_max is not None and value > clip_max)
+    ):
+        value = _draw_distribution_value(distribution, params)
+        attempts += 1
+    if clip_min is not None and value < clip_min:
+        value = clip_min
+    if clip_max is not None and value > clip_max:
+        value = clip_max
+    return value
+
+
 def _null_fraction_for(column: ColumnDef, row_count: int) -> float:
     """The fraction of `row_count` rows this column should turn null.
 

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

@@ -3,10 +3,11 @@
 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`, `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.
+`after`, `business_hours`, `growth`, `seasonality`, `distribution` and its
+parameters -- 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                                   |
 |-------------|-----------------------------------------------|--------------------------------------------|
@@ -20,6 +21,11 @@ than surfacing as a wrong-looking dataset or a downstream dbt test failure.
 | `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 |
+| `distribution` | numeric columns                             | draw shape: `uniform` (default), `normal`, `lognormal`, `exponential` |
+| `mean`      | numeric columns, with `distribution: normal` or `exponential` | normal: the centre; exponential: the average (scale) |
+| `stddev`    | numeric columns, with `distribution: normal`   | normal: the spread |
+| `median`    | numeric columns, with `distribution: lognormal`| lognormal: the typical value, `exp(mu)`   |
+| `spread`    | numeric columns, with `distribution: lognormal`| lognormal: sigma of the underlying normal (0.3 mild, 1.0 heavy tail) |
 """
 
 from __future__ import annotations
@@ -95,6 +101,33 @@ def _is_temporal_type(base_type: str) -> bool:
     return any(key in base_type for key in ("timestamp", "datetime"))
 
 
+def _is_numeric_type(base_type: str) -> bool:
+    """True for the integer and float/decimal types `min`/`max`/`distribution` apply to.
+
+    Mirrors generate.faker's own two numeric branches exactly, so a hint this
+    module accepts is guaranteed to land on a branch that reads it.
+    """
+    return any(
+        key in base_type
+        for key in ("int", "integer", "bigint", "smallint", "decimal", "numeric", "float", "double")
+    )
+
+
+# Distributions a numeric column's `distribution` hint may name.
+_DISTRIBUTIONS = ("uniform", "normal", "lognormal", "exponential")
+
+# Which distribution(s) each shape parameter is meaningful under -- checked
+# against the note's own `distribution` (default "uniform" when absent), so
+# a `stddev` with no `distribution` key is rejected the same as one paired
+# with the wrong distribution.
+_PARAM_DISTRIBUTIONS: dict[str, tuple[str, ...]] = {
+    "mean": ("normal", "exponential"),
+    "stddev": ("normal",),
+    "median": ("lognormal",),
+    "spread": ("lognormal",),
+}
+
+
 def _validate_column_hints(
     table_name: str,
     column: ColumnDef,
@@ -110,6 +143,7 @@ def _validate_column_hints(
     is_enum = bool(column.enum_values)
     is_boolean = "boolean" in base_type or "bool" in base_type
     is_temporal = _is_temporal_type(base_type)
+    is_numeric = _is_numeric_type(base_type)
     is_nullable = not is_pk and "not null" not in column.settings
 
     if "null_rate" in note:
@@ -170,6 +204,31 @@ def _validate_column_hints(
             raise ValueError(f'{label}: "seasonality" only applies to date/timestamp columns.')
         _check_fraction(label, "seasonality", note["seasonality"])
 
+    if "distribution" in note:
+        if not is_numeric:
+            raise ValueError(f'{label}: "distribution" only applies to numeric columns.')
+        if note["distribution"] not in _DISTRIBUTIONS:
+            allowed = ", ".join(f'"{d}"' for d in _DISTRIBUTIONS)
+            raise ValueError(
+                f'{label}: "distribution" must be one of {allowed} (got {note["distribution"]!r}).'
+            )
+
+    # mean/stddev/median/spread only make sense alongside the distribution
+    # they shape, so each is checked against the note's own `distribution`
+    # (absent means "uniform", which none of them apply to either).
+    for param_key, required_distributions in _PARAM_DISTRIBUTIONS.items():
+        if param_key not in note:
+            continue
+        if not is_numeric:
+            raise ValueError(f'{label}: "{param_key}" only applies to numeric columns.')
+        if note.get("distribution") not in required_distributions:
+            options = " or ".join(f'"{d}"' for d in required_distributions)
+            raise ValueError(f'{label}: "{param_key}" only applies with "distribution": {options}.')
+        if param_key == "mean":
+            _check_number(label, param_key, note[param_key])
+        else:
+            _check_positive_number(label, param_key, note[param_key])
+
 
 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:
@@ -181,6 +240,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_number(label: str, key: str, value: object) -> None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f'{label}: "{key}" must be a number (got {value!r}).')
+
+
+def _check_positive_number(label: str, key: str, value: object) -> None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+        raise ValueError(f'{label}: "{key}" must be a number greater than 0 (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}).')

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

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

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

@@ -36,8 +36,10 @@ tests/test_dbt_integration.py
 tests/test_dbt_naming.py
 tests/test_dbt_project.py
 tests/test_dbt_tests.py
+tests/test_distributions.py
 tests/test_faker_name_inference.py
 tests/test_generation.py
+tests/test_lone_country.py
 tests/test_options.py
 tests/test_release_stress.py
 tests/test_row_identity.py

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

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

model2data-1.7.1/tests/test_distributions.py

@@ -0,0 +1,258 @@
+"""Numeric distribution hints: `distribution` and its `mean`/`stddev`/`median`/`spread`
+parameters on integer and decimal columns.
+
+The product ask this closes was "can I make a normal distribution or another kind
+of distribution as well?" on a numeric column -- `min`/`max` alone could only shape
+a uniform spread. 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.
+"""
+
+import statistics
+
+import pytest
+
+from model2data.generate.core import generate_data_from_dbml
+from model2data.parse.dbml import ColumnDef, TableDef
+
+
+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])}
+
+
+# ---------------------------------------------------------
+# Step 0: pin today's (uniform) behaviour before touching it
+# ---------------------------------------------------------
+def test_no_distribution_hint_reproduces_pre_1_7_frames():
+    """A numeric column with no `distribution` key must still produce exactly
+    what 1.6.0 produced with the same seed -- the guard rail every distribution
+    added here works against."""
+    tables = {
+        "t": TableDef(
+            name="t",
+            columns=[
+                ColumnDef("id", "int", {"pk"}),
+                ColumnDef("amount", "numeric", {"not null"}),
+                ColumnDef("qty", "int", {"not null"}),
+            ],
+        )
+    }
+    data = generate_data_from_dbml(tables, [], base_rows=8, seed=777)
+    assert data["t"]["amount"].tolist() == [
+        4169.09,
+        3848.52,
+        5163.13,
+        3006.66,
+        25.14,
+        4363.61,
+        685.34,
+        8357.29,
+    ]
+    assert data["t"]["qty"].tolist() == [7, 89, 51, 52, 82, 100, 97, 9]
+
+
+# ---------------------------------------------------------
+# Shape: each distribution draws roughly what it says it does
+# ---------------------------------------------------------
+def test_normal_distribution_matches_mean_and_stddev():
+    tables = _single_column_table(
+        ColumnDef(
+            "amount",
+            "numeric",
+            {"not null"},
+            note={"distribution": "normal", "mean": 100, "stddev": 10},
+        )
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=1)
+    values = data["t"]["amount"].tolist()
+    assert 97 <= statistics.mean(values) <= 103
+    assert 8 <= statistics.stdev(values) <= 12
+
+
+def test_lognormal_distribution_median_and_mean():
+    tables = _single_column_table(
+        ColumnDef(
+            "amount",
+            "numeric",
+            {"not null"},
+            note={"distribution": "lognormal", "median": 80, "spread": 0.5},
+        )
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=2)
+    values = data["t"]["amount"].tolist()
+    sample_median = statistics.median(values)
+    assert 70 <= sample_median <= 90
+    assert statistics.mean(values) > sample_median
+
+
+def test_exponential_distribution_matches_mean():
+    tables = _single_column_table(
+        ColumnDef(
+            "amount", "numeric", {"not null"}, note={"distribution": "exponential", "mean": 30}
+        )
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=3)
+    values = data["t"]["amount"].tolist()
+    assert 26 <= statistics.mean(values) <= 34
+
+
+def test_missing_parameters_default_to_midpoint_and_derived_spread():
+    """No `mean`/`stddev` at all: normal centres on the midpoint of the
+    default int range (0-100 -> 50) with stddev (max-min)/6."""
+    tables = _single_column_table(
+        ColumnDef("qty", "int", {"not null"}, note={"distribution": "normal"})
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=7)
+    values = data["t"]["qty"].tolist()
+    assert 45 <= statistics.mean(values) <= 55
+    assert 12 <= statistics.stdev(values) <= 21
+
+
+def test_missing_lognormal_parameters_default_to_midpoint_and_half_spread():
+    """No `median`/`spread`: lognormal centres on the midpoint of the default
+    decimal range (0-10,000 -> 5,000)."""
+    tables = _single_column_table(
+        ColumnDef("amount", "numeric", {"not null"}, note={"distribution": "lognormal"})
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=8)
+    values = data["t"]["amount"].tolist()
+    assert 4000 <= statistics.median(values) <= 6000
+
+
+def test_missing_exponential_mean_defaults_to_midpoint():
+    """No `mean`: exponential's scale defaults to the midpoint of the default
+    int range (0-100 -> 50)."""
+    tables = _single_column_table(
+        ColumnDef("qty", "int", {"not null"}, note={"distribution": "exponential"})
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=5000, seed=9)
+    values = data["t"]["qty"].tolist()
+    assert 40 <= statistics.mean(values) <= 60
+
+
+# ---------------------------------------------------------
+# Clipping and typing
+# ---------------------------------------------------------
+def test_clipping_with_explicit_min_leaves_no_negatives():
+    """A normal whose mean sits close to an explicit `min` would otherwise
+    draw negatives; redraw-then-clamp keeps every value in bounds."""
+    tables = _single_column_table(
+        ColumnDef(
+            "amount",
+            "numeric",
+            {"not null"},
+            note={"distribution": "normal", "mean": 5, "stddev": 10, "min": 0},
+        )
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=2000, seed=4)
+    values = data["t"]["amount"].tolist()
+    assert min(values) >= 0
+
+
+def test_integer_columns_stay_ints_under_a_distribution():
+    tables = _single_column_table(
+        ColumnDef(
+            "qty", "int", {"not null"}, note={"distribution": "normal", "mean": 50, "stddev": 10}
+        )
+    )
+    data = generate_data_from_dbml(tables, [], base_rows=200, seed=5)
+    values = data["t"]["qty"].tolist()
+    assert all(isinstance(v, int) for v in values)
+
+
+def test_unique_normal_column_stays_unique():
+    """`ensure_unique` still resolves collisions when the generator draws
+    from a distribution instead of `random.sample` -- given a spread wide
+    enough to hold that many distinct values."""
+    tables = {
+        "t": TableDef(
+            name="t",
+            columns=[
+                ColumnDef(
+                    "id",
+                    "int",
+                    {"pk"},
+                    note={"distribution": "normal", "mean": 5000, "stddev": 500},
+                )
+            ],
+        )
+    }
+    data = generate_data_from_dbml(tables, [], base_rows=200, seed=6)
+    values = data["t"]["id"].tolist()
+    assert len(set(values)) == len(values)
+
+
+# ---------------------------------------------------------
+# Validation: every error names the column
+# ---------------------------------------------------------
+def test_distribution_on_a_non_numeric_column_is_rejected():
+    tables = _single_column_table(ColumnDef("label", "varchar", note={"distribution": "normal"}))
+    with pytest.raises(ValueError, match=r"t\.label"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_distribution_rejects_an_unknown_value():
+    tables = _single_column_table(ColumnDef("total", "numeric", note={"distribution": "gaussian"}))
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_stddev_without_distribution_is_rejected():
+    tables = _single_column_table(ColumnDef("total", "numeric", note={"stddev": 5}))
+    with pytest.raises(
+        ValueError, match=r't\.total: "stddev" only applies with "distribution": "normal"\.'
+    ):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_stddev_with_the_wrong_distribution_is_rejected():
+    tables = _single_column_table(
+        ColumnDef("total", "numeric", note={"distribution": "exponential", "stddev": 5})
+    )
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_median_with_the_wrong_distribution_is_rejected():
+    tables = _single_column_table(
+        ColumnDef("total", "numeric", note={"distribution": "normal", "median": 5})
+    )
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_spread_with_the_wrong_distribution_is_rejected():
+    tables = _single_column_table(
+        ColumnDef("total", "numeric", note={"distribution": "normal", "spread": 0.5})
+    )
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_mean_without_a_matching_distribution_is_rejected():
+    tables = _single_column_table(ColumnDef("total", "numeric", note={"mean": 5}))
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+@pytest.mark.parametrize(
+    "note",
+    [
+        {"distribution": "normal", "stddev": -1},
+        {"distribution": "normal", "stddev": 0},
+        {"distribution": "lognormal", "median": -5},
+        {"distribution": "lognormal", "spread": 0},
+    ],
+)
+def test_non_positive_stddev_median_spread_is_rejected(note):
+    tables = _single_column_table(ColumnDef("total", "numeric", note=note))
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)
+
+
+def test_a_bool_value_is_rejected_where_a_number_is_expected():
+    tables = _single_column_table(
+        ColumnDef("total", "numeric", note={"distribution": "normal", "mean": True})
+    )
+    with pytest.raises(ValueError, match=r"t\.total"):
+        generate_data_from_dbml(tables, [], base_rows=5, seed=1)

model2data-1.7.1/tests/test_lone_country.py

@@ -0,0 +1,132 @@
+"""A lone `country` column reads as an international mix, not one repeated
+country.
+
+Since 1.3.0 every row draws one address from a per-table pool, and that
+pool's country is always the locale's own -- right when a sibling
+city/street/state/postcode column needs it to agree, wrong when `country` is
+the only address-shaped column in the table. These tests pin: the mix (a
+majority-but-not-all home-country share, several distinct countries), that a
+sibling place column switches it back off, that a declared `country` type
+behaves like the name, and that `distinct`/`null_rate`/determinism/locale
+keep working the same way they do everywhere else.
+"""
+
+from model2data.generate.core import generate_data_from_dbml
+from model2data.parse.dbml import ColumnDef, TableDef
+
+
+def _customers_table(*extra_columns: ColumnDef) -> TableDef:
+    return TableDef(
+        name="customers",
+        columns=[
+            ColumnDef(name="id", data_type="int", settings={"pk"}),
+            ColumnDef(name="country", data_type="varchar", settings={"not null"}),
+            *extra_columns,
+        ],
+    )
+
+
+class TestLoneCountryColumn:
+    def test_lone_country_column_reads_as_an_international_mix(self):
+        df = generate_data_from_dbml(
+            tables={"customers": _customers_table()},
+            refs=[],
+            base_rows=500,
+            seed=1,
+            locale="nl_BE",
+        )["customers"]
+
+        counts = df["country"].value_counts(normalize=True)
+        assert len(counts) >= 5
+
+        home_share = counts.get("Belgium", 0.0)
+        assert 0.5 <= home_share <= 0.7
+        assert counts.idxmax() == "Belgium"
+
+    def test_a_sibling_place_column_keeps_the_country_single(self):
+        df = generate_data_from_dbml(
+            tables={
+                "customers": _customers_table(
+                    ColumnDef(name="city", data_type="varchar", settings={"not null"})
+                )
+            },
+            refs=[],
+            base_rows=200,
+            seed=2,
+            locale="nl_BE",
+        )["customers"]
+
+        assert set(df["country"]) == {"Belgium"}
+
+    def test_declared_country_type_behaves_like_the_name(self):
+        df = generate_data_from_dbml(
+            tables={
+                "customers": TableDef(
+                    name="customers",
+                    columns=[
+                        ColumnDef(name="id", data_type="int", settings={"pk"}),
+                        # Named generically; the *declared type* is what
+                        # says "country".
+                        ColumnDef(name="hq", data_type="country", settings={"not null"}),
+                    ],
+                )
+            },
+            refs=[],
+            base_rows=500,
+            seed=3,
+            locale="nl_BE",
+        )["customers"]
+
+        counts = df["hq"].value_counts(normalize=True)
+        assert len(counts) >= 5
+        assert 0.5 <= counts.get("Belgium", 0.0) <= 0.7
+
+    def test_distinct_hint_still_bounds_the_pool(self):
+        df = generate_data_from_dbml(
+            tables={
+                "customers": TableDef(
+                    name="customers",
+                    columns=[
+                        ColumnDef(name="id", data_type="int", settings={"pk"}),
+                        ColumnDef(
+                            name="country",
+                            data_type="varchar",
+                            settings={"not null"},
+                            note={"distinct": 3},
+                        ),
+                    ],
+                )
+            },
+            refs=[],
+            base_rows=300,
+            seed=4,
+            locale="nl_BE",
+        )["customers"]
+
+        assert df["country"].nunique() <= 3
+
+    def test_same_seed_reproduces_the_same_mix(self):
+        def run():
+            return generate_data_from_dbml(
+                tables={"customers": _customers_table()},
+                refs=[],
+                base_rows=200,
+                seed=5,
+                locale="nl_BE",
+            )["customers"]
+
+        first_run, second_run = run(), run()
+        assert list(first_run["country"]) == list(second_run["country"])
+
+    def test_default_locale_also_produces_a_mix(self):
+        df = generate_data_from_dbml(
+            tables={"customers": _customers_table()},
+            refs=[],
+            base_rows=500,
+            seed=6,
+        )["customers"]
+
+        counts = df["country"].value_counts(normalize=True)
+        assert len(counts) >= 5
+        assert 0.5 <= counts.get("United States", 0.0) <= 0.7
+        assert counts.idxmax() == "United States"