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 install russiafaker==2.0.0Ссылка на PyPI: https://pypi.org/project/russiafaker/2.0.0/
git clone https://github.com/waratecs123/FakerRussia.git
cd FakerRussia
pip install .https://github.com/waratecs123/FakerRussia/releases/tag/FakerRussiarussiafaker/
├── __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 russiafaker import FakerRussia
# Создание экземпляра генератора
generator = FakerRussia()Параметр my_gender принимает значения "мужской" или "женский":
from russiafaker import FakerRussia
# Генерация данных для мужчины
male_generator = FakerRussia(my_gender="мужской")
# Генерация данных для женщины
female_generator = FakerRussia(my_gender="женский")При отсутствии параметра пол определяется случайным образом.
from russiafaker import FakerRussia
generator = FakerRussia()
person = generator.generate_person()
# Вывод краткой информации
print(person)
# Или полный вывод всех данных
print(generator)Каждая категория данных доступна через соответствующий атрибут:
| Атрибут | Класс генератора | Описание |
|---|---|---|
bio |
BioGenerator | Биографические данные |
address |
AddressGenerator | Адресные данные |
contact |
ContactGenerator | Контактные данные |
document |
DocumentGenerator | Документальные данные |
finance |
FinanceGenerator | Финансовые данные |
work |
WorkGenerator | Рабочие данные |
vehicle |
VehicleGenerator | Транспортные данные |
family |
FamilyGenerator | Семейные данные |
Примеры доступа:
from russiafaker import FakerRussia
generator = FakerRussia()
person = generator.generate_person()
# Биографические данные (через объект PersonData)
full_name = person.full_name
age = person.age
birth_date = person.birth_date
# Или через прямой доступ к генераторам
full_name_direct = generator.bio.full_name
age_direct = generator.bio.age
# Адресные данные
region = person.region
city = person.city
registration = person.registration_address
# Контактные данные
phone = person.phone
email = person.email
# Документальные данные
inn = person.inn
snils = person.snils
# Финансовые данные
salary = person.salary
cards_count = person.number_cards
# Рабочие данные
job = person.job
experience = person.work_experience
# Транспортные данные
car = person.car
plate = person.car_reg_number
# Семейные данные
marital_status = person.marital_status
children = person.children_countfrom russiafaker import FakerRussia
generator = FakerRussia()
person = generator.generate_person()
# Преобразование всех данных в словарь
person_dict = person.to_dict()
print(person_dict)Некоторые свойства возвращают списки. Для удобства вывода предусмотрен параметр visualization:
from russiafaker import FakerRussia
generator = FakerRussia()
person = generator.generate_person()
# Возвращает список Python
vaccinations_list = person.vaccinations
# Пример: ['Гепатит B', 'Корь', 'Грипп']
# Для методов генераторов можно использовать параметр visualization
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() очищает все сгенерированные данные и позволяет сгенерировать новый набор:
from russiafaker import FakerRussia
generator = FakerRussia()
# Первая генерация
person1 = generator.generate_person()
print(person1)
# Сброс всех данных
generator.reset()
# Вторая генерация (новый набор данных)
person2 = generator.generate_person()
print(person2)Полученные данные могут быть сохранены в файл или базу данных:
from russiafaker import FakerRussia
import json
generator = FakerRussia()
person = generator.generate_person()
# Сохранение в текстовый файл
with open('person_profile.txt', 'w', encoding='utf-8') as f:
f.write(str(person))
# Сохранение в JSON
with open('person_profile.json', 'w', encoding='utf-8') as f:
json.dump(person.to_dict(), f, ensure_ascii=False, indent=2)from russiafaker import FakerRussia
generator = FakerRussia()
people = []
for i in range(10):
person = generator.generate_person()
people.append(person)
generator.reset() # Сброс для следующего человека
for person in people:
print(f"{person.full_name}, {person.age} лет, {person.city}")ФИО: Иванов Иван Иванович
Год рождения: 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
Тип жилья: Квартира
Номер телефона: +7 (495) 123-45-67
Мобильный оператор: МТС
Модель телефона: iPhone 14 Pro
Email: ivan.ivanov@mail.ru
Социальные сети: ВКонтакте, 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
-
ИНН: 12-значный номер с двумя контрольными цифрами, вычисляемыми по весовым коэффициентам. Первые 4 цифры соответствуют коду региона по месту жительства.
-
СНИЛС: 11-значный номер с контрольным числом, вычисляемым как остаток от деления суммы произведений цифр на весовые коэффициенты на 101.
-
Номера банковских карт: 16-значные номера с контрольной суммой по алгоритму Луна, обеспечивающим формальную корректность номера.
-
ЕНП: 16-значный номер полиса ОМС с контрольной суммой по алгоритму Луна, первая цифра фиксирована как 2.
-
Дата выдачи паспорта: Определяется на основании возраста: в 14 лет, 20 лет или 45 лет в зависимости от текущего возраста.
-
Зарплата: Определяется на основании должности и уровня квалификации. Каждая должность имеет диапазоны зарплат для разных уровней опыта.
-
Количество детей: Зависит от стажа брака: при стаже 1-5 лет — 1-3 ребёнка, при стаже 6-15 лет — 4-6 детей, при большем стаже — 1-10 детей.
-
Возраст супруга: Может совпадать с возрастом человека, отличаться на небольшую величину или быть значительно больше/меньше.
Библиотека использует вероятностные подходы для повышения реалистичности:
| Свойство | Вероятность | Описание |
|---|---|---|
| Фактический адрес | 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 russiafaker.b_h__base_generator import BaseGenerator
from russiafaker.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, который обеспечивает:
- перехват исключений при выполнении методов генерации;
- логирование ошибок;
- возврат безопасного значения по умолчанию.
В случае возникновения ошибки при генерации данных метод вернёт значение по умолчанию, определённое в базовом классе.
-
Вымышленность данных: Все генерируемые данные являются вымышленными и не соответствуют реальным людям, организациям или документам.
-
Недействительность идентификаторов: Номера документов, телефонов, банковских карт и другие идентификаторы генерируются алгоритмически и не являются действительными для использования в реальных системах.
-
Вероятностный характер: Некоторые характеристики генерируются с использованием вероятностных механизмов, что может приводить к различным результатам при повторных генерациях.
-
Возрастные ограничения: Некоторые свойства доступны только для определённых возрастных групп (например, паспортные данные — с 14 лет).
-
Локализация: Библиотека ориентирована исключительно на российскую специфику и не предназначена для генерации данных других стран.
Проект распространяется под лицензией MIT.