Metadata-Version: 2.4
Name: dumph
Version: 1.1.3
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
License-File: LICENSE
Summary: Philippine mock data generator and python bindings for local dataset seeding, development workflows and automated testing.
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="beaver 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 dixtures 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 record's gender and birthdates are consistent with the generated 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 edietor and type-checker experience.

## Table of Contents 

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
    - [Arguments and Parameters](#arguments-and-parameters)
    - [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 and emails come from the row’s name.
- **Complete address hierarchy:** Region, province, city/municipality, barangay and ZIP code from the same real location.
- **Government ID formats:** SSS, TIN and PhilHealth numbers in standard formats.
- **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 two-method Python API.
- **Fully typed:** [PEP 561](https://peps.python.org/pep-0561/) type stubs and a `FieldType` literal.
- **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 `list` of `dict`s. Each key is column header from your schema and each value is generated according to the field type you mapped it to.

### 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 `FieldType` to get autocompletion and static checking for your schema:

```python
from dumph import Dummy
from dumph.types import FieldType

schema: Dict[str, FieldType] = {
    'ID': 'uuid',
    'Name': 'full_name',
    'Phone': 'phone_number',
}

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

> Annotating the schema variable is recommended. Without it, type checkers inder `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',
    }
)

# 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 built-in types.
- Unknown field types are **not** an error, the column is filled with `None`. Double-check spelling against the [built-in types](#built-in-types) table.
- Fields generated within the same row share state. For example, `first_name`, `full_name`, `gender` and `email` always agree and all address fields come from the same location.
- 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. Take no arguments.

#### `Dummy.seed(row, feature)`

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`). Order is preserved. |

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

#### `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`.

### 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. |
| `last_name`    | `str`  | Filipino surname. |
| `full_name`    | `str`  | First and last name combined. |
| `gender`       | `str`  | `Male` or `Female`. |
| `birthdate`    | `str`  | Date in `YYYY-MM-DD` format, consistent with `age`. |
| `age`          | `int`  | Age between 18 and 70. |
| `civil_status` | `str`  | Civil status (e.g. single, married). |
| `blood_type`   | `str`  | Blood type (e.g. `O+`). |
| `email`        | `str`  | Email built from the row's first and last name (`firstname.lastname@domain`). |

#### 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

| 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. |

## 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)
