russiafaker 1.0.0

FakerRussia - генератор российских персональных данных

FakerRussia

>> Вебсайт <<

>> Вебсайт (Альтернативная ссылка)<<

О проекте

FakerRussia представляет собой программную библиотеку для генерации реалистичных персональных данных, адаптированных к российской специфике. Разработка предназначена для использования в целях тестирования программного обеспечения, наполнения баз данных тестовыми наборами информации, создания демонстрационных стендов, проведения нагрузочных испытаний, а также для любых иных сценариев, требующих наличия правдоподобных персональных данных, соответствующих российским реалиям.

Библиотека обеспечивает генерацию комплексного профиля человека, включающего следующие категории данных:

• биографические сведения;
• адресные данные;
• контактная информация;
• документальные данные;
• финансовые показатели;
• сведения о трудовой деятельности;
• транспортные данные;
• семейное положение.

Все генерируемые характеристики находятся в логической взаимосвязи друг с другом, что обеспечивает высокую степень реалистичности итогового результата и исключает появление противоречивых комбинаций признаков.

Возможности

Биографические данные

Категория	Описание
ФИО	Полное имя, фамилия и отчество с учётом половой принадлежности
Возраст и дата рождения	Случайный возраст от 1 до 110 лет, дата рождения формируется с учётом возраста
Пол	Мужской или женский, может быть задан явно при инициализации
Антропометрические параметры	Рост, вес, индекс массы тела с учётом возрастных и половых нормативов
Знак зодиака	Определяется на основании даты рождения
Поколение	Классификация по поколенческой теории
Группа крови	Включает резус-фактор
Религия	Случайный выбор из перечня вероисповеданий
Телосложение	Тип конституции тела
Цвет глаз и волос	С учётом вероятности отсутствия волос
Образование	Уровень образования, соответствующий возрасту
Размер обуви	С учётом пола и возраста
Показатели здоровья	Зрение (с возможным дефектом), слух, пульс в состоянии покоя
Группа инвалидности	С вероятностным присвоением
Прививки	Список вакцинаций с возможностью отсутствия
Военная категория годности	С учётом пола и возраста
Место учёбы	Школа, колледж или вуз в зависимости от уровня образования
Средний балл аттестата	Для лиц, завершивших обучение

Адресные данные

Категория	Описание
Регион	Субъект Российской Федерации
Город	Населенный пункт в составе выбранного региона
Улица	Наименование улицы в выбранном городе
Адрес регистрации	Полный адрес с почтовым индексом, номером дома и возможным корпусом
Фактический адрес	Может совпадать с регистрацией, находиться в том же городе или в другом регионе
Тип жилья	Категория жилого помещения

Контактные данные

Категория	Описание
Номер телефона	Формат с кодом страны и города, генерируется для лиц старше 6 лет
Мобильный оператор	Случайный оператор из списка российских операторов связи
Модель телефона	Актуальные модели мобильных устройств
Email адрес	Формируется из имени пользователя и домена
Социальные сети и мессенджеры	Список из 1-15 платформ
IPv4 адрес	Генерация в стандартном формате
IPv6 адрес	Генерация в стандартном формате
Игровая платформа	Для лиц старше 4 лет с возможностью отсутствия интереса к видеоиграм

Документальные данные

Категория	Описание
ИНН	12-значный номер с корректной контрольной суммой, первые 4 цифры соответствуют региону
СНИЛС	11-значный номер с контрольным числом, формат XXX-XXX-XXX YY
Паспорт	Серия и номер с кодом региона, генерируется для лиц старше 14 лет
Дата выдачи паспорта	Рассчитывается на основании возраста (14, 20 или 45 лет)
Код подразделения	Формируется на основании региона
ЕНП	16-значный номер полиса ОМС с контрольной суммой по алгоритму Луна
Административные нарушения	Список нарушений с учётом наличия автомобиля и возраста

Финансовые данные

