farsi-faker 1.0.0

Generate realistic fake Persian/Farsi names for testing - تولید اسم‌های فارسی فیک با 10,000+ اسم اصیل

Farsi Faker | فارسی فیکر

Generate realistic fake Persian/Farsi names for testing and development

تولید اسم‌های فارسی فیک واقع‌گرایانه برای تست و توسعه

Installation • Quick Start • Documentation • Examples • Contributing

---

✨ Features

• 🎯 10,000+ Authentic Names - Real Persian names from Iranian datasets
• 👥 Gender-Specific - Separate male and female name generation
• ⚡ High Performance - Optimized pickle-based data storage
• 🔄 Reproducible - Seed support for consistent results
• 🚀 Zero Dependencies - No external packages required for production
• 🔒 Thread-Safe - Safe for concurrent use
• 📝 Fully Typed - Complete type hints for better IDE support
• ✅ Well Tested - Comprehensive test coverage
• 🌍 Unicode Support - Full Persian/Farsi character support

---

📦 Installation

From PyPI (Recommended)

pip install farsi-faker

From Source

git clone https://github.com/alisadeghiaghili/farsi-faker.git
cd farsi-faker
pip install -e .

Requirements

• Python 3.7+
• No external dependencies for production use
• Optional: pandas for data processing (development only)

---

🚀 Quick Start

Basic Usage

from farsi_faker import FarsiFaker

# Create faker instance
faker = FarsiFaker()

# Generate a random person
person = faker.full_name()
print(person)
# {'name': 'علی احمدی', 'first_name': 'علی', 'last_name': 'احمدی', 'gender': 'male'}

# Generate male name
male = faker.full_name('male')
print(male['name'])  # محمد رضایی

# Generate female name
female = faker.full_name('female')
print(female['name'])  # فاطمه محمدی

Generate Multiple Names

# Generate 10 random names
people = faker.generate_names(10)

# Generate 50 male names
men = faker.generate_names(50, 'male')

# Generate 30 female names
women = faker.generate_names(30, 'female')

Generate Balanced Dataset

# Generate 100 people with 60% male ratio
dataset = faker.generate_dataset(100, male_ratio=0.6)

# Verify ratio
males = sum(1 for p in dataset if p['gender'] == 'male')
print(f"Males: {males}, Females: {100 - males}")
# Males: 60, Females: 40

Reproducible Results

# Use seed for reproducible results
faker1 = FarsiFaker(seed=42)
faker2 = FarsiFaker(seed=42)

name1 = faker1.full_name()
name2 = faker2.full_name()

assert name1 == name2  # True - same results!

Quick One-Off Generation

from farsi_faker import generate_fake_name

# Quick generation without creating instance
person = generate_fake_name('male')
print(person['name'])  # علی احمدی

---

📖 Documentation

Class: FarsiFaker

Main class for generating Persian names.

Constructor

FarsiFaker(seed: Optional[int] = None)

Parameters:

• seed (int, optional): Random seed for reproducible results

Example:

faker = FarsiFaker()  # Random generation
faker = FarsiFaker(seed=42)  # Reproducible generation

---

Methods

male_first_name() -> str

Generate a random male first name.

Returns: Male Persian name as string

Example:

name = faker.male_first_name()
# 'محمد'

---

female_first_name() -> str

Generate a random female first name.

Returns: Female Persian name as string

Example:

name = faker.female_first_name()
# 'فاطمه'

---

first_name(gender=None) -> Tuple[str, str]

Generate a first name with optional gender specification.

Parameters:

• gender (str, optional): Gender ('male', 'female', 'm', 'f', 'مرد', 'زن', etc.)

Returns: Tuple of (name, normalized_gender)

Example:

name, gender = faker.first_name('male')
# ('علی', 'male')

name, gender = faker.first_name()  # Random
# ('مریم', 'female')

---

last_name() -> str

Generate a random family name.

Returns: Persian family name as string

Example:

