Russian Names

russiannames is a Python 3 library dedicated to parse Russian names, surnames and midnames, identify person gender by fullname and how name is written. It uses an embedded DuckDB engine over bundled Parquet datasets to speed-up name parsing — no database server required.

Documentation

Usage and API documentation lives in this README (see the sections below).

Installation

Install the library with pip:

pip install russiannames

The reference datasets (Parquet files) are bundled with the package, so no external database, download, or restore step is needed. NamesParser() works out of the box.

To use your own datasets, point the library at a directory containing names.parquet, surnames.parquet and midnames.parquet via either the NamesParser(data_dir=...) argument or the RUSSIANNAMES_DATA_DIR environment variable.

Features

Bundled Parquet datasets used for identification

• 375449 surnames - dataset: surnames.parquet
• 32134 first names - dataset: names.parquet
• 48274 midnames - dataset: midnames.parquet

Detailed database statistics by gender and collection

Supports 12 formats of Russian full names writing style

Supports names with following ethnics identification

9 ethnic types in names, surnames and middle names supported

Limitations

• very rare names, surnames or middlenames could be not parsed
• ethnic identification is still on early stage

Speed optimization

• datasets are loaded into an in-memory DuckDB database and indexed on the lookup key (text) for fast exact-match queries

Usage and Examples

Parse name and identify gender

Parses names and returns: format, surname, first name, middle name, parsed (True/False) and gender

>>> from russiannames.parser import NamesParser
>>> parser = NamesParser()
>>> parser.parse('Нигматуллин Ринат Ахметович')
{'format': 'sfm', 'sn': 'Нигматуллин', 'fn': 'Ринат', 'mn': 'Ахметович', 'gender': 'm', 'text': 'Нигматуллин Ринат Ахметович', 'parsed': True}
>>> parser.parse('Петрова C.Я.')
{'format': 'sFM', 'sn': 'Петрова', 'fn_s': 'C', 'mn_s': 'Я', 'gender': 'f', 'text': 'Петрова C.Я.', 'parsed': True}

Gender field could have one of following values:

• m: Male
• f: Female
• u: Unknown / unidentified
• -: Impossible to identify

Command line

rusnames "Нигматуллин Ринат Ахметович"

Ethnic identification (experimental)

Parses surname, first name and middle name and tries to identify person ethic affiliation of the person

>>> from russiannames.parser import NamesParser
>>> parser = NamesParser()
>>> parser.classify('Нигматуллин', 'Ринат', 'Ахметович')
{'ethnics': ['tur'], 'gender': 'm'}
>>> parser.classify('Алексеева', 'Ольга', 'Ивановна')
{'ethnics': ['slav'], 'gender': 'f'}

Supported languages

• Russian

Requirements

• Python 3.9+
• duckdb

Related projects

• Slavic names https://github.com/wb-08/SlavicNames - same data shipped as SQLite database