Категория	Описание
БИК	Банковский идентификационный код, формируется с учётом региона
Количество банковских карт	От 0 до 5 для лиц старше установленного возраста
Названия банков	Соответствуют количеству карт
Номера банковских карт	16-значные номера с корректной контрольной суммой по алгоритму Луна
CVV/CVC коды	Трехзначные коды для каждой карты
Зарплата	Определяется на основании должности и уровня квалификации
Типы карт	Debit или Credit для каждой карты
Сроки действия	В формате MM/YY для каждой карты
ИНН и КПП банков	Реквизиты, соответствующие выбранным банкам
Статус банкротства	Вероятностное значение для совершеннолетних лиц

Рабочие данные

Категория	Описание
Должность	Профессия или статус занятости (безработный, самозанятый, пенсионер)
Трудовой стаж	Количество лет, рассчитывается на основании возраста и пенсионного возраста
Уровень квалификации	Определяется на основании стажа работы
Место работы	ИП или организация с названием
Заболевания	Список заболеваний, соответствующий военной категории
Вредные привычки	Для лиц старше 10 лет с вероятностью отсутствия
Хобби	Список увлечений, соответствующих возрастной группе
Уровень английского языка	Случайный уровень из стандартной классификации
Дата начала работы	Рассчитывается с учётом стажа и даты достижения совершеннолетия
Рабочий график	Тип занятости (полный день, удаленная работа и др.)

Транспортные данные

Категория	Описание
Марка и модель автомобиля	Для лиц старше 16 лет с вероятностью 50%
Государственный регистрационный номер	Формат Б000ББ 00 с кодом региона
Состояние автомобиля	В идеальном состоянии или с перечнем повреждений/дефектов
Цвет	Случайный цвет из установленного перечня
Год выпуска	От 1990 до текущего года
Технические характеристики	Тип кузова, тип двигателя, объём, трансмиссия, привод, мощность

Семейные данные

Категория	Описание
Семейный статус	Для лиц старше 18 лет выбирается из перечня статусов
ФИО супруга	Генерируется с учётом пола человека и его семейного статуса
Возраст супруга	Может совпадать с возрастом человека или отличаться
Дата бракосочетания	Формируется с учётом даты рождения и совершеннолетия
Количество лет в браке	Рассчитывается на основании даты бракосочетания
Количество детей	Определяется на основании стажа брака
Имена детей	Случайные имена для каждого ребёнка
Проживание с родителями	Вероятностное значение на основании возраста, зарплаты и наличия супруга
Количество членов семьи	Рассчитывается с учётом супруга и детей

Требования к окружению

Компонент	Требование
Python	Версия 3.8 и выше
Операционная система	Windows, Linux, macOS (платформонезависимость)
Зависимости	Отсутствуют внешних зависимостей, используется только стандартная библиотека Python

Установка

Стандартная установка из исходных кодов

Метода с установкой напрямую через pip не предусмотрено, так как выдаётся запрос с ошибкой, при попытке выложить данную библиотеку на сайт PyPi. По некоторым данным это связанно вновь с блокировками РКН

Выполните следующие команды в терминале:

git clone https://github.com/waratecs123/FakerRussia/tree/main
cd FakerRussia
pip install .

Или вы можете скачать напрямую из GitHub Releases:

https://github.com/waratecs123/FakerRussia/releases/tag/FakerRussia

Архитектура проекта

Структура директорий

