polarfactory 0.1.0__tar.gz

polarfactory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Castro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

polarfactory-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: polarfactory
+Version: 0.1.0
+Summary: Generate Python objects filled with realistic test data.
+Keywords: testing,test data,factory,fixtures,dataclasses,pydantic
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.11 ; extra == 'pydantic'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/PinnLabs/Polars
+Project-URL: Documentation, https://pinnlabs.github.io/Polars/
+Project-URL: Changelog, https://github.com/PinnLabs/Polars/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/PinnLabs/Polars/issues
+Provides-Extra: pydantic
+Description-Content-Type: text/markdown
+
+# polarfactory
+
+Generate Python objects filled with realistic test data, from the type hints you
+already have.
+
+```bash
+pip install polarfactory
+pip install "polarfactory[pydantic]"  # optional: Pydantic v2 support
+```
+
+## Quickstart
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+
+from polarfactory import build, build_many
+
+
+@dataclass
+class Address:
+    city: str
+    country: str
+
+
+@dataclass
+class User:
+    id: int
+    name: str
+    email: str
+    created: datetime
+    address: Address
+    tags: list[str]
+    nickname: str | None
+
+
+user = build(User, seed=42)
+# User(id=8753, name='Grace Rossi', email='mateo.brown2@example.org',
+#      created=datetime.datetime(2022, 3, 4, 1, 29, 27, tzinfo=datetime.timezone.utc),
+#      address=Address(city='Toronto', country='Nigeria'),
+#      tags=['hwnoekxw', 'lucfvluc', 'pxxscfvm'], nickname='dpsjyett')
+
+build(User, seed=42, name="Ana")  # same values, except name
+build_many(User, 3, seed=1)  # three different users, same list every run
+```
+
+- Same seed, same object, in every process.
+- Works with dataclasses, plain classes and Pydantic v2 models, including
+  nested ones.
+- Field names like `email`, `name` or `city` get realistic values.
+- Errors say how to fix the problem.
+
+Full documentation: <https://pinnlabs.github.io/Polars/>
+
+## License
+
+MIT

polarfactory-0.1.0/README.md

@@ -0,0 +1,57 @@
+# polarfactory
+
+Generate Python objects filled with realistic test data, from the type hints you
+already have.
+
+```bash
+pip install polarfactory
+pip install "polarfactory[pydantic]"  # optional: Pydantic v2 support
+```
+
+## Quickstart
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+
+from polarfactory import build, build_many
+
+
+@dataclass
+class Address:
+    city: str
+    country: str
+
+
+@dataclass
+class User:
+    id: int
+    name: str
+    email: str
+    created: datetime
+    address: Address
+    tags: list[str]
+    nickname: str | None
+
+
+user = build(User, seed=42)
+# User(id=8753, name='Grace Rossi', email='mateo.brown2@example.org',
+#      created=datetime.datetime(2022, 3, 4, 1, 29, 27, tzinfo=datetime.timezone.utc),
+#      address=Address(city='Toronto', country='Nigeria'),
+#      tags=['hwnoekxw', 'lucfvluc', 'pxxscfvm'], nickname='dpsjyett')
+
+build(User, seed=42, name="Ana")  # same values, except name
+build_many(User, 3, seed=1)  # three different users, same list every run
+```
+
+- Same seed, same object, in every process.
+- Works with dataclasses, plain classes and Pydantic v2 models, including
+  nested ones.
+- Field names like `email`, `name` or `city` get realistic values.
+- Errors say how to fix the problem.
+
+Full documentation: <https://pinnlabs.github.io/Polars/>
+
+## License
+
+MIT

