dataforge-py 0.2.0__py3-none-any.whl

dataforge/providers/datetime.py

@@ -0,0 +1,397 @@
+"""DateTime provider — generates fake dates, times, and datetimes.
+
+This provider is locale-independent — it uses Python's datetime module
+directly and generates values within configurable ranges.
+"""
+
+import datetime as _dt
+from typing import Literal, overload
+
+from dataforge.providers.base import BaseProvider
+
+# Epoch boundaries (as ordinals for fast random int generation)
+_MIN_DATE = _dt.date(1970, 1, 1)
+_MAX_DATE = _dt.date(2030, 12, 31)
+_MIN_ORDINAL = _MIN_DATE.toordinal()
+_MAX_ORDINAL = _MAX_DATE.toordinal()
+_SECONDS_IN_DAY = 86400
+_EPOCH_ORDINAL = _MIN_DATE.toordinal()  # cached for unix_timestamp()
+
+# Pre-computed default timestamp range — avoids .toordinal() on every call
+_MIN_TIMESTAMP = 0  # (_MIN_ORDINAL - _EPOCH_ORDINAL) * _SECONDS_IN_DAY
+_MAX_TIMESTAMP = (_MAX_ORDINAL - _EPOCH_ORDINAL + 1) * _SECONDS_IN_DAY - 1
+
+# IANA timezone names — common subset for fast random selection
+_TIMEZONES: tuple[str, ...] = (
+    "UTC",
+    "US/Eastern",
+    "US/Central",
+    "US/Mountain",
+    "US/Pacific",
+    "US/Alaska",
+    "US/Hawaii",
+    "Canada/Eastern",
+    "Canada/Central",
+    "Canada/Pacific",
+    "Europe/London",
+    "Europe/Paris",
+    "Europe/Berlin",
+    "Europe/Madrid",
+    "Europe/Rome",
+    "Europe/Amsterdam",
+    "Europe/Brussels",
+    "Europe/Vienna",
+    "Europe/Warsaw",
+    "Europe/Moscow",
+    "Europe/Istanbul",
+    "Europe/Athens",
+    "Europe/Helsinki",
+    "Europe/Stockholm",
+    "Europe/Oslo",
+    "Europe/Zurich",
+    "Asia/Tokyo",
+    "Asia/Shanghai",
+    "Asia/Hong_Kong",
+    "Asia/Seoul",
+    "Asia/Singapore",
+    "Asia/Dubai",
+    "Asia/Kolkata",
+    "Asia/Bangkok",
+    "Asia/Jakarta",
+    "Asia/Karachi",
+    "Asia/Riyadh",
+    "Asia/Taipei",
+    "Australia/Sydney",
+    "Australia/Melbourne",
+    "Australia/Perth",
+    "Pacific/Auckland",
+    "America/Sao_Paulo",
+    "America/Mexico_City",
+    "America/Buenos_Aires",
+    "America/Bogota",
+    "America/Lima",
+    "Africa/Cairo",
+    "Africa/Lagos",
+    "Africa/Johannesburg",
+    "Africa/Nairobi",
+)
+
+
+class DateTimeProvider(BaseProvider):
+    """Generates fake dates, times, datetimes, and dates of birth.
+
+    This provider does **not** require locale data — it uses Python's
+    ``datetime`` module directly.
+
+    Parameters
+    ----------
+    engine : RandomEngine
+        The shared random engine instance.
+    """
+
+    __slots__ = ()
+
+    _provider_name = "dt"
+    _locale_modules = ()
+    _field_map = {
+        "date": "date",
+        "time": "time",
+        "datetime": "datetime",
+        "date_of_birth": "date_of_birth",
+        "dob": "date_of_birth",
+        "timezone": "timezone",
+        "unix_timestamp": "unix_timestamp",
+    }
+
+    # ------------------------------------------------------------------
+    # Scalar helpers
+    # ------------------------------------------------------------------
+
+    def _one_date(
+        self,
+        start: _dt.date = _MIN_DATE,
+        end: _dt.date = _MAX_DATE,
+    ) -> _dt.date:
+        # Use pre-computed ordinals for default range to avoid
+        # .toordinal() per call.
+        if start is _MIN_DATE and end is _MAX_DATE:
+            ordinal = self._engine.random_int(_MIN_ORDINAL, _MAX_ORDINAL)
+        else:
+            ordinal = self._engine.random_int(start.toordinal(), end.toordinal())
+        return _dt.date.fromordinal(ordinal)
+
+    @staticmethod
+    def _date_to_iso(d: _dt.date) -> str:
+        """Format date as ISO 8601 string without ``strftime`` overhead."""
+        return f"{d.year:04d}-{d.month:02d}-{d.day:02d}"
+
+    def _one_time(self) -> _dt.time:
+        total_seconds = self._engine.random_int(0, _SECONDS_IN_DAY - 1)
+        hour = total_seconds // 3600
+        minute = (total_seconds % 3600) // 60
+        second = total_seconds % 60
+        return _dt.time(hour, minute, second)
+
+    @staticmethod
+    def _time_to_hms(t: _dt.time) -> str:
+        """Format time as ``HH:MM:SS`` without ``strftime`` overhead."""
+        return f"{t.hour:02d}:{t.minute:02d}:{t.second:02d}"
+
+    def _one_time_str(self) -> str:
+        """Generate a random time as ``HH:MM:SS`` string — fast path.
+
+        Bypasses ``_dt.time`` object creation entirely by using
+        ``divmod`` arithmetic directly on the random seconds value.
+        """
+        total = self._engine.random_int(0, _SECONDS_IN_DAY - 1)
+        h, rem = divmod(total, 3600)
+        m, s = divmod(rem, 60)
+        return f"{h:02d}:{m:02d}:{s:02d}"
+
+    def _one_datetime(
+        self,
+        start: _dt.date = _MIN_DATE,
+        end: _dt.date = _MAX_DATE,
+    ) -> _dt.datetime:
+        d = self._one_date(start, end)
+        t = self._one_time()
+        return _dt.datetime.combine(d, t)
+
+    def _one_date_of_birth(self, min_age: int = 18, max_age: int = 80) -> _dt.date:
+        today = _dt.date.today()
+        start = today.replace(year=today.year - max_age)
+        end = today.replace(year=today.year - min_age)
+        return self._one_date(start, end)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @overload
+    def date(self) -> str: ...
+    @overload
+    def date(self, count: Literal[1]) -> str: ...
+    @overload
+    def date(self, count: int) -> str | list[str]: ...
+    def date(
+        self,
+        count: int = 1,
+        fmt: str = "%Y-%m-%d",
+        start: _dt.date | None = None,
+        end: _dt.date | None = None,
+    ) -> str | list[str]:
+        """Generate a random date string.
+
+        Parameters
+        ----------
+        count : int
+            Number of dates to generate.
+        fmt : str
+            strftime format string.
+        start : datetime.date | None
+            Earliest date (default: 1970-01-01).
+        end : datetime.date | None
+            Latest date (default: 2030-12-31).
+        """
+        s = start or _MIN_DATE
+        e = end or _MAX_DATE
+        # Fast path: default ISO format avoids expensive strftime
+        if fmt == "%Y-%m-%d":
+            _iso = self._date_to_iso
+            # Pre-compute ordinals once for the batch instead of
+            # per-item .toordinal() calls inside _one_date().
+            if s is _MIN_DATE and e is _MAX_DATE:
+                s_ord, e_ord = _MIN_ORDINAL, _MAX_ORDINAL
+            else:
+                s_ord, e_ord = s.toordinal(), e.toordinal()
+            _ri = self._engine.random_int
+            _from_ord = _dt.date.fromordinal
+            if count == 1:
+                return _iso(_from_ord(_ri(s_ord, e_ord)))
+            return [_iso(_from_ord(_ri(s_ord, e_ord))) for _ in range(count)]
+        if count == 1:
+            return self._one_date(s, e).strftime(fmt)
+        return [self._one_date(s, e).strftime(fmt) for _ in range(count)]
+
+    @overload
+    def time(self) -> str: ...
+    @overload
+    def time(self, count: Literal[1]) -> str: ...
+    @overload
+    def time(self, count: int) -> str | list[str]: ...
+    def time(self, count: int = 1, fmt: str = "%H:%M:%S") -> str | list[str]:
+        """Generate a random time string.
+
+        Parameters
+        ----------
+        count : int
+            Number of times to generate.
+        fmt : str
+            strftime format string.
+        """
+        # Fast path: default HH:MM:SS format — skip _dt.time object
+        if fmt == "%H:%M:%S":
+            if count == 1:
+                return self._one_time_str()
+            # Inlined batch: avoid method call overhead per item
+            _ri = self._engine.random_int
+            result: list[str] = []
+            for _ in range(count):
+                total = _ri(0, _SECONDS_IN_DAY - 1)
+                h, rem = divmod(total, 3600)
+                m, s = divmod(rem, 60)
+                result.append(f"{h:02d}:{m:02d}:{s:02d}")
+            return result
+        if count == 1:
+            return self._one_time().strftime(fmt)
+        return [self._one_time().strftime(fmt) for _ in range(count)]
+
+    @overload
+    def datetime(self) -> str: ...
+    @overload
+    def datetime(self, count: Literal[1]) -> str: ...
+    @overload
+    def datetime(self, count: int) -> str | list[str]: ...
+    def datetime(
+        self,
+        count: int = 1,
+        fmt: str = "%Y-%m-%d %H:%M:%S",
+        start: _dt.date | None = None,
+        end: _dt.date | None = None,
+    ) -> str | list[str]:
+        """Generate a random datetime string.
+
+        Parameters
+        ----------
+        count : int
+            Number of datetimes to generate.
+        fmt : str
+            strftime format string.
+        start : datetime.date | None
+            Earliest date (default: 1970-01-01).
+        end : datetime.date | None
+            Latest date (default: 2030-12-31).
+        """
+        s = start or _MIN_DATE
+        e = end or _MAX_DATE
+        if count == 1:
+            return self._one_datetime(s, e).strftime(fmt)
+        return [self._one_datetime(s, e).strftime(fmt) for _ in range(count)]
+
+    @overload
+    def date_of_birth(self) -> str: ...
+    @overload
+    def date_of_birth(self, count: Literal[1]) -> str: ...
+    @overload
+    def date_of_birth(self, count: int) -> str | list[str]: ...
+    def date_of_birth(
+        self,
+        count: int = 1,
+        min_age: int = 18,
+        max_age: int = 80,
+        fmt: str = "%Y-%m-%d",
+    ) -> str | list[str]:
+        """Generate a random date of birth.
+
+        Parameters
+        ----------
+        count : int
+            Number of dates to generate.
+        min_age : int
+            Minimum age in years.
+        max_age : int
+            Maximum age in years.
+        fmt : str
+            strftime format string.
+        """
+        # Compute today() once for the entire batch
+        today = _dt.date.today()
+        start = today.replace(year=today.year - max_age)
+        end = today.replace(year=today.year - min_age)
+
+        if fmt == "%Y-%m-%d":
+            _iso = self._date_to_iso
+            s_ord, e_ord = start.toordinal(), end.toordinal()
+            _ri = self._engine.random_int
+            _from_ord = _dt.date.fromordinal
+            if count == 1:
+                return _iso(_from_ord(_ri(s_ord, e_ord)))
+            return [_iso(_from_ord(_ri(s_ord, e_ord))) for _ in range(count)]
+        if count == 1:
+            return self._one_date(start, end).strftime(fmt)
+        return [self._one_date(start, end).strftime(fmt) for _ in range(count)]
+
+    def date_object(self, count: int = 1) -> _dt.date | list[_dt.date]:
+        """Generate a random ``datetime.date`` object.
+
+        Parameters
+        ----------
+        count : int
+            Number of date objects to generate.
+        """
+        if count == 1:
+            return self._one_date()
+        return [self._one_date() for _ in range(count)]
+
+    def datetime_object(self, count: int = 1) -> _dt.datetime | list[_dt.datetime]:
+        """Generate a random ``datetime.datetime`` object.
+
+        Parameters
+        ----------
+        count : int
+            Number of datetime objects to generate.
+        """
+        if count == 1:
+            return self._one_datetime()
+        return [self._one_datetime() for _ in range(count)]
+
+    @overload
+    def timezone(self) -> str: ...
+    @overload
+    def timezone(self, count: Literal[1]) -> str: ...
+    @overload
+    def timezone(self, count: int) -> str | list[str]: ...
+    def timezone(self, count: int = 1) -> str | list[str]:
+        """Generate a random IANA timezone string (e.g. ``"Europe/Berlin"``).
+
+        Parameters
+        ----------
+        count : int
+            Number of timezone strings to generate.
+        """
+        if count == 1:
+            return self._engine.choice(_TIMEZONES)
+        return self._engine.choices(_TIMEZONES, count)
+
+    def unix_timestamp(
+        self,
+        count: int = 1,
+        start: _dt.date | None = None,
+        end: _dt.date | None = None,
+    ) -> int | list[int]:
+        """Generate a random Unix timestamp (seconds since epoch).
+
+        Parameters
+        ----------
+        count : int
+            Number of timestamps to generate.
+        start : datetime.date | None
+            Earliest date (default: 1970-01-01).
+        end : datetime.date | None
+            Latest date (default: 2030-12-31).
+        """
+        # Use pre-computed constants for default range to avoid
+        # .toordinal() per call.
+        if start is None and end is None:
+            min_ts = _MIN_TIMESTAMP
+            max_ts = _MAX_TIMESTAMP
+        else:
+            s = start or _MIN_DATE
+            e = end or _MAX_DATE
+            min_ts = (s.toordinal() - _EPOCH_ORDINAL) * _SECONDS_IN_DAY
+            max_ts = (e.toordinal() - _EPOCH_ORDINAL + 1) * _SECONDS_IN_DAY - 1
+
+        if count == 1:
+            return self._engine.random_int(min_ts, max_ts)
+        _ri = self._engine.random_int
+        return [_ri(min_ts, max_ts) for _ in range(count)]

dataforge/providers/ecommerce.py

@@ -0,0 +1,316 @@
+"""E-commerce provider — products, SKUs, tracking, reviews."""
+
+from typing import Literal, overload
+
+from dataforge.providers.base import BaseProvider
+
+_PRODUCT_ADJECTIVES: tuple[str, ...] = (
+    "Premium",
+    "Deluxe",
+    "Ultra",
+    "Pro",
+    "Essential",
+    "Classic",
+    "Modern",
+    "Smart",
+    "Eco",
+    "Advanced",
+    "Elite",
+    "Basic",
+    "Compact",
+    "Portable",
+    "Wireless",
+    "Digital",
+    "Organic",
+    "Vintage",
+    "Artisan",
+    "Custom",
+    "Heavy-Duty",
+    "Lightweight",
+    "Industrial",
+    "Professional",
+    "Commercial",
+    "Residential",
+)
+
+_PRODUCT_MATERIALS: tuple[str, ...] = (
+    "Steel",
+    "Aluminum",
+    "Bamboo",
+    "Cotton",
+    "Leather",
+    "Silk",
+    "Wooden",
+    "Ceramic",
+    "Glass",
+    "Rubber",
+    "Plastic",
+    "Granite",
+    "Marble",
+    "Carbon Fiber",
+    "Titanium",
+    "Bronze",
+    "Copper",
+    "Linen",
+    "Wool",
+    "Concrete",
+    "Paper",
+    "Foam",
+    "Nylon",
+)
+
+_PRODUCT_ITEMS: tuple[str, ...] = (
+    "Chair",
+    "Table",
+    "Lamp",
+    "Keyboard",
+    "Mouse",
+    "Monitor",
+    "Headphones",
+    "Speaker",
+    "Camera",
+    "Watch",
+    "Bag",
+    "Wallet",
+    "Bottle",
+    "Mug",
+    "Plate",
+    "Bowl",
+    "Knife",
+    "Pan",
+    "Pillow",
+    "Blanket",
+    "Towel",
+    "Mirror",
+    "Clock",
+    "Frame",
+    "Shelf",
+    "Desk",
+    "Sofa",
+    "Bench",
+    "Stool",
+    "Rack",
+    "Cabinet",
+    "Drawer",
+    "Basket",
+    "Box",
+    "Case",
+    "Cover",
+    "Mat",
+    "Rug",
+    "Curtain",
+    "Vase",
+    "Candle",
+    "Planter",
+    "Tray",
+    "Hook",
+    "Stand",
+)
+
+_PRODUCT_CATEGORIES: tuple[str, ...] = (
+    "Electronics",
+    "Clothing",
+    "Home & Garden",
+    "Sports & Outdoors",
+    "Books",
+    "Toys & Games",
+    "Automotive",
+    "Health & Beauty",
+    "Food & Beverages",
+    "Office Supplies",
+    "Pet Supplies",
+    "Jewelry",
+    "Music",
+    "Tools & Hardware",
+    "Baby Products",
+    "Arts & Crafts",
+    "Industrial",
+    "Software",
+    "Furniture",
+)
+
+_TRACKING_PREFIXES: tuple[str, ...] = (
+    "1Z",
+    "94",
+    "92",
+    "TBA",
+    "JD",
+    "SF",
+    "YT",
+)
+
+_REVIEW_TITLES: tuple[str, ...] = (
+    "Great product!",
+    "Highly recommended",
+    "Good value for money",
+    "Exceeded expectations",
+    "Exactly as described",
+    "Decent quality",
+    "Not bad",
+    "Could be better",
+    "Disappointed",
+    "Amazing!",
+    "Perfect fit",
+    "Solid build quality",
+    "Love it!",
+    "Just okay",
+    "Works as expected",
+    "Would buy again",
+    "Five stars",
+    "Better than expected",
+    "Fantastic purchase",
+    "Very satisfied",
+)
+
+
+class EcommerceProvider(BaseProvider):
+    """Generates fake e-commerce data."""
+
+    __slots__ = ()
+
+    _provider_name = "ecommerce"
+    _locale_modules: tuple[str, ...] = ()
+    _field_map: dict[str, str] = {
+        "product_name": "product_name",
+        "product": "product_name",
+        "product_category": "product_category",
+        "category": "product_category",
+        "sku": "sku",
+        "price_with_currency": "price_with_currency",
+        "review_rating": "review_rating",
+        "rating": "review_rating",
+        "review_title": "review_title",
+        "tracking_number": "tracking_number",
+        "order_id": "order_id",
+    }
+
+    _CURRENCIES: tuple[tuple[str, str], ...] = (
+        ("$", "USD"),
+        ("€", "EUR"),
+        ("£", "GBP"),
+        ("¥", "JPY"),
+        ("$", "CAD"),
+        ("$", "AUD"),
+    )
+
+    # --- Scalar helpers ---
+
+    def _one_product_name(self) -> str:
+        _c = self._engine.choice
+        return (
+            f"{_c(_PRODUCT_ADJECTIVES)} {_c(_PRODUCT_MATERIALS)} {_c(_PRODUCT_ITEMS)}"
+        )
+
+    def _one_sku(self) -> str:
+        letters = "".join(chr(self._engine.random_int(65, 90)) for _ in range(3))
+        return f"{letters}-{self._engine.random_digits_str(6)}"
+
+    def _one_tracking(self) -> str:
+        prefix = self._engine.choice(_TRACKING_PREFIXES)
+        return prefix + self._engine.random_digits_str(18)
+
+    def _one_order_id(self) -> str:
+        return f"ORD-{self._engine.random_digits_str(10)}"
+
+    # --- Public API ---
+
+    @overload
+    def product_name(self) -> str: ...
+    @overload
+    def product_name(self, count: Literal[1]) -> str: ...
+    @overload
+    def product_name(self, count: int) -> str | list[str]: ...
+    def product_name(self, count: int = 1) -> str | list[str]:
+        """Generate a fake product name."""
+        if count == 1:
+            return self._one_product_name()
+        return [self._one_product_name() for _ in range(count)]
+
+    @overload
+    def product_category(self) -> str: ...
+    @overload
+    def product_category(self, count: Literal[1]) -> str: ...
+    @overload
+    def product_category(self, count: int) -> str | list[str]: ...
+    def product_category(self, count: int = 1) -> str | list[str]:
+        """Generate a product category."""
+        if count == 1:
+            return self._engine.choice(_PRODUCT_CATEGORIES)
+        return self._engine.choices(_PRODUCT_CATEGORIES, count)
+
+    @overload
+    def sku(self) -> str: ...
+    @overload
+    def sku(self, count: Literal[1]) -> str: ...
+    @overload
+    def sku(self, count: int) -> str | list[str]: ...
+    def sku(self, count: int = 1) -> str | list[str]:
+        """Generate a product SKU (e.g., ABC-123456)."""
+        if count == 1:
+            return self._one_sku()
+        return [self._one_sku() for _ in range(count)]
+
+    @overload
+    def price_with_currency(self) -> str: ...
+    @overload
+    def price_with_currency(self, count: Literal[1]) -> str: ...
+    @overload
+    def price_with_currency(self, count: int) -> str | list[str]: ...
+    def price_with_currency(self, count: int = 1) -> str | list[str]:
+        """Generate a price with currency symbol (e.g., $49.99)."""
+        if count == 1:
+            sym, _ = self._engine.choice(self._CURRENCIES)
+            return f"{sym}{self._engine.random_int(1, 99999) / 100:.2f}"
+        _ri = self._engine.random_int
+        _c = self._engine.choice
+        return [
+            f"{_c(self._CURRENCIES)[0]}{_ri(1, 99999) / 100:.2f}" for _ in range(count)
+        ]
+
+    @overload
+    def review_rating(self) -> int: ...
+    @overload
+    def review_rating(self, count: Literal[1]) -> int: ...
+    @overload
+    def review_rating(self, count: int) -> int | list[int]: ...
+    def review_rating(self, count: int = 1) -> int | list[int]:
+        """Generate a review rating (1-5)."""
+        if count == 1:
+            return self._engine.random_int(1, 5)
+        return [self._engine.random_int(1, 5) for _ in range(count)]
+
+    @overload
+    def review_title(self) -> str: ...
+    @overload
+    def review_title(self, count: Literal[1]) -> str: ...
+    @overload
+    def review_title(self, count: int) -> str | list[str]: ...
+    def review_title(self, count: int = 1) -> str | list[str]:
+        """Generate a product review title."""
+        if count == 1:
+            return self._engine.choice(_REVIEW_TITLES)
+        return self._engine.choices(_REVIEW_TITLES, count)
+
+    @overload
+    def tracking_number(self) -> str: ...
+    @overload
+    def tracking_number(self, count: Literal[1]) -> str: ...
+    @overload
+    def tracking_number(self, count: int) -> str | list[str]: ...
+    def tracking_number(self, count: int = 1) -> str | list[str]:
+        """Generate a shipping tracking number."""
+        if count == 1:
+            return self._one_tracking()
+        return [self._one_tracking() for _ in range(count)]
+
+    @overload
+    def order_id(self) -> str: ...
+    @overload
+    def order_id(self, count: Literal[1]) -> str: ...
+    @overload
+    def order_id(self, count: int) -> str | list[str]: ...
+    def order_id(self, count: int = 1) -> str | list[str]:
+        """Generate an order ID (e.g., ORD-1234567890)."""
+        if count == 1:
+            return self._one_order_id()
+        return [self._one_order_id() for _ in range(count)]