FakerRussia/
├── __init__.py                     # Точка входа, класс FakerRussia
├── b_a__address_generator.py       # Модуль генерации адресных данных
├── b_b__bio_generator.py           # Модуль генерации биографических данных
├── b_c__contact_generator.py       # Модуль генерации контактных данных
├── b_d__document_generator.py      # Модуль генерации документальных данных
├── b_e__finance_generator.py       # Модуль генерации финансовых данных
├── b_f__work_generator.py          # Модуль генерации рабочих данных
├── b_g__vehicle_generator.py       # Модуль генерации транспортных данных
├── b_h__base_generator.py          # Базовый класс для всех генераторов
├── b_i__family_generator.py        # Модуль генерации семейных данных
├── a__data/                        # Директория исходных данных
│   ├── address/                    # Данные для адресов
│   ├── administrative_violations/  # Административные нарушения
│   ├── bad_habits/                 # Вредные привычки
│   ├── bank/                       # Данные о банках
│   ├── blood_type/                 # Группы крови
│   ├── body_type/                  # Типы телосложения
│   ├── business_type/              # Типы бизнеса
│   ├── car/                        # Данные об автомобилях
│   ├── company_name/               # Названия компаний
│   ├── disease/                    # Заболевания
│   ├── education_level/            # Уровни образования
│   ├── educational_institution/    # Учебные заведения
│   ├── email/                      # Данные для email
│   ├── english_level/              # Уровни английского языка
│   ├── eye_color/                  # Цвета глаз
│   ├── female/                     # Женские имена, фамилии, отчества
│   ├── generation/                 # Поколения
│   ├── hair_color/                 # Цвета волос
│   ├── hobby/                      # Хобби
│   ├── housing_type/               # Типы жилья
│   ├── inn/                        # Данные для ИНН
│   ├── job/                        # Профессии
│   ├── male/                       # Мужские имена, фамилии, отчества
│   ├── marital_status/             # Семейные статусы
│   ├── mobile_operator/            # Мобильные операторы
│   ├── nationality/                # Национальности
│   ├── other/                      # Общие данные и константы
│   ├── passport/                   # Данные для паспортов
│   ├── phone/                      # Данные для телефонов
│   ├── religion/                   # Религии
│   ├── small_age/                  # Ответы для малолетних
│   ├── social_networks_messengers/ # Социальные сети и мессенджеры
│   ├── vaccinations/               # Прививки
│   ├── weight/                     # Весовые нормативы
│   └── work_schedule/              # Графики работы
└── b__additional_algorithms/       # Вспомогательные алгоритмы
    ├── a_a__handle_errors.py       # Декоратор обработки ошибок
    ├── a_b__choice_machine_family.py   # Функции для генерации семейных данных
    ├── a_c__choice_value.py        # Утилита для выбора значений
    ├── a_d__choice_machine_finance.py  # Функции для генерации финансовых данных
    ├── a_e__check_spouse.py        # Декоратор проверки наличия супруга
    └── a_f__characteristics_car.py # Функции для характеристик автомобиля

Диаграмма зависимостей модулей

FakerRussia (главный класс)
    │
    ├── BioGenerator
    │
    ├── AddressGenerator
    │
    ├── WorkGenerator ───────────────► BioGenerator
    │
    ├── ContactGenerator ────────────► BioGenerator
    │                           └──► AddressGenerator
    │
    ├── VehicleGenerator ────────────► BioGenerator
    │                           └──► AddressGenerator
    │
    ├── DocumentGenerator ───────────► BioGenerator
    │                           ├──► AddressGenerator
    │                           └──► VehicleGenerator
    │
    ├── FinanceGenerator ────────────► BioGenerator
    │                           ├──► AddressGenerator
    │                           ├──► DocumentGenerator
    │                           └──► WorkGenerator
    │
    └── FamilyGenerator ─────────────► BioGenerator
                                └──► FinanceGenerator

Все генераторы наследуются от BaseGenerator, который обеспечивает:

• загрузку данных из JSON-файлов;
• унифицированную обработку путей к файлам;
• доступ к общим константам и настройкам.

Руководство по использованию

Инициализация генератора

from FakerRussia import FakerRussia

# Создание экземпляра генератора
generator = FakerRussia()

Указание пола при инициализации

Параметр my_gender принимает значения "male" или "female":

# Генерация данных для мужчины
male_generator = FakerRussia(my_gender="male")

# Генерация данных для женщины
female_generator = FakerRussia(my_gender="female")

При отсутствии параметра пол определяется случайным образом.

Получение полного профиля

Для вывода всех сгенерированных данных используется метод __str__:

