🎲 Iki Data Generator
Generate realistic, diverse synthetic data with 729 built-in fields across 22 categories. Perfect for testing, development, and prototyping — without the legal baggage of real data.
What Is This?
Iki Data Generator is a Python library that creates synthetic datasets on demand. Instead of wrestling with dummy data or copy-pasting fake records, you define a schema (which fields you want), call .many(n) to generate n records, and export them to CSV, JSON, SQL, Excel, Parquet, or one of 14 total file formats. That's it.
It's built for developers who need:
- Test data for unit/integration tests
- Demo data for presentations or prototypes
- Mock databases for local development
- Privacy-friendly datasets with realistic properties but zero personal info
- Performance testing with large datasets
Why Use Iki Data Generator?
✅ You Get
| Benefit | What It Means |
|---|---|
| 729 Fields | First name, email, credit card, medical codes, stock prices, cryptocurrency addresses, ML metrics, etc. |
| 22 Categories | Personal, Finance, Commerce, Health, Location, Education, Legal, AI, Developer Tools, Blockchain, Telecom, Travel, and more |
| Easy Schema | Simple string shortcuts or full-control dicts, freely mixed in the same schema |
| Flexible Export | CSV, TSV, JSON, NDJSON, SQL, CQL, Firebase JSON, Excel, HTML, Pickle, XML, DBUnit XML, Parquet, DuckDB |
| Zero Dependencies on Real Data | No need to anonymize or worry about PII |
| Reproducible | Pass a seed and get the exact same dataset every run |
| Extensible | Add your own providers as plain Python classes dropped into the providers/ tree |
❌ You Don't Get
- No real person's data
- No need for data anonymization lawyers
- No internet calls to fake APIs
- No massive CSV files to download and commit
Installation
From PyPI
pip install iki-data-generator
From Source
git clone https://github.com/ikidevz/IkiDataGenerator.git
cd Iki-Data-Generator
pip install -e .
Requirements
- Python ≥ 3.10
- Dependencies (installed automatically):
duckdb,pandas,pyarrow,numpy,openpyxl,python_bcrypt,python_dateutil,rstr,lorem_text
Quick Start (60 Seconds)
The Simplest Example
from ikidatagen import IkiDataGenerator
# Define what fields you want (plain string shorthand)
schema = ["first_name", "last_name", "email_address", "gender_binary"]
# Generate 100 records and export
IkiDataGenerator(schema).many(100).export("users")
Result: output/users.csv with 100 realistic user records (export() defaults to CSV only — pass formats=[...] for more).
A More Realistic Example
from ikidatagen import IkiDataGenerator
schema = [
{
"label": "User ID",
"key_label": "row_number",
"options": {"blank_percentage": 0}, # no blanks for the ID column
},
"first_name",
"last_name",
"email_address",
{
"label": "Account Created",
"key_label": "current_timestamp",
"options": {"blank_percentage": 5}, # 5% will be null
},
{
"label": "IP Address",
"key_label": "ip_address_v4",
"options": {"blank_percentage": 25}, # 25% will be null
},
{
"label": "Full Profile",
"key_label": "template",
"options": {
"template": "{{first_name}} {{last_name}} ({{email_address}})"
},
},
]
# Generate 500 records and save to both CSV and JSON
IkiDataGenerator(schema).many(500).export("users", formats=["csv", "json"])
Result: output/users.csv and output/users.json with 500 complete user records, ready to use.
Schema Definition
A schema is a list where each entry is either a plain string or a dict. You can freely mix both in the same schema.
Shorthand — plain string
"first_name"
Expands to {"key_label": "first_name", "label": "first_name", "group": None, "options": {}}. The output column is named after the field itself, and the provider's category (group) is auto-resolved from the internal registry.
Full control — dict
{
"key_label": "salary_range", # required — which provider to use
"label": "Salary", # optional — renames the output column (defaults to key_label)
"group": "finance", # optional — only needed to disambiguate a key_label that exists in more than one category
"options": {"blank_percentage": 10},
}
key_label is the only required key. label, group, and options are all optional.
Key Parameters (per-field options)
These options are handled by BaseGenerator/BaseProvider and work for every field, on top of whatever provider-specific options that field accepts (e.g. template, min, max, from_date):
| Option | Type | Description |
|---|---|---|
blank_percentage |
float (0–100) |
Percentage of generated rows to leave as None for this field. |
unique |
bool |
Retry generation until the value is unique across the dataset for this field. |
max_unique_tries |
int |
Max retry attempts before raising when unique=True (default 1000). |
choices |
list |
Ignore the provider entirely and sample from this fixed list instead. |
weights |
list |
Optional weights matching choices for weighted random sampling. |
mask |
bool |
Replace the generated value with the literal string "[REDACTED]". |
noise |
bool |
Randomly perturb a string value (character swap/repeat/drop/insert) — useful for dirty-data testing. |
constraints |
dict |
Post-process the value: min_length, max_length, min_value, max_value, allowed_values. |
strict |
bool |
Provider-level (default True). If True, unknown/misspelled options raise a ValueError; if False, they emit a warning instead. |
schema = [
{
"key_label": "country",
"options": {
"choices": ["US", "CA", "MX"],
"weights": [0.7, 0.2, 0.1],
},
},
{
"key_label": "email_address",
"options": {"unique": True, "max_unique_tries": 5000},
},
{
"key_label": "ssn",
"options": {"mask": True},
},
]
Complete Provider Reference (729 fields)
Every key_label below can be used directly in a schema. Columns:
key_label— the provider name to use in your schema.- Example Output — an actual sample value generated by that provider (seeded, so it's reproducible), so you can see what the field produces without running it yourself.
- Advanced Options — field-specific options this provider accepts on top of the universal
blank_percentage(every provider supportsblank_percentage, so it isn't repeated per row — see Key Parameters). Defaults are shown next to each option;—means the provider takes no extra options. Options marked(required)have no default and must be supplied.
Every provider also accepts the schema-level options handled by the generator itself: unique, max_unique_tries, choices, weights, mask, noise, constraints, strict (see Key Parameters).
schema = [
{"key_label": "number", "options": {"blank_percentage": 5, "min": 1, "max": 100, "decimals": 2}},
{
"key_label": "datetime",
"options": {
"from_date": "2020-01-01",
"to_date": "2024-12-31",
"date_format": "ISO 8601 (UTC)",
},
},
]
The datetime provider accepts common bound formats for from_date and to_date, including ISO strings (YYYY-MM-DD), slash-separated values (MM/DD/YYYY), dashed values (DD-MM-YYYY), dotted values (DD.MM.YYYY), and month-name strings. The date_format option also accepts common aliases like YYYY-MM-DD, DD/MM/YYYY, DD-MM-YYYY, SQL datetime, and ISO 8601 (UTC).
🧑 Personal — personal (65 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
age_group |
'13-17' |
— |
business_type |
'Mutual Organization' |
— |
buzzword |
'e-business' |
— |
catch_praise |
'Sharable bifurcated algorithm' |
— |
company_name |
'America Movil' |
— |
conference_name |
'Oracle OpenWorld' |
— |
daily_habit |
'Self-Reflection' |
— |
degree |
'Doctor of Education [EdD]' |
— |
department_corporate |
'Customer Service' |
— |
dream_job |
'Retail Account Representative' |
— |
duns_number |
'10-433-2181' |
— |
education_level |
'Technical Certification' |
— |
ein |
'10-4332181' |
— |
employment_status |
'Apprentice' |
— |
event_type |
'Festival' |
— |
fake_company_name |
'York, York and York' |
— |
first_name |
'Gregory' |
— |
first_name_female |
'Johanna' |
— |
first_name_male |
'Nemesio' |
— |
full_name |
'Gregory York' |
— |
gender |
'Bigender' |
— |
gender_abbrev |
'M' |
— |
gender_binary |
'Male' |
— |
gender_facebook |
'Trans* Woman' |
— |
hair_color |
'Brown' |
— |
hashtag |
'#voltages' |
— |
hobby |
'Reading' |
— |
income_level |
'Very High' |
— |
industry |
'Education' |
— |
interview_stage |
'Final Round' |
— |
job_title |
'Retail Account Representative' |
— |
language |
'Turkish' |
— |
language_code |
'tr' |
— |
last_name |
'Richardson' |
— |
legal_entity |
'Partnership' |
— |
life_stage |
'Middle-aged' |
— |
linkedin_skill |
'Retail Account Representative' |
— |
marital_status |
'Engaged' |
— |
military_rank |
'General' |
— |
mood |
'Relaxed' |
— |
nationality |
'Réunionese' |
— |
occupation |
'Retail Account Representative' |
— |
organization_type |
'NGO' |
— |
performance_rating |
'Exceeds Expectations' |
— |
personality_trait |
'Extrovert' |
— |
pet_name |
'Gregory' |
— |
pet_type |
'Cat' |
— |
project_status |
'Canceled' |
— |
pronoun |
'he/him' |
— |
quote |
"The single most important thing in a child's performance...' |
— |
race |
'Sri Lankan' |
— |
reaction |
'Thanks' |
— |
relationship_type |
'Teammate' |
— |
religion |
'Paganism' |
— |
role |
'Viewer' |
— |
salary_range |
'$20,000 - $30,000' |
— |
shirt_size |
'XXL' |
— |
shoe_size |
'6.5' |
type='US' |
slogan |
'MILO Everyday!' |
— |
ssn |
'655-15-0410' |
— |
suffix |
'V' |
— |
team_name |
'Operations Team' |
— |
title |
'Amb.' |
— |
university |
'Nanjing University' |
— |
zodiac_sign |
'Aquarius' |
— |
🛍️ Commerce — commerce (62 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
barcode_ean13 |
'1043321819600' |
— |
barcode_upc |
'104332181960' |
— |
bban |
'6022768040250165' |
country='US' |
bundle_type |
'Starter Pack' |
— |
click_depth |
1 |
— |
coffee_type |
'Iced Coffee' |
— |
coupon_code |
'INTRO19' |
— |
credit_card_number |
'30104332181969' |
— |
credit_card_type |
'Diners Club' |
— |
currency |
'$' |
— |
currency_code |
'AUD' |
— |
currency_symbol |
'$' |
— |
customer_feedback_score |
6 |
— |
delivery_route_code |
'RT-760' |
— |
delivery_status |
'Failed Attempt' |
— |
delivery_time_window |
'5PM-7PM' |
— |
department_retail |
'Curtains & Blinds' |
— |
discount_percentage |
'62%' |
— |
fabric_type |
'Cashmere' |
— |
freight_mode |
'Freight Forwarding' |
— |
furniture_type |
'Recliner' |
— |
gem_stone |
'Jade' |
— |
iban |
'SE26 AHFT 6804 0250 1652 5808' |
continent=None |
ingredient |
'Eggs' |
— |
inventory_status |
'Coming Soon' |
— |
invoice_number |
'INV-026226' |
— |
loyalty_tier |
'Silver' |
— |
meal_type |
'Late-night Meal' |
— |
membership_level |
'Basic' |
— |
money |
'$639.43' |
min=0, max=1000, currency='$' |
office_supply |
'Binder' |
— |
order_status |
'Awaiting Shipment' |
— |
package_weight |
'1.2 ton' |
— |
payment_method |
'American Express' |
— |
payment_status |
'Pending' |
— |
postal_service |
'China Post' |
— |
price_sensitivity_level |
'Very High' |
— |
product_category |
' Sports and Outdoor Equipment' |
— |
product_description |
'Classic snack' |
— |
product_name |
'GoSports BattleChip Backyard Golf Cornhole Game' |
— |
product_price |
'$699.23' |
— |
product_subcategory |
'Technology' |
— |
promo_expiry_date |
'12/09/2028' |
— |
recipe_name |
'Mango Float' |
— |
recommendation_slot_position |
'Notification Bar' |
— |
restaurant_type |
'Vietnamese' |
— |
return_reason |
'Voucher Not Applied' |
— |
review_text |
'Not worth the price' |
— |
sales_channel |
'Retail' |
— |
shipment_status |
'Failed Attempt' |
— |
shipping_method |
'Priority Shipping' |
— |
sku |
'SKU-117-AH' |
— |
stock_industry |
'Insurance' |
— |
stock_market |
'Tokyo Stock Exchange [TSE]' |
— |
stock_market_cap |
'$26.18B' |
— |
stock_name |
'Monolithic Power Systems' |
— |
stock_sector |
'Semiconductors' |
— |
stock_symbol |
'MPWR' |
— |
subscription_plan |
'Plus' |
— |
tracking_number |
'FDX-72117550' |
— |
warranty_period |
'90 Days' |
— |
water_type |
'Spring' |
— |
💻 Developer Tools — developer_tools (104 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
api_endpoint_path |
'/api/v1/tags' |
— |
api_key |
'auth_hbVrpoiVgRV5IfLBcbfnoGMbJmTPSIAoCLrZ3aWZkSBvrjn9' |
prefix=None |
api_version |
'v2.4' |
— |
app_bundle_id |
'gov.fda.Mat Lam Tam' |
— |
app_name |
'Bamity' |
— |
app_store_category |
'Home-5G' |
— |
app_version |
'0.43' |
— |
automation_action |
'Close Curtains' |
— |
automation_trigger |
'Sunset' |
— |
base64_image |
'data:image/jxl;base64,zwCjspVIvoMOs4cSB3CI16U0M5SXCuE49a...' |
— |
battery_level |
'82%' |
— |
browser |
'Tor Browser 13.0.4' |
— |
churn_risk_score |
0.64 |
— |
cloud_provider |
'Render' |
— |
cloud_storage |
'Linode Object Storage' |
— |
container_id |
'qahfU7680403' |
— |
cookie_name |
'newsletter_subscribed' |
— |
css_class_name |
'.col-1' |
— |
css_color_name |
'darkmagenta' |
— |
data_center |
'US-WEST-1' |
— |
database_type |
'Amazon Aurora' |
— |
device_location |
'Kitchen' |
— |
dns_record_type |
'AAAA' |
— |
docker_image |
'telegraf' |
— |
document_type |
'Purchase Order' |
— |
dummy_image_url |
'http://dummyimage.com/214x125.png/010203/000000' |
min_w=100, min_h=100, max_w=1000, max_h=1000 |
electrical_component |
'Fuse' |
— |
email_address |
'Bonnie@mail.web.de' |
— |
encryption_algorithm |
'RSA' |
— |
energy_mode |
'Sustainability Mode' |
— |
engagement_level |
'Occasional' |
— |
error_message |
'Driver initialization error' |
— |
feature_usage_event |
'Report Exported' |
— |
file_extension |
'.sys' |
— |
file_name |
'wayne.armstrong.sys' |
— |
file_size |
'25108.23 B' |
— |
fingerprint_id |
'FP03279' |
— |
firmware_build |
'FW-2025.08.02-2824' |
— |
firmware_version |
'0.4.7' |
— |
font_family |
'Gantari' |
— |
form_factor |
'Smartphone' |
— |
framework |
'Tornado' |
— |
git_commit_hash |
'a043bae' |
short=True |
hardware_type |
'Motherboard' |
— |
http_method |
'OPTIONS' |
— |
http_status_code |
417 |
— |
incident_type |
'Application Bug' |
— |
iot_device_type |
'Wearable ECG Patch' |
— |
ip_address_v4 |
'163.177.121.157' |
— |
ip_address_v4_cidr |
'163.177.121.157/8' |
— |
ip_address_v6 |
'bdd6:40fb:667:1ad1:1c80:317f:a3b1:799d' |
— |
ip_address_v6_cidr |
'bdd6:40fb:667:1ad1:1c80:317f:a3b1:799d/48' |
— |
json_web_token |
'ObroVR5f.BbnGbmPIoLZaZSvj.9vfg2MZUI-yJ1N3KTcosfogrOxxnr7PM' |
— |
keyboard_layout |
'AZERTY' |
— |
laptop_brand |
'VAIO' |
— |
license_type |
'MIT' |
— |
log_level |
'SUCCESS' |
— |
mac_address |
'39:0C:8C:7D:72:47' |
— |
md5 |
'0e135f9a84077741f2dc14bbd919ad28' |
— |
memory_size |
'4GB' |
— |
microservice_name |
'order-service' |
— |
mime_type |
'audio/basic' |
— |
network_protocol |
'Telnet' |
— |
notification_type |
'SMS' |
— |
operating_system |
'Solaris' |
— |
package_manager |
'choco' |
— |
password_strength |
'Weak' |
— |
permission_level |
'Write' |
— |
port_number |
11211 |
— |
power_source |
'DC' |
— |
power_state |
'Charging' |
— |
printer_type |
'All-in-One' |
— |
programming_language |
'ColdFusion' |
— |
protocol_version |
'IPv6' |
— |
resolution |
'1366x768' |
— |
response_time |
'35ms' |
— |
screen_size |
'14"' |
— |
security_question |
'What was your first concert?' |
— |
sensor_reading |
'127.89' |
— |
sensor_type |
'Light Level' |
— |
server_name |
'db-prod-01' |
— |
sha1 |
'cb84b588591f028862121131c2c10873c4ae563e' |
length=16 |
sha256 |
'8b2d8bdbe7e4ec8bc1f0fd170ffaadf7a8416a32f2c036955af5fc51...' |
length=16 |
slack_channel |
'#voltages' |
— |
smart_device_brand |
'Amazon Echo' |
— |
smart_device_type |
'Video Doorbell' |
— |
social_media_platform |
'LinkedIn' |
— |
software_framework |
'TensorFlow' |
— |
software_license |
'Creative Commons' |
— |
storage_type |
'External SSD' |
— |
subject_line |
'Appointment Confirmation' |
— |
subscription_renewal_status |
'Auto-renew' |
— |
technology_stack |
'MEAN' |
— |
ticket_priority |
'Blocker' |
— |
top_level_domain |
'.mil' |
— |
uptime_percentage |
'97.5%' |
— |
user_agent |
'Mozilla/5.0 (Macintosh; Intel Mac OS X 13_4_1) AppleWebK...' |
— |
user_cohort |
'2026-Q1' |
— |
username |
'meredith-diaz' |
— |
uuid_v1 |
'64fdbe6b-8a1e-11f1-8196-c5846cafb4a6' |
— |
uuid_v4 |
'903bd11b-71d6-434f-b8c8-e617b819c124' |
— |
verification_code |
'602276' |
length=6 |
version_number |
'2023.01.24' |
version_format='auto' |
wifi_ssid |
'Home-5G' |
— |
🏥 Health — health (67 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
allergy |
'Mold' |
— |
allergy_flag |
'Yes' |
— |
appointment_status |
'Lab Work Required Before Visit' |
— |
blood_pressure_category |
'Morning Surge Hypertension' |
— |
blood_pressure_reading |
'104/60' |
— |
blood_type |
'A-' |
— |
body_part |
'Knee' |
— |
calorie_count |
'643 cal' |
— |
chromosome |
'Chromosome 21' |
— |
diet_type |
'Soft Diet [Post-Surgery]' |
— |
dietary_restriction |
'Low-FODMAP' |
— |
disability_type |
'Tourette Syndrome' |
— |
disease_name |
'Cancer' |
— |
drug_company |
'UNICHEM' |
— |
drug_name_brand |
'BUSPIRONE HYDROCHLORIDE' |
— |
drug_name_generic |
'BUSPIRONE' |
— |
emergency_type |
'Evacuation Alert' |
— |
exercise_type |
'Zumba' |
— |
fda_ndc_code |
'04332-181' |
— |
food_allergy |
'Mold' |
— |
hcpcs_code |
'E0981' |
— |
hcpcs_name |
'Wheelchair accessory, seat upholstery, replacement only,...' |
— |
health_insurance_plan |
'Medicare' |
— |
heart_rate |
'146 bpm' |
— |
hormone |
'Thyroid-Stimulating Hormone [TSH]' |
— |
hospital_city |
'OWENSBORO' |
— |
hospital_department |
'Anesthesiology' |
— |
hospital_name |
'NORTHSTAR ANESTHESIA' |
— |
hospital_npi |
'1710352570' |
— |
hospital_postal_code |
'423039811' |
— |
hospital_state |
'KY' |
— |
hospital_street_address |
'1201 PLEASANT VALLEY RD' |
— |
icd10_diagnosis_code |
'T8169XS' |
— |
icd10_dx_desc_long |
'Other acute reaction to foreign substance accidentally l...' |
— |
icd10_dx_desc_short |
'Oth acute reaction to foreign sub acc left dur proc, seq...' |
— |
icd10_proc_desc_long |
'Occlusion of Right Internal Jugular Vein, Open Approach' |
— |
icd10_proc_desc_short |
'Occlusion of Right Internal Jugular Vein, Open Approach' |
— |
icd10_procedure_code |
'05LM0ZZ' |
— |
icd9_diagnosis_code |
'8509' |
— |
icd9_dx_desc_long |
'Concussion, unspecified' |
— |
icd9_dx_desc_short |
'Concussion NOS' |
— |
icd9_proc_desc_long |
'Closed reduction of dislocation of shoulder' |
— |
icd9_proc_desc_short |
'Cl reduc disloc-shoulder' |
— |
icd9_procedure_code |
'7971' |
— |
lab_result_value |
'8.5' |
— |
lab_test |
'EEG' |
— |
lab_test_type |
'Thyroid Panel [TSH/T3/T4]' |
— |
macro_nutrient |
'Monounsaturated Fat' |
— |
meal_rating |
'3.6' |
— |
medical_device_id |
'SURG-24592' |
— |
medical_specialty |
'Nephrology' |
— |
medicare_beneficiary_id |
'2A43-J21-WD9R' |
— |
medication_dosage |
'5ml syrup' |
— |
mental_health_condition |
'Borderline Personality Disorder' |
— |
nhs_number |
'104 332 1802' |
— |
nutrient |
'Vitamin B9 [Folate]' |
— |
organ |
'Stomach' |
— |
pain_level |
6 |
— |
pharmacy_name |
'Safeway Pharmacy' |
— |
prescription_id |
'MED126225' |
— |
serving_size |
'3 cups' |
— |
symptom |
'Loss of Taste' |
— |
triage_level |
'Medium' |
— |
vaccination_status |
'Not Vaccinated' |
— |
vaccination_type |
'Cholera Vaccine' |
— |
vitamin_name |
'Vitamin D3' |
— |
workout_duration |
'2 hour' |
— |
✨ Basic / Utility — basic (47 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
address_line_2 |
'Room 52' |
— |
binomial_distribution |
5 |
trials=10, probability=0.5 |
blank |
None |
— |
boolean |
True |
— |
color |
'Rich black (FOGRA39)' |
— |
current_timestamp |
'2026-07-28 00:50:52' |
format='%Y-%m-%d %H:%M:%S' |
custom_list |
'C' |
values=None |
datetime |
'07/07/2013' |
from_date=None, to_date=None, date_format='mm/dd/yyyy', minimum_age=None, maximum_age=None (supports ISO, slash, dash, dot, month-name, and common aliases like YYYY-MM-DD, DD/MM/YYYY, SQL datetime, ISO 8601 (UTC)) |
day_of_week |
'Saturday' |
— |
dice_roll |
6 |
— |
dimension |
'3197.5x126.0' |
type='2D' |
duration |
'57 seconds' |
— |
emoji |
'📬' |
— |
encrypt |
'30877432d1026706d7e805da846a32c3bb81e3c29b62179273c8eb5b...' |
— |
exponential_distribution |
1.1973453573638597 |
lam=1.0 |
frequency |
'Occasionally' |
— |
geometric_distribution |
1 |
probability=0.5 |
height |
'160.0 mm' |
— |
hex_color |
'#010203' |
— |
imperial_unit |
'mile' |
— |
isbn |
'0-433-21819-3' |
— |
metric_prefix |
'femto' |
— |
mongodb_object_id |
'6a67fceea043bae1606ff151' |
— |
month |
'November' |
— |
nato_phonetic |
'Uniform' |
— |
normal_distribution |
0.18 |
mean=0.0, std_dev=1.0, decimals=2 |
number |
639 |
min=0, max=1000, decimals=0, values=None |
paper_size |
'4x6' |
— |
paragraphs |
'Voluptatum inventore ex magnam fugiat ab cupiditate earu...' |
min_paragraph=1, max_paragraph=10 |
password |
'^2#a6hQ]' |
min_length=8, upper_num=1, lower_num=1, numbers_num=1, symbols_num=1 |
password_hash |
'$2b$04$Vfo89b6.4Xx61SwGUDs2EuiD3LMP8iWDfRYEwTQdCcCpRHqPu...' |
min_length=8, max_length=16, rounds=4, fast=False |
poisson_distribution |
0 |
mean=0.0 |
priority_level |
'Low' |
— |
punctuation |
'Interrobang' |
— |
rating |
3.6 |
— |
row_number |
1 |
— |
season |
'Midwinter' |
— |
sentences |
'"Corrupti nobis magni qui dolorem, ducimus recusandae co...' |
min_sentence=1, max_sentence=10 |
sentiment |
'Positive' |
— |
sequence |
1 |
start_at=1, step=1, repeat=1, restart_at=None |
short_hex_color |
'#010' |
— |
temperature |
'21.6°C' |
type='celsius' |
time |
'23:16' |
time_from='00:00', time_to='23:59', fmt='24 Hour' |
ulid |
'01KYK383MKNKYD008A5AVVG594' |
— |
weather_condition |
'Freezing Rain' |
— |
weight |
'557.5 gram' |
— |
words |
'voltages' |
— |
📣 Marketing — marketing (43 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
ad_click_count |
40 |
— |
ad_impression_count |
'214' |
— |
average_order_value |
'$6397.87' |
— |
browsing_duration |
'20h' |
— |
campaign_name |
'Limited Time Offer' |
— |
cart_abandonment_status |
'Recovered via Reminder' |
— |
channel_source |
'TikTok Shop Integration' |
— |
churn_risk |
'Recently Re-Engaged' |
— |
click_through_rate |
'31.97%' |
— |
conversion_status |
'Converted via Promo' |
— |
conversion_value |
'$138.24' |
— |
coupon_usage_status |
'Redeemed' |
— |
cross_sell_opportunity |
'Low' |
— |
customer_feedback_rating |
5 |
— |
customer_lifetime_value |
'$671,487' |
min=1000, max=1000000 |
customer_mood_intent |
'Browsing' |
— |
customer_segment |
'Brand Loyalists' |
— |
discount_value |
'5%' |
currency='$' |
email_open_rate |
'63.94%' |
— |
engagement_recency |
'7 years 5 months 3 weeks' |
— |
engagement_score |
0.64 |
— |
influencer_attribution |
'None' |
— |
last_purchase_date |
'2024-10-06' |
years_ago=5 |
loyalty_points_balance |
'214' |
— |
next_best_action |
'This Item Is Selling Quickly' |
— |
preferred_communication_channel |
'Facebook Messenger' |
— |
preferred_product_category |
'Fitness' |
— |
price_sensitivity |
'Low' |
— |
product_affinity_score |
0.64 |
— |
product_view_count |
655 |
— |
promotion_type |
'Launch Offer' |
— |
recent_search_term |
'Travel Carry-On Bag' |
— |
recommendation_confidence_score |
0.63 |
fmt='decimal' |
recommendation_reason |
'This Item Is Selling Quickly' |
— |
recommended_product |
'GoSports BattleChip Backyard Golf Cornhole Game' |
— |
referral_source |
'Friend Invitation Email' |
— |
return_rate |
'1%' |
— |
seasonal_interest |
'Back-to-School' |
— |
session_count |
40 |
— |
sms_response_status |
'Clicked Link' |
— |
time_since_last_purchase |
'21 days' |
— |
upsell_opportunity |
'Low' |
— |
user_preference_tag |
'Beauty Routine Focused' |
— |
🏦 Finance — finance (41 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
account_number |
'104332181960' |
— |
account_type |
'Investment Linked Account' |
— |
aml_risk_category |
'Sanction Watchlist Match' |
— |
asset_type |
'Silver' |
— |
bank_branch_code |
'001043321819' |
— |
bank_city |
'Santa Maria' |
— |
bank_country_code |
'NU' |
— |
bank_lei |
'2138AJI0Y6DPBHSAHX52' |
— |
bank_name |
'Rabobank' |
— |
bank_riad_code |
'R60227680' |
— |
bank_routing_number |
'104332182' |
— |
bank_state |
'CA' |
— |
bank_street |
'1554 South Broadway' |
— |
bank_swift_bic |
'ROBPUSAJTRX' |
— |
credit_score |
414 |
— |
credit_score_band |
'Fair' |
— |
credit_utilization |
'81%' |
— |
expense_amount |
'639.43' |
min=0, max=1000, currency='$' |
expense_category |
'Fuel' |
— |
financial_goal |
'Wedding Fund' |
— |
fraud_score |
'0.64' |
— |
grant_type |
'Nonprofit Grant' |
— |
insurance_policy_id |
'DENT-216739' |
— |
insurance_provider |
'Kaiser Permanente' |
— |
insurance_type |
'Title Insurance' |
— |
investment_persona |
'Speculative Trader' |
— |
investment_return_rate |
'5.6%' |
min_return=-20.0, max_return=20.0 |
investment_strategy |
'Options Trading' |
— |
kyc_status |
'Additional Documentation Requested' |
— |
loan_type |
'Emergency Loan' |
— |
payment_term |
'Open Account Payment' |
— |
risk_level |
'Stable' |
— |
savings_goal |
'Loan Payoff Buffer' |
— |
spending_behavior |
'Rewards and Points Optimizer' |
— |
spending_category |
'Home Improvement' |
— |
tax_id |
'754-24-1409' |
type='SSN' |
tax_type |
'Import Duty' |
— |
transaction_pattern |
'Travel-Based Card Usage' |
— |
transaction_type |
'Automated Payment' |
— |
transfer_channel |
'Bills Payment Auto-Debit' |
— |
wealth_segment |
'Emerging Affluent' |
— |
🎬 Entertainment — entertainment (36 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
award_name |
'BET Award' |
— |
book_author |
'Maeve Christopher (Goodreads Author)' |
— |
book_genre |
'Romance' |
— |
book_isbn |
'B00AF0R61Q' |
— |
book_title |
'Fame Fortune secrets' |
— |
broadcast_network |
'CTV' |
— |
content_rating |
'TV-MA' |
— |
demand_forecast |
'End-of-Life [Phase Out]' |
— |
episode_number |
'Season 2 Episode 1' |
— |
game_publisher |
'Vivendi Games' |
— |
game_title |
'Yokai Sangokushi' |
— |
guitar_type |
'Electric' |
— |
hotel_city |
'Surgut��' |
— |
hotel_country |
'Russia��' |
— |
hotel_name |
'Hotel Impuls' |
— |
magazine_title |
'Bloomberg Businessweek' |
— |
media_format |
'MiniDisc' |
— |
movie_genres |
'Adventure,Family,Fantasy' |
— |
movie_title |
'Beings' |
— |
musical_genre |
'Classical' |
— |
musical_instrument |
'Violin' |
— |
news_category |
'Environment' |
— |
parental_rating |
'AO' |
— |
podcast_name |
'This American Life' |
— |
product_grade |
'Scrap / For Recycling' |
— |
product_grocery |
'Pretzels' |
— |
record_label |
'EMI' |
— |
shelf_location |
'Aisle 3 - Level 2 - Slot 14' |
— |
sound_effect |
'Typing' |
— |
stock_reorder_flag |
'Overstocked' |
— |
streaming_service |
'Viu' |
— |
supernatural_creature |
'Goblin' |
— |
supplier_contract |
'Wholesale Bulk Allocation' |
— |
video_format |
'AVI' |
— |
video_quality |
'720p' |
— |
warehouse_location |
'WH-4606' |
— |
🌍 Location — location (36 providers)
| key_label | Example Output | Advanced Options |
| ----------------------------- | --------------------------------- | ----------------------- | ------ | ------- |
| city | 'Murter Island��' | — |
| compass_direction | 'North-Northwest' | — |
| continent | 'Oceania' | — |
| country | 'Niue' | field='name' | 'iso2' | 'iso3' |
| country_code | 'NU' | — |
| elevation | '204 m' | — |
| facility_type | 'Train Station' | — |
| federal_holiday | 'Martin Luther King Jr. Day' | — |
| floor_number | 'Penthouse' | — |
| geo_zone | 'Community Center' | — |
| holiday | "Valentine's Day" | — |
| home_type | 'Mansion' | — |
| latitude | 25.096824 | — |
| longitude | 50.193647 | — |
| noise_category | 'Extremely Loud' | — |
| noise_level | 83.9 | — |
| noise_source | 'Rock concert / loud nightclub' | — |
| phone | '104-332-1819' | format='###-###-####' |
| postal_code | '609' | — |
| property_type | 'Condo' | — |
| public_service_request_type | 'Water Leakage Report' | — |
| road_type | 'Parkway' | — |
| state | 'Havlíčkův Brod' | — |
| state_abbrev | '631' | — |
| street_address | '43321 Villanueva Terrace' | — |
| street_name | 'Wayne Alley' | — |
| street_number | '104' | — |
| street_suffix | 'Trail' | — |
| street_type | 'Walkway' | — |
| subregion | 'Northern Europe' | — |
| time_zone | 'Europe/Prague' | — |
| timezone_abbrev | 'EAT' | — |
| timezone_offset | 'UTC+8' | prefix='UTC' |
| traffic_flow_level | 'Holiday Traffic' | — |
| urban_land_use | 'Shopping Mall' | — |
| venue_type | 'Community Center' | — |
🌿 Nature — nature (37 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
air_quality_category |
'Hazardous' |
— |
air_quality_index |
327 |
— |
animal_habitat |
'Prairie' |
— |
animal_name |
'Dove, laughing' |
— |
animal_scientific_name |
'Streptopelia senegalensis' |
— |
biome |
'Chaparral' |
— |
bird_species |
'Cardinal' |
— |
chemical_element |
'Lead' |
— |
chemical_symbol |
'Pb' |
— |
climate_zone |
'Temperate' |
— |
constellation |
'Pisces' |
— |
dog_breed |
'Siberian Husky' |
— |
ecosystem |
'Prairie' |
— |
element_state |
'Solid' |
— |
energy_source |
'Wave' |
— |
environmental_issue |
'Air Pollution' |
— |
fish_species |
'Sturgeon' |
— |
flower_type |
'Daisy' |
— |
geological_formation |
'Mesa' |
— |
hazard_risk_zone |
'Coastal Flooding Zone' |
— |
insect_species |
'Wasp' |
— |
moon_phase |
'Waxing Crescent' |
— |
natural_resource |
'Clay' |
— |
ocean |
'Pacific Ocean' |
— |
particle |
'Electron' |
— |
planet |
'Venus' |
— |
plant_common_name |
'Tiger Grass' |
— |
plant_family |
'Poaceae' |
— |
plant_scientific_name |
'Thysanolaena latifolia (Roxb. ex Hornem.) Honda' |
— |
precipitation_type |
'Freezing Rain' |
— |
satellite |
'Hubble Telescope' |
— |
species |
'Monkey' |
— |
tree_species |
'Birch' |
— |
vegetation_type |
'Tundra Vegetation' |
— |
wavelength |
'639nm' |
— |
wind_direction |
'South' |
— |
wind_speed |
'127.9 mph' |
unit='mph' |
🤖 AI / ML — ai (22 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
compute_precision |
'FP16' |
— |
concept_drift_status |
'Slight Shift' |
— |
cpu_utilization |
'82%' |
— |
data_drift_score |
0.64 |
— |
gpu_utilization |
'82%' |
— |
inference_endpoint |
'/api/v1/tags' |
— |
inference_result |
'No Significant Pattern' |
— |
memory_footprint |
'152MB' |
— |
model_confidence |
0.64 |
— |
model_deployment_env |
'IoT Gateway' |
— |
model_explainability_method |
'Permutation Feature Importance' |
— |
model_framework |
'FastAI' |
— |
model_input_format |
'Multimodal Data' |
— |
model_latency |
'27ms' |
— |
model_lifecycle_stage |
'Versioned Snapshot' |
— |
model_output_format |
'Recommendation List' |
— |
model_owner |
'ML Ops Team' |
— |
model_task |
'Recommendation' |
— |
model_training_dataset |
'Kaggle Competitions Dataset' |
— |
model_type |
'Support Vector Machine [SVM]' |
— |
model_version |
'exp_115_a' |
— |
retraining_frequency |
'Event-Driven Retraining' |
— |
📱 Telecom — telecom (23 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
apn_settings |
'internet.telstra.com' |
— |
bluetooth_version |
'5.2' |
— |
call_quality_rating |
'Excellent' |
— |
carrier_lock_status |
'Locked' |
— |
data_plan |
'10GB prepaid' |
— |
download_speed |
'20 Mbps' |
— |
dual_sim_capability |
'Single SIM' |
— |
esim_profiles_count |
2 |
— |
hotspot_capability |
'Enabled' |
— |
imei_number |
'858224121167399' |
— |
latency |
'92ms' |
— |
mobile_carrier |
'Singtel' |
— |
network_operator_code |
'854114' |
— |
network_type |
'3G HSPA' |
— |
nfc_support |
'Supported' |
— |
roaming_status |
'Roaming' |
— |
signal_strength |
'5 bars' |
— |
sim_card_type |
'Micro SIM' |
— |
upload_speed |
'10 Mbps' |
— |
volte_support |
'Partial Support' |
— |
wifi_band |
'2.4GHz' |
— |
wifi_calling_support |
'Carrier Dependent' |
— |
wifi_standard |
'802.11g' |
— |
🏛️ Political — political (20 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
approval_rating |
'81%' |
— |
border_control_status |
'Temporary Emergency Controls' |
— |
cabinet_position |
'Environmental Affairs Minister' |
— |
campaign_funding_source |
'Foreign Influence [Illegal]' |
— |
diplomatic_relationship |
'Neutral' |
— |
election_type |
'Constituent Assembly Election' |
— |
geopolitical_region |
'ASEAN' |
— |
government_branch |
'Military Command' |
— |
head_of_government |
'Prime Minister' |
— |
head_of_state |
'Sultan' |
— |
lobbying_influence_level |
'Low' |
— |
military_alliance |
'Non-Aligned Movement [Political Position]' |
— |
party_affiliation_strength |
'Active Party Member' |
— |
policy_domain |
'Education' |
— |
political_ideology |
'Populist' |
— |
political_party |
'Constitutional Democratic Party' |
— |
sanction_type |
'Technology Export Ban' |
— |
treaty_type |
'Cultural Exchange Treaty' |
— |
voter_eligibility |
'Disqualified Due to Conviction' |
— |
voter_turnout |
'81%' |
— |
⚖️ Legal — legal (18 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
appeal_status |
'Remanded to Lower Court' |
— |
bail_status |
'Bail Reduced' |
— |
case_reference_number |
'G.R. No. 23112' |
— |
contract_type |
'Employment Contract' |
— |
court_level |
'Appeals Court' |
— |
crime_type |
'Counterfeiting' |
— |
evidence_type |
'Testimonial Evidence' |
— |
law_type |
'Tax Law' |
— |
legal_compliance_status |
'Flagged for Audit' |
— |
legal_fee_category |
'Administrative Fee' |
— |
legal_filing_type |
'Motion' |
— |
legal_jurisdiction |
'Special Economic Zone' |
— |
legal_representation |
'Corporate Legal Department' |
— |
legislation_status |
'Proposed' |
— |
notary_status |
'Not Required by Law' |
— |
penalty_type |
'Fine' |
— |
regulatory_agency |
'FDA' |
— |
verdict |
'Mistrial' |
— |
⛓️ Blockchain / Crypto — blockchain (16 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
bitcoin_address |
'bc1brpoig8f1cbfno6b9m80o2rak1vr' |
— |
blockchain_network |
'Ethereum' |
— |
cryptocurrency_address |
'0xbVrpoiVgRV5IfLBcbfnoGMbJmTPSIAoCLrZ3aWZk' |
— |
cryptocurrency_name |
'PolySwarm' |
— |
cryptocurrency_symbol |
'NCT' |
— |
cryptocurrency_wallet |
'AlphaWallet' |
— |
ethereum_address |
'0x30877432D1026706D7e805dA846a32c3Bb81e3c2' |
— |
nft_token_id |
'OhbVrpoiVgRV5IfL' |
length=16, hex_only=False |
solana_address |
'h82pJGF9p7kpzb6eU326EFZf2cDnimbT' |
— |
tezos_account |
'tz1h82pJGF9p7kpzb6eU326EFZf2cDnimbTF' |
— |
tezos_block |
'tz1h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAE' |
— |
tezos_contract |
'tz1h82pJGF9p7kpzb6eU326EFZf2cDnimbTF' |
— |
tezos_operation |
'tz1h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN' |
— |
tezos_signature |
'tz1h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R...' |
— |
transaction_hash |
'0xe3087743fb2cd10267ad0b6ebd7ec805da846a32c3bbd81eb3c2b9...' |
length=64 |
tron_address |
'Th82pJGF9p7kpzb6eU326EFZf2cDnimbTF' |
— |
🎮 Gaming — gaming (13 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
achievement_title |
'Top Damage Dealer in Raid' |
— |
avatar_class |
'Druid' |
— |
badge |
'Speed Champion' |
— |
console_platform |
'Nintendo 3DS' |
— |
game_genre |
'Action' |
— |
guild_name |
'Eternal Horizon' |
— |
in_game_currency_balance |
83810 |
max=99999 |
leaderboard_rank |
655 |
len=1000 |
match_result |
'Forfeit Loss' |
— |
player_role |
'Infiltrator' |
— |
quest_completion_rate |
0.64 |
— |
session_outcome |
'Abandoned Early' |
— |
skill_level |
'Master Tier' |
— |
🚗 Automotive — car (12 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
car_base_model |
'Galant' |
— |
car_make |
'Mitsubishi' |
— |
car_model |
'Galant' |
— |
car_model_year |
'2013' |
— |
car_vin |
'82HFE9767U326DEZ2' |
— |
driver_license_number |
'AX4332181' |
pattern=None |
engine_type |
'Tri-Motor Electric' |
— |
fuel_type |
'Ethanol' |
— |
gas_type |
'E85' |
— |
license_plate |
'D04 3HE' |
— |
transmission_type |
'8-Speed Automatic' |
— |
vehicle_type |
'Light-Duty Truck' |
— |
📚 Education — education (11 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
academic_subject |
'Computer Science' |
— |
attendance_status |
'Medical Leave' |
— |
certification |
'PRINCE2 Practitioner' |
— |
classroom_number |
'Lab 8A' |
format='Auto' |
college_major |
'Law' |
— |
elearning_platform |
'edX' |
— |
gpa |
3.6 |
— |
grade_level |
'11th Grade' |
— |
qualification |
'Bachelor’s Degree' |
— |
school_type |
'Magnet School' |
— |
semester |
'Winter' |
— |
🏗️ Infrastructure — infrastructure (9 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
building_type |
'Observation Tower' |
— |
construction_heavy_equipment |
'Hydraulic Hammer' |
— |
construction_material |
'Iron' |
— |
construction_role |
'Equipment Operator' |
— |
construction_standard_cost_code |
'07 46 24.13 - Wood Shingle Siding' |
— |
construction_subcontract_category |
'Construction Clean and Final Clean' |
— |
construction_trade |
'Pipelayer' |
— |
material_type |
'Glass Fiber Reinforced Concrete' |
— |
tool_type |
'Leveling Laser' |
— |
🧩 Advanced — advanced (8 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
character_sequence |
'ud04P' |
pattern='@@##%' |
digit_sequence |
'10433218' |
length=8 |
json_array |
'[true, "alpha", 892.18]' |
min_elements=1, max_elements=3 |
lambda |
'custom_value' |
func (required) |
naughty_string |
'パーティーへ行かないか' |
— |
regular_expression |
'' |
format='' |
template |
None |
template='', schema_labels=None |
url |
'http://pinterest.com/favorites?sort=newest' |
protocol=True, host=True, path=True, query_string=True |
🏅 Sports & Athletics — gaming_sports (6 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
athlete_name |
'Sugar Ray Leonard' |
— |
equipment_type |
'Volleyball' |
— |
league |
'MLB' |
— |
olympic_sport |
'Triathlon' |
— |
sport |
'Golf' |
— |
stadium_name |
'MetLife Stadium' |
— |
✈️ Travel — travel (33 providers)
key_label |
Example Output | Advanced Options |
|---|---|---|
airport_code |
'null' |
— |
airport_continent |
'AS' |
— |
airport_coordinate |
'43.442318, 78.858286' |
— |
airport_country_code |
'KZ' |
— |
airport_elevation_ft |
'1067' |
— |
airport_gps_code |
'XAAK' |
— |
airport_municipality |
'Kokpek' |
— |
airport_name |
'Kokpek Highway Strip' |
— |
airport_region_code |
'KZ-ALM' |
— |
airport_terminal |
'Terminal 1' |
— |
amenity |
'Swimming Pool' |
— |
bed_size |
'Twin' |
— |
boarding_gate |
'Gate 2' |
— |
flight_airline_code |
'NIQ' |
— |
flight_airline_name |
'AVCON JET MALTA LTD' |
— |
flight_arrival_airport |
'Kokpek Highway Strip' |
— |
flight_arrival_airport_code |
'null' |
— |
flight_arrival_city |
'Kokpek' |
— |
flight_arrival_country |
'Niue' |
— |
flight_departure_airport |
'Kokpek Highway Strip' |
— |
flight_departure_airport_code |
'null' |
— |
flight_departure_city |
'Kokpek' |
— |
flight_departure_country |
'Niue' |
— |
flight_departure_time |
'09:58 PM' |
— |
flight_duration_hours |
20.251258676482728 |
— |
flight_number |
'NIQ1825' |
— |
flight_status |
'Landed' |
— |
parking_type |
'Valet Parking' |
— |
room_type |
'Presidential Suite' |
— |
seat_number |
'41A' |
— |
ticket_type |
'Economy' |
— |
transport_mode |
'Tram' |
— |
travel_duration |
'20h' |
— |
Total: 729 providers across 22 categories — 51 accept advanced, field-specific options beyond blank_percentage.
Seven additional category folders (
communication,construction,crypto,governance,it,products,sports) exist inproviders/as reserved placeholders for future providers and currently contain no fields.
Export Formats
export() writes one file per requested format into output_dir (default "output/"):
IkiDataGenerator(schema).many(100).export(
"users",
output_dir="output",
formats=["csv", "json", "sql", "parquet"],
)
| Format | File | Notes |
|---|---|---|
csv |
.csv |
Default format if formats is omitted |
tsv |
.tsv |
Tab-separated |
json |
.json |
Pretty-printed JSON array |
ndjson |
.ndjson |
Newline-delimited JSON, streaming-friendly |
html |
.html |
Renders an HTML <table> |
pickle |
.pkl |
Python pickle of the list of dicts |
sql |
.sql |
INSERT statements, with optional CREATE TABLE |
cql |
.cql |
Cassandra Query Language script |
firebase |
_firebase.json |
Firestore-style JSON document map |
excel |
.xlsx |
Excel workbook via openpyxl |
xml |
.xml |
Generic <root><record>…</record></root> |
dbunit |
_dbunit.xml |
DBUnit flat XML fixture |
parquet |
.parquet |
Columnar format via pyarrow |
duckdb |
.duckdb |
Loads rows straight into a DuckDB table |
table_name is used both as the output filename stem and (for sql/cql/dbunit/duckdb) as the actual table name, so it must be a plain name — no path separators.
Two more export paths exist outside .export():
IkiDataGenerator(...).many(n).dataframe(engine="pandas" | "polars")— return the generated rows as a DataFrame.Exporter.to_sqlalchemy(data, connection_string, table_name, if_exists)— write directly to any SQLAlchemy-supported database.
Core API
IkiDataGenerator(schema, seed=None)
The main entry point.
gen = IkiDataGenerator(schema, seed=42)
gen.many(100) # generate 100 rows, stored internally
gen.data # -> list[dict] of generated rows
gen.one() # generate and return a single dict
await gen.many_async(100) # async variant of .many()
gen.dataframe() # -> pandas/polars DataFrame (requires .many() first)
gen.export("users", formats=["csv", "json"])
.many(n)returnsself, so calls chain:IkiDataGenerator(schema).many(100).export("users")..stream(n, batch_size=1000)yields lists of row-dicts in batches — use this for datasets too large to hold in memory..export(..., stream=True, n=...)streams generation straight intocsv/json/ndjsonoutput without materializing the full dataset first (other formats fall back to generating the full list)..generate_event_stream(n, start_time=None, step_seconds=60, ...)adds a monotonically increasingevent_timestampandevent_sequenceto each row — handy for simulating log/event data.
Dataset
A thin, higher-level wrapper around IkiDataGenerator for schema-driven workflows:
from ikidatagen import Dataset
ds = Dataset.from_schema(schema, seed=42)
rows = ds.generate(100) # -> list[dict]
ds.export_recipe("recipe.json") # save {schema, seed} for later reuse
SchemaBuilder
Build a schema programmatically instead of hand-writing the list:
from ikidatagen import SchemaBuilder
schema = (
SchemaBuilder()
.add_field("first_name")
.add_field("email_address", label="Email")
.add_field("salary_range", options={"blank_percentage": 10})
.build()
)
It can also infer a schema from existing data:
SchemaBuilder.from_dataframe(existing_df) # one field per DataFrame column
SchemaBuilder.from_dataclass(SomeDataclass) # one field per dataclass attribute
ProviderFactory / KEY_LABEL_REGISTRY / resolve_key_label
Low-level plumbing that resolves a key_label to its category and instantiates the provider class. Useful mainly for introspection or building custom tooling on top of the library:
from ikidatagen import ProviderFactory, KEY_LABEL_REGISTRY, resolve_key_label
ProviderFactory.resolve_group("email_address", group=None) # -> "developer_tools"
resolve_key_label("zip_code") # -> "postal_code" (deprecated alias)
A handful of key_labels are deprecated aliases that still work but emit a DeprecationWarning pointing at the canonical name (e.g. zip_code → postal_code, job → job_title, ssn_number → ssn).
Advanced Features
- Reproducibility — pass
seed=toIkiDataGenerator/Datasetfor identical output across runs. - Streaming —
.stream()and.export(..., stream=True)for datasets too large to hold in memory. - Async generation —
await gen.many_async(n). - Weighted categorical sampling —
options={"choices": [...], "weights": [...]}, bypassing the provider entirely. - Uniqueness constraints —
options={"unique": True, "max_unique_tries": N}. - Masking & noise injection —
options={"mask": True}oroptions={"noise": True}for privacy-safe or intentionally dirty test data. - Value constraints —
options={"constraints": {"min_length": ..., "max_length": ..., "min_value": ..., "max_value": ..., "allowed_values": [...]}}. - Cross-field templates — the
templateprovider (advancedcategory) interpolates other fields already generated in the same row via{{Label}}placeholders. - Password hashing — the
password_hashprovider usesbcryptby default; passoptions={"fast": True}to switch to a SHA-256-based hash for bulk fixture generation where cryptographic strength doesn't matter. - Event streams —
.generate_event_stream()attaches synthetic, monotonically increasing timestamps/sequence numbers. - Recipe export —
Dataset.export_recipe()saves{schema, seed}as JSON so a dataset can be regenerated identically later. - Strict option validation — providers raise on unknown
optionskeys by default (strict=Trueat the provider level); pass"strict": Falsein a field'soptionsto downgrade this to a warning.
👉 See How Advanced Options Work (In Depth) for exactly what each of these does under the hood, including a few non-obvious gotchas (e.g. unique isn't enforced in .stream(), mask skips noise/constraints).
How Advanced Options Work (In Depth)
This section explains the mechanics behind each advanced option — what actually happens inside base_generator.py when you set it — so you know exactly what to expect, including a couple of behavioral gotchas that aren't obvious from the option name alone.
blank_percentage
Every provider accepts blank_percentage (0–100). What happens with it differs slightly depending on how you generate data:
.many(n)/.export()(non-streaming): the exact number of blank rows is computed up front —round(n * pct / 100)— and that many distinct row indices are randomly chosen (viarng.sample) to be set toNonefor that field. Withn=100andblank_percentage=25, you get exactly 25 blanks, not "approximately.".stream()/.export(..., stream=True): each row independently rollsrng.random() < pct, so the blank rate is a probability, not a guaranteed count. Over a large stream it converges to the target percentage, but any individual batch can deviate.
schema = [{"key_label": "email_address", "options": {"blank_percentage": 25}}]
IkiDataGenerator(schema).many(100).data # exactly 25 rows have email_address = None
unique + max_unique_tries
{"key_label": "email_address", "options": {"unique": True, "max_unique_tries": 5000}}
When unique=True, the generator keeps a seen set per field and retries generation (up to max_unique_tries, default 1000) until it produces a value not already in that set. If it can't find one in time, it raises:
ValueError: [Schema Error] Unable to generate unique value for '<label>' after 1000 tries.
Two things worth knowing:
- Uniqueness is scoped to a single field/column, not across the whole row.
uniqueis only enforced in.many()/ non-streaming generation..stream()calls the provider directly without the retry/uniqueness loop, so don't rely onuniquefor streamed output — pick a naturally-high-cardinality provider (e.g.uuid_v4) instead.- A blank row (from
blank_percentage) is never checked for uniqueness —Nonevalues don't count against theseenset.
choices + weights
{"key_label": "country", "options": {"choices": ["US", "CA", "MX"], "weights": [0.7, 0.2, 0.1]}}
When choices is set, the provider is bypassed entirely for that field — the value comes from rng.choice(choices) (uniform) or rng.choices(choices, weights=weights) (weighted) instead of the provider's own generation logic. This means choices works identically for every key_label, even ones that don't natively support constrained value sets. weights must be the same length as choices or a ValueError is raised at generation time.
mask
{"key_label": "ssn", "options": {"mask": True}}
The provider still runs (so blank/unique logic still applies normally), but the generated value is thrown away and replaced with the literal string "[REDACTED]". Masking short-circuits before noise and constraints are applied — if you set mask alongside noise or constraints on the same field, those are silently skipped for that field.
noise
{"key_label": "last_name", "options": {"noise": True}}
Applies exactly one random perturbation to string values — a character swap, repeat, drop, or insert (chosen uniformly) — to simulate messy real-world/dirty data for testing data-cleaning pipelines. Only applies to non-empty strings; numbers, booleans, dates, etc. pass through unchanged. It runs after generation but before constraints, so a constraint like max_length can still trim a noisy value back down.
constraints
{
"key_label": "username",
"options": {
"constraints": {
"min_length": 5,
"max_length": 20,
"min_value": 0,
"max_value": 1000,
"allowed_values": ["admin", "user", "guest"],
}
},
}
Applied last, in this order, only to the keys you actually provide:
| Key | Behavior |
|---|---|
min_length |
If the (string) value is shorter, pads it with repeated "x" characters to reach the minimum. |
max_length |
If the (string) value is longer, truncates it. |
min_value |
If the (numeric) value is lower, clamps it up to min_value. |
max_value |
If the (numeric) value is higher, clamps it down to max_value. |
allowed_values |
If the value isn't in the list, it's replaced with the first item in allowed_values. |
strict
{"key_label": "number", "options": {"strict": False, "typo_option": 123}}
Every provider raises ValueError by default when it receives an options key it doesn't recognize (strict=True, the default at the provider level) — this catches typos in your schema early. Set "strict": False to downgrade that to a UserWarning instead of a hard failure, e.g. when passing shared options across providers that don't all understand every key.
Reproducibility (seed)
IkiDataGenerator(schema, seed=42).many(100) # identical output every run
seed creates one random.Random(seed) instance shared by the generator, every provider instance, and the blank/unique/choices logic. Providers that need extra entropy (e.g. normal_distribution, which uses numpy) derive their own seed from this shared RNG (self._rng.randint(0, 2**32 - 1)), so the whole pipeline stays deterministic end-to-end for a given seed.
Streaming (.stream() / export(..., stream=True))
for batch in IkiDataGenerator(schema, seed=1).stream(n=1_000_000, batch_size=5000):
process(batch) # list[dict] of up to 5000 rows, never holding all 1M in memory
IkiDataGenerator(schema).export("big_table", formats=["ndjson"], stream=True, n=1_000_000)
Streaming generates and yields rows in fixed-size batches without materializing the full dataset. .export(..., stream=True) only streams for csv, json, and ndjson; any other requested format falls back to generating the full dataset in memory first. As noted above, blank_percentage becomes probabilistic and unique is not enforced in streaming mode.
Async generation
rows = await IkiDataGenerator(schema).many_async(1000)
many_async() is a thin async def wrapper around the same synchronous generate_many() — it exists so the library can be called from async codebases without blocking the event loop's syntax, not because generation itself runs concurrently or does async I/O.
Cross-field templates
schema = [
"first_name",
"last_name",
{"key_label": "template", "label": "Full Profile", "options": {"template": "{{first_name}} {{last_name}}"}},
]
The template provider (in the advanced category) interpolates {{Label}} placeholders using the output label of fields already generated earlier in the same row — schema order matters. Referencing a field that appears later in the schema, or one that doesn't exist at all, raises a ValueError at generation time rather than silently producing a blank/broken string.
Password hashing modes
{"key_label": "password_hash", "options": {"fast": True}}
By default, password_hash generates a random plaintext password internally and hashes it with bcrypt (rounds controls cost factor, default 4). Pass "fast": True to switch to a SHA-256-based hash instead — bcrypt is intentionally slow (that's the point for real security), which makes it a poor fit for generating millions of fixture rows quickly. fast=True trades cryptographic hashing strength for throughput; don't use it to model real production password hashes.
Event streams
IkiDataGenerator(schema).generate_event_stream(
n=1000, start_time="2026-01-01T00:00:00Z", step_seconds=30
)
Generates n normal rows, then stamps each with a monotonically increasing event_sequence (starting at 1) and an event_timestamp spaced step_seconds apart starting at start_time (defaults to "now" in UTC if omitted) — useful for simulating log lines, sensor readings, or clickstream events with realistic ordering.
Recipe export
ds = Dataset.from_schema(schema, seed=42)
ds.generate(100)
ds.export_recipe("recipe.json") # writes {"schema": [...], "seed": 42}
Saves just the schema + seed (not the generated rows) as JSON, so anyone can reproduce the exact same dataset later with Dataset.from_schema(json.load(open("recipe.json"))["schema"], seed=...).
Custom Providers
Every provider is a plain Python class. To add your own field:
- Create
src/ikidatagen/providers/<group>/<key_label>.py(or a new<group>/folder). - Define a class named
<KeyLabelInPascalCase>Providerthat subclassesBaseProviderand implementsgenerate_non_blank(self, row_data=None, row_index=None). - Register the
key_label→ group mapping inKEY_LABEL_REGISTRYinsideschema_registry.py(or simply pass"group": "<group>"explicitly in your schema — no registry entry needed in that case).
# providers/personal/favorite_number.py
from ..base_provider import BaseProvider
class FavoriteNumberProvider(BaseProvider):
def __init__(self, blank_percentage: float = 0.0, **kwargs):
super().__init__(blank_percentage=blank_percentage, **kwargs)
def generate_non_blank(self, row_data=None, row_index=None):
return self._rng.randint(1, 100)
schema = [{"key_label": "favorite_number", "group": "personal"}]
Project Structure
Iki-Data-Generator/
├── main.py # example usage script
├── requirements.txt
├── src/
│ └── ikidatagen/
│ ├── core.py # IkiDataGenerator — main entrypoint
│ ├── base_generator.py # schema normalization + row generation loop
│ ├── provider_factory.py # resolves key_label -> provider class
│ ├── schema_registry.py # KEY_LABEL_REGISTRY + deprecated aliases
│ ├── schema_builder.py # SchemaBuilder
│ ├── dataset.py # Dataset wrapper
│ ├── dataset_manager.py # loads bundled JSON/CSV reference data
│ ├── exporters.py # Exporter — all 14 export formats
│ ├── optional_categories.py # reserved/optional category extras
│ ├── payload.py # in-memory lookup payloads
│ ├── external_datasets/ # bundled JSON/CSV reference data
│ └── providers/ # 729 field providers across 22 categories
│ ├── base_provider.py
│ ├── personal/ commerce/ finance/ health/ developer_tools/
│ ├── location/ nature/ entertainment/ marketing/ ai/
│ ├── telecom/ travel/ political/ legal/ blockchain/
│ ├── gaming/ gaming_sports/ car/ education/ infrastructure/
│ ├── basic/ advanced/
│ └── communication/ construction/ crypto/ governance/ it/ products/ sports/ (reserved, currently empty)
├── examples/ # 45 runnable example scripts
└── tests/ # smoke tests, integration tests, provider coverage tests
Common Issues
"Unknown key_label 'xxx'" — the key_label isn't in KEY_LABEL_REGISTRY. Check for typos; the error message includes fuzzy "did you mean?" suggestions. If it's a custom provider, pass "group" explicitly.
"No data to export" — call .many(n) before .export(...), or pass stream=True together with n=... to .export().
"Unknown option(s) ignored" / raised error — a provider's options dict contains a key it doesn't recognize. By default this raises (strict=True); pass "options": {"strict": False, ...} to downgrade it to a warning instead.
Template field renders literally / raises — template interpolates {{Label}} using the output label of other fields already defined earlier in the schema, not the key_label. Make sure referenced fields appear before the template field.
Testing
pip install -e .
python tests/quick_smoke_test.py # fast sanity check across common providers
python tests/full_providers_smoke.py # exercises every registered provider
python -m pytest tests/
Contributing
Issues and pull requests are welcome — especially new providers, bug fixes, and additional export formats. When adding a provider, please also add a corresponding test under tests/.
License
MIT — see LICENSE.
Links
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file iki_data_generator-1.1.2.tar.gz.
File metadata
- Download URL: iki_data_generator-1.1.2.tar.gz
- Upload date:
- Size: 18.3 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
30652ba77d44539a188f2bebd1868c59fe31109f6d78ebf055ddc0779500d5e8
|
|
| MD5 |
06e96e486d436286b8f8f820951991ce
|
|
| BLAKE2b-256 |
552383c59f00c39e65157d3c393f9aa40122f0a9f19ea55f8b3bff5f2e0f0d9e
|
File details
Details for the file iki_data_generator-1.1.2-py3-none-any.whl.
File metadata
- Download URL: iki_data_generator-1.1.2-py3-none-any.whl
- Upload date:
- Size: 18.7 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.12.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ea64d62c42f7f405f9deb2bcb7b0f5506ec017b9d03f3c17212cf6cbb68c296f
|
|
| MD5 |
8d63bd6f905959c6e7853e8f3afb0a55
|
|
| BLAKE2b-256 |
a1737904ba1c127ac91b648b62f036f2f5416181128cc4d51c0cad2b92abf521
|
