Metadata-Version: 2.4
Name: dumph
Version: 1.2.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: LICENSE
Summary: Philippine mock data generator and python bindings for local dataset seeding, development workflows and automated testing.
Keywords: mock-data,philippines,dataset-generator,rust,pyo3,seeding
Author-email: "Christian Joyce G. Garcia" <cjggarcia.dev@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<p align="center">
    <img src="https://gitlab.com/cjggarcia.dev/dumph/-/raw/main/assets/banner.png?ref_type=heads" alt="dumph banner">
</p>

<p align="center">
    <a href="https://pypi.org/project/dumph/"><img src="https://img.shields.io/pypi/v/dumph?style=flat-square&color=blue" alt="PyPI Version"></a>
    <a href="https://pypistats.com/packages/dumph"><img src="https://pypistats.com/api/badges/dumph?period=total" alt="PyPI Stats"></a>
    <a href="https://pypi.org/project/dumph/"><img src="https://img.shields.io/badge/python-%3E%3D3.8-blue?style=flat-square&logo=python&logoColor=white" alt="Python Versions"></a>
    <a href="https://www.rust-lang.org/"><img src="https://img.shields.io/badge/rust-1.85%2B-orange?style=flat-square&logo=rust" alt="Rust Version"></a>
    <a href="https://gitlab.com/cjggarcia.dev/dumph"><img src="https://img.shields.io/badge/GitLab-repo-fc6d26?style=flat-square&logo=gitlab&logoColor=white" alt="GitLab"></a>
    <a href="https://pypi.org/project/dumph/"><img src="https://img.shields.io/pypi/implementation/dumph?style=flat-square" alt="Python Implementation"></a>
    <a href="https://gitlab.com/cjggarcia.dev/dumph/-/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green?style=flat-square" alt="License"></a>
</p>

# Dumph

> Philippine mock data generator and Python bindings for local dataset seeding, development workflows and automated testing

**Dumph** is a library for generating realistic Philippine mock data, with first-class Python bindings. It is built for database seeding, development workflows and automated testing, without maintaining hand-written fixtures or relying on foreign-locale generators.

Each record is generated as a coherent whole rather than a collection of independent random values:

- **Identity:** first names are matched to the record's gender, birthdates are consistent with the generated age and civil status is plausible for that age.
- **Contact:** email addresses are derived from the record's name and phone numbers follow Philippine carrier and area code conventions.
- **Geography:** barangay, city/municipality, province, region and ZIP code are always drawn from the same real location, so the address hierarchy is never mismatched.

The core is implemented in [Rust](https://rust-lang.org/) and exposed to Python through [PyO3](https://pyo3.rs/v0.29.3/). Geographic data spans *Luzon*, *Visayas* and *Mindanao* and is embedded directly in the compiled library, so [Dumph](https://gitlab.com/cjggarcia.dev/dumph) runs offline with no runtime data files, and ships with complete type hints for a smooth editor and type-checker experience.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
    - [Quick Start](#quick-start)
    - [Reproducible Output](#reproducible-output)
    - [Field Options](#field-options)
    - [Location Filters](#location-filters)
    - [Unique Values](#unique-values)
    - [Streaming](#streaming)
    - [Flexible Custom Types](#flexible-custom-types)
    - [Saving to JSON or CSV](#saving-to-json-or-csv)
    - [Type Hints](#type-hints)
    - [Nested Address](#nested-address)
    - [Seeding a Database Example](#seeding-a-database-example)
    - [Notes](#notes)
- [API Reference](#api-reference)
    - [Arguments and Parameters](#arguments-and-parameters)
    - [Field Options Reference](#field-options-reference)
    - [Built-in Types](#built-in-types)
- [Data Sources](#data-sources)
- [Changelog](#changelog)
- [License](#license)
- [Author](#author)

## Features

- **Localized Philippine data:** Filipino names, mobile and landline numbers and addresses.
- **Consistent rows:** Names match gender, birthdate matches age, civil status fits the age and emails come from the row's name.
- **Complete address hierarchy:** Region, province, city/municipality, barangay and ZIP code from the same real location.
- **Location filters:** Restrict generated addresses to an island group, region, province or city.
- **Reproducible output:** Pass a `seed` to get the same data every run, for stable test fixtures.
- **Field options:** Set ranges, date bounds, probabilities and uniqueness per column.
- **Unique values:** `unique=True` guarantees no repeats, for tables with unique constraints.
- **Streaming:** `seed_iter()` generates one row at a time for very large datasets.
- **Government and ID formats:** SSS, TIN, PhilHealth, PhilSys, Pag-IBIG, UMID, passport, driver's license and plate numbers.
- **Profile fields:** Middle name, suffix, username, occupation, employer, religion, height and weight.
- **Flexible dynamic types:** Built-in pattern matching for custom integer ranges, precision-controlled floats and custom choices.
- **Custom schemas:** Map your own column names to built-in field types.
- **Built-in export:** Save to JSON or CSV with one call.
- **Rust core:** Native extension with a small Python API: `seed()`, `seed_iter()` and `save()`.
- **Fully typed:** [PEP 561](https://peps.python.org/pep-0561/) type stubs with `FieldType` and `FieldSpec`.
- **Zero runtime dependencies:** Datasets are compiled into the library.

## Installation

Install from [PyPI](https://pypi.org/project/dumph):

```bash
pip install dumph
```

**Requirements:** Python 3.8 or newer.

Verify installation:

```bash
python -c "from dumph import Dummy; print(Dummy())"
```

## Usage

### Quick start

```python
from dumph import Dummy


dump = Dummy()

schema = {
    'ID': 'uuid',
    'Firstname': 'first_name',
    'Lastname': 'last_name',
    'Gender': 'gender',
    'Birthdate': 'birthdate',
    'Age': 'age',
    'Email': 'email',
    'Phone': 'phone_number',
    'Barangay': 'barangay',
    'City/Municipality': 'city_mun',
    'Province': 'province',
    'Region': 'region',
    'Zip Code': 'zip_code',
}

# Generate 100 rows of consistent, localized records
data = dump.seed(row=100, feature=schema)

print(data[0])
```

> `seed()` returns a `list` of `dict`s. Each key is a column header from your schema and each value is generated according to the field type you mapped it to.

### Reproducible output

Pass `seed` to get identical data on every run. Because birthdates and ages depend on today's date, also pass `as_of` for output that is identical on any day:

```python
a = dump.seed(row=50, feature=schema, seed=42, as_of='2026-01-01')
b = dump.seed(row=50, feature=schema, seed=42, as_of='2026-01-01')

assert a == b
```

> Output is stable for the same Dumph version. It is not guaranteed to stay identical across releases.

### Field options

Replace a field type string with a dict to configure that column:

```python
schema = {
    'Name': 'full_name',
    'Age': {'type': 'age', 'min': 18, 'max': 30},
    'Score': {'type': 'integer', 'min': 1, 'max': 10},
    'Hired': {'type': 'date', 'start': '2022-01-01', 'end': '2025-12-31'},
    'Active': {'type': 'boolean', 'probability': 0.8},
    'Email': {'type': 'email', 'unique': True},
}

data = dump.seed(row=100, feature=schema)
```

See the [field options reference](#field-options-reference) for every option.

### Location filters

Restrict generated addresses with `region`, `province` and `city_mun`:

```python
# Any location in Mindanao
data = dump.seed(row=100, feature=schema, region='Mindanao')

# A single province
data = dump.seed(row=100, feature=schema, province='Misamis Oriental')
```

Filters are case-insensitive. `region` matches an island group (`Luzon`, `Visayas`, `Mindanao`) or part of a region name. `province` and `city_mun` use an exact name when one exists, otherwise a partial match. A filter that matches nothing raises `ValueError`.

### Unique values

Set `unique` on a column to guarantee no repeated values within a call:

```python
schema = {
    'ID': {'type': 'uuid', 'unique': True},
    'Email': {'type': 'email', 'unique': True},
    'TIN': {'type': 'tin_number', 'unique': True},
}
```

When a value repeats, the whole row is regenerated, so related fields stay consistent. If the pool of possible values runs out (for example, a unique `blood_type` across many rows), `ValueError` is raised.

### Streaming

`seed_iter()` takes the same arguments as `seed()` but returns an iterator that generates one row at a time, so memory use stays flat for large datasets:

```python
for record in dump.seed_iter(row=1_000_000, feature=schema, seed=1):
    ...  # insert, write, or process one row at a time
```

### Flexible Custom Types

You can use dynamic patterns to configure custom ranges and selections directly inside your schema:

```python
schema = {
    'Name': 'full_name',
    'Score': 'int:50:100',
    'Rating': 'float:1.0:5.0:2',
    'Department': 'choice:HR,IT,Sales,Finance'
}

data = dump.seed(row=100, feature=schema)
```

### Saving to JSON or CSV

```python
# Writes test_schema.json
dump.save(data, 'test_schema', 'json')

# Writes test_schema.csv (column order follows your schema)
dump.save(data, 'test_schema', 'csv')
```

> The file extension is added automatically, pass the filename *without* an extension.

### Type hints

Dumph ships with type stubs and a `py.typed` marker. Use `FieldSpec` to get autocompletion and static checking for your schema, including options dicts:

```python
from typing import Dict

from dumph import Dummy, FieldSpec

schema: Dict[str, FieldSpec] = {
    'ID': 'uuid',
    'Name': 'full_name',
    'Phone': 'phone_number',
    'Age': {'type': 'age', 'min': 18, 'max': 30},
    'Rating': 'float:1.0:5.0:2',
}

rows = Dummy().seed(row=100, feature=schema)
```

> Annotating the schema variable is recommended. Without it, type checkers infer `dict[str, str]` for a variable and will reject it. Passing the dictionary literal directly to `seed()` needs no annotation.

### Nested Address

```python
dump = Dummy()
rows = dump.seed(row=1, feature={'Location': 'address'})

# {
#     'Location': {
#         'barangay': '...',
#         'city': '...',
#         'province': '...',
#         'region': '...',
#         'zip_code': '...'
#     }
# }
```

### Seeding a database (example)

```python
from dumph import Dummy

dump = Dummy()

residents = dump.seed(
    row=500,
    feature={
        'first_name': 'first_name',
        'last_name': 'last_name',
        'birthdate': 'birthdate',
        'civil_status': 'civil_status',
        'barangay': 'barangay',
        'city_mun': 'city_mun',
    },
    seed=42,
)

# Use the records with your ORM or SQL client of choice,
# e.g., Django's Model.objects.bulk_create(...)
```

### Notes

- Column names in the schema are fully up to you, only the **values** must be valid field types.
- Unknown field types, unknown options and invalid ranges raise `ValueError`. For a typo such as `'frist_name'`, the error suggests the closest valid type and lists all valid types.
- Fields generated within the same row share state. For example, `first_name`, `full_name`, `gender` and `email` always agree, `civil_status` fits `age`, `weight_kg` fits `height_cm` and all address fields come from the same location.
- Emails vary in format from row to row (for example `juan.delacruz`, `jdelacruz` or `juan_delacruz42`). Use `unique=True` when you need no duplicates.
- `suffix` is `None` for most rows and is only generated for men. In CSV, `None` is written as an empty cell.
- Nested values (such as `address`) are best exported to JSON. In CSV they are written as their Python string representation.
- All generated data is **fictitious**. Government ID numbers follow format conventions only and are not real or verifiable. Do not use them for anything other than development and testing.

## API Reference

### Arguments and Parameters

#### `Dummy()`

Creates a new generator instance. Takes no arguments.

#### `Dummy.seed(row, feature, *, seed, region, province, city_mun, as_of)`

Generates mock records.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `row` | `int` | Yes | Number of records (rows) to generate. |
| `feature` | `dict` | Yes | Schema mapping each output column name (`str`) to a [built-in field type](#built-in-types) (`str`) or an [options dict](#field-options-reference). Order is preserved. |
| `seed` | `int` | No | Seed for reproducible output. Omit for random output each call. |
| `region` | `str` | No | Restrict locations to an island group (`Luzon`, `Visayas`, `Mindanao`) or part of a region name. |
| `province` | `str` | No | Restrict locations to a province. |
| `city_mun` | `str` | No | Restrict locations to a city or municipality. |
| `as_of` | `str` | No | Reference date (`YYYY-MM-DD`) used for ages and birthdates. Defaults to today. |

The parameters after `feature` are keyword-only.

**Returns:** `list[dict]`, one dictionary per generated row.

**Raises:** `ValueError` for unknown field types or options, invalid ranges or dates, no matching location, or an exhausted `unique` pool.

#### `Dummy.seed_iter(row, feature, *, seed, region, province, city_mun, as_of)`

Same parameters as `seed()`. Returns an iterator that yields one `dict` per row instead of building a list.

#### `Dummy.save(data, filename, fmt)`

Writes generated data to a file.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `data` | `list` | Yes | The list returned by `seed()`. |
| `filename` | `str` | Yes | Output file name **without** extension. The extension is appended based on `fmt`. |
| `fmt` | `str` | Yes | Output format: `'json'` or `'csv'` (case-insensitive). |

**Returns:** `None`. A confirmation message is printed on success.

**Raises:** `ValueError` if `fmt` is neither `json` nor `csv`.

### Field Options Reference

A schema value can be a field type string, or a dict with a required `type` key and any of these options:

| Option | Type | Applies to | Description |
|---|---|---|---|
| `type` | `str` | All | Required. Any [built-in type](#built-in-types). |
| `min` | `int` | `age`, `birthdate`, `integer` | Lower bound. Age defaults to 18, integer to 0. |
| `max` | `int` | `age`, `birthdate`, `integer` | Upper bound. Age defaults to 70, integer to 100. |
| `start` | `str` | `date` | Earliest date, `YYYY-MM-DD`. Defaults to `2020-01-01`. |
| `end` | `str` | `date` | Latest date, `YYYY-MM-DD`. Defaults to today (or `as_of`). |
| `probability` | `float` | `boolean` | Chance of `True`, from 0 to 1. Defaults to 0.5. |
| `unique` | `bool` | All | Guarantee no repeated values. Defaults to `False`. |

> `age` and `birthdate` share one age range, so `min` and `max` on either column apply to both.

### Built-in Types

#### Utility

| Type | Alias | Output | Description |
|---|---|---|---|
| `uuid` | `id` | `str` | Random UUID (v4). |
| `color` | none | `str` | Random color name. |
| `status` | none | `str` | Random status value. |

#### Personal

| Type | Output | Description |
|---|---|---|
| `first_name` | `str` | Filipino first name, matching the row's gender. |
| `middle_name` | `str` | Middle name, taken from a Filipino surname. |
| `last_name` | `str` | Filipino surname. |
| `full_name` | `str` | First and last name combined. |
| `suffix` | `str` or `None` | Generational suffix (`Jr.`, `II`, `III` and similar). Men only, `None` for most rows. |
| `gender` | `str` | `Male` or `Female`. |
| `birthdate` | `str` | Date in `YYYY-MM-DD` format, exactly matching `age`. |
| `age` | `int` | Age between 18 and 70 by default. Configurable with `min` and `max`. |
| `civil_status` | `str` | `Single`, `Married`, `Widowed` or `Separated`, weighted by age. |
| `blood_type` | `str` | Blood type (e.g. `O+`). |
| `email` | `str` | Email built from the row's first and last name in one of several common formats, such as `juan.delacruz`, `jdelacruz` or `juan_delacruz42`. |
| `username` | `str` | Username built from the row's name, e.g. `juan_delacruz42`. |

#### Profile

| Type | Output | Description |
|---|---|---|
| `occupation` | `str` | Common occupation. |
| `employer` | `str` | Generic employer or institution. |
| `religion` | `str` | Religion, weighted by approximate national distribution. |
| `height_cm` | `int` | Height in centimeters, based on the row's gender. |
| `weight_kg` | `float` | Weight in kilograms, plausible for the row's height. |

#### Contact

| Type | Output | Description |
|---|---|---|
| `phone_number` | `str` | Philippine mobile number with a carrier prefix, formatted as `+63 <prefix> <number>`. |
| `landline` | `str` | Landline number with an area code, formatted as `(<area code>) <number>`. |

#### Geographic

> All geographic types in a single row come from the **same** location.

| Type | Output | Description |
|---|---|---|
| `address` | `dict` | Nested object with `barangay`, `city`, `province`, `region` and `zip_code`. |
| `full_address` | `str` | `Barangay, City/Municipality, Province, Region ZIP`. |
| `barangay` | `str` | Barangay name. |
| `city_mun` | `str` | City or municipality name. |
| `province` | `str` | Province name. |
| `region` | `str` | Region name. |
| `zip_code` | `str` | ZIP code of the city/municipality. |

#### Government and IDs

| Type | Output | Description |
|---|---|---|
| `sss_number` | `str` | Social Security System number. |
| `tin_number` | `str` | Tax Identification Number (`XXX-XXX-XXX-XXX`). |
| `philhealth_number` | `str` | PhilHealth identification number. |
| `philsys_number` | `str` | PhilSys Card Number, 16 digits (`XXXX-XXXX-XXXX-XXXX`). |
| `pagibig_number` | `str` | Pag-IBIG MID number, 12 digits (`XXXX-XXXX-XXXX`). |
| `umid_number` | `str` | UMID CRN, 12 digits (`XXXX-XXXXXXX-X`). |
| `passport_number` | `str` | Passport number (`P1234567A`). |
| `drivers_license` | `str` | Driver's license number, starting with the row's surname initial. |
| `plate_number` | `str` | Vehicle plate number (`ABC 1234`). |

#### Generic

| Type | Output | Description |
|---|---|---|
| `integer` | `int` | Random integer. Use `min` and `max` (default 0 to 100). |
| `date` | `str` | Random date in `YYYY-MM-DD` format. Use `start` and `end`. |
| `boolean` | `bool` | Random `True` or `False`. Use `probability` (default 0.5). |

#### Dynamic / Flexible Custom Types

| Pattern Syntax | Output | Description |
|---|---|---|
| `int:min:max` | `int` | Randomized integer within the inclusive range `[min, max]` (e.g., `'int:10:50'`). |
| `float:min:max:decimals` | `float` | Randomized floating-point number within range, rounded to specified decimal places (e.g., `'float:1.0:5.0:2'`). |
| `choice:val1,val2,...` | `str` | Randomly picks one value from a comma-separated list of strings (e.g., `'choice:Yes,No'`). |

## Data Sources

[Dumph](https://gitlab.com/cjggarcia.dev/dumph) datasets are compiled from publicly available sources:

| Data | Source |
|------|--------|
| First names | [Forebears.io - Philippines forenames](https://forebears.io/philippines/forenames) |
| Surnames | [Forebears.io - Philippines surnames](https://forebears.io/philippines/surnames) |
| Regions, provinces, cities/municipalities, barangays and ZIP codes | [PSGC Cloud API](https://psgc.cloud/api-docs/v2) |

## Changelog

See [CHANGELOG.md](https://gitlab.com/cjggarcia.dev/dumph/-/blob/main/CHANGELOG.md) for the list of changes in each release.

## License

This project is licensed under the [Apache License 2.0](https://gitlab.com/cjggarcia.dev/dumph/-/blob/main/LICENSE?ref_type=heads)

## Author

Created and maintained by [cjggarcia.dev](https://gitlab.com/cjggarcia.dev)
