fakerforge 0.1.0__py3-none-any.whl

fakerforge/__init__.py

@@ -0,0 +1,7 @@
+"""Synthetic data generation built on the Faker library."""
+
+from fakerforge.faker import FakerForge
+
+__version__ = "0.1.0"
+
+__all__ = ["FakerForge", "__version__"]

fakerforge/constraints/__init__.py

@@ -0,0 +1,5 @@
+"""Constraint extension point."""
+
+from fakerforge.constraints.base import Constraint
+
+__all__ = ["Constraint"]

fakerforge/constraints/base.py

@@ -0,0 +1,35 @@
+"""Base class for value constraints."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Constraint(ABC):
+    """A predicate that accepts or rejects a single generated value.
+
+    Subclasses implement :meth:`check`. Built-in constraint types are not
+    part of this release.
+    """
+
+    @abstractmethod
+    def check(self, value: Any) -> bool:
+        """Return whether ``value`` satisfies this constraint.
+
+        Args:
+            value: Generated field value.
+
+        Returns:
+            ``True`` when the value is accepted.
+        """
+
+    def message(self, field: str, value: Any) -> str:
+        """Describe a failed check.
+
+        Args:
+            field: Record field name.
+            value: Value that failed :meth:`check`.
+
+        Returns:
+            A short failure message.
+        """
+        return f"{field!r} failed {type(self).__name__}: {value!r}"

fakerforge/distributions/__init__.py

@@ -0,0 +1,6 @@
+"""Distribution sampling."""
+
+from fakerforge.distributions.base import Distribution
+from fakerforge.distributions.engine import DistributionEngine, DistributionError
+
+__all__ = ["Distribution", "DistributionEngine", "DistributionError"]

fakerforge/distributions/base.py

@@ -0,0 +1,26 @@
+"""Base class for sampling distributions."""
+
+import random
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Distribution(ABC):
+    """A reproducible sampling strategy.
+
+    Implementations must draw randomness only from the :class:`random.Random`
+    instance passed to :meth:`sample`. Built-in uniform, normal, log-normal,
+    and categorical sampling lives on
+    :class:`fakerforge.distributions.DistributionEngine`.
+    """
+
+    @abstractmethod
+    def sample(self, rng: random.Random) -> Any:
+        """Draw one value.
+
+        Args:
+            rng: Random instance owned by the caller.
+
+        Returns:
+            The sampled value.
+        """

fakerforge/distributions/engine.py

@@ -0,0 +1,335 @@
+"""Seeded sampling for numeric and categorical values.
+
+``DistributionEngine`` is the API the schema generator should call. It keeps
+its own random stream, seeded from the same value as ``FakerForge``, so
+distribution draws stay reproducible and do not consume Faker provider draws.
+"""
+
+import hashlib
+import math
+import random
+from collections.abc import Sequence
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+# Matches ``fakerforge.faker.Seed`` without importing that module.
+Seed = int | float | str | bytes | bytearray | None
+
+MAX_REJECTION_ATTEMPTS = 1000
+
+_NUMERIC = ("uniform", "normal", "lognormal")
+
+
+class DistributionError(ValueError):
+    """Raised when sampling cannot satisfy a hard bound.
+
+    Normal and log-normal bounds are inclusive. Draws outside the bounds are
+    discarded and sampled again. They are never clipped to ``min`` or ``max``.
+    This error means every attempt fell outside the bounds.
+    """
+
+
+class DistributionEngine:
+    """Sample uniform, normal, log-normal, and categorical values.
+
+    NumPy is used when it is installed. Without NumPy, the engine samples
+    with :mod:`random`. The two backends are each deterministic for a seed,
+    and they do not produce the same series.
+
+    Args:
+        seed: Seed for this engine's random stream. ``None`` draws entropy
+            from the operating system.
+        use_numpy: ``True`` requires NumPy, ``False`` uses the standard
+            library, and ``None`` uses NumPy when it imports.
+    """
+
+    def __init__(
+        self, seed: Seed | None = None, *, use_numpy: bool | None = None
+    ) -> None:
+        numpy = _import_numpy()
+        if use_numpy is True and numpy is None:
+            raise ImportError(
+                "NumPy is required for this distribution engine. "
+                "Install it with: pip install 'fakerforge[numpy]'"
+            )
+        self._numpy = numpy if use_numpy is not False else None
+        self._py_rng = random.Random(seed)
+        self._np_rng: Any = _numpy_generator(self._numpy, seed) if self._numpy else None
+
+    @property
+    def uses_numpy(self) -> bool:
+        """Return whether sampling is going through NumPy."""
+        return self._numpy is not None
+
+    def reseed(self, seed: Seed | None = None) -> None:
+        """Replace this engine's random stream.
+
+        Args:
+            seed: New seed. ``None`` draws entropy from the operating system.
+        """
+        self._py_rng.seed(seed)
+        if self._numpy is not None:
+            self._np_rng = _numpy_generator(self._numpy, seed)
+
+    def number(
+        self,
+        *,
+        distribution: str,
+        mean: float | None = None,
+        std: float | None = None,
+        min: float | None = None,
+        max: float | None = None,
+    ) -> float:
+        """Draw one float from a numeric distribution.
+
+        ``min`` and ``max`` are inclusive hard bounds for normal and
+        log-normal sampling. A draw outside those bounds is thrown away and
+        another draw is taken, up to ``MAX_REJECTION_ATTEMPTS``. The engine
+        does not clip a value to the nearest bound. If every attempt misses,
+        this method raises :class:`DistributionError`.
+
+        Uniform samples lie in the half-open interval ``[min, max)``. When
+        ``min == max``, uniform returns that value.
+
+        Log-normal ``mean`` and ``std`` are the mean and standard deviation
+        of the underlying normal distribution, matching NumPy's
+        ``Generator.lognormal``. Every untruncated log-normal sample is
+        greater than zero. ``min`` must be ``>= 0`` and ``max`` must be
+        ``> 0``.
+
+        Args:
+            distribution: ``"uniform"``, ``"normal"``, ``"lognormal"``, or
+                ``"log-normal"``.
+            mean: Required for normal and log-normal. Not accepted for uniform.
+            std: Required for normal and log-normal, and must be ``> 0``.
+                Not accepted for uniform.
+            min: Lower inclusive bound. Required for uniform.
+            max: Upper inclusive bound for normal and log-normal. Required
+                for uniform, where the upper end is exclusive unless it
+                equals ``min``.
+
+        Returns:
+            A Python ``float``.
+
+        Raises:
+            ValueError: The distribution name or parameters are invalid.
+            DistributionError: Normal or log-normal rejection sampling could
+                not find a value inside the bounds.
+        """
+        kind = _distribution_name(distribution)
+        lower = _optional_float(min, "min")
+        upper = _optional_float(max, "max")
+        _require_ordered(lower, upper)
+        if kind == "uniform":
+            _reject_unused(mean, "mean", kind)
+            _reject_unused(std, "std", kind)
+            if lower is None or upper is None:
+                raise ValueError("uniform requires min and max")
+            if lower == upper:
+                return lower
+            return self._uniform(lower, upper)
+        center = _required_float(mean, "mean")
+        scale = _required_float(std, "std")
+        if scale <= 0:
+            raise ValueError("std must be greater than 0")
+        if lower is not None and upper is not None and lower == upper:
+            raise ValueError(
+                f"{kind} bounds must span a range; values are not clipped to a point"
+            )
+        if kind == "lognormal":
+            _validate_lognormal_bounds(lower, upper)
+        draw = (
+            self._normal_draw(center, scale)
+            if kind == "normal"
+            else self._lognormal_draw(center, scale)
+        )
+        return _draw_until_in_bounds(draw, lower, upper, kind)
+
+    def categorical(
+        self,
+        values: Sequence[Any],
+        weights: Sequence[float] | None = None,
+    ) -> Any:
+        """Draw one of ``values``.
+
+        Omit ``weights`` for a uniform categorical distribution. Weights do
+        not need to sum to 1; they are normalized. Selection follows the
+        position in ``values``, so duplicate labels stay distinct.
+
+        Args:
+            values: Non-empty sequence of choices. Strings are not treated
+                as sequences of characters.
+            weights: Non-negative weights, one per value. At least one
+                weight must be positive.
+
+        Returns:
+            The chosen element of ``values``, unchanged.
+
+        Raises:
+            ValueError: ``values`` or ``weights`` are empty, misaligned, or
+                not a usable weight vector.
+            TypeError: A weight is not numeric.
+        """
+        choices = _choices(values)
+        if weights is None:
+            index = self._weighted_index(len(choices), None)
+        else:
+            index = self._weighted_index(len(choices), _weights(weights, len(choices)))
+        return choices[index]
+
+    def _uniform(self, low: float, high: float) -> float:
+        if self._np_rng is not None:
+            return float(self._np_rng.uniform(low, high))
+        return low + (high - low) * self._py_rng.random()
+
+    def _normal_draw(self, mean: float, std: float) -> Any:
+        if self._np_rng is not None:
+            rng = self._np_rng
+            return lambda: float(rng.normal(mean, std))
+        rng_py = self._py_rng
+        return lambda: rng_py.normalvariate(mean, std)
+
+    def _lognormal_draw(self, mean: float, std: float) -> Any:
+        if self._np_rng is not None:
+            rng = self._np_rng
+            return lambda: float(rng.lognormal(mean, std))
+        rng_py = self._py_rng
+        return lambda: rng_py.lognormvariate(mean, std)
+
+    def _weighted_index(self, count: int, weights: list[float] | None) -> int:
+        numpy = self._numpy
+        if self._np_rng is not None and numpy is not None:
+            probabilities = (
+                None if weights is None else _numpy_probabilities(numpy, weights)
+            )
+            return int(self._np_rng.choice(count, p=probabilities))
+        if weights is None:
+            return self._py_rng.randrange(count)
+        return self._py_rng.choices(range(count), weights=weights, k=1)[0]
+
+
+def _draw_until_in_bounds(
+    draw: Any,
+    lower: float | None,
+    upper: float | None,
+    distribution: str,
+) -> float:
+    for _ in range(MAX_REJECTION_ATTEMPTS):
+        value = float(draw())
+        if _inside(value, lower, upper):
+            return value
+    raise DistributionError(
+        f"{distribution} sample fell outside {_bound_label(lower, upper)} on "
+        f"{MAX_REJECTION_ATTEMPTS} consecutive draws. Bounds are inclusive "
+        "and out-of-range draws are discarded, not clipped."
+    )
+
+
+def _inside(value: float, lower: float | None, upper: float | None) -> bool:
+    if lower is not None and value < lower:
+        return False
+    if upper is not None and value > upper:
+        return False
+    return True
+
+
+def _bound_label(lower: float | None, upper: float | None) -> str:
+    low = "-inf" if lower is None else repr(lower)
+    high = "inf" if upper is None else repr(upper)
+    return f"[{low}, {high}]"
+
+
+def _distribution_name(distribution: str) -> str:
+    if not isinstance(distribution, str):
+        raise TypeError("distribution must be a string")
+    name = distribution.strip().lower().replace("-", "")
+    if name not in _NUMERIC:
+        allowed = "uniform, normal, lognormal"
+        raise ValueError(
+            f"unknown distribution {distribution!r}; expected one of {allowed}"
+        )
+    return name
+
+
+def _optional_float(value: object, label: str) -> float | None:
+    if value is None:
+        return None
+    return _finite_float(value, label)
+
+
+def _required_float(value: object, label: str) -> float:
+    if value is None:
+        raise ValueError(f"{label} is required")
+    return _finite_float(value, label)
+
+
+def _finite_float(value: object, label: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError(f"{label} must be an int or float")
+    number = float(value)
+    if not math.isfinite(number):
+        raise ValueError(f"{label} must be finite")
+    return number
+
+
+def _reject_unused(value: object, label: str, distribution: str) -> None:
+    if value is not None:
+        raise ValueError(f"{distribution} does not accept {label}")
+
+
+def _require_ordered(lower: float | None, upper: float | None) -> None:
+    if lower is not None and upper is not None and lower > upper:
+        raise ValueError("min must be less than or equal to max")
+
+
+def _validate_lognormal_bounds(lower: float | None, upper: float | None) -> None:
+    if lower is not None and lower < 0:
+        raise ValueError("lognormal min must be greater than or equal to 0")
+    if upper is not None and upper <= 0:
+        raise ValueError("lognormal max must be greater than 0")
+
+
+def _choices(values: Sequence[Any]) -> Sequence[Any]:
+    if isinstance(values, (str, bytes)) or not isinstance(values, Sequence):
+        raise TypeError("values must be a sequence of choices")
+    if len(values) == 0:
+        raise ValueError("values must not be empty")
+    return values
+
+
+def _weights(weights: Sequence[float], count: int) -> list[float]:
+    if isinstance(weights, (str, bytes)) or not isinstance(weights, Sequence):
+        raise TypeError("weights must be a sequence of numbers")
+    if len(weights) != count:
+        raise ValueError("weights must have the same length as values")
+    parsed = [_finite_float(weight, "weight") for weight in weights]
+    if any(weight < 0 for weight in parsed):
+        raise ValueError("weights must be greater than or equal to 0")
+    if sum(parsed) <= 0:
+        raise ValueError("at least one weight must be greater than 0")
+    return parsed
+
+
+def _numpy_probabilities(numpy: ModuleType, weights: list[float]) -> Any:
+    probabilities = numpy.asarray(weights, dtype=float)
+    total = float(probabilities.sum())
+    return probabilities / total
+
+
+def _import_numpy() -> ModuleType | None:
+    try:
+        return import_module("numpy")
+    except ImportError:
+        return None
+
+
+def _numpy_generator(numpy: ModuleType, seed: Seed | None) -> Any:
+    return numpy.random.default_rng(_numpy_seed(seed))
+
+
+def _numpy_seed(seed: Seed | None) -> int | None:
+    if seed is None:
+        return None
+    digest = hashlib.sha256(repr(seed).encode("utf-8")).digest()
+    return int.from_bytes(digest[:8], "big")

fakerforge/faker.py

@@ -0,0 +1,200 @@
+"""Faker-compatible entry point."""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from faker import Faker
+from faker.providers import BaseProvider
+
+from fakerforge.distributions.engine import DistributionEngine
+from fakerforge.providers.finance import FinanceProvider
+from fakerforge.schema.dataset import DatabaseSchema, DatasetSchema
+from fakerforge.schema.generate import generate_dataset
+from fakerforge.schema.result import DatabaseResult, DatasetResult
+
+# Matches ``faker.typing.SeedType`` without depending on a private module.
+Seed = int | float | str | bytes | bytearray | None
+
+# Registered on every instance. Later ``add_provider`` calls take precedence.
+_BUILTIN_PROVIDERS: tuple[type[BaseProvider], ...] = (FinanceProvider,)
+
+
+class FakerForge:
+    """Wrapper around a :class:`faker.Faker` instance.
+
+    Attributes and methods that FakerForge does not define are delegated to
+    the underlying Faker instance. Built-in domain providers, including
+    finance, are registered with ``add_provider`` and use that instance's
+    random generator. Numeric and categorical distributions use a separate
+    :class:`~fakerforge.distributions.DistributionEngine` seeded with the
+    same value. Seeding uses ``seed_instance``, so it affects only this
+    object and leaves Faker's shared random state alone.
+
+    Args:
+        locale: Locale or sequence of locales forwarded to Faker. ``None``
+            selects Faker's default locale.
+        seed: Seed forwarded to ``seed_instance``. ``None`` leaves this
+            instance unseeded.
+        providers: Extra providers registered after the built-in providers.
+            Each item may be a provider class or an already constructed
+            provider. A provider added here overrides a built-in method of
+            the same name.
+    """
+
+    def __init__(
+        self,
+        locale: str | Sequence[str] | None = None,
+        *,
+        seed: Seed | None = None,
+        providers: Sequence[type[BaseProvider] | BaseProvider] | None = None,
+    ) -> None:
+        if locale is None:
+            self._faker = Faker()
+        else:
+            self._faker = Faker(locale)
+        self._seed = seed
+        self._distributions = DistributionEngine(seed)
+        if seed is not None:
+            self._faker.seed_instance(seed)
+        registered: tuple[type[BaseProvider] | BaseProvider, ...] = _BUILTIN_PROVIDERS
+        if providers:
+            registered = (*registered, *providers)
+        for provider in registered:
+            self.add_provider(provider)
+
+    @property
+    def faker(self) -> Faker:
+        """Return the wrapped Faker instance."""
+        return self._faker
+
+    def seed_instance(self, seed: Seed | None = None) -> None:
+        """Reseed this instance only.
+
+        This reseeds both the wrapped Faker generator and the distribution
+        engine.
+
+        Args:
+            seed: Seed forwarded to ``Faker.seed_instance`` and the
+                distribution engine.
+        """
+        self._seed = seed
+        self._faker.seed_instance(seed)
+        self._distributions.reseed(seed)
+
+    @property
+    def distributions(self) -> DistributionEngine:
+        """Return the seeded distribution engine.
+
+        Schema generation should sample through this object so numeric draws
+        stay on the engine's random stream.
+        """
+        return self._distributions
+
+    def number(
+        self,
+        *,
+        distribution: str,
+        mean: float | None = None,
+        std: float | None = None,
+        min: float | None = None,
+        max: float | None = None,
+    ) -> float:
+        """Draw one float from ``distribution``.
+
+        See :meth:`DistributionEngine.number` for parameters, inclusive
+        normal and log-normal bounds, and the rejection rule. Out-of-range
+        normal and log-normal draws are discarded, not clipped.
+
+        Args:
+            distribution: ``"uniform"``, ``"normal"``, ``"lognormal"``, or
+                ``"log-normal"``.
+            mean: Required for normal and log-normal.
+            std: Required for normal and log-normal, and must be ``> 0``.
+            min: Lower bound. Required for uniform.
+            max: Upper bound. Required for uniform.
+
+        Returns:
+            A Python ``float``.
+        """
+        return self._distributions.number(
+            distribution=distribution,
+            mean=mean,
+            std=std,
+            min=min,
+            max=max,
+        )
+
+    def categorical(
+        self,
+        values: Sequence[Any],
+        weights: Sequence[float] | None = None,
+    ) -> Any:
+        """Draw one of ``values``, optionally with weights.
+
+        Args:
+            values: Non-empty sequence of choices.
+            weights: Non-negative weights, one per value. Omit them for a
+                uniform categorical draw.
+
+        Returns:
+            The chosen element of ``values``.
+        """
+        return self._distributions.categorical(values, weights)
+
+    def generate(
+        self,
+        schema: Mapping[str, Any] | DatasetSchema | DatabaseSchema,
+        *,
+        rows: int | Mapping[str, int] | None = None,
+    ) -> DatasetResult | DatabaseResult:
+        """Generate a dataset from a declarative schema.
+
+        The schema is validated before any row is produced. Integer ``min``
+        and ``max`` are inclusive. Float fields use the half-open uniform
+        interval ``[min, max)``. ``nullable`` fields are ``None`` with
+        probability ``null_probability`` (default ``0.1``). Unique fields
+        never repeat a non-null value; nulls may repeat. Derived fields are
+        computed from an earlier field. A date that depends on a date is
+        drawn on or after that date. Foreign keys are copied from parent
+        rows that were already generated.
+
+        Args:
+            schema: A field mapping, a parsed dataset, or a relational
+                mapping of tables.
+            rows: Row count for a single table, or a mapping of table name
+                to row count. Relational tables may instead set ``rows``
+                on each table.
+
+        Returns:
+            A ``DatasetResult`` for one table, or a ``DatabaseResult`` whose
+            keys are table names. Both expose ``validate()``. ``rows`` holds
+            the records, and ``frame`` is a DataFrame when pandas is installed.
+
+        Raises:
+            ValueError: ``rows`` is missing or not a non-negative integer.
+            SchemaError: The schema is invalid for this instance.
+            GenerationError: A unique column or foreign key cannot be filled
+                without inventing a value.
+        """
+        return generate_dataset(self, schema, rows=rows)
+
+    def add_provider(self, provider: type[BaseProvider] | BaseProvider) -> None:
+        """Register a Faker provider on the underlying instance.
+
+        Args:
+            provider: Provider class or instance accepted by
+                ``Faker.add_provider``.
+        """
+        self._faker.add_provider(provider)
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate unknown attribute lookup to the wrapped Faker instance."""
+        return getattr(self._faker, name)
+
+    def __dir__(self) -> list[str]:
+        """Include delegated Faker attributes in interactive completion."""
+        return sorted(set(super().__dir__()) | set(dir(self._faker)))
+
+    def __repr__(self) -> str:
+        locales = getattr(self._faker, "locales", None)
+        return f"FakerForge(locales={locales!r}, seed={self._seed!r})"

