Phoney - Documentation
Description: Phoney - Generate realistic fake data for testing, development, and anonymization. Supports 50+ locales with complete profiles.

# Phoney

Generate realistic fake data for testing, development, and anonymization

Get Started Quick Start

## Overview

Phoney is a comprehensive fake data generator designed for developers who need realistic test data. It supports over 50 locales and generates everything from names and emails to complete user profiles with financial information.

### 50+ Locales

Generate locale-specific data for countries worldwide with proper name formats, phone numbers, and cultural considerations.

### Complete Profiles

Create full user profiles including names, contact information, demographics, and financial data in one call.

### Zero Dependencies

Lightweight and fast with no external dependencies. Perfect for CI/CD pipelines and production environments.

## Installation

Get started with Phoney in seconds using pip or your preferred package manager.

`pip install phoney`

Or install from GitHub for the latest features:

`pip install git+https://github.com/YTstyo/phoney.git`

## Quick Start

Jump right in with these common usage patterns and examples.

### Basic Usage

    from phoney import Phoney

    # Initialize the generator
    phoney = Phoney()

    # Generate individual data
    print(phoney.first_name(locale='de_DE'))  # → 'Hans'
    print(phoney.phone(locale='ja_JP'))       # → '+81 90-1234-5678'
    print(phoney.email('John', 'Doe'))        # → 'john.doe@example.com'

### Complete Profile Generation

    # Generate a complete profile
    profile = phoney.profile(locale='fr_FR')

    print(profile)
    # Output:
    # {
    #   'first_name': 'Marie',
    #   'last_name': 'Dubois',
    #   'full_name': 'Marie Dubois',
    #   'gender': 'female',
    #   'age': 28,
    #   'birthdate': '1995-03-15',
    #   'email': 'marie.dubois@example.fr',
    #   'phone': '+33 6 12 34 56 78',
    #   'username': 'marie_dubois_95',
    #   'credit_card': {
    #     'issuer': 'Visa',
    #     'number': '4532123456789012',
    #     'expiry': '12/2028',
    #     'cvv': '123'
    #   },
    #   'locale': 'fr_FR'
    # }

### Financial Data Generation

    from phoney.financial import FinancialDataGenerator

    # Generate financial data
    financial = FinancialDataGenerator(locale='en_US')
    data = financial.generate()

    print(data)
    # Output:
    # {
    #   'credit_card': {
    #     'issuer': 'MasterCard',
    #     'number': '5555444433332222',
    #     'expiry': '08/2027',
    #     'cvv': '456'
    #   },
    #   'iban': 'US64SVBKUS6S3300958879',
    #   'bic': 'SVBKUS6S'
    # }

## Features

Comprehensive data generation capabilities for all your testing needs.

- Generate names, emails, phones, and addresses for 50+ locales
- Create complete user profiles with demographics and preferences
- Generate financial data including credit cards, IBANs, and BICs
- Create usernames, passwords, and social media handles
- Generate UUIDs, user agents, and other technical identifiers
- Zero dependencies for easy integration
- Lightweight and performant
- Extensive locale support with cultural accuracy
- Modular architecture for custom implementations

## Modules

Phoney is organized into focused modules that handle specific data generation tasks.

### age.py

Generate random ages and birthdates with configurable ranges. Supports age constraints for realistic demographics.

`generate_age(min_age=18, max_age=80)`

### agent.py

Create realistic browser user agent strings for desktop and mobile devices across different browsers and versions.

`generate_user_agent(device_type="desktop")`

### create_profile.py

Generate complete user profiles combining data from all other modules. Includes names, contact info, username, and financial data.

`generate_profile(locale, gender=None)`

### data_loader.py

Load and manage locale-specific data including names, phone formats, and email domains from organized data files.

`load_names(locale)
get_available_locales()`

### emailgen.py

Create realistic email addresses based on names and locale-specific domain patterns with various formatting styles.

`generate_email(first_name, last_name, locale)`

### financial.py

Generate fake financial data including valid credit card numbers, IBANs, BICs, and other banking information.

`FinancialDataGenerator(locale='en_US')`

### person.py

Generate person data including first names, last names, and genders based on locale-specific cultural patterns.

`generate_person(locale, gender=None)`

### phone.py

Create phone numbers in the correct format for any locale with proper country codes and regional patterns.