generator = FakerRussia()
print(generator)

Доступ к отдельным категориям

Каждая категория данных доступна через соответствующий атрибут:

Атрибут	Класс генератора	Описание
bio	BioGenerator	Биографические данные
address	AddressGenerator	Адресные данные
contact	ContactGenerator	Контактные данные
document	DocumentGenerator	Документальные данные
finance	FinanceGenerator	Финансовые данные
work	WorkGenerator	Рабочие данные
vehicle	VehicleGenerator	Транспортные данные
family	FamilyGenerator	Семейные данные

Примеры доступа:

generator = FakerRussia()

# Биографические данные
full_name = generator.bio.full_name
age = generator.bio.age
birth_date = generator.bio.year

# Адресные данные
region = generator.address.region
city = generator.address.city
registration = generator.address.registration_address

# Контактные данные
phone = generator.contact.phone
email = generator.contact.email

# Документальные данные
inn = generator.document.inn
snils = generator.document.snils

# Финансовые данные
salary = generator.finance.salary
cards_count = generator.finance.number_cards

# Рабочие данные
job = generator.work.job
experience = generator.work.work_experience

# Транспортные данные
car = generator.vehicle.car
plate = generator.vehicle.car_registration_number

# Семейные данные
marital_status = generator.family.marital_status
children = generator.family.children_count

Работа со списковыми значениями

Некоторые свойства возвращают списки. Для удобства вывода предусмотрен параметр visualization:

generator = FakerRussia()

# Возвращает список Python
vaccinations_list = generator.bio.vaccinations()
# Пример: ['Гепатит B', 'Корь', 'Грипп']

# Возвращает строку с элементами через запятую
vaccinations_str = generator.bio.vaccinations(visualization=True)
# Пример: "Гепатит B, Корь, Грипп"

Аналогично работают следующие методы:

Метод	Класс	Описание
vaccinations()	BioGenerator	Список прививок
social_networks()	ContactGenerator	Список социальных сетей
administrative_violations()	DocumentGenerator	Список нарушений
bank()	FinanceGenerator	Список банков
bank_card()	FinanceGenerator	Список номеров карт
cvv_cvc()	FinanceGenerator	Список CVV/CVC кодов
card_type()	FinanceGenerator	Список типов карт
validity_period()	FinanceGenerator	Список сроков действия
inn_bank()	FinanceGenerator	Список ИНН банков
kpp_bank()	FinanceGenerator	Список КПП банков
diseases()	WorkGenerator	Список заболеваний
bad_habits()	WorkGenerator	Список вредных привычек
hobby()	WorkGenerator	Список хобби
car_condition_type()	VehicleGenerator	Список повреждений
children_names()	FamilyGenerator	Список имён детей

Сброс данных

Метод reset() очищает все сгенерированные данные и позволяет сгенерировать новый набор:

generator = FakerRussia()

# Первая генерация
print(generator)

# Сброс всех данных
generator.reset()

# Вторая генерация (новый набор данных)
print(generator)

Сохранение результата

Полученные данные могут быть сохранены в файл или базу данных:

generator = FakerRussia()

# Сохранение в текстовый файл
with open('person_profile.txt', 'w', encoding='utf-8') as f:
    f.write(str(generator))

# Сохранение в JSON
import json

profile = {
    'bio': {
        'full_name': generator.bio.full_name,
        'age': generator.bio.age,
        'gender': generator.bio.gender
    },
    'address': {
        'region': generator.address.region,
        'city': generator.address.city
    }
}

with open('person_profile.json', 'w', encoding='utf-8') as f:
    json.dump(profile, f, ensure_ascii=False, indent=2)

Примеры сгенерированных данных

Биографические данные

