dataforge-py 0.2.0__py3-none-any.whl

dataforge/__init__.py

@@ -0,0 +1,20 @@
+"""dataforge — High-performance fake data generator for testing.
+
+Usage::
+
+    from dataforge import DataForge
+
+    forge = DataForge(locale="en_US", seed=42)
+    forge.person.first_name()           # "James"
+    forge.address.full_address()        # "4821 Oak Ave, Chicago, IL 60614"
+    forge.person.full_name(count=1000)  # list of 1000 full names
+
+    # Unique values
+    forge.unique.person.first_name()    # guaranteed unique per call
+"""
+
+from dataforge.core import DataForge
+from dataforge.schema import Schema
+
+__version__ = "0.2.0"
+__all__ = ["DataForge", "Schema", "__version__"]

dataforge/backend.py

@@ -0,0 +1,147 @@
+"""RandomEngine — the speed engine behind dataforge.
+
+Provides a unified interface for random selection using stdlib
+``random`` — optimised for both scalar picks and batch generation.
+"""
+
+import random as _random
+from typing import TypeVar
+
+_T = TypeVar("_T")
+
+# Pre-computed power-of-10 table for random_digits_str — eliminates
+# per-call ``10**n`` computation for n=1..18.
+_POW10: tuple[int, ...] = tuple(10**i for i in range(19))  # _POW10[0]=1 .. _POW10[18]
+
+
+class RandomEngine:
+    """Core randomness engine.
+
+    Parameters
+    ----------
+    seed : int | None
+        Optional seed for reproducibility.
+    """
+
+    __slots__ = ("_rng",)
+
+    def __init__(self, seed: int | None = None) -> None:
+        self._rng: _random.Random = _random.Random(seed)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def choice(self, data: tuple[_T, ...]) -> _T:
+        """Return a single random element from *data*.
+
+        Uses stdlib ``random.Random.choice`` which is the fastest path
+        for picking one item.
+        """
+        return self._rng.choice(data)
+
+    def choices(self, data: tuple[_T, ...], count: int) -> list[_T]:
+        """Return *count* random elements from *data*."""
+        return self._rng.choices(data, k=count)
+
+    def random_int(self, min_val: int = 0, max_val: int = 9999) -> int:
+        """Return a random integer between *min_val* and *max_val* inclusive."""
+        return self._rng.randint(min_val, max_val)
+
+    def numerify(self, pattern: str) -> str:
+        """Replace every ``#`` in *pattern* with a random digit.
+
+        Example: ``"#####"`` → ``"38201"``
+
+        Optimized: if the pattern is all ``#`` characters, generates
+        all digits in a single call via :meth:`random_digits_str`.
+        For mixed patterns, pre-counts ``#`` and generates all digits
+        in one bulk call, then substitutes via iterator.
+        """
+        # Fast path: pattern is entirely # characters (very common).
+        # Use length check instead of iterating all characters with all().
+        hash_count = pattern.count("#")
+        if hash_count == len(pattern):
+            return self.random_digits_str(hash_count)
+        if hash_count == 0:
+            return pattern
+        # Slow path optimized: generate all digits in one call, then
+        # substitute via iterator — avoids N random_digit() calls.
+        digits = self.random_digits_str(hash_count)
+        it = iter(digits)
+        return "".join(next(it) if ch == "#" else ch for ch in pattern)
+
+    def getrandbits(self, k: int) -> int:
+        """Return a random integer with *k* random bits.
+
+        This is the fastest way to generate a large block of randomness
+        in a single call — used by providers that need to build strings
+        from many random hex/decimal digits (IPv6, MAC, barcodes, etc.).
+        """
+        return self._rng.getrandbits(k)
+
+    def random_digits_str(self, n: int) -> str:
+        """Return a string of *n* random decimal digits.
+
+        Uses a pre-computed ``_POW10`` lookup table to avoid per-call
+        ``10**n`` computation.  For small n (≤ 18), a single
+        ``randint`` call is the fastest path.
+        """
+        _pow10 = _POW10
+        if n <= 18:
+            val = self._rng.randint(0, _pow10[n] - 1)
+            return str(val).zfill(n)
+        # For larger n, concatenate chunks of 18 digits
+        parts: list[str] = []
+        remaining = n
+        _max18 = _pow10[18] - 1
+        _randint = self._rng.randint
+        while remaining > 0:
+            chunk = min(remaining, 18)
+            val = _randint(0, _pow10[chunk] - 1)
+            parts.append(str(val).zfill(chunk))
+            remaining -= chunk
+        return "".join(parts)
+
+    def seed(self, value: int) -> None:
+        """Re-seed the engine for reproducibility."""
+        self._rng.seed(value)
+
+    def weighted_choices(
+        self,
+        data: tuple[_T, ...],
+        weights: tuple[float, ...] | list[float],
+        count: int,
+    ) -> list[_T]:
+        """Return *count* random elements from *data* with *weights*.
+
+        Each element in *data* is selected with probability proportional
+        to its corresponding weight.
+
+        Parameters
+        ----------
+        data : tuple
+            The items to choose from.
+        weights : tuple[float, ...] or list[float]
+            Non-negative weights (need not sum to 1).
+        count : int
+            Number of items to pick.
+
+        Returns
+        -------
+        list
+        """
+        # Accept both tuple and list directly — stdlib choices() handles
+        # both; avoid redundant list() conversion.
+        return self._rng.choices(data, weights=weights, k=count)
+
+    def weighted_choice(
+        self,
+        data: tuple[_T, ...],
+        weights: tuple[float, ...] | list[float],
+    ) -> _T:
+        """Return a single random element from *data* with *weights*.
+
+        Scalar version of :meth:`weighted_choices`.
+        """
+        return self._rng.choices(data, weights=weights, k=1)[0]