name = faker.last_name()
# 'احمدی'

---

full_name(gender=None) -> Dict[str, str]

Generate a complete person with full name and metadata.

Parameters:

• gender (str, optional): Desired gender

Returns: Dictionary with keys:

• name: Full name
• first_name: First name only
• last_name: Family name only
• gender: Normalized gender ('male' or 'female')

Example:

person = faker.full_name('female')
# {
#     'name': 'فاطمه محمدی',
#     'first_name': 'فاطمه',
#     'last_name': 'محمدی',
#     'gender': 'female'
# }

---

generate_names(count=10, gender=None) -> List[Dict[str, str]]

Generate multiple full names.

Parameters:

• count (int): Number of names to generate
• gender (str, optional): Gender for all names

Returns: List of person dictionaries

Raises: ValueError if count is not positive

Example:

people = faker.generate_names(5, 'male')
# [
#     {'name': 'علی احمدی', 'first_name': 'علی', ...},
#     {'name': 'محمد رضایی', 'first_name': 'محمد', ...},
#     ...
# ]

---

generate_dataset(count=100, male_ratio=0.5) -> List[Dict[str, str]]

Generate a balanced dataset with specified gender ratio.

Parameters:

• count (int): Total number of names
• male_ratio (float): Ratio of male names (0.0 to 1.0)

Returns: List of person dictionaries (shuffled)

Raises: ValueError if parameters are invalid

Example:

# 60% male, 40% female
dataset = faker.generate_dataset(100, male_ratio=0.6)

# All female
all_women = faker.generate_dataset(50, male_ratio=0.0)

# Balanced
balanced = faker.generate_dataset(100, male_ratio=0.5)

---

get_stats() -> Dict[str, int]

Get statistics about the names database.

Returns: Dictionary with:

• male_names_count: Number of male first names
• female_names_count: Number of female first names
• last_names_count: Number of family names
• total_names: Sum of all names
• possible_combinations: Total possible combinations

Example:

stats = faker.get_stats()
print(f"Possible combinations: {stats['possible_combinations']:,}")
# Possible combinations: 21,000,000

---

Function: generate_fake_name()

generate_fake_name(gender=None, seed=None) -> Dict[str, str]

Convenience function for quick one-off name generation.

Parameters:

• gender (str, optional): Desired gender
• seed (int, optional): Random seed

Returns: Person dictionary

Example:

from farsi_faker import generate_fake_name

person = generate_fake_name('male', seed=42)
print(person['name'])

---

🎨 Examples

Example 1: Create Test Dataset for Django

from farsi_faker import FarsiFaker
from myapp.models import User

faker = FarsiFaker(seed=42)
dataset = faker.generate_dataset(100, male_ratio=0.5)

for person in dataset:
    User.objects.create(
        name=person['name'],
        first_name=person['first_name'],
        last_name=person['last_name'],
        gender=person['gender']
    )

Example 2: Export to CSV

import csv
from farsi_faker import FarsiFaker

faker = FarsiFaker()
dataset = faker.generate_dataset(1000, male_ratio=0.6)

with open('people.csv', 'w', encoding='utf-8', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=['name', 'first_name', 'last_name', 'gender'])
    writer.writeheader()
    writer.writerows(dataset)

Example 3: pandas DataFrame

import pandas as pd
from farsi_faker import FarsiFaker

faker = FarsiFaker(seed=123)
dataset = faker.generate_dataset(500, male_ratio=0.55)

df = pd.DataFrame(dataset)
print(df.head())
print(df['gender'].value_counts())

Example 4: pytest Fixture

import pytest
from farsi_faker import FarsiFaker

@pytest.fixture
def fake_users():
    faker = FarsiFaker(seed=42)
    return faker.generate_dataset(10, male_ratio=0.5)

def test_user_creation(fake_users):
    assert len(fake_users) == 10
    assert all('name' in user for user in fake_users)

Example 5: API Mock Data

from flask import Flask, jsonify
from farsi_faker import FarsiFaker

app = Flask(__name__)
faker = FarsiFaker()

@app.route('/api/users/random')
def random_user():
    return jsonify(faker.full_name())

@app.route('/api/users/<int:count>')
def multiple_users(count):
    users = faker.generate_names(min(count, 100))  # Max 100
    return jsonify(users)

---

🎯 Gender Input Options

The package accepts various gender formats:

English

• 'male', 'm' → Male
• 'female', 'f' → Female

Persian (فارسی)

• 'مرد', 'پسر', 'مذکر' → Male
• 'زن', 'دختر', 'مونث' → Female

Examples

faker = FarsiFaker()

# All these work for male
faker.full_name('male')
faker.full_name('m')
faker.full_name('مرد')
faker.full_name('پسر')

# All these work for female
faker.full_name('female')
faker.full_name('f')
faker.full_name('زن')
faker.full_name('دختر')

# Case-insensitive
faker.full_name('MALE')
faker.full_name('Female')

---

📊 Database Statistics

from farsi_faker import FarsiFaker

faker = FarsiFaker()
stats = faker.get_stats()

print(f"Male names: {stats['male_names_count']:,}")
print(f"Female names: {stats['female_names_count']:,}")
print(f"Last names: {stats['last_names_count']:,}")
print(f"Total names: {stats['total_names']:,}")
print(f"Possible combinations: {stats['possible_combinations']:,}")

Example Output:

Male names: 3,500
Female names: 3,800
Last names: 2,700
Total names: 10,000
Possible combinations: 19,710,000

---

🧪 Testing

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=farsi_faker --cov-report=html

# View coverage report
open htmlcov/index.html

---

🛠️ Development

Setup Development Environment

# Clone repository
git clone https://github.com/alisadeghiaghili/farsi-faker.git
cd farsi-faker

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[all]"

Code Quality

# Format code
black farsi_faker/
isort farsi_faker/

# Type checking
mypy farsi_faker/

# Run tests
pytest tests/ -v

Building and Publishing

# Build distribution packages
python -m build

# Check distribution
twine check dist/*

# Upload to PyPI
twine upload dist/*

---

📁 Project Structure

farsi-faker/
├── farsi_faker/              # Main package
│   ├── __init__.py          # Package initialization
│   ├── faker.py             # Core FarsiFaker class
│   ├── _version.py          # Version information
│   └── data/                # Data directory
│       ├── __init__.py
│       └── names.pkl        # Pickle database (embedded)
├── tests/                    # Test suite
│   ├── __init__.py
│   └── test_faker.py
├── scripts/                  # Development scripts
│   └── create_pickle.py     # Build pickle from CSV
├── data_sources/             # Original CSV files
│   ├── iranianNamesDataset.csv
│   └── iranian-surname-frequencies.csv
├── setup.py                  # Setup configuration
├── pyproject.toml           # Project metadata
├── MANIFEST.in              # Distribution files
├── LICENSE                   # MIT License
├── README.md                 # This file
└── CHANGELOG.md             # Version history

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run tests (pytest tests/)
6. Commit changes (git commit -m 'Add amazing feature')
7. Push to branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Code Style

• Follow PEP 8
• Use Black for formatting
• Add type hints
• Write docstrings
• Add tests for new features

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 Ali Sadeghi Aghili

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

📞 Contact & Links

• Author: Ali Sadeghi Aghili
• Email: [e-mail]
• GitHub: https://github.com/alisadeghiaghili/farsi-faker
• PyPI: https://pypi.org/project/farsi-faker/
• Issues: https://github.com/alisadeghiaghili/farsi-faker/issues

---

🙏 Acknowledgments

• Names dataset sourced from publicly available Iranian name databases
• Inspired by Faker library
• Built with ❤️ for the Persian/Farsi development community

---

⭐ Star History

If you find this project useful, please consider giving it a star! ⭐

---

Made with ❤️ by Ali Sadeghi Aghili