ФИО: Иванов Иван Иванович
Год рождения: 15.05.1990
Возраст: 34
Пол: male
ФИО отца: Иванов Иван Петрович
ФИО матери: Иванова (девичья фамилия - Петрова) Мария Ивановна
Национальность: Русский
Рост: 178
Вес: 82
Индекс массы тела: 25.87
Знак зодиака: Телец
Поколение: Миллениалы
Группа крови: A (II) Rh+
Религия: Православие
Телосложение: Нормальное
Цвет глаз: Карие
Цвет волос: Русые
Образование: Высшее
Средний балл школьного аттестата: 4.32
Текущее место обучения: Московский государственный университет
Размер обуви: 43
Зрение: -2.5
Уровень слуха: Нормальный
Инвалидность: Отсутствует
Пульс в покое: 72
Прививки (вакцинации): Гепатит B, Корь, Грипп
Военная категория годности: Б

Адресные данные

Регион: Московская область
Город: Москва
Улица: Тверская
Адрес регистрации: 101000, Московская область - Город Москва - Тверская д. 25 корп. 3
Фактический адрес: 101000, Московская область - Город Москва - Тверская д. 25 корп. 3
Тип жилья: Квартира

Контактные данные

Номер телефона: [phone]
Мобильный оператор: МТС
Модель телефона: iPhone 14 Pro
Email: [e-mail]
Социальные сети: ВКонтакте, Telegram, WhatsApp
IPv4: 192.168.1.1
IPv6: 2001:0db8:85a3:0000:0000:8a2e:0370:7334
Игровая платформа: PlayStation 5

Документальные данные

ИНН: 770123456789
СНИЛС: 123-456-789 01
Паспорт: 45 01 123456
Дата выдачи паспорта: 15.05.2014
Код подразделения паспорта: 770-001
ЕНП: 2770123456789012
Административные нарушения: Превышение скорости, Неиспользование ремня безопасности

Финансовые данные

БИК: 044525974
Количество карт: 2
Банки: Сбербанк, Тинькофф
ИНН банков: 7707083893, 7710140679
КПП банков: 773601001, 771001001
Номера карт: 4276123456789012, 5213245678901234
CVV/CVC: 123, 456
Типы карт: Debit, Credit
Сроки действия: 12/25, 08/26
Зарплата: 85000
Банкротство: False

Рабочие данные

Работает ли человек: True
Работа: Программист
Стаж работы: 12
Дата начала работы: 15.08.2012
Уровень работы: Эксперт
Место работы: ООО 'Технологии будущего'
Болезни: Остеохондроз, Гастрит
Вредные привычки: Кофеиновая зависимость
Хобби: Чтение, Спорт, Путешествия
Уровень английского языка: Upper Intermediate
Рабочий график: Полный день

Транспортные данные

Машина: Toyota Camry
Тип кузова: Седан
Тип двигателя: Бензиновый
Объем двигателя: 2.5
Тип трансмиссии: Автоматическая
Привод: Передний
Мощность двигателя: 181
Номер машины: А123БВ 77
Повреждение: В идеальном состоянии
Цвет: Серебристый
Год выпуска: 2020

Семейные данные

Семейный статус: Женат
ФИО супруга: Иванова Анна Петровна
Возраст супруга: 32
Дата бракосочетания: 15.05.2015
Лет в браке: 9
Количество детей: 2
Имена детей: Сергей, Екатерина
Живёт ли с родителями: False
Количество членов семьи: 4

Особенности реализации

Алгоритмы генерации

1. ИНН: 12-значный номер с двумя контрольными цифрами, вычисляемыми по весовым коэффициентам. Первые 4 цифры соответствуют коду региона по месту жительства.

2. СНИЛС: 11-значный номер с контрольным числом, вычисляемым как остаток от деления суммы произведений цифр на весовые коэффициенты на 101.

3. Номера банковских карт: 16-значные номера с контрольной суммой по алгоритму Луна, обеспечивающим формальную корректность номера.

4. ЕНП: 16-значный номер полиса ОМС с контрольной суммой по алгоритму Луна, первая цифра фиксирована как 2.

5. Дата выдачи паспорта: Определяется на основании возраста: в 14 лет, 20 лет или 45 лет в зависимости от текущего возраста.

