model2data 1.2.0__tar.gz → 1.3.0__tar.gz

{model2data-1.2.0/model2data.egg-info → model2data-1.3.0}/PKG-INFO

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

model2data-1.3.0/model2data/__init__.py

@@ -0,0 +1,12 @@
+"""Model2Data: Generate analytics-ready datasets from DBML models."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Read the installed distribution's version rather than repeating it here.
+    # The literal that used to live in this file said 0.1.1 for every release up
+    # to and including 1.2.0: nothing reads `__version__`, so nothing caught it
+    # drifting. Deriving it means it cannot drift again.
+    __version__ = version("model2data")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0.dev0"

{model2data-1.2.0 → model2data-1.3.0}/model2data/cli.py

@@ -18,6 +18,7 @@ from model2data.generate.core import (
     get_unresolved_composite_keys,
 )
 from model2data.generate.faker import (
+    DEFAULT_LOCALE,
     get_duplicate_unique_columns,
     get_unmapped_columns,
     reset_stats,
@@ -125,6 +126,15 @@ def main(
             "Using the same seed will always produce identical datasets."
         ),
     ),
+    locale: Optional[str] = typer.Option(
+        None,
+        "--locale",
+        help=(
+            f"Faker locale for generated people and addresses "
+            f"(default: {DEFAULT_LOCALE}).\n"
+            "Examples: en_GB, nl_BE, fr_FR, de_DE."
+        ),
+    ),
     name: Optional[str] = typer.Option(
         None,
         "--name",
@@ -214,6 +224,7 @@ def main(
         base_rows=rows,
         seed=seed,
         row_overrides=row_overrides,
+        locale=locale,
     )
 
     # -------------------------

{model2data-1.2.0 → model2data-1.3.0}/model2data/generate/core.py

@@ -10,7 +10,10 @@ from faker import Faker
 
 from model2data.generate.faker import (
     generate_column_values,
+    release_row_pools,
     reset_duplicate_unique_columns,
+    reset_row_pools,
+    set_locale,
 )
 from model2data.generate.relationships import (
     build_fk_lookup,
@@ -18,8 +21,6 @@ from model2data.generate.relationships import (
 )
 from model2data.parse.dbml import TableDef
 
-fake = Faker()
-
 # Tables the most recent generate_data_from_dbml() call found stuck in an
 # unresolved FK cycle (never reached indegree 0 during the topological
 # sort). Exposed out-of-band, mirroring generate.faker's
@@ -66,6 +67,7 @@ def generate_data_from_dbml(
     base_rows: int = 100,
     seed: Optional[int] = None,
     row_overrides: Optional[Mapping[str, int]] = None,
+    locale: Optional[str] = None,
 ) -> dict[str, pd.DataFrame]:
     """
     Generate synthetic datasets from parsed DBML definitions.
