model2data 1.7.0__tar.gz → 1.7.1__tar.gz

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

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

{model2data-1.7.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

{model2data-1.7.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.7.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:
@@ -827,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:

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

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

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

@@ -39,6 +39,7 @@ 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.7.0 → model2data-1.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "model2data"
-version = "1.7.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_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"