polarfactory-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "polarfactory"
+version = "0.1.0"
+description = "Generate Python objects filled with realistic test data."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+keywords = [
+    "testing",
+    "test data",
+    "factory",
+    "fixtures",
+    "dataclasses",
+    "pydantic",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/PinnLabs/Polars"
+Documentation = "https://pinnlabs.github.io/Polars/"
+Changelog = "https://github.com/PinnLabs/Polars/blob/main/CHANGELOG.md"
+Issues = "https://github.com/PinnLabs/Polars/issues"
+
+[project.optional-dependencies]
+pydantic = ["pydantic>=2.11"]
+
+[build-system]
+requires = ["uv_build>=0.7.3,<0.14"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "B",
+    "UP",
+]
+
+[tool.mypy]
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+test = ["pytest>=9.2.0"]
+dev = [
+    { include-group = "test" },
+    "mypy>=2.4.1",
+    "pydantic>=2.11",
+    "ruff>=0.17.3",
+]
+docs = ["mkdocs-material>=9.7.7"]

polarfactory-0.1.0/pyproject.toml.orig

@@ -0,0 +1,63 @@
+[project]
+name = "polarfactory"
+version = "0.1.0"
+description = "Generate Python objects filled with realistic test data."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["testing", "test data", "factory", "fixtures", "dataclasses", "pydantic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/PinnLabs/Polars"
+Documentation = "https://pinnlabs.github.io/Polars/"
+Changelog = "https://github.com/PinnLabs/Polars/blob/main/CHANGELOG.md"
+Issues = "https://github.com/PinnLabs/Polars/issues"
+
+[project.optional-dependencies]
+pydantic = [
+    "pydantic>=2.11",
+]
+
+[build-system]
+requires = ["uv_build>=0.7.3,<0.14"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.mypy]
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+# CI installs only "test" to prove the core works without pydantic.
+test = [
+    "pytest>=9.2.0",
+]
+dev = [
+    { include-group = "test" },
+    "mypy>=2.4.1",
+    "pydantic>=2.11",
+    "ruff>=0.17.3",
+]
+docs = [
+    "mkdocs-material>=9.7.7",
+]

polarfactory-0.1.0/src/polarfactory/__init__.py

@@ -0,0 +1,5 @@
+from polarfactory._build import build, build_many, register, reset_registry
+
+__all__ = ["build", "build_many", "register", "reset_registry", "__version__"]
+
+__version__ = "0.1.0"

polarfactory-0.1.0/src/polarfactory/_build.py

@@ -0,0 +1,423 @@
+import dataclasses
+import inspect
+import random
+import string
+import sys
+import types
+from collections.abc import Callable
+from datetime import date, datetime, time, timedelta, timezone
+from decimal import Decimal
+from enum import Enum
+from typing import Any, Literal, TypeVar, Union, cast, get_args, get_origin, get_type_hints
+from uuid import UUID
+
+from polarfactory._constraints import (
+    Constraints,
+    UnsupportedConstraint,
+    describe,
+    fit_length,
+    generate_from_pattern,
+    generate_number,
+)
+from polarfactory._names import NAME_GENERATORS
+from polarfactory.errors import GenerationError, PolarFactoryError
+
+T = TypeVar("T")
+
+_MAX_DEPTH = 3
+_NONE_PROBABILITY = 0.25
+_DATE_ANCHOR = datetime(2025, 1, 1, tzinfo=timezone.utc)
+_DATE_WINDOW = timedelta(days=5 * 365)
+
+
+def _generate_int(rng: random.Random) -> int:
+    return rng.randint(0, 10_000)
+
+
+def _generate_str(rng: random.Random) -> str:
+    return "".join(rng.choices(string.ascii_lowercase, k=8))
+
+
+def _generate_bool(rng: random.Random) -> bool:
+    return rng.random() < 0.5
+
+
+def _generate_float(rng: random.Random) -> float:
+    return round(rng.uniform(0, 10_000), 2)
+
+
+def _generate_bytes(rng: random.Random) -> bytes:
+    return rng.randbytes(8)
+
+
+def _generate_datetime(rng: random.Random) -> datetime:
+    return _DATE_ANCHOR - timedelta(seconds=rng.randrange(int(_DATE_WINDOW.total_seconds())))
+
+
+def _generate_date(rng: random.Random) -> date:
+    return _DATE_ANCHOR.date() - timedelta(days=rng.randrange(_DATE_WINDOW.days))
+
+
+def _generate_time(rng: random.Random) -> time:
+    return time(rng.randrange(24), rng.randrange(60), rng.randrange(60))
+
+
+def _generate_timedelta(rng: random.Random) -> timedelta:
+    return timedelta(seconds=rng.randint(0, 30 * 24 * 60 * 60))
+
+
+def _generate_uuid(rng: random.Random) -> UUID:
+    return UUID(int=rng.getrandbits(128), version=4)
+
+
+def _generate_decimal(rng: random.Random) -> Decimal:
+    return Decimal(f"{rng.randint(0, 1_000_000) / 100:.2f}")
+
+
+_DEFAULT_GENERATORS: dict[Any, Callable[[random.Random], Any]] = {
+    int: _generate_int,
+    str: _generate_str,
+    bool: _generate_bool,
+    float: _generate_float,
+    bytes: _generate_bytes,
+    datetime: _generate_datetime,
+    date: _generate_date,
+    time: _generate_time,
+    timedelta: _generate_timedelta,
+    UUID: _generate_uuid,
+    Decimal: _generate_decimal,
+}
+_GENERATORS = dict(_DEFAULT_GENERATORS)
+
+
+def register(tp: type[T], fn: Callable[[random.Random], T]) -> None:
+    if not callable(fn):
+        raise PolarFactoryError(f"register() expects a callable for {tp!r}, got {fn!r}")
+    _GENERATORS[tp] = fn
+
+
+def reset_registry() -> None:
+    _GENERATORS.clear()
+    _GENERATORS.update(_DEFAULT_GENERATORS)
+
+
+def _type_name(tp: Any) -> str:
+    return str(tp) if get_origin(tp) else getattr(tp, "__name__", str(tp))
+
+
+class _DepthExceededError(GenerationError):
+    pass
+
+
+def _override_hint(path: str) -> str:
+    root, field = path.split(".")[:2]
+    return f"build({root}, {field}=...)"
+
+
+def _type_hints(obj: Any, cls: type[Any], namespace: dict[str, Any] | None = None) -> Any:
+    try:
+        return get_type_hints(obj, namespace)
+    except NameError as exc:
+        raise GenerationError(
+            f"cannot resolve type hints of {cls.__name__}: {exc}. "
+            f"Define or import it in module '{cls.__module__}'"
+        ) from exc
+
+
+@dataclasses.dataclass(frozen=True)
+class _FieldSpec:
+    name: str
+    type: Any
+    init: bool = True
+    constraints: Constraints | None = None
+
+
+def _is_dataclass_type(tp: Any) -> bool:
+    return isinstance(tp, type) and dataclasses.is_dataclass(tp)
+
+
+def _is_buildable(tp: Any) -> bool:
+    # A Python-defined __init__ marks a plain class; builtins like complex use slot wrappers.
+    return _is_dataclass_type(tp) or (
+        isinstance(tp, type) and inspect.isfunction(getattr(tp, "__init__", None))
+    )
+
+
+def _pydantic_support(tp: Any) -> types.ModuleType | None:
+    # Never import pydantic ourselves: a pydantic model can only exist once the user has.
+    if "pydantic" not in sys.modules:
+        return None
+    from polarfactory import _pydantic
+
+    return _pydantic if _pydantic.is_model(tp) else None
+
+
+def _field_specs(cls: type[Any]) -> list[_FieldSpec]:
+    pydantic_support = _pydantic_support(cls)
+    if pydantic_support is not None:
+        return cast(list[_FieldSpec], pydantic_support.field_specs(cls))
+    if _is_dataclass_type(cls):
+        hints = _type_hints(cls, cls)
+        specs = [
+            _FieldSpec(field.name, hints[field.name], field.init)
+            for field in dataclasses.fields(cls)
+        ]
+        # InitVar pseudo-fields are __init__ arguments but not part of dataclasses.fields().
+        return specs + [
+            _FieldSpec(name, hint.type)
+            for name, hint in hints.items()
+            if isinstance(hint, dataclasses.InitVar)
+        ]
+    hints = _type_hints(cls.__init__, cls)
+    params = list(inspect.signature(cls.__init__).parameters.values())[1:]  # drop self
+    return [
+        # A missing hint is stored as Parameter.empty so an override can still supply the value.
+        _FieldSpec(param.name, hints.get(param.name, param.empty))
+        for param in params
+        if param.kind not in (param.VAR_POSITIONAL, param.VAR_KEYWORD)
+    ]
+
+
+def _resolve_forward_ref(tp: str, owner: type) -> Any:
+    # shortcut: Python 3.10 leaves list["X"] unresolved, and this only looks in owner's module, so
+    # a field inherited from another module raises NameError. Drop this when 3.10 support ends.
+    holder = types.SimpleNamespace(__annotations__={"value": tp})
+    return _type_hints(holder, owner, vars(sys.modules[owner.__module__]))["value"]
+
+
+_COLLECTION_HINTS: dict[Any, str] = {
+    list: "list[X]",
+    set: "set[X]",
+    dict: "dict[K, V]",
+    tuple: "tuple[X, Y] or tuple[X, ...]",
+}
+
+
+def _generate_items(
+    tp: Any,
+    seed: str,
+    path: str,
+    ancestors: tuple[type, ...],
+    sizes: tuple[int, int],
+    suffix: str = "",
+) -> list[Any]:
+    # The length depends only on seed, so dict keys and values get the same length.
+    length = random.Random(seed).randint(*sizes)
+    try:
+        return [_generate(tp, f"{seed}:{i}{suffix}", path, ancestors) for i in range(length)]
+    except _DepthExceededError:
+        return []
+
+
+def _generate_collection(
+    kind: type,
+    tp: Any,
+    seed: str,
+    path: str,
+    ancestors: tuple[type, ...],
+    constraints: Constraints | None,
+) -> Any:
+    args = get_args(tp)
+    if not args:
+        raise GenerationError(
+            f"cannot generate field '{path}' of type {kind.__name__}. "
+            f"Use {_COLLECTION_HINTS[kind]}, or pass it as an override: {_override_hint(path)}"
+        )
+    if kind is tuple and args[-1] is not Ellipsis:
+        return tuple(_generate(arg, f"{seed}:{i}", path, ancestors) for i, arg in enumerate(args))
+    sizes = constraints.size_range(1, 3) if constraints else (1, 3)
+    items = _generate_items(args[0], seed, path, ancestors, sizes)
+    if kind is list:
+        return items
+    if kind is tuple:
+        return tuple(items)
+    values = (
+        _generate_items(args[1], seed, path, ancestors, sizes, ":value") if kind is dict else []
+    )
+    try:
+        return dict(zip(items, values, strict=False)) if kind is dict else set(items)
+    except TypeError as exc:
+        what = "keys" if kind is dict else "items"
+        raise GenerationError(
+            f"cannot generate field '{path}' of type {_type_name(tp)}: {what} are not hashable. "
+            f"Use a hashable type, or pass it as an override: {_override_hint(path)}"
+        ) from exc
+
+
+def _generate_union(
+    members: list[Any],
+    seed: str,
+    path: str,
+    ancestors: tuple[type, ...],
+    constraints: Constraints | None,
+) -> Any:
+    # Generate every member so an unsupported one fails no matter which member the seed picks.
+    values = []
+    depth_errors = []
+    for i, member in enumerate(members):
+        try:
+            values.append(_generate(member, f"{seed}:{i}", path, ancestors, constraints))
+        except _DepthExceededError as exc:
+            depth_errors.append(exc)
+    if not values:
+        raise depth_errors[0]
+    return random.Random(seed).choice(values)
+
+
+def _generate_optional(
+    tp: Any,
+    seed: str,
+    path: str,
+    ancestors: tuple[type, ...],
+    constraints: Constraints | None,
+) -> Any:
+    try:
+        value = _generate(tp, f"{seed}:value", path, ancestors, constraints)
+    except _DepthExceededError:
+        return None
+    return None if random.Random(seed).random() < _NONE_PROBABILITY else value
+
+
+def _generate_object(
+    cls: type[Any],
+    seed: str,
+    path: str,
+    ancestors: tuple[type, ...],
+    overrides: dict[str, object],
+) -> Any:
+    ancestors = (*ancestors, cls)
+    if len(ancestors) - len(set(ancestors)) > _MAX_DEPTH:
+        raise _DepthExceededError(
+            f"cannot generate field '{path}' of type {cls.__name__}: "
+            f"required self-reference exceeds max depth {_MAX_DEPTH}. "
+            f"Make it Optional or a list, or pass it as an override: {_override_hint(path)}"
+        )
+    values: dict[str, Any] = dict(overrides)
+    for field in _field_specs(cls):
+        if field.init and field.name not in overrides:
+            field_path = f"{path}.{field.name}"
+            if field.type is inspect.Parameter.empty:
+                raise GenerationError(
+                    f"cannot generate field '{field_path}': parameter '{field.name}' of "
+                    f"{cls.__name__}.__init__ has no type hint. "
+                    f"Add one, or pass it as an override: {_override_hint(field_path)}"
+                )
+            values[field.name] = _generate(
+                field.type, f"{seed}:{field.name}", field_path, ancestors, field.constraints
+            )
+    pydantic_support = _pydantic_support(cls)
+    if pydantic_support is not None:
+        return pydantic_support.construct(cls, values, path)
+    return cls(**values)
+
+
+def _generate_constrained(
+    tp: Any,
+    generator: Callable[[random.Random], Any],
+    constraints: Constraints,
+    seed: str,
+    path: str,
+) -> Any:
+    rng = random.Random(seed)
+    try:
+        if tp in (int, float, Decimal):
+            return generate_number(tp, constraints, rng)
+        if tp is str and constraints.pattern is not None:
+            return generate_from_pattern(constraints.pattern, rng)
+        if tp is str:
+            return fit_length(generator(rng), constraints, random.Random(f"{seed}:length"))
+    except UnsupportedConstraint as exc:
+        raise GenerationError(
+            f"cannot generate field '{path}' with {describe(constraints)}: {exc}. "
+            f"Pass it as an override: {_override_hint(path)}"
+        ) from exc
+    return generator(rng)
+
+
+def _generate(
+    tp: Any,
+    seed: str,
+    path: str,
+    ancestors: tuple[type, ...],
+    constraints: Constraints | None = None,
+) -> Any:
+    if isinstance(tp, str):
+        tp = _resolve_forward_ref(tp, ancestors[-1])
+    generator = _GENERATORS.get(tp)
+    if tp is str and generator is _generate_str:
+        # Only while str uses the default generator, so register(str, ...) still wins.
+        generator = NAME_GENERATORS.get(path.rsplit(".", 1)[-1], generator)
+    if generator is not None:
+        # Constraints only steer built-in generators; a registered one is used as is.
+        if constraints is not None and _GENERATORS.get(tp) is _DEFAULT_GENERATORS.get(tp):
+            return _generate_constrained(tp, generator, constraints, seed, path)
+        return generator(random.Random(seed))
+    origin = get_origin(tp)
+    if origin is Literal:
+        return random.Random(seed).choice(get_args(tp))
+    if origin is None and isinstance(tp, type) and issubclass(tp, Enum):
+        members = list(tp)
+        if not members:
+            raise GenerationError(
+                f"cannot generate field '{path}' of type {tp.__name__}: enum has no members. "
+                f"Add a member, or pass it as an override: {_override_hint(path)}"
+            )
+        return random.Random(seed).choice(members)
+    if _is_buildable(tp):
+        return _generate_object(tp, seed, path, ancestors, {})
+    kind = origin or tp
+    if kind in _COLLECTION_HINTS:
+        return _generate_collection(kind, tp, seed, path, ancestors, constraints)
+    if origin in (Union, types.UnionType):
+        args = get_args(tp)
+        inner = [arg for arg in args if arg is not type(None)]
+        if len(inner) < len(args):
+            core = inner[0] if len(inner) == 1 else Union[tuple(inner)]  # noqa: UP007 - built at runtime
+            return _generate_optional(core, seed, path, ancestors, constraints)
+        return _generate_union(inner, seed, path, ancestors, constraints)
+    raise GenerationError(
+        f"cannot generate field '{path}' of type {_type_name(tp)}. "
+        f"Pass it as an override: {_override_hint(path)}"
+    )
+
+
+def _check_build_args(func: str, cls: type[Any], overrides: dict[str, object]) -> None:
+    if not _is_buildable(cls):
+        raise PolarFactoryError(
+            f"{func}() expects a dataclass or a class with __init__, got {cls!r}"
+        )
+
+    fields = _field_specs(cls)
+    init_by_name = {field.name: field.init for field in fields}
+    for name in overrides:
+        if name not in init_by_name:
+            valid = ", ".join(field.name for field in fields if field.init)
+            raise PolarFactoryError(
+                f"{func}() got unknown field '{name}' for {cls.__name__}; valid fields: {valid}"
+            )
+        if not init_by_name[name]:
+            raise PolarFactoryError(
+                f"{func}() cannot set field '{cls.__name__}.{name}': it has init=False. "
+                "Set it on the built object instead"
+            )
+
+
+def _base_seed(seed: int | None) -> int:
+    return random.Random().getrandbits(64) if seed is None else seed
+
+
+def build(cls: type[T], /, *, seed: int | None = None, **overrides: object) -> T:
+    _check_build_args("build", cls, overrides)
+    root_seed = str(_base_seed(seed))
+    return cast(T, _generate_object(cls, root_seed, cls.__name__, (), overrides))
+
+
+def build_many(cls: type[T], n: int, /, *, seed: int | None = None, **overrides: object) -> list[T]:
+    _check_build_args("build_many", cls, overrides)
+    if n < 0:
+        raise PolarFactoryError(f"build_many() expects n >= 0, got {n}")
+    base_seed = _base_seed(seed)
+    return [
+        cast(T, _generate_object(cls, f"{base_seed}:{i}", cls.__name__, (), overrides))
+        for i in range(n)
+    ]

polarfactory-0.1.0/src/polarfactory/_constraints.py

@@ -0,0 +1,153 @@
+"""Value generation under field constraints (bounds, lengths, regex patterns)."""
+
+import dataclasses
+import importlib
+import math
+import random
+import string
+import sys
+from decimal import Decimal
+from typing import Any
+
+# shortcut: the stdlib regex parser is private API (sre_parse, renamed re._parser in 3.11).
+# Replace it with a small own parser if a Python release changes its token format.
+sre_parse: Any = importlib.import_module(
+    "re._parser" if sys.version_info >= (3, 11) else "sre_parse"
+)
+
+_NAMES = ("ge", "gt", "le", "lt", "min_length", "max_length", "pattern")
+_SPAN = 10_000
+_UNBOUNDED_REPEAT = 3
+_CATEGORIES = {
+    sre_parse.CATEGORY_DIGIT: string.digits,
+    sre_parse.CATEGORY_WORD: string.ascii_letters + string.digits + "_",
+    sre_parse.CATEGORY_SPACE: " ",
+}
+_ANY_CHAR = string.ascii_letters + string.digits
+
+
+@dataclasses.dataclass(frozen=True)
+class Constraints:
+    ge: Any = None
+    gt: Any = None
+    le: Any = None
+    lt: Any = None
+    min_length: int | None = None
+    max_length: int | None = None
+    pattern: str | None = None
+
+    @classmethod
+    def from_metadata(cls, metadata: list[Any]) -> "Constraints | None":
+        # Duck-typed so annotated_types and pydantic metadata work without importing either.
+        found = {
+            name: getattr(item, name)
+            for item in metadata
+            for name in _NAMES
+            if getattr(item, name, None) is not None
+        }
+        return cls(**found) if found else None
+
+    def size_range(self, low: int, high: int) -> tuple[int, int]:
+        lo = self.min_length if self.min_length is not None else low
+        hi = self.max_length if self.max_length is not None else max(lo, high)
+        return min(lo, hi), hi
+
+
+class UnsupportedConstraint(ValueError):
+    pass
+
+
+def generate_number(tp: type, constraints: Constraints, rng: random.Random) -> Any:
+    step = 1.0 if tp is int else 0.01
+    lo = _bound(constraints.ge, constraints.gt, step)
+    hi = _bound(constraints.le, constraints.lt, -step)
+    if lo is None and hi is None:
+        lo, hi = 0.0, float(_SPAN)
+    elif lo is None:
+        lo = hi - _SPAN if hi < 0 else 0.0  # type: ignore[operator]
+    elif hi is None:
+        hi = max(lo, 0.0) + _SPAN
+    assert lo is not None and hi is not None
+    if tp is int:
+        low, high = math.ceil(lo), math.floor(hi)
+        if low > high:
+            raise UnsupportedConstraint("no int fits these bounds")
+        return rng.randint(low, high)
+    if lo > hi:
+        raise UnsupportedConstraint("no number fits these bounds")
+    value = min(max(round(rng.uniform(lo, hi), 2), lo), hi)
+    return Decimal(str(value)) if tp is Decimal else value
+
+
+def _bound(inclusive: Any, exclusive: Any, step: float) -> float | None:
+    if inclusive is not None:
+        return float(inclusive)
+    if exclusive is not None:
+        return float(exclusive) + step
+    return None
+
+
+def describe(constraints: Constraints) -> str:
+    return ", ".join(
+        f"{field.name}={getattr(constraints, field.name)!r}"
+        for field in dataclasses.fields(constraints)
+        if getattr(constraints, field.name) is not None
+    )
+
+
+def fit_length(value: str, constraints: Constraints, rng: random.Random) -> str:
+    lo, hi = constraints.size_range(0, max(len(value), 8))
+    if lo <= len(value) <= hi:
+        return value
+    return "".join(rng.choices(string.ascii_lowercase, k=rng.randint(lo, hi)))
+
+
+def generate_from_pattern(pattern: str, rng: random.Random) -> str:
+    try:
+        return _emit(sre_parse.parse(pattern), rng)
+    except UnsupportedConstraint as exc:
+        raise UnsupportedConstraint(f"pattern {pattern!r} uses {exc}") from exc
+
+
+def _emit(items: Any, rng: random.Random) -> str:
+    out = []
+    for op, arg in items:
+        if op is sre_parse.LITERAL:
+            out.append(chr(arg))
+        elif op is sre_parse.ANY:
+            out.append(rng.choice(_ANY_CHAR))
+        elif op is sre_parse.IN:
+            out.append(rng.choice(_charset(arg)))
+        elif op is sre_parse.CATEGORY:
+            out.append(rng.choice(_category(arg)))
+        elif op in (sre_parse.MAX_REPEAT, sre_parse.MIN_REPEAT):
+            low, high, sub = arg
+            high = low + _UNBOUNDED_REPEAT if high is sre_parse.MAXREPEAT else high
+            out.extend(_emit(sub, rng) for _ in range(rng.randint(low, high)))
+        elif op is sre_parse.SUBPATTERN:
+            out.append(_emit(arg[-1], rng))
+        elif op is sre_parse.BRANCH:
+            out.append(_emit(rng.choice(arg[1]), rng))
+        elif op is not sre_parse.AT:  # anchors like ^ and $ produce no characters
+            raise UnsupportedConstraint(f"unsupported regex feature {str(op).lower()}")
+    return "".join(out)
+
+
+def _charset(items: Any) -> str:
+    chars = []
+    for op, arg in items:
+        if op is sre_parse.LITERAL:
+            chars.append(chr(arg))
+        elif op is sre_parse.RANGE:
+            chars.extend(chr(code) for code in range(arg[0], arg[1] + 1))
+        elif op is sre_parse.CATEGORY:
+            chars.append(_category(arg))
+        else:
+            raise UnsupportedConstraint(f"unsupported regex feature {str(op).lower()}")
+    return "".join(chars)
+
+
+def _category(category: Any) -> str:
+    if category not in _CATEGORIES:
+        raise UnsupportedConstraint(f"unsupported regex feature {str(category).lower()}")
+    return _CATEGORIES[category]

polarfactory-0.1.0/src/polarfactory/_names.py

@@ -0,0 +1,94 @@
+"""Realistic str values picked from the field name, e.g. a field called `email` gets an email."""
+
+import random
+from collections.abc import Callable
+
+FIRST_NAMES = (
+    "Ana", "Bruno", "Carla", "David", "Elena", "Fatima", "Grace", "Hiro", "Isabel", "James",
+    "Kenji", "Laura", "Mateo", "Nadia", "Omar", "Priya", "Quentin", "Rosa", "Samuel", "Tara",
+)  # fmt: skip
+LAST_NAMES = (
+    "Silva", "Smith", "Garcia", "Kim", "Müller", "Rossi", "Nguyen", "Okafor", "Costa", "Tanaka",
+    "Novak", "Haddad", "Johansson", "Patel", "Dubois", "Moreno", "Kowalski", "Ali", "Brown", "Lee",
+)  # fmt: skip
+CITIES = (
+    "Lisbon", "São Paulo", "Tokyo", "Nairobi", "Berlin", "Toronto", "Mumbai", "Sydney",
+    "Mexico City", "Seoul", "Cairo", "Paris", "Buenos Aires", "Oslo", "Lagos",
+)  # fmt: skip
+COUNTRIES = (
+    "Portugal", "Brazil", "Japan", "Kenya", "Germany", "Canada", "India", "Australia",
+    "Mexico", "South Korea", "Egypt", "France", "Argentina", "Norway", "Nigeria",
+)  # fmt: skip
+WORDS = (
+    "amber", "bright", "cloud", "delta", "echo", "field", "garden", "harbor", "island", "jade",
+    "kite", "lemon", "maple", "north", "ocean", "pixel", "quiet", "river", "silver", "timber",
+    "urban", "velvet", "willow", "yellow", "zephyr", "stone", "spark", "meadow", "copper", "light",
+)  # fmt: skip
+# Reserved for documentation (RFC 2606), so generated addresses never reach a real inbox.
+DOMAINS = ("example.com", "example.org", "example.net")
+
+
+def _ascii(text: str) -> str:
+    return text.lower().replace("ü", "u").replace(" ", "")
+
+
+def _first_name(rng: random.Random) -> str:
+    return rng.choice(FIRST_NAMES)
+
+
+def _last_name(rng: random.Random) -> str:
+    return rng.choice(LAST_NAMES)
+
+
+def _name(rng: random.Random) -> str:
+    return f"{_first_name(rng)} {_last_name(rng)}"
+
+
+def _email(rng: random.Random) -> str:
+    first, last = _ascii(_first_name(rng)), _ascii(_last_name(rng))
+    return f"{first}.{last}{rng.randint(1, 99)}@{rng.choice(DOMAINS)}"
+
+
+def _username(rng: random.Random) -> str:
+    return f"{_ascii(_first_name(rng))}_{rng.choice(WORDS)}{rng.randint(1, 999)}"
+
+
+def _words(rng: random.Random, low: int, high: int) -> list[str]:
+    return [rng.choice(WORDS) for _ in range(rng.randint(low, high))]
+
+
+def _slug(rng: random.Random) -> str:
+    return "-".join(_words(rng, 2, 4))
+
+
+def _url(rng: random.Random) -> str:
+    return f"https://{rng.choice(DOMAINS)}/{_slug(rng)}"
+
+
+def _phone(rng: random.Random) -> str:
+    # 555-0100 to 555-0199 is reserved for fiction, so no real person gets called.
+    return f"+1-555-01{rng.randint(0, 99):02d}"
+
+
+def _title(rng: random.Random) -> str:
+    return " ".join(_words(rng, 2, 5)).capitalize()
+
+
+def _description(rng: random.Random) -> str:
+    return " ".join(_words(rng, 8, 15)).capitalize() + "."
+
+
+NAME_GENERATORS: dict[str, Callable[[random.Random], str]] = {
+    "email": _email,
+    "name": _name,
+    "first_name": _first_name,
+    "last_name": _last_name,
+    "city": lambda rng: rng.choice(CITIES),
+    "country": lambda rng: rng.choice(COUNTRIES),
+    "url": _url,
+    "phone": _phone,
+    "username": _username,
+    "title": _title,
+    "description": _description,
+    "slug": _slug,
+}

polarfactory-0.1.0/src/polarfactory/_pydantic.py

@@ -0,0 +1,31 @@
+"""Pydantic v2 support. Only imported once the user has imported pydantic themselves."""
+
+from typing import Any
+
+import pydantic
+
+from polarfactory._build import _FieldSpec
+from polarfactory._constraints import Constraints
+from polarfactory.errors import GenerationError
+
+
+def is_model(tp: Any) -> bool:
+    return isinstance(tp, type) and issubclass(tp, pydantic.BaseModel)
+
+
+def field_specs(cls: type[pydantic.BaseModel]) -> list[_FieldSpec]:
+    return [
+        _FieldSpec(name, info.annotation, constraints=Constraints.from_metadata(info.metadata))
+        for name, info in cls.model_fields.items()
+    ]
+
+
+def construct(cls: type[pydantic.BaseModel], values: dict[str, Any], path: str) -> Any:
+    try:
+        # by_name so fields with an alias accept the attribute name we generated under.
+        return cls.model_validate(values, by_name=True)
+    except pydantic.ValidationError as exc:
+        raise GenerationError(
+            f"values for '{path}' failed {cls.__name__} validation. "
+            f"Pass the failing fields as overrides. Details:\n{exc}"
+        ) from exc

polarfactory-0.1.0/src/polarfactory/errors.py

@@ -0,0 +1,6 @@
+class PolarFactoryError(TypeError):
+    """Base class for every error raised by polarfactory."""
+
+
+class GenerationError(PolarFactoryError):
+    """A field value could not be generated."""