dataforger 0.1.1__tar.gz

dataforger-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karmanshi Shrivastava
+
+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.

dataforger-0.1.1/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: dataforger
+Version: 0.1.1
+Summary: Generate fake data from Python or the command line.
+License: MIT License
+        
+        Copyright (c) 2026 Karmanshi Shrivastava
+        
+        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.
+        
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# dataforger
+
+Generate realistic fake data from Python or the command line, and save it as
+CSV or JSON. Dataforger uses only the Python standard library and has no
+third-party runtime dependencies.
+
+Built-in names, streets, companies, and email domains are stored in
+`src/dataforger/data.json`. Country names and their associated cities are
+stored in `src/dataforger/countries.json`; when generating a record with both
+country and city fields, the city is selected from that country's list.
+
+## Install
+
+Requires Python 3.10 or later.
+
+From a checkout of this repository:
+
+```console
+python -m pip install .
+```
+
+After publishing the package to PyPI:
+
+```console
+python -m pip install dataforger
+```
+
+## Publishing to PyPI
+
+The GitHub Actions workflow runs the tests on Python 3.10 through 3.13 and
+builds wheel and source distributions on pushes and pull requests. To publish,
+configure a PyPI trusted publisher for this GitHub repository, using workflow
+`.github/workflows/publish.yml` and the GitHub environment `pypi`. Then create
+and publish a GitHub Release; the workflow publishes its tested distributions
+to PyPI using trusted publishing.
+
+## Command line
+
+Run `dataforger` without field options for an interactive prompt. Or specify
+all options directly:
+
+```console
+dataforger --rows 100 --field name:name --field email:email --field age:age --format csv --output users.csv --seed 42
+```
+
+The `--field` option can be repeated. Supported field types are `name`,
+`first_name`, `last_name`, `email`, `phone`, `address`, `city`, `country`,
+`company`, `uuid`, `date`, `age`, `integer`, `float`, and `boolean`. If
+`--field` is omitted, the command prompts for the row count, format, output
+path, and fields. When using command-line field options, the defaults are 10
+rows, JSON format, and `data.json`.
+
+## Python API
+
+```python
+from dataforger import generate_data, write_data
+
+records = generate_data(
+    {"name": "name", "email": "email", "age": "age"},
+    rows=100,
+    seed=42,
+)
+
+write_data(records, "users.json", "json")
+write_data(records, "users.csv", "csv")
+```
+
+`generate_data` returns a list of dictionaries. Pass the resulting records,
+an output path, and either `"csv"` or `"json"` to `write_data`.

dataforger-0.1.1/README.md

@@ -0,0 +1,69 @@
+# dataforger
+
+Generate realistic fake data from Python or the command line, and save it as
+CSV or JSON. Dataforger uses only the Python standard library and has no
+third-party runtime dependencies.
+
+Built-in names, streets, companies, and email domains are stored in
+`src/dataforger/data.json`. Country names and their associated cities are
+stored in `src/dataforger/countries.json`; when generating a record with both
+country and city fields, the city is selected from that country's list.
+
+## Install
+
+Requires Python 3.10 or later.
+
+From a checkout of this repository:
+
+```console
+python -m pip install .
+```
+
+After publishing the package to PyPI:
+
+```console
+python -m pip install dataforger
+```
+
+## Publishing to PyPI
+
+The GitHub Actions workflow runs the tests on Python 3.10 through 3.13 and
+builds wheel and source distributions on pushes and pull requests. To publish,
+configure a PyPI trusted publisher for this GitHub repository, using workflow
+`.github/workflows/publish.yml` and the GitHub environment `pypi`. Then create
+and publish a GitHub Release; the workflow publishes its tested distributions
+to PyPI using trusted publishing.
+
+## Command line
+
+Run `dataforger` without field options for an interactive prompt. Or specify
+all options directly:
+
+```console
+dataforger --rows 100 --field name:name --field email:email --field age:age --format csv --output users.csv --seed 42
+```
+
+The `--field` option can be repeated. Supported field types are `name`,
+`first_name`, `last_name`, `email`, `phone`, `address`, `city`, `country`,
+`company`, `uuid`, `date`, `age`, `integer`, `float`, and `boolean`. If
+`--field` is omitted, the command prompts for the row count, format, output
+path, and fields. When using command-line field options, the defaults are 10
+rows, JSON format, and `data.json`.
+
+## Python API
+
+```python
+from dataforger import generate_data, write_data
+
+records = generate_data(
+    {"name": "name", "email": "email", "age": "age"},
+    rows=100,
+    seed=42,
+)
+
+write_data(records, "users.json", "json")
+write_data(records, "users.csv", "csv")
+```
+
+`generate_data` returns a list of dictionaries. Pass the resulting records,
+an output path, and either `"csv"` or `"json"` to `write_data`.