@@ -78,9 +80,19 @@ def generate_data_from_dbml(
     present in `row_overrides` fall back to `base_rows`; unknown names are
     ignored.
 
+    `locale` picks the Faker locale every generated person and address is drawn
+    from -- `"nl_BE"`, `"fr_FR"`, `"en_GB"` -- defaulting to `DEFAULT_LOCALE`.
+    It is a per-run setting rather than a per-column one on purpose: a table
+    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.
     """
+    # 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)
+
     if seed is not None:
         random.seed(seed)
         Faker.seed(seed)
@@ -88,6 +100,7 @@ def generate_data_from_dbml(
     reset_cycle_state()
     reset_dedup_state()
     reset_duplicate_unique_columns()
+    reset_row_pools()
 
     # ---------------------------------------------------------
     # Classify references
@@ -193,6 +206,9 @@ def generate_data_from_dbml(
 
         df = _coerce_integer_dtypes(df, table_def)
         generated[table_name] = df
+        # This table is finished: nothing will read its people or addresses
+        # again, and on a million-row table they are worth tens of megabytes.
+        release_row_pools(table_name)
 
     return generated
 

{model2data-1.2.0 → model2data-1.3.0}/model2data/generate/faker.py

@@ -3,15 +3,258 @@ from __future__ import annotations
 import random
 import re
 import uuid
+from dataclasses import dataclass
 from datetime import datetime, timedelta
-from typing import Callable, Optional
+from typing import Callable, Optional, Union
 
 import pandas as pd
 from faker import Faker
 
 from model2data.parse.dbml import ColumnDef
 
-fake = Faker()
+# ---------------------------------------------------------
+# Locale
+# ---------------------------------------------------------
+# The locale every generated person and address comes from until a caller says
+# otherwise. Named rather than left implicit because locale is on its way to
+# being a first-class option in the CLI and the studio, and this is the seam it
+# plugs into: one instance, swapped in one place.
+DEFAULT_LOCALE = "en_US"
+
+_locale = DEFAULT_LOCALE
+fake = Faker(DEFAULT_LOCALE)
+
+
+def current_locale() -> str:
+    """The locale generation is currently drawing from."""
+    return _locale
+
+
+def set_locale(locale: Optional[str]) -> None:
+    """Point generation at a locale, or back at the default when given None.
+
+    Rebinding the module-level `fake` reaches every provider here, because each
+    one looks the name up when it runs rather than capturing it. The row pools
+    are dropped on the way through: a Belgian address sitting next to an
+    American one in the same table is precisely the incoherence they exist to
+    prevent.
+    """
+    global fake, _locale
+    target = locale or DEFAULT_LOCALE
+    if target == _locale:
+        return
+    try:
+        fake = Faker(target)
+    except (AttributeError, ValueError) as exc:
+        # Faker's own message for a bad locale names the attribute it failed to
+        # find, which reads like an internal error rather than a typo in a flag.
+        raise ValueError(
+            f"Unknown locale {target!r}. Use a Faker locale name such as "
+            f"'en_US', 'en_GB', 'nl_BE' or 'fr_FR'."
+        ) from exc
+    _locale = target
+    _resolve_locale()
+    _person_state.clear()
+    _address_state.clear()
+
+
+# ---------------------------------------------------------
+# Per-row identities
+# ---------------------------------------------------------
+# Columns are generated one at a time, so nothing connected the `first_name`,
+# `last_name` and `email` of a single row: each drew from Faker independently
+# and one row described three different people. Anyone who points a BI tool at
+# the output sees it immediately, which makes it a credibility problem rather
+# than a cosmetic one.
+#
+# The fix is a per-table pool of identities, one per row index. A column whose
+# name (or declared type) means "a person's email" reads row i's identity
+# instead of rolling its own, so every person-shaped column in a row agrees.
+#
+# Addresses get the same treatment, one pool along. What that can and cannot
+# promise is worth being precise about: every component now comes from the same
+# locale, so a row reads as one country with one set of conventions instead of
+# "Brussels, Texas, 3000, Japan". It is not real geography -- Faker does not
+# pair a city with its state or its postcode even inside a locale, so the
+# postcode is a plausible postcode for that country rather than that city's.
+# Closing that last gap needs a reference table of real combinations, not a
+# cleverer arrangement of Faker calls.
+#
+# Both classes carry only what is drawn and compute the rest, and both use
+# slots. A million-row `person` table is a normal request: storing five strings
+# per row in a dict-backed object costs hundreds of megabytes, storing three
+# slotted references costs tens, and the derived strings then exist only for
+# the columns a schema actually declares.
+@dataclass(frozen=True, slots=True)
+class _Person:
+    first_name: str
+    last_name: str
+    email_domain: str
+
+    @property
+    def full_name(self) -> str:
+        return f"{self.first_name} {self.last_name}"
+
+    @property
+    def user_name(self) -> str:
+        return f"{_slug(self.first_name)[:1]}{_slug(self.last_name)}"
+
+    @property
+    def email(self) -> str:
+        return f"{_slug(self.first_name)}.{_slug(self.last_name)}@{self.email_domain}"
+
+
+@dataclass(frozen=True, slots=True)
+class _Address:
+    street: str
+    city: str
+    state: str
+    country: str
+    postcode: str
+
+    @property
+    def full(self) -> str:
+        """The row's own components, not a separate `fake.address()` draw.
+
+        Composing it here rather than calling Faker again is the whole point:
+        an `address` column has to agree with the `city` column beside it.
+        """
+        lines = [self.street, f"{self.postcode} {self.city}".strip(), self.country]
+        return ", ".join(line for line in lines if line)
+
+
+class _FromRow:
+    """Marker for a provider that reads row i's person or address.
+
+    A sentinel rather than a callable so `_NAME_PATTERNS` can stay a single
+    ordered list: splitting these patterns into lists of their own would quietly
+    reorder them against the rest, and that order is load-bearing (see the
+    comment on `_NAME_PATTERNS`).
+    """
+
+    __slots__ = ("pool", "field")
+
+    def __init__(self, pool: str, field: str) -> None:
+        self.pool = pool
+        self.field = field
+
+
+_Provider = Union[Callable[[], object], _FromRow]
+
+# One pool per table, keyed by table name, grown on demand and released as soon
+# as that table's frame is finished.
+_person_state: dict[str, list[_Person]] = {}
+_address_state: dict[str, list[_Address]] = {}
+
+
+def _slug(value: str) -> str:
+    """Reduce a name to something that can sit inside an email or a username."""
+    return re.sub(r"[^a-z0-9]+", "", value.lower()) or "user"
+
+
+# Resolved once per locale, not once per row. Both of these are constant for a
+# locale, and a million-row table makes the difference stark: `current_country`
+# would be recomputed a million times for an answer that never changes, and
+# probing for an administrative-unit provider means catching AttributeError --
+# on a locale that has none, four raised exceptions per row.
+_country_name: str = ""
+_state_provider: Optional[str] = None
+
+
+def _first_provider(*names: str) -> Optional[str]:
+    """The first of these provider names this locale actually has, else None.
+
+    Locales disagree about what exists: `state` is American, `province` is
+    Belgian, and plenty of countries have no administrative unit worth naming.
+    None is the honest answer there -- better than inventing a region the
+    country does not have, purely so a column looks full.
+    """
+    for name in names:
+        try:
+            fake.format(name)
+        except (AttributeError, TypeError, ValueError):
+            continue
+        return name
+    return None
+
+
+def _resolve_locale() -> None:
+    """Cache the per-locale constants the address pool reads on every row."""
+    global _country_name, _state_provider
+    # `current_country` is the locale's own country, and it is what stops a US
+    # street from landing in Japan. Locales too generic to have one (plain "en")
+    # fall back to a single country picked once, so at least every row agrees.
+    if _first_provider("current_country"):
+        _country_name = str(fake.current_country())
+    else:
+        _country_name = fake.country()
+    _state_provider = _first_provider("state", "province", "administrative_unit", "region")
+
+
+def _new_person() -> _Person:
+    return _Person(
+        first_name=fake.first_name(),
+        last_name=fake.last_name(),
+        email_domain=fake.free_email_domain(),
+    )
+
+
+def _new_address() -> _Address:
+    return _Address(
+        street=fake.street_address(),
+        city=fake.city(),
+        state=str(fake.format(_state_provider)) if _state_provider else "",
+        country=_country_name,
+        postcode=fake.postcode(),
+    )
+
+
+def reset_row_pools() -> None:
+    """Drop every table's person and address pool.
+
+    Called per run by generate_data_from_dbml alongside the other per-run state.
+    Without it a second run in the same process reuses the first run's people,
+    which looks harmless right up until a seeded run stops reproducing.
+    """
+    _person_state.clear()
+    _address_state.clear()
+
+
+def release_row_pools(table_name: str) -> None:
+    """Drop one table's pools once its frame is finished.
+
+    A pool only has to outlive the columns of its own table. Holding every
+    table's pool until the end of the run means a schema of twenty million-row
+    tables carries twenty million identities nothing will read again; releasing
+    per table bounds the cost to the largest single table instead of the sum.
+    """
+    _person_state.pop(table_name, None)
+    _address_state.pop(table_name, None)
+
+
+def _row_pool(pool: str, table_name: Optional[str], row_count: int) -> list:
+    """Row i's person or address for this table, created and cached as needed.
+
+    Keyed by table so two tables of people hold two different populations, and
+    grown rather than rebuilt so every column of the same table sees the same
+    row i. Callers with no table name (core's composite-key repair, which
+    regenerates a single cell) share one bucket; that path only ever touches key
+    columns, never person or address ones.
+    """
+    key = table_name or ""
+    # Written out per pool rather than shared behind a generic helper: the two
+    # loops are three lines each, and pairing the right factory with the right
+    # pool is exactly the thing a reader (and a type checker) wants to see.
+    if pool == "person":
+        people = _person_state.setdefault(key, [])
+        while len(people) < row_count:
+            people.append(_new_person())
+        return people
+
+    addresses = _address_state.setdefault(key, [])
+    while len(addresses) < row_count:
+        addresses.append(_new_address())
+    return addresses
 
 
 # ---------------------------------------------------------
@@ -21,25 +264,25 @@ fake = Faker()
 # "first_name" before any looser pattern gets a chance. There is
 # deliberately no generic "name" pattern, since "product_name" or
 # "company_name" would otherwise be filled with a person's name.
-_NAME_PATTERNS: list[tuple[str, Callable[[], object]]] = [
-    ("first_name", lambda: fake.first_name()),
-    ("last_name", lambda: fake.last_name()),
-    ("full_name", lambda: fake.name()),
-    ("user_name", lambda: fake.user_name()),
-    ("username", lambda: fake.user_name()),
+_NAME_PATTERNS: list[tuple[str, _Provider]] = [
+    ("first_name", _FromRow("person", "first_name")),
+    ("last_name", _FromRow("person", "last_name")),
+    ("full_name", _FromRow("person", "full_name")),
+    ("user_name", _FromRow("person", "user_name")),
+    ("username", _FromRow("person", "user_name")),
     ("password", lambda: fake.password()),
-    ("email", lambda: fake.email()),
+    ("email", _FromRow("person", "email")),
     ("phone", lambda: fake.phone_number()),
     ("mobile", lambda: fake.phone_number()),
     ("fax", lambda: fake.phone_number()),
-    ("street", lambda: fake.street_address()),
-    ("address", lambda: fake.address().replace("\n", ", ")),
-    ("city", lambda: fake.city()),
-    ("province", lambda: fake.state()),
-    ("state", lambda: fake.state()),
-    ("country", lambda: fake.country()),
-    ("zip", lambda: fake.postcode()),
-    ("postal", lambda: fake.postcode()),
+    ("street", _FromRow("address", "street")),
+    ("address", _FromRow("address", "full")),
+    ("city", _FromRow("address", "city")),
+    ("province", _FromRow("address", "state")),
+    ("state", _FromRow("address", "state")),
+    ("country", _FromRow("address", "country")),
+    ("zip", _FromRow("address", "postcode")),
+    ("postal", _FromRow("address", "postcode")),
     ("homepage", lambda: fake.url()),
     ("website", lambda: fake.url()),
     ("url", lambda: fake.url()),
@@ -141,7 +384,7 @@ def get_duplicate_unique_columns() -> list[str]:
     return list(_duplicate_unique_columns)
 
 
-def _infer_by_name(column_name: str) -> Optional[Callable[[], object]]:
+def _infer_by_name(column_name: str) -> Optional[_Provider]:
     normalized = re.sub(r"[^a-z0-9]+", "_", column_name.lower())
     padded = f"_{normalized}_"
     for pattern, generator in _NAME_PATTERNS:
@@ -156,8 +399,27 @@ def _infer_by_name(column_name: str) -> Optional[Callable[[], object]]:
 # declaration in any schema would stop generating emails.
 _SQL_TYPES_SHADOWING_A_PROVIDER = frozenset({"text", "json", "jsonb", "xml", "binary", "year"})
 
-
-def _infer_by_type(base_type: str) -> Optional[Callable[[], object]]:
+# Declared types that name a person or address field. `contact email` says
+# exactly what a column called `email` says, so it has to reach the same row --
+# otherwise row-level coherence has a second door it does not cover.
+_ROW_TYPE_FIELDS = {
+    "first_name": ("person", "first_name"),
+    "last_name": ("person", "last_name"),
+    "name": ("person", "full_name"),
+    "user_name": ("person", "user_name"),
+    "username": ("person", "user_name"),
+    "email": ("person", "email"),
+    "address": ("address", "full"),
+    "street_address": ("address", "street"),
+    "city": ("address", "city"),
+    "state": ("address", "state"),
+    "province": ("address", "state"),
+    "country": ("address", "country"),
+    "postcode": ("address", "postcode"),
+}
+
+
+def _infer_by_type(base_type: str) -> Optional[_Provider]:
     """The provider a column's declared type names, if it names one deliberately.
 
     `sku ean13` and `home_state state` are the user saying which generator they
@@ -169,6 +431,9 @@ def _infer_by_type(base_type: str) -> Optional[Callable[[], object]]:
     """
     if base_type in _SQL_TYPES_SHADOWING_A_PROVIDER:
         return None
+    row_field = _ROW_TYPE_FIELDS.get(base_type)
+    if row_field is not None:
+        return _FromRow(*row_field)
     try:
         fake.format(base_type)
     except (AttributeError, TypeError):
@@ -311,7 +576,12 @@ def generate_column_values(
     # -----------------------------------------------------
     else:
         generator = _infer_by_type(base_type) or _infer_by_name(column.name)
-        if generator is not None:
+        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 ensure_unique:
+                values = _deduplicate_identity(values)
+        elif generator is not None:
             values = [generator() for _ in range(row_count)]
             values = (
                 _deduplicate(values, generator, column_name=unique_label)
@@ -375,6 +645,35 @@ def _deduplicate(
     return result
 
 
+def _deduplicate_identity(values: list) -> list:
+    """Make identity-derived values unique without swapping the person.
+
+    `_deduplicate` resolves a collision by calling the generator again, which
+    for an identity column would hand row i a different person's email and undo
+    the coherence this module just established. Suffixing keeps the row's
+    identity and disambiguates only the value, the way a real system issues
+    `jane.doe2@...` once `jane.doe@...` is taken. It also always succeeds, so
+    an identity column never lands in `_duplicate_unique_columns`.
+    """
+    seen: set = set()
+    result = []
+    for value in values:
+        candidate = value
+        counter = 1
+        while candidate in seen:
+            counter += 1
+            candidate = _suffixed(str(value), counter)
+        seen.add(candidate)
+        result.append(candidate)
+    return result
+
+
+def _suffixed(value: str, counter: int) -> str:
+    """Append a disambiguating number, before the @ when the value is an email."""
+    local, at, domain = value.partition("@")
+    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.
 
@@ -390,3 +689,8 @@ def _random_datetime(start_days: int = -365, end_days: int = 0) -> datetime:
     end = midnight + timedelta(days=end_days)
     random_second = random.randint(0, int((end - start).total_seconds()))
     return start + timedelta(seconds=random_second)
+
+
+# The default locale's constants, resolved at import so the first generation
+# does not pay for them and `set_locale`'s early return stays correct.
+_resolve_locale()

{model2data-1.2.0 → model2data-1.3.0/model2data.egg-info}/PKG-INFO

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

{model2data-1.2.0 → model2data-1.3.0}/model2data.egg-info/SOURCES.txt

@@ -33,4 +33,5 @@ tests/test_dbt_project.py
 tests/test_dbt_tests.py
 tests/test_faker_name_inference.py
 tests/test_generation.py
-tests/test_release_stress.py
+tests/test_release_stress.py
+tests/test_row_identity.py

{model2data-1.2.0 → model2data-1.3.0}/pyproject.toml

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

model2data-1.3.0/tests/test_row_identity.py

@@ -0,0 +1,372 @@
+"""Person-shaped columns in one row have to describe one person.
+
+Columns are generated independently, one at a time, so before the identity
+pool a single row's first_name, last_name and email came from three unrelated
+Faker draws. These tests pin the row-level agreement, and the two properties it
+must not cost: reproducibility under a seed, and uniqueness where it is asked
+for.
+"""
+
+import re
+
+import pytest
+from faker import Faker
+
+import model2data.generate.faker as faker_module
+from model2data.generate.core import generate_data_from_dbml
+from model2data.generate.faker import (
+    DEFAULT_LOCALE,
+    _slug,
+    current_locale,
+    generate_column_values,
+    reset_row_pools,
+    set_locale,
+)
+from model2data.parse.dbml import ColumnDef, TableDef
+
+
+def _person_table(name: str = "customers", columns: list[ColumnDef] | None = None) -> TableDef:
+    return TableDef(
+        name=name,
+        columns=columns
+        or [
+            ColumnDef(name="first_name", data_type="varchar", settings={"not null"}),
+            ColumnDef(name="last_name", data_type="varchar", settings={"not null"}),
+            ColumnDef(name="full_name", data_type="varchar", settings={"not null"}),
+            ColumnDef(name="user_name", data_type="varchar", settings={"not null"}),
+            ColumnDef(name="email", data_type="varchar", settings={"not null"}),
+        ],
+    )
+
+
+def _assert_row_is_one_person(row) -> None:
+    first, last = row["first_name"], row["last_name"]
+    assert row["full_name"] == f"{first} {last}"
+    assert row["email"].startswith(f"{_slug(first)}.{_slug(last)}@")
+    assert row["user_name"] == f"{_slug(first)[:1]}{_slug(last)}"
+
+
+class TestRowIdentityCoherence:
+    def test_person_columns_in_a_row_describe_one_person(self):
+        frames = generate_data_from_dbml(
+            tables={"customers": _person_table()}, refs=[], base_rows=25, seed=1
+        )
+        df = frames["customers"]
+        assert len(df) == 25
+        for _, row in df.iterrows():
+            _assert_row_is_one_person(row)
+
+    def test_two_tables_draw_from_different_populations(self):
+        frames = generate_data_from_dbml(
+            tables={
+                "customers": _person_table("customers"),
+                "employees": _person_table("employees"),
+            },
+            refs=[],
+            base_rows=30,
+            seed=2,
+        )
+        # Asserted on the keying rather than on the values. "These two sets of
+        # emails do not overlap" is true here, but only by a probability -- the
+        # same shape of luck-based assertion that made the password test fail
+        # the first time the RNG moved.
+        customers_pool = faker_module._row_pool("person", "customers", 30)
+        employees_pool = faker_module._row_pool("person", "employees", 30)
+        assert customers_pool is not employees_pool
+
+        # And the values follow from that: two tables of people are two groups
+        # of people, not one pool handed out twice.
+        assert list(frames["customers"]["email"]) != list(frames["employees"]["email"])
+
+    def test_same_seed_reproduces_the_same_people(self):
+        def run():
+            return generate_data_from_dbml(
+                tables={"customers": _person_table()}, refs=[], base_rows=15, seed=7
+            )["customers"]
+
+        first_run, second_run = run(), run()
+        assert list(first_run["email"]) == list(second_run["email"])
+        assert list(first_run["full_name"]) == list(second_run["full_name"])
+
+    def test_unique_email_stays_unique_without_swapping_the_person(self):
+        # A tiny name space forces collisions, so the suffixing path actually
+        # runs rather than being skipped because every value happened to differ.
+        table = _person_table(
+            columns=[
+                ColumnDef(name="first_name", data_type="varchar", settings={"not null"}),
+                ColumnDef(name="last_name", data_type="varchar", settings={"not null"}),
+                ColumnDef(name="email", data_type="varchar", settings={"not null", "unique"}),
+            ],
+        )
+        df = generate_data_from_dbml(tables={"customers": table}, refs=[], base_rows=400, seed=3)[
+            "customers"
+        ]
+
+        assert df["email"].is_unique
+        for _, row in df.iterrows():
+            # The suffix may sit before the @, but the row's own name is still
+            # what the address is built from.
+            local = row["email"].split("@")[0]
+            assert re.fullmatch(
+                rf"{re.escape(_slug(row['first_name']))}\.{re.escape(_slug(row['last_name']))}\d*",
+                local,
+            )
+
+    def test_declared_email_type_also_reaches_the_identity(self):
+        table = TableDef(
+            name="contacts",
+            columns=[
+                ColumnDef(name="first_name", data_type="varchar", settings={"not null"}),
+                ColumnDef(name="last_name", data_type="varchar", settings={"not null"}),
+                # Declared as a provider rather than named `email`.
+                ColumnDef(name="contact", data_type="email", settings={"not null"}),
+            ],
+        )
+        df = generate_data_from_dbml(tables={"contacts": table}, refs=[], base_rows=20, seed=4)[
+            "contacts"
+        ]
+        for _, row in df.iterrows():
+            assert row["contact"].startswith(
+                f"{_slug(row['first_name'])}.{_slug(row['last_name'])}@"
+            )
+
+    def test_email_declared_as_text_is_still_an_email(self):
+        # `email text` means the SQL type; the name inference must still win,
+        # and still go through the identity.
+        table = TableDef(
+            name="people",
+            columns=[
+                ColumnDef(name="first_name", data_type="varchar", settings={"not null"}),
+                ColumnDef(name="last_name", data_type="varchar", settings={"not null"}),
+                ColumnDef(name="email", data_type="text", settings={"not null"}),
+            ],
+        )
+        df = generate_data_from_dbml(tables={"people": table}, refs=[], base_rows=10, seed=5)[
+            "people"
+        ]
+        for _, row in df.iterrows():
+            assert row["email"].startswith(f"{_slug(row['first_name'])}.{_slug(row['last_name'])}@")
+
+    def test_password_column_is_not_identity_derived(self):
+        # `password` sits between `username` and `email` in the pattern list, so
+        # it is the entry most at risk of having been swept into the identity
+        # work. Asserted against the pattern table rather than the output: an
+        # earlier version of this test looked for "@" in the generated password,
+        # which passed only by luck -- Faker's passwords include punctuation, "@"
+        # among it, so the test failed the first time the RNG moved.
+        assert isinstance(faker_module._infer_by_name("email"), faker_module._FromRow)
+        assert not isinstance(faker_module._infer_by_name("password"), faker_module._FromRow)
+
+        table = TableDef(
+            name="users",
+            columns=[
+                ColumnDef(name="first_name", data_type="varchar", settings={"not null"}),
+                ColumnDef(name="last_name", data_type="varchar", settings={"not null"}),
+                ColumnDef(name="email", data_type="varchar", settings={"not null"}),
+                ColumnDef(name="password", data_type="varchar", settings={"not null"}),
+            ],
+        )
+        df = generate_data_from_dbml(tables={"users": table}, refs=[], base_rows=20, seed=21)[
+            "users"
+        ]
+        assert df["password"].nunique() == 20
+        for _, row in df.iterrows():
+            # Exact comparison, not a substring heuristic: the password must not
+            # be one of the identity's own values.
+            assert row["password"] not in {row["first_name"], row["last_name"], row["email"]}
+
+    def test_non_person_columns_are_untouched(self):
+        reset_row_pools()
+        cities = generate_column_values(
+            ColumnDef(name="city", data_type="varchar", settings={"not null"}),
+            row_count=10,
+            table_name="places",
+        )
+        assert len(cities) == 10
+        assert all(isinstance(city, str) and city for city in cities)
+
+
+@pytest.fixture(autouse=True)
+def _restore_locale():
+    """Locale is process-wide state, so a test that changes it must not leak."""
+    yield
+    set_locale(None)
+    # set_locale returns early when the locale is already the default, which
+    # would leave the cached per-locale constants behind for any test that
+    # stubbed `fake` rather than switching locale. Re-resolve unconditionally.
+    faker_module._resolve_locale()
+
+
+def _address_table(name: str = "sites") -> TableDef:
+    return TableDef(
+        name=name,
+        columns=[
+            ColumnDef(name="street", data_type="varchar", settings={"not null"}),
+            ColumnDef(name="address", data_type="varchar", settings={"not null"}),
+            ColumnDef(name="city", data_type="varchar", settings={"not null"}),
+            ColumnDef(name="state", data_type="varchar", settings={"not null"}),
+            ColumnDef(name="country", data_type="varchar", settings={"not null"}),
+            ColumnDef(name="zip", data_type="varchar", settings={"not null"}),
+        ],
+    )
+
+
+class TestAddressCoherence:
+    def test_address_column_is_built_from_the_row_beside_it(self):
+        df = generate_data_from_dbml(
+            tables={"sites": _address_table()}, refs=[], base_rows=20, seed=11
+        )["sites"]
+        for _, row in df.iterrows():
+            # The composed address has to be this row's street, city and
+            # postcode -- not a separate draw that happens to look like one.
+            assert row["street"] in row["address"]
+            assert row["city"] in row["address"]
+            assert row["zip"] in row["address"]
+
+    def test_every_row_is_in_one_country(self):
+        df = generate_data_from_dbml(
+            tables={"sites": _address_table()}, refs=[], base_rows=30, seed=12
+        )["sites"]
+        # The old behaviour drew country independently, so a US street could sit
+        # in Japan. One locale means one country, on every row.
+        assert set(df["country"]) == {"United States"}
+
+    def test_declared_city_type_agrees_with_the_row(self):
+        table = TableDef(
+            name="offices",
+            columns=[
+                ColumnDef(name="address", data_type="varchar", settings={"not null"}),
+                # Declared as a provider rather than named `city`.
+                ColumnDef(name="located_in", data_type="city", settings={"not null"}),
+            ],
+        )
+        df = generate_data_from_dbml(tables={"offices": table}, refs=[], base_rows=15, seed=13)[
+            "offices"
+        ]
+        for _, row in df.iterrows():
+            assert row["located_in"] in row["address"]
+
+
+class TestLocale:
+    def test_default_locale_is_the_documented_one(self):
+        assert current_locale() == DEFAULT_LOCALE
+
+    def test_locale_changes_the_country_and_the_addresses(self):
+        def country_and_cities(locale):
+            df = generate_data_from_dbml(
+                tables={"sites": _address_table()},
+                refs=[],
+                base_rows=20,
+                seed=14,
+                locale=locale,
+            )["sites"]
+            return set(df["country"]), set(df["city"])
+
+        us_country, us_cities = country_and_cities(None)
+        be_country, be_cities = country_and_cities("nl_BE")
+
+        assert us_country == {"United States"}
+        assert be_country == {"Belgium"}
+        assert not us_cities & be_cities
+
+    def test_locale_applies_to_people_too(self):
+        df = generate_data_from_dbml(
+            tables={"customers": _person_table()},
+            refs=[],
+            base_rows=20,
+            seed=15,
+            locale="fr_FR",
+        )["customers"]
+        # Still coherent, just French: the pool swap must not break the
+        # first.last@domain derivation.
+        for _, row in df.iterrows():
+            _assert_row_is_one_person(row)
+
+    def test_locale_is_restored_between_runs(self):
+        generate_data_from_dbml(
+            tables={"sites": _address_table()}, refs=[], base_rows=2, seed=16, locale="nl_BE"
+        )
+        assert current_locale() == "nl_BE"
+        # Passing nothing means the default, not "whatever the last run used".
+        generate_data_from_dbml(tables={"sites": _address_table()}, refs=[], base_rows=2, seed=16)
+        assert current_locale() == DEFAULT_LOCALE
+
+    def test_unknown_locale_says_so_plainly(self):
+        with pytest.raises(ValueError, match="Unknown locale 'zz_ZZ'"):
+            generate_data_from_dbml(
+                tables={"sites": _address_table()}, refs=[], base_rows=2, locale="zz_ZZ"
+            )
+
+
+class TestPoolLifetime:
+    def test_pools_are_released_once_a_table_is_finished(self):
+        # A million-row table is a normal request; holding its identities for
+        # the rest of the run is what makes that unaffordable.
+        generate_data_from_dbml(
+            tables={"customers": _person_table(), "sites": _address_table()},
+            refs=[],
+            base_rows=50,
+            seed=17,
+        )
+        assert faker_module._person_state == {}
+        assert faker_module._address_state == {}
+
+    def test_pool_rows_stay_small(self):
+        # Slots rather than a per-instance __dict__. Worth a test because the
+        # difference is ~6x per row (344 bytes vs 56), the derived fields are
+        # properties precisely so they are not stored, and a million-row person
+        # table is a normal request -- an innocent-looking field added here
+        # would cost hundreds of megabytes on one.
+        assert not hasattr(faker_module._new_person(), "__dict__")
+        assert not hasattr(faker_module._new_address(), "__dict__")
+
+
+class _LocaleMissing:
+    """A Faker with named providers removed, standing in for a thinner locale.
+
+    Every locale Faker actually ships has `current_country` and at least one
+    administrative unit, so the fallbacks for a locale without them cannot be
+    reached by naming a real one -- but they still decide what lands in a
+    column, and the docstrings make a claim about what they do. This stands in
+    for the locale that would reach them.
+    """
+
+    def __init__(self, inner, missing):
+        self._inner = inner
+        self._missing = set(missing)
+
+    def format(self, name, *args, **kwargs):
+        if name in self._missing:
+            raise AttributeError(name)
+        return self._inner.format(name, *args, **kwargs)
+
+    def __getattr__(self, name):
+        if name in self._missing:
+            raise AttributeError(name)
+        return getattr(self._inner, name)
+
+
+class TestThinLocales:
+    def test_no_administrative_unit_leaves_state_empty(self, monkeypatch):
+        stub = _LocaleMissing(
+            Faker("en_US"), {"state", "province", "administrative_unit", "region"}
+        )
+        monkeypatch.setattr(faker_module, "fake", stub)
+        faker_module._resolve_locale()
+
+        address = faker_module._new_address()
+        # Empty is the honest answer for a country with no region worth naming.
+        # Inventing one just to fill the column would be worse data, not better.
+        assert address.state == ""
+        assert address.city and address.street and address.country
+
+    def test_no_current_country_still_puts_every_row_in_one_country(self, monkeypatch):
+        stub = _LocaleMissing(Faker("en_US"), {"current_country"})
+        monkeypatch.setattr(faker_module, "fake", stub)
+        faker_module._resolve_locale()
+
+        countries = {faker_module._new_address().country for _ in range(10)}
+        # The point of the fallback is agreement, not accuracy: one country
+        # picked once beats a different random country on every row.
+        assert len(countries) == 1
+        assert countries != {""}

model2data-1.2.0/model2data/__init__.py

@@ -1,3 +0,0 @@
-"""Model2Data: Generate analytics-ready datasets from DBML models."""
-
-__version__ = "0.1.1"