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 and exposed to Python through PyO3. Geographic data spans Luzon, Visayas and Mindanao and is embedded directly in the compiled library, so 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
• Installation
• Usage
  • Quick Start
  • Flexible Custom Types
  • Saving to JSON or CSV
  • Type Hints
  • Nested Address
  • Seeding a Database Example
  • Notes
• API Reference
  • Arguments and Parameters
  • Built-in Types
• Data Sources
• Changelog
• License
• 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.
• 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 two-method Python API.
• Fully typed: PEP 561 type stubs and a FieldType literal.
• Zero runtime dependencies: Datasets are compiled into the library.

Installation

Install from PyPI:

pip install dumph

Requirements: Python 3.8 or newer.

Verify installation:

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

Usage

Quick start

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 dicts. Each key is column header from your schema and each value is generated according to the field type you mapped it to.

Flexible Custom Types

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

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

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

from dumph import Dummy
from dumph.types import FieldType

schema: Dict[str, FieldType] = {
    'ID': 'uuid',
    'Name': 'full_name',
    'Phone': 'phone_number',
    'Rating': 'int:1.0:5.0:2',
}

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

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

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

Seeding a database (example)

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

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 datasets are compiled from publicly available sources:

Data	Source
First names	Forebears.io - Philippines forenames
Surnames	Forebears.io - Philippines surnames
Regions, provinces, cities/municipalities, barangays and ZIP codes	PSGC Cloud API

Changelog

See CHANGELOG.md for the list of changes in each release.

LICENSE

This project is licensed under the Apache License 2.0

Author

Created and maintained by cjggarcia.dev