dataforger-0.1.1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dataforger"
+version = "0.1.1"
+description = "Generate fake data from Python or the command line."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.scripts]
+dataforger = "dataforger.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dataforger = ["data.json", "countries.json"]

dataforger-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dataforger-0.1.1/src/dataforger/__init__.py

@@ -0,0 +1,3 @@
+from dataforger.core import FIELD_TYPES, generate_data, write_data
+
+__all__ = ["FIELD_TYPES", "generate_data", "write_data"]

dataforger-0.1.1/src/dataforger/cli.py

@@ -0,0 +1,98 @@
+import argparse
+import sys
+from collections.abc import Sequence
+
+from dataforger.core import FIELD_TYPES, Format, generate_data, write_data
+
+
+def _parse_fields(values: Sequence[str]) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    for value in values:
+        name, separator, field_type = value.partition(":")
+        name = name.strip()
+        field_type = field_type.strip()
+        if not separator or not name or not field_type:
+            raise ValueError(
+                f"Invalid field {value!r}; use the format NAME:TYPE."
+            )
+        if name in fields:
+            raise ValueError(f"Field {name!r} was specified more than once.")
+        fields[name] = field_type
+    return fields
+
+
+def _prompt_fields() -> dict[str, str]:
+    print(f"Available field types: {', '.join(FIELD_TYPES)}")
+    fields: dict[str, str] = {}
+    while True:
+        name = input("Field name (leave blank when finished): ").strip()
+        if not name:
+            break
+        field_type = input("Field type [name]: ").strip() or "name"
+        if name in fields:
+            raise ValueError(f"Field {name!r} was specified more than once.")
+        fields[name] = field_type
+    if not fields:
+        raise ValueError("At least one field is required.")
+    return fields
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dataforger",
+        description="Generate fake data in CSV or JSON format.",
+    )
+    parser.add_argument(
+        "--field",
+        action="append",
+        metavar="NAME:TYPE",
+        help="field to generate; repeat for additional fields (e.g. name:name)",
+    )
+    parser.add_argument("--rows", type=int, help="number of records to generate")
+    parser.add_argument(
+        "--format",
+        choices=("csv", "json"),
+        help="output format (defaults to json)",
+    )
+    parser.add_argument("--output", help="output file path")
+    parser.add_argument("--seed", type=int, help="seed for repeatable data")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.field:
+            fields = _parse_fields(args.field)
+            rows = 10 if args.rows is None else args.rows
+            output_format: Format = args.format or "json"
+            output = args.output or f"data.{output_format}"
+        else:
+            default_rows = args.rows if args.rows is not None else 10
+            rows_input = input(f"Number of rows [{default_rows}]: ").strip()
+            rows = int(rows_input) if rows_input else default_rows
+            format_input = input(
+                f"Output format (csv/json) [{args.format or 'json'}]: "
+            ).strip()
+            output_format = format_input or args.format or "json"
+            output = input(
+                f"Output file [{args.output or f'data.{output_format}'}]: "
+            ).strip() or args.output or f"data.{output_format}"
+            fields = _prompt_fields()
+
+        records = generate_data(fields, rows=rows, seed=args.seed)
+        path = write_data(records, output, output_format)
+    except (OSError, ValueError) as error:
+        parser.error(str(error))
+    except KeyboardInterrupt:
+        print("\nGeneration cancelled.", file=sys.stderr)
+        return 130
+
+    print(f"Generated {len(records)} rows in {path}.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dataforger-0.1.1/src/dataforger/core.py

@@ -0,0 +1,250 @@
+import csv
+import json
+import random
+import uuid
+from collections.abc import Mapping, Sequence
+from datetime import date, timedelta
+from importlib.resources import files
+from pathlib import Path
+from typing import Callable, Literal
+
+Format = Literal["csv", "json"]
+
+_DATA_KEYS = (
+    "first_names",
+    "last_names",
+    "streets",
+    "street_types",
+    "companies",
+    "company_suffixes",
+    "email_domains",
+)
+
+
+def _load_data() -> dict[str, tuple[str, ...]]:
+    raw_data = json.loads(
+        files("dataforger").joinpath("data.json").read_text(encoding="utf-8")
+    )
+    if not isinstance(raw_data, dict):
+        raise ValueError("Bundled data.json must contain a JSON object.")
+
+    data: dict[str, tuple[str, ...]] = {}
+    for key in _DATA_KEYS:
+        values = raw_data.get(key)
+        if (
+            not isinstance(values, list)
+            or not values
+            or any(not isinstance(value, str) or not value for value in values)
+        ):
+            raise ValueError(
+                f"Bundled data.json must define {key!r} as a non-empty list "
+                "of strings."
+            )
+        data[key] = tuple(values)
+    return data
+
+
+_DATA = _load_data()
+
+
+def _load_country_cities() -> dict[str, tuple[str, ...]]:
+    raw_data = json.loads(
+        files("dataforger").joinpath("countries.json").read_text(encoding="utf-8")
+    )
+    if not isinstance(raw_data, dict) or not raw_data:
+        raise ValueError("Bundled countries.json must contain a non-empty JSON object.")
+
+    country_cities: dict[str, tuple[str, ...]] = {}
+    for country, cities in raw_data.items():
+        if (
+            not isinstance(country, str)
+            or not country
+            or not isinstance(cities, list)
+            or not cities
+            or any(not isinstance(city, str) or not city for city in cities)
+        ):
+            raise ValueError(
+                "Bundled countries.json must map country names to non-empty "
+                "lists of city names."
+            )
+        country_cities[country] = tuple(cities)
+    return country_cities
+
+
+_COUNTRY_CITIES = _load_country_cities()
+
+FIELD_TYPES = (
+    "name",
+    "first_name",
+    "last_name",
+    "email",
+    "phone",
+    "address",
+    "city",
+    "country",
+    "company",
+    "uuid",
+    "date",
+    "age",
+    "integer",
+    "float",
+    "boolean",
+)
+
+def _first_name(rng: random.Random) -> str:
+    return rng.choice(_DATA["first_names"])
+
+
+def _last_name(rng: random.Random) -> str:
+    return rng.choice(_DATA["last_names"])
+
+
+def _name(rng: random.Random) -> str:
+    return f"{_first_name(rng)} {_last_name(rng)}"
+
+
+def _email(rng: random.Random) -> str:
+    first = _first_name(rng).lower()
+    last = _last_name(rng).lower()
+    suffix = rng.randint(1, 9999)
+    return f"{first}.{last}{suffix}@{rng.choice(_DATA['email_domains'])}"
+
+
+def _phone(rng: random.Random) -> str:
+    area = rng.randint(200, 999)
+    exchange = rng.randint(200, 999)
+    subscriber = rng.randint(0, 9999)
+    return f"+1-{area}-{exchange}-{subscriber:04d}"
+
+
+def _address(rng: random.Random, city: str) -> str:
+    number = rng.randint(1, 9999)
+    street = rng.choice(_DATA["streets"])
+    street_type = rng.choice(_DATA["street_types"])
+    return f"{number} {street} {street_type}, {city}"
+
+
+def _company(rng: random.Random) -> str:
+    company = rng.choice(_DATA["companies"])
+    suffix = rng.choice(_DATA["company_suffixes"])
+    return f"{company} {suffix}"
+
+
+def _date(rng: random.Random) -> str:
+    start = date(1970, 1, 1)
+    days = (date.today() - start).days
+    return (start + timedelta(days=rng.randint(0, days))).isoformat()
+
+
+def _integer(rng: random.Random) -> int:
+    return rng.randint(0, 100_000)
+
+
+def _age(rng: random.Random) -> int:
+    return rng.randint(0, 100)
+
+
+def _float(rng: random.Random) -> float:
+    return round(rng.uniform(0, 100_000), 2)
+
+
+_PROVIDERS: dict[str, Callable[[random.Random], object]] = {
+    "name": _name,
+    "first_name": _first_name,
+    "last_name": _last_name,
+    "email": _email,
+    "phone": _phone,
+    "company": _company,
+    "uuid": lambda rng: str(uuid.UUID(int=rng.getrandbits(128), version=4)),
+    "date": _date,
+    "age": _age,
+    "integer": _integer,
+    "float": _float,
+    "boolean": lambda rng: rng.choice((True, False)),
+}
+
+
+def generate_data(
+    fields: Mapping[str, str],
+    rows: int = 10,
+    seed: int | None = None,
+) -> list[dict[str, object]]:
+    """Generate records using a mapping of field names to supported value types."""
+    if not fields:
+        raise ValueError("At least one field is required.")
+    if isinstance(rows, bool) or not isinstance(rows, int) or rows < 1:
+        raise ValueError("rows must be a positive integer.")
+
+    for name, field_type in fields.items():
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("Field names must be non-empty strings.")
+        if not isinstance(field_type, str) or field_type not in FIELD_TYPES:
+            raise ValueError(
+                f"Unknown field type {field_type!r}. Choose from: "
+                f"{', '.join(FIELD_TYPES)}."
+            )
+
+    rng = random.Random(seed)
+
+    records: list[dict[str, object]] = []
+    for _ in range(rows):
+        location_country = (
+            rng.choice(tuple(_COUNTRY_CITIES))
+            if any(
+                field_type in ("address", "city", "country")
+                for field_type in fields.values()
+            )
+            else None
+        )
+        location_city = (
+            rng.choice(_COUNTRY_CITIES[location_country])
+            if location_country is not None
+            and any(field_type in ("address", "city") for field_type in fields.values())
+            else None
+        )
+        record: dict[str, object] = {}
+        for name, field_type in fields.items():
+            if field_type == "country":
+                record[name] = location_country
+            elif field_type == "city":
+                assert location_city is not None
+                record[name] = location_city
+            elif field_type == "address":
+                assert location_city is not None
+                record[name] = _address(rng, location_city)
+            else:
+                record[name] = _PROVIDERS[field_type](rng)
+        records.append(record)
+    return records
+
+
+def write_data(
+    records: Sequence[Mapping[str, object]],
+    output: str | Path,
+    format: Format,
+) -> Path:
+    """Write generated records to a CSV or JSON file and return its path."""
+    if format not in ("csv", "json"):
+        raise ValueError("format must be 'csv' or 'json'.")
+    if not records:
+        raise ValueError("At least one record is required.")
+
+    path = Path(output)
+    if format == "json":
+        with path.open("w", encoding="utf-8") as file:
+            json.dump(
+                [dict(record) for record in records],
+                file,
+                indent=2,
+                ensure_ascii=False,
+            )
+            file.write("\n")
+    else:
+        fieldnames = list(records[0])
+        if not fieldnames:
+            raise ValueError("Records must contain at least one field.")
+        with path.open("w", encoding="utf-8", newline="") as file:
+            writer = csv.DictWriter(file, fieldnames=fieldnames)
+            writer.writeheader()
+            writer.writerows(records)
+    return path