fakerforge/generator/__init__.py

@@ -0,0 +1,5 @@
+"""Schema-driven record generation."""
+
+from fakerforge.generator.generator import Generator
+
+__all__ = ["Generator"]

fakerforge/generator/generator.py

@@ -0,0 +1,68 @@
+"""Generate records by calling Faker provider methods."""
+
+from typing import Any
+
+from fakerforge.faker import FakerForge
+from fakerforge.schema.schema import Schema
+
+
+class Generator:
+    """Build records from a :class:`~fakerforge.schema.Schema`.
+
+    Each field calls the named provider on the supplied
+    :class:`~fakerforge.FakerForge`. The generator does not reseed; pass a
+    seeded forge when results must be reproducible.
+
+    Args:
+        forge: FakerForge instance used to resolve provider methods.
+    """
+
+    def __init__(self, forge: FakerForge) -> None:
+        if not isinstance(forge, FakerForge):
+            raise TypeError("forge must be a FakerForge instance")
+        self._forge = forge
+
+    @property
+    def forge(self) -> FakerForge:
+        """Return the forge used to populate records."""
+        return self._forge
+
+    def generate_one(self, schema: Schema) -> dict[str, Any]:
+        """Generate a single record.
+
+        Args:
+            schema: Fields to populate.
+
+        Returns:
+            A dictionary keyed by field name.
+
+        Raises:
+            TypeError: ``schema`` is not a :class:`Schema`, or a provider
+                attribute is not callable.
+        """
+        if not isinstance(schema, Schema):
+            raise TypeError("schema must be a Schema instance")
+        record: dict[str, Any] = {}
+        for column in schema.fields:
+            method = getattr(self._forge, column.provider)
+            if not callable(method):
+                raise TypeError(f"provider {column.provider!r} is not callable")
+            record[column.name] = method(**dict(column.kwargs))
+        return record
+
+    def generate(self, schema: Schema, *, count: int) -> list[dict[str, Any]]:
+        """Generate ``count`` records.
+
+        Args:
+            schema: Fields to populate.
+            count: Number of records. Zero yields an empty list.
+
+        Returns:
+            Records in generation order.
+
+        Raises:
+            ValueError: ``count`` is not a non-negative integer.
+        """
+        if isinstance(count, bool) or not isinstance(count, int) or count < 0:
+            raise ValueError("count must be a non-negative integer")
+        return [self.generate_one(schema) for _ in range(count)]