`generate_phone(locale=None)`

### username.py

Generate usernames, secure passwords, social media handles, and complete online presence profiles.

`generate_username(first_name, last_name)`

### uuidgen.py

Generate UUIDs (universally unique identifiers) of various versions (v1, v3, v4, v5) for different use cases.

`generate_uuid(version=4)`

### career.py

Job titles with levels, salary ranges per locale, employment history and skills lists.

`generate_job_title()
generate_salary()
generate_employment_history()
generate_skills()`

### internet.py

Domains, URLs, hostnames, IPv4/IPv6 and MAC addresses. Locale-aware TLDs; country/region-aware IPv4/IPv6 with data file overrides.

`generate_tld(locale=None)
generate_domain(tld=None, locale=None)
generate_url(scheme='https', domain=None, path_segments=None, query_params=None, locale=None)
generate_ipv4(country=None, locale=None)
generate_ipv6(global_unicast=True, country=None, locale=None)
generate_mac()`

### identifiers

Device and barcode identifiers with correct check digits and constraints.

`generate_imei(tac=None)
generate_vin()
generate_ean13(prefix="")
generate_upca(prefix="")
generate_isbn13(group_prefix="978")`

## Internet Data Files

Override built-in defaults by adding files under `phoney/data/internet`.

Overrides
Provide your own datasets for accuracy and compliance requirements.
Files:
• `tlds.txt` — Preferred TLDs, one per line
• `words.txt` — Wordlist used for domains and paths
• `ipv4_prefixes.<CC>.txt` — Country IPv4 CIDRs, one per line (e.g., `ipv4_prefixes.GB.txt`)
• `ipv6_prefixes.<CC>.txt` — Country IPv6 CIDRs, one per line (e.g., `ipv6_prefixes.JP.txt`)
Generate per-country prefixes (offline)
Use the helper to build `ipv4_prefixes.<CC>.txt` and `ipv6_prefixes.<CC>.txt` from RIR delegated datasets.
Steps:
1) Download the following files to `tools/data/`:
`delegated-apnic-extended-latest`, `delegated-arin-extended-latest`, `delegated-ripencc-extended-latest`, `delegated-lacnic-extended-latest`, `delegated-afrinic-extended-latest`
2) Run the builder:

    python tools/build_prefixes.py

The script writes output files under `phoney/data/internet`.
Tip: Use the one-step PowerShell helper on Windows:

    ./tools/fetch_and_build_prefixes.ps1

## API Reference

Complete reference for the Phoney class and all available methods.

ipv4(country=None, locale=None)
Generate a public-looking IPv4 address. If country-specific prefixes are provided via data files, outputs are drawn from those; otherwise a regional fallback is used. Private/reserved ranges are avoided.
Parameters:
• country (str): ISO country code, e.g. 'GB'
• locale (str): Locale like 'en_GB' or 'en-GB' (also accepts bare 'GB')
Returns: str - IPv4 address
ipv6(global_unicast=True, country=None, locale=None)
Generate a valid IPv6 address. Prefers country-specific CIDR prefixes when present via data files; else uses RIR regional /12 fallback by locale. Always returns canonical compressed form.
Parameters:
• global_unicast (bool): when True (default), ensures address is from 2000::/3 if no locale/country match
• country (str): ISO country code, e.g. 'JP'
• locale (str): Locale like 'ja_JP' or 'ja-JP' (also accepts bare 'JP')
Returns: str - IPv6 address
imei(tac=None)
Generate a 15-digit IMEI with a valid Luhn check digit. Optionally pass an 8-digit TAC.
Parameters:
• tac (str|None): 8-digit Type Allocation Code to anchor the IMEI
Returns: str - IMEI
vin()
Generate a 17-character VIN with correct check digit; excludes letters I, O, and Q.
Returns: str - VIN
ean13(prefix="")
Generate an EAN-13 barcode number with a valid checksum. Optional numeric prefix is supported.
Parameters:
• prefix (str): Optional starting digits (will be trimmed to fit 12-digit body)
upca(prefix="")
Generate a 12-digit UPC-A barcode with a valid checksum. Optional numeric prefix is supported.
Parameters:
• prefix (str): Optional starting digits for the 11-digit body
isbn13(group_prefix="978")
Generate an ISBN-13 number (default group prefix 978) with a valid checksum.
Parameters:
• group_prefix (str): Usually 978 or 979
Phoney()
Main class for generating fake data. Initialize once and use throughout your application.
Usage:

    phoney = Phoney()
    # No parameters required for initialization

first_name(locale='en_US', gender=None)
Generate a first name for the specified locale and gender.
Parameters:
• locale (str): Locale code (e.g., 'en_US', 'fr_FR')
• gender (str): 'male' or 'female', None for random
Returns: str - First name
profile(locale='en_US', gender=None)
Generate a complete user profile with all demographic and contact information.
Parameters:
• locale (str): Locale code
• gender (str): 'male' or 'female', None for random
Returns: dict - Complete profile with name, age, contact info, username, and credit card data
phone(locale='en_US')
Generate a phone number in the format appropriate for the specified locale.
Parameters:
• locale (str): Locale code
Returns: str - Formatted phone number with country code
email(first_name, last_name, locale='en_US')
Generate an email address based on the provided names and locale.
Parameters:
• first_name (str): First name
• last_name (str): Last name
• locale (str): Locale code for domain selection
Returns: str - Email address
username(first_name, last_name)
Generate a username based on the provided names using various formatting patterns.
Parameters:
• first_name (str): First name
• last_name (str): Last name
Returns: str - Username

## Supported Locales

Phoney supports over 50 locales across different regions with culturally appropriate data.

### Asian Locales

🇮🇳
India
hi_IN
🇯🇵
Japan
ja_JP
🇰🇷
South Korea
ko_KR
🇨🇳
China
zh_CN

### European Locales

🇩🇰
Denmark
da_DK
🇩🇪
Germany
de_DE
🇬🇧
United Kingdom
en_GB
🇺🇸
United States
en_US
🇪🇸
Spain
es_ES
🇫🇮
Finland
fi_FI
🇫🇷
France
fr_FR
🇮🇹
Italy
it_IT
🇳🇱
Netherlands
nl_NL
🇵🇱
Poland
pl_PL
🇧🇷
Brazil
pt_BR
🇷🇺
Russia
ru_RU
🇸🇪
Sweden
sv_SE
🇹🇷
Turkey
tr_TR

### Middle East & Africa

🇪🇬
Egypt
ar_EG

## Examples

Real-world examples of how to use Phoney in your projects.

### Creating Test Users for a Database

    from phoney import Phoney

    # Create test users for different locales
    phoney = Phoney()
    users = []

    locales = ['en_US', 'de_DE', 'fr_FR', 'ja_JP', 'es_ES']

    for locale in locales:
        for i in range(5):
            user = phoney.profile(locale=locale)
            users.append(user)

    # Now you have 25 realistic test users from 5 different countries
    print(f"Created {len(users)} test users")
    for user in users[:3]:  # Show first 3
        print(f"{user['full_name']} ({user['locale']}) - {user['email']}")

### Testing User Registration Flow

    from phoney import Phoney
    from phoney.username import generate_password

    phoney = Phoney()

    def create_test_registration_data():
        # Generate a realistic test user
        profile = phoney.profile(locale='en_US')

        return {
            'first_name': profile['first_name'],
            'last_name': profile['last_name'],
            'email': profile['email'],
            'phone': profile['phone'],
            'username': profile['username'],
            'password': generate_password(min_length=8, max_length=12),
            'date_of_birth': profile['birthdate'],
            'user_agent': phoney.user_agent()
        }

    # Use in your tests
    test_user = create_test_registration_data()
    # POST to /api/register with test_user data

### Generating Sample Data for Development

    import json
    from phoney import Phoney

    phoney = Phoney()

    # Generate sample data for frontend development
    sample_data = {
        'customers': [],
        'orders': [],
        'products': []
    }

    # Create 100 sample customers
    for i in range(100):
        customer = phoney.profile()
        sample_data['customers'].append({
            'id': i + 1,
            'name': customer['full_name'],
            'email': customer['email'],
            'phone': customer['phone'],
            'age': customer['age'],
            'country': customer['locale'].split('_')[1],
            'created_at': '2024-01-01'
        })

    # Save to JSON file
    with open('sample_data.json', 'w') as f:
        json.dump(sample_data, f, indent=2)

    print("Sample data generated successfully!")