6. Зарплата: Определяется на основании должности и уровня квалификации. Каждая должность имеет диапазоны зарплат для разных уровней опыта.

7. Количество детей: Зависит от стажа брака: при стаже 1-5 лет — 1-3 ребёнка, при стаже 6-15 лет — 4-6 детей, при большем стаже — 1-10 детей.

8. Возраст супруга: Может совпадать с возрастом человека, отличаться на небольшую величину или быть значительно больше/меньше.

Вероятностные механизмы

Библиотека использует вероятностные подходы для повышения реалистичности:

Свойство	Вероятность	Описание
Фактический адрес	30%	Совпадает с адресом регистрации
Наличие автомобиля	50%	Для лиц старше 16 лет
Наличие банковских карт	50%	Для лиц старше установленного возраста
Наличие прививок	70%	Вероятность наличия хотя бы одной прививки
Наличие вредных привычек	50%	Для лиц старше 10 лет
Наличие инвалидности	30%	Вероятность присвоения группы инвалидности
Идеальное состояние авто	50%	Вероятность отсутствия повреждений
Проживание с родителями	50%	При выполнении условий (возраст < 40, зарплата < 65000, отсутствие супруга)

Расширение функциональности

Модификация существующих данных

Все исходные данные хранятся в JSON-файлах в директории a__data. Для изменения генерируемых данных достаточно отредактировать соответствующий файл. Формат данных должен соответствовать существующей структуре.

Пример структуры файла a__data/car/cars.json:

{
    "CARS": {
        "Toyota Camry": {
            "body_type": "Седан",
            "engine_type": "Бензиновый",
            "engine_capacity": 2.5,
            "transmission_type": "Автоматическая",
            "drive_type": "Передний",
            "engine_power": 181
        }
    }
}

Добавление нового генератора

Для создания собственного генератора необходимо унаследоваться от BaseGenerator:

import random
from FakerRussia.b_h__base_generator import BaseGenerator
from FakerRussia.b__additional_algorithms.a_a__handle_errors import handle_errors

class CustomGenerator(BaseGenerator):
    """
    Пользовательский генератор для расширения функциональности
    """
    
    def __init__(self):
        super().__init__()
        self._data = None
        self._load_custom_data()
    
    def _load_custom_data(self):
        """
        Загрузка пользовательских данных из JSON-файла
        """
        data = self._load_json('a__data/custom/custom_data.json')
        self.CUSTOM_DATA = data.get("CUSTOM_DATA", [])
    
    @property
    @handle_errors
    def custom_property(self) -> str:
        """
        Получение пользовательского свойства
        """
        if self._data is None:
            self._data = random.choice(self.CUSTOM_DATA)
        return self._data
    
    def reset(self):
        """
        Сброс сгенерированных данных
        """
        self._data = None
        return "Пользовательские данные сброшены"

Обработка ошибок

Библиотека использует декоратор @handle_errors, который обеспечивает:

• перехват исключений при выполнении методов генерации;
• логирование ошибок;
• возврат безопасного значения по умолчанию.

В случае возникновения ошибки при генерации данных метод вернёт значение по умолчанию, определённое в базовом классе.

Ограничения и допущения

1. Вымышленность данных: Все генерируемые данные являются вымышленными и не соответствуют реальным людям, организациям или документам.

2. Недействительность идентификаторов: Номера документов, телефонов, банковских карт и другие идентификаторы генерируются алгоритмически и не являются действительными для использования в реальных системах.

3. Вероятностный характер: Некоторые характеристики генерируются с использованием вероятностных механизмов, что может приводить к различным результатам при повторных генерациях.

4. Возрастные ограничения: Некоторые свойства доступны только для определённых возрастных групп (например, паспортные данные — с 14 лет).

5. Локализация: Библиотека ориентирована исключительно на российскую специфику и не предназначена для генерации данных других стран.

Лицензия

Проект распространяется под лицензией MIT.