dataforge/cli.py

@@ -0,0 +1,166 @@
+"""dataforge CLI — generate fake data from the command line.
+
+Usage::
+
+    dataforge --count 100 --format csv name email phone
+    dataforge --count 10 --format json first_name last_name city
+    dataforge --locale de_DE --count 5 full_name address
+    dataforge --list-fields
+
+Supported output formats: text, csv, json, jsonl
+"""
+
+import argparse
+import csv
+import io
+import json
+import sys
+
+from dataforge import DataForge
+from dataforge.registry import get_field_map
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dataforge",
+        description="Generate fake data for testing from the command line.",
+    )
+    parser.add_argument(
+        "fields",
+        nargs="*",
+        help="Fields to generate (e.g. first_name email city). "
+        "Use --list-fields to see all available fields.",
+    )
+    parser.add_argument(
+        "-n",
+        "--count",
+        type=int,
+        default=10,
+        help="Number of rows to generate (default: 10).",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=("text", "csv", "json", "jsonl"),
+        default="text",
+        help="Output format (default: text).",
+    )
+    parser.add_argument(
+        "-l",
+        "--locale",
+        default="en_US",
+        help="Locale for data generation (default: en_US).",
+    )
+    parser.add_argument(
+        "-s",
+        "--seed",
+        type=int,
+        default=None,
+        help="Random seed for reproducible output.",
+    )
+    parser.add_argument(
+        "--list-fields",
+        action="store_true",
+        help="List all available field names and exit.",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        metavar="FILE",
+        help="Write output to FILE instead of stdout.",
+    )
+    parser.add_argument(
+        "--no-header",
+        action="store_true",
+        help="Omit header row in text and csv output formats.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the dataforge CLI."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    field_map = get_field_map()
+
+    if args.list_fields:
+        # Group fields by provider
+        for name in sorted(field_map.keys()):
+            provider, method = field_map[name]
+            print(f"  {name:24s}  ({provider}.{method})")
+        return 0
+
+    if not args.fields:
+        # Default fields
+        args.fields = ["first_name", "last_name", "email"]
+
+    # Validate fields before generating
+    for field in args.fields:
+        if field not in field_map:
+            print(
+                f"Error: unknown field '{field}'. Use --list-fields to see options.",
+                file=sys.stderr,
+            )
+            return 1
+
+    forge = DataForge(locale=args.locale, seed=args.seed)
+
+    # Column-first batch generation — dramatically faster than row-by-row
+    headers = args.fields
+    rows = forge.to_dict(headers, count=args.count)
+
+    # Determine output destination
+    out_file = None
+    if args.output:
+        out_file = open(args.output, "w", encoding="utf-8", newline="")
+    out = out_file or sys.stdout
+
+    try:
+        # Output
+        fmt = args.format
+
+        if fmt == "text":
+            # Aligned columns
+            col_widths = [len(h) for h in headers]
+            for row in rows:
+                for i, h in enumerate(headers):
+                    col_widths[i] = max(col_widths[i], len(row[h]))
+
+            if not args.no_header:
+                header_line = "  ".join(
+                    h.ljust(col_widths[i]) for i, h in enumerate(headers)
+                )
+                sep_line = "  ".join("-" * col_widths[i] for i in range(len(headers)))
+                print(header_line, file=out)
+                print(sep_line, file=out)
+            for row in rows:
+                line = "  ".join(
+                    row[h].ljust(col_widths[i]) for i, h in enumerate(headers)
+                )
+                print(line, file=out)
+
+        elif fmt == "csv":
+            buf = io.StringIO()
+            writer = csv.DictWriter(buf, fieldnames=headers)
+            if not args.no_header:
+                writer.writeheader()
+            writer.writerows(rows)
+            print(buf.getvalue(), end="", file=out)
+
+        elif fmt == "json":
+            print(json.dumps(rows, indent=2, ensure_ascii=False), file=out)
+
+        elif fmt == "jsonl":
+            for row in rows:
+                print(json.dumps(row, ensure_ascii=False), file=out)
+    finally:
+        if out_file is not None:
+            out_file.close()
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())