dataforge-py 0.2.0__py3-none-any.whl

dataforge/providers/profile.py

@@ -0,0 +1,265 @@
+"""ProfileProvider — generates coherent fake user profiles.
+
+Each profile composes data from multiple providers (person, internet,
+address, phone) to produce a consistent record where names, emails,
+and usernames relate to each other.
+
+Individual string fields are exposed in ``_field_map`` for Schema
+compatibility.  The compound ``profile()`` method returns a ``dict``
+and is available only via direct API use.
+"""
+
+from typing import TYPE_CHECKING, Literal, overload
+
+from dataforge.backend import RandomEngine
+from dataforge.providers.base import BaseProvider
+
+if TYPE_CHECKING:
+    from dataforge.core import DataForge
+
+
+class ProfileProvider(BaseProvider):
+    """Generates coherent fake user profiles.
+
+    Unlike other providers, ``ProfileProvider`` needs a reference to
+    the parent :class:`DataForge` instance so it can delegate to
+    ``person``, ``internet``, ``address``, and ``phone`` providers.
+
+    Parameters
+    ----------
+    engine : RandomEngine
+        The shared random engine instance.
+    forge : DataForge
+        The parent DataForge instance for cross-provider access.
+    """
+
+    __slots__ = ("_forge",)
+
+    _provider_name = "profile"
+    _locale_modules: tuple[str, ...] = ()
+    _needs_forge: bool = True
+    _field_map: dict[str, str] = {
+        "profile_first_name": "profile_first_name",
+        "profile_last_name": "profile_last_name",
+        "profile_email": "profile_email",
+        "profile_phone": "profile_phone",
+        "profile_city": "profile_city",
+        "profile_state": "profile_state",
+        "profile_zip_code": "profile_zip_code",
+        "profile_job_title": "profile_job_title",
+    }
+
+    def __init__(self, engine: RandomEngine, forge: "DataForge") -> None:
+        super().__init__(engine)
+        self._forge = forge
+
+    # ------------------------------------------------------------------
+    # Individual field methods (for _field_map / Schema compatibility)
+    # These delegate to sub-providers — values are independent per call.
+    # For coherent profiles, use profile() instead.
+    # ------------------------------------------------------------------
+
+    @overload
+    def profile_first_name(self) -> str: ...
+    @overload
+    def profile_first_name(self, count: Literal[1]) -> str: ...
+    @overload
+    def profile_first_name(self, count: int) -> str | list[str]: ...
+    def profile_first_name(self, count: int = 1) -> str | list[str]:
+        """Generate a first name (delegates to PersonProvider).
+
+        Parameters
+        ----------
+        count : int
+            Number of names to generate.
+
+        Returns
+        -------
+        str or list[str]
+        """
+        return self._forge.person.first_name(count)
+
+    @overload
+    def profile_last_name(self) -> str: ...
+    @overload
+    def profile_last_name(self, count: Literal[1]) -> str: ...
+    @overload
+    def profile_last_name(self, count: int) -> str | list[str]: ...
+    def profile_last_name(self, count: int = 1) -> str | list[str]:
+        """Generate a last name (delegates to PersonProvider).
+
+        Parameters
+        ----------
+        count : int
+            Number of names to generate.
+
+        Returns
+        -------
+        str or list[str]
+        """
+        return self._forge.person.last_name(count)
+
+    @overload
+    def profile_email(self) -> str: ...
+    @overload
+    def profile_email(self, count: Literal[1]) -> str: ...
+    @overload
+    def profile_email(self, count: int) -> str | list[str]: ...
+    def profile_email(self, count: int = 1) -> str | list[str]:
+        """Generate an email address (delegates to InternetProvider).
+
+        Parameters
+        ----------
+        count : int
+            Number of emails to generate.
+
+        Returns
+        -------
+        str or list[str]
+        """
+        return self._forge.internet.email(count)
+
+    @overload
+    def profile_phone(self) -> str: ...
+    @overload
+    def profile_phone(self, count: Literal[1]) -> str: ...
+    @overload
+    def profile_phone(self, count: int) -> str | list[str]: ...
+    def profile_phone(self, count: int = 1) -> str | list[str]:
+        """Generate a phone number (delegates to PhoneProvider).
+
+        Parameters
+        ----------
+        count : int
+            Number of phone numbers to generate.
+
+        Returns
+        -------
+        str or list[str]
+        """
+        return self._forge.phone.phone_number(count)
+
+    @overload
+    def profile_city(self) -> str: ...
+    @overload
+    def profile_city(self, count: Literal[1]) -> str: ...
+    @overload
+    def profile_city(self, count: int) -> str | list[str]: ...
+    def profile_city(self, count: int = 1) -> str | list[str]:
+        """Generate a city name (delegates to AddressProvider).
+
+        Parameters
+        ----------
+        count : int
+            Number of cities to generate.
+
+        Returns
+        -------
+        str or list[str]
+        """
+        return self._forge.address.city(count)
+
+    @overload
+    def profile_state(self) -> str: ...
+    @overload
+    def profile_state(self, count: Literal[1]) -> str: ...
+    @overload
+    def profile_state(self, count: int) -> str | list[str]: ...
+    def profile_state(self, count: int = 1) -> str | list[str]:
+        """Generate a state name (delegates to AddressProvider).
+
+        Parameters
+        ----------
+        count : int
+            Number of states to generate.
+
+        Returns
+        -------
+        str or list[str]
+        """
+        return self._forge.address.state(count)
+
+    @overload
+    def profile_zip_code(self) -> str: ...
+    @overload
+    def profile_zip_code(self, count: Literal[1]) -> str: ...
+    @overload
+    def profile_zip_code(self, count: int) -> str | list[str]: ...
+    def profile_zip_code(self, count: int = 1) -> str | list[str]:
+        """Generate a zip code (delegates to AddressProvider).
+
+        Parameters
+        ----------
+        count : int
+            Number of zip codes to generate.
+
+        Returns
+        -------
+        str or list[str]
+        """
+        return self._forge.address.zip_code(count)
+
+    @overload
+    def profile_job_title(self) -> str: ...
+    @overload
+    def profile_job_title(self, count: Literal[1]) -> str: ...
+    @overload
+    def profile_job_title(self, count: int) -> str | list[str]: ...
+    def profile_job_title(self, count: int = 1) -> str | list[str]:
+        """Generate a job title (delegates to CompanyProvider).
+
+        Parameters
+        ----------
+        count : int
+            Number of job titles to generate.
+
+        Returns
+        -------
+        str or list[str]
+        """
+        return self._forge.company.job_title(count)
+
+    # ------------------------------------------------------------------
+    # Compound profile method (direct API only, not in _field_map)
+    # ------------------------------------------------------------------
+
+    def profile(self, count: int = 1) -> dict[str, str] | list[dict[str, str]]:
+        """Generate a coherent user profile.
+
+        Each profile is a ``dict`` with keys: ``first_name``,
+        ``last_name``, ``email``, ``phone``, ``city``, ``state``,
+        ``zip_code``, ``job_title``.
+
+        The ``email`` is derived from the same first/last name for
+        coherence within each profile.
+
+        Parameters
+        ----------
+        count : int
+            Number of profiles to generate.
+
+        Returns
+        -------
+        dict[str, str] or list[dict[str, str]]
+        """
+
+        def _one_profile() -> dict[str, str]:
+            first = self._forge.person.first_name()
+            last = self._forge.person.last_name()
+            # Build a coherent email from the person's name
+            domain = self._forge.internet.domain()
+            email = f"{first.lower()}.{last.lower()}@{domain}"
+            return {
+                "first_name": first,
+                "last_name": last,
+                "email": email,
+                "phone": self._forge.phone.phone_number(),
+                "city": self._forge.address.city(),
+                "state": self._forge.address.state(),
+                "zip_code": self._forge.address.zip_code(),
+                "job_title": self._forge.company.job_title(),
+            }
+
+        if count == 1:
+            return _one_profile()
+        return [_one_profile() for _ in range(count)]

dataforge/providers/science.py

@@ -0,0 +1,365 @@
+"""Science provider — elements, units, formulas, planets, etc."""
+
+from typing import Literal, overload
+
+from dataforge.providers.base import BaseProvider
+
+_CHEMICAL_ELEMENTS: tuple[str, ...] = (
+    "Hydrogen",
+    "Helium",
+    "Lithium",
+    "Beryllium",
+    "Boron",
+    "Carbon",
+    "Nitrogen",
+    "Oxygen",
+    "Fluorine",
+    "Neon",
+    "Sodium",
+    "Magnesium",
+    "Aluminum",
+    "Silicon",
+    "Phosphorus",
+    "Sulfur",
+    "Chlorine",
+    "Argon",
+    "Potassium",
+    "Calcium",
+    "Scandium",
+    "Titanium",
+    "Vanadium",
+    "Chromium",
+    "Manganese",
+    "Iron",
+    "Cobalt",
+    "Nickel",
+    "Copper",
+    "Zinc",
+    "Gallium",
+    "Germanium",
+    "Arsenic",
+    "Selenium",
+    "Bromine",
+    "Krypton",
+    "Rubidium",
+    "Strontium",
+    "Yttrium",
+    "Zirconium",
+    "Niobium",
+    "Molybdenum",
+    "Technetium",
+    "Ruthenium",
+    "Rhodium",
+    "Palladium",
+    "Silver",
+    "Gold",
+    "Platinum",
+    "Iridium",
+)
+
+_ELEMENT_SYMBOLS: tuple[str, ...] = (
+    "H",
+    "He",
+    "Li",
+    "Be",
+    "B",
+    "C",
+    "N",
+    "O",
+    "F",
+    "Ne",
+    "Na",
+    "Mg",
+    "Al",
+    "Si",
+    "P",
+    "S",
+    "Cl",
+    "Ar",
+    "K",
+    "Ca",
+    "Sc",
+    "Ti",
+    "V",
+    "Cr",
+    "Mn",
+    "Fe",
+    "Co",
+    "Ni",
+    "Cu",
+    "Zn",
+    "Ga",
+    "Ge",
+    "As",
+    "Se",
+    "Br",
+    "Kr",
+    "Rb",
+    "Sr",
+    "Y",
+    "Zr",
+    "Nb",
+    "Mo",
+    "Tc",
+    "Ru",
+    "Rh",
+    "Pd",
+    "Ag",
+    "Au",
+    "Pt",
+    "Ir",
+)
+
+_SI_UNITS: tuple[str, ...] = (
+    "meter (m)",
+    "kilogram (kg)",
+    "second (s)",
+    "ampere (A)",
+    "kelvin (K)",
+    "mole (mol)",
+    "candela (cd)",
+    "hertz (Hz)",
+    "newton (N)",
+    "pascal (Pa)",
+    "joule (J)",
+    "watt (W)",
+    "coulomb (C)",
+    "volt (V)",
+    "farad (F)",
+    "ohm (Ω)",
+    "siemens (S)",
+    "weber (Wb)",
+    "tesla (T)",
+    "henry (H)",
+    "lumen (lm)",
+    "lux (lx)",
+    "becquerel (Bq)",
+    "gray (Gy)",
+    "sievert (Sv)",
+)
+
+_PLANETS: tuple[str, ...] = (
+    "Mercury",
+    "Venus",
+    "Earth",
+    "Mars",
+    "Jupiter",
+    "Saturn",
+    "Uranus",
+    "Neptune",
+)
+
+_GALAXIES: tuple[str, ...] = (
+    "Milky Way",
+    "Andromeda",
+    "Triangulum",
+    "Centaurus A",
+    "Messier 87",
+    "Sombrero Galaxy",
+    "Whirlpool Galaxy",
+    "Pinwheel Galaxy",
+    "Cartwheel Galaxy",
+    "Cigar Galaxy",
+    "Black Eye Galaxy",
+    "Sunflower Galaxy",
+    "Tadpole Galaxy",
+    "Hoag's Object",
+    "NGC 1300",
+)
+
+_CONSTELLATIONS: tuple[str, ...] = (
+    "Orion",
+    "Ursa Major",
+    "Ursa Minor",
+    "Cassiopeia",
+    "Scorpius",
+    "Leo",
+    "Gemini",
+    "Taurus",
+    "Sagittarius",
+    "Andromeda",
+    "Aquarius",
+    "Aries",
+    "Cancer",
+    "Capricornus",
+    "Libra",
+    "Pisces",
+    "Virgo",
+    "Cygnus",
+    "Lyra",
+    "Pegasus",
+    "Perseus",
+    "Draco",
+    "Centaurus",
+    "Canis Major",
+    "Canis Minor",
+)
+
+_SCIENTIFIC_DISCIPLINES: tuple[str, ...] = (
+    "Physics",
+    "Chemistry",
+    "Biology",
+    "Mathematics",
+    "Astronomy",
+    "Geology",
+    "Ecology",
+    "Genetics",
+    "Neuroscience",
+    "Biochemistry",
+    "Quantum Mechanics",
+    "Thermodynamics",
+    "Electrodynamics",
+    "Organic Chemistry",
+    "Inorganic Chemistry",
+    "Molecular Biology",
+    "Astrophysics",
+    "Cosmology",
+    "Paleontology",
+    "Oceanography",
+    "Meteorology",
+    "Seismology",
+    "Virology",
+    "Immunology",
+    "Epidemiology",
+)
+
+_METRIC_PREFIXES: tuple[str, ...] = (
+    "yotta (Y)",
+    "zetta (Z)",
+    "exa (E)",
+    "peta (P)",
+    "tera (T)",
+    "giga (G)",
+    "mega (M)",
+    "kilo (k)",
+    "hecto (h)",
+    "deca (da)",
+    "deci (d)",
+    "centi (c)",
+    "milli (m)",
+    "micro (μ)",
+    "nano (n)",
+    "pico (p)",
+    "femto (f)",
+    "atto (a)",
+)
+
+
+class ScienceProvider(BaseProvider):
+    """Generates fake science data — elements, planets, units, etc."""
+
+    __slots__ = ()
+
+    _provider_name = "science"
+    _locale_modules: tuple[str, ...] = ()
+    _field_map: dict[str, str] = {
+        "chemical_element": "chemical_element",
+        "element": "chemical_element",
+        "element_symbol": "element_symbol",
+        "si_unit": "si_unit",
+        "unit": "si_unit",
+        "planet": "planet",
+        "galaxy": "galaxy",
+        "constellation": "constellation",
+        "scientific_discipline": "scientific_discipline",
+        "discipline": "scientific_discipline",
+        "metric_prefix": "metric_prefix",
+    }
+
+    # --- Public API ---
+
+    @overload
+    def chemical_element(self) -> str: ...
+    @overload
+    def chemical_element(self, count: Literal[1]) -> str: ...
+    @overload
+    def chemical_element(self, count: int) -> str | list[str]: ...
+    def chemical_element(self, count: int = 1) -> str | list[str]:
+        """Generate a chemical element name (e.g., Hydrogen, Carbon)."""
+        if count == 1:
+            return self._engine.choice(_CHEMICAL_ELEMENTS)
+        return self._engine.choices(_CHEMICAL_ELEMENTS, count)
+
+    @overload
+    def element_symbol(self) -> str: ...
+    @overload
+    def element_symbol(self, count: Literal[1]) -> str: ...
+    @overload
+    def element_symbol(self, count: int) -> str | list[str]: ...
+    def element_symbol(self, count: int = 1) -> str | list[str]:
+        """Generate a chemical element symbol (e.g., H, C, Fe)."""
+        if count == 1:
+            return self._engine.choice(_ELEMENT_SYMBOLS)
+        return self._engine.choices(_ELEMENT_SYMBOLS, count)
+
+    @overload
+    def si_unit(self) -> str: ...
+    @overload
+    def si_unit(self, count: Literal[1]) -> str: ...
+    @overload
+    def si_unit(self, count: int) -> str | list[str]: ...
+    def si_unit(self, count: int = 1) -> str | list[str]:
+        """Generate an SI unit (e.g., meter (m), joule (J))."""
+        if count == 1:
+            return self._engine.choice(_SI_UNITS)
+        return self._engine.choices(_SI_UNITS, count)
+
+    @overload
+    def planet(self) -> str: ...
+    @overload
+    def planet(self, count: Literal[1]) -> str: ...
+    @overload
+    def planet(self, count: int) -> str | list[str]: ...
+    def planet(self, count: int = 1) -> str | list[str]:
+        """Generate a planet name from our solar system."""
+        if count == 1:
+            return self._engine.choice(_PLANETS)
+        return self._engine.choices(_PLANETS, count)
+
+    @overload
+    def galaxy(self) -> str: ...
+    @overload
+    def galaxy(self, count: Literal[1]) -> str: ...
+    @overload
+    def galaxy(self, count: int) -> str | list[str]: ...
+    def galaxy(self, count: int = 1) -> str | list[str]:
+        """Generate a galaxy name (e.g., Milky Way, Andromeda)."""
+        if count == 1:
+            return self._engine.choice(_GALAXIES)
+        return self._engine.choices(_GALAXIES, count)
+
+    @overload
+    def constellation(self) -> str: ...
+    @overload
+    def constellation(self, count: Literal[1]) -> str: ...
+    @overload
+    def constellation(self, count: int) -> str | list[str]: ...
+    def constellation(self, count: int = 1) -> str | list[str]:
+        """Generate a constellation name (e.g., Orion, Leo)."""
+        if count == 1:
+            return self._engine.choice(_CONSTELLATIONS)
+        return self._engine.choices(_CONSTELLATIONS, count)
+
+    @overload
+    def scientific_discipline(self) -> str: ...
+    @overload
+    def scientific_discipline(self, count: Literal[1]) -> str: ...
+    @overload
+    def scientific_discipline(self, count: int) -> str | list[str]: ...
+    def scientific_discipline(self, count: int = 1) -> str | list[str]:
+        """Generate a scientific discipline (e.g., Physics, Genetics)."""
+        if count == 1:
+            return self._engine.choice(_SCIENTIFIC_DISCIPLINES)
+        return self._engine.choices(_SCIENTIFIC_DISCIPLINES, count)
+
+    @overload
+    def metric_prefix(self) -> str: ...
+    @overload
+    def metric_prefix(self, count: Literal[1]) -> str: ...
+    @overload
+    def metric_prefix(self, count: int) -> str | list[str]: ...
+    def metric_prefix(self, count: int = 1) -> str | list[str]:
+        """Generate a metric prefix (e.g., kilo (k), nano (n))."""
+        if count == 1:
+            return self._engine.choice(_METRIC_PREFIXES)
+        return self._engine.choices(_METRIC_PREFIXES, count)