### Setup local development environment for russiannames

Source: https://github.com/datacoon/russiannames/blob/master/CONTRIBUTING.rst

Commands to create a virtual environment, navigate to the project directory, and install the package in development mode.

```bash
$ mkvirtualenv russiannames
$ cd russiannames/
$ python setup.py develop
```

--------------------------------

### Install russiannames Python Library

Source: https://github.com/datacoon/russiannames/blob/master/README.md

Instructions for installing the russiannames Python library using pip or by building from source. It also outlines the steps to set up the MongoDB database required by the library.

```bash
pip install russiannames
```

```bash
python setup.py install
```

```bash
mongorestore --db names /path/to/names_data
```

--------------------------------

### Command Line Parsing

Source: https://context7.com/datacoon/russiannames/llms.txt

Examples of parsing single names and abbreviated names directly from the command line using the `rusnames.py` script.

```APIDOC
## Command Line Parsing

### Description
Parse a single name or an abbreviated name from the command line.

### Usage
```bash
# Parse a full name
python bin/rusnames.py "Исинбаев Иван Моисеевич"

# Output:
# {'format': 'sfm',
#  'fn': 'Иван',
#  'gender': 'm',
#  'mn': 'Моисеевич',
#  'parsed': True,
#  'sn': 'Исинбаев',
#  'text': 'Исинбаев Иван Моисеевич'}

# Parse an abbreviated name
python bin/rusnames.py "Акимов Б.В."

# Output:
# {'format': 'sFM', 'sn': 'Акимов', 'fn_s': 'Б', 'mn_s': 'В', ...}
```
```

--------------------------------

### Run tests and quality checks

Source: https://github.com/datacoon/russiannames/blob/master/CONTRIBUTING.rst

Commands to install test dependencies, run flake8 for linting, execute tests with nosetests, and run tox for multi-version testing.

```bash
$ pip install -r tests/requirements.txt
$ flake8 russiannames tests
$ nosetests
$ tox
```

--------------------------------

### Parse Russian Names and Identify Gender

Source: https://github.com/datacoon/russiannames/blob/master/docs/index.md

Demonstrates how to initialize the NamesParser and extract structured information from a full name string, including gender and name components.

```python
from russiannames.parser import NamesParser
parser = NamesParser()
# Parse full name
result = parser.parse('Нигматуллин Ринат Ахметович')
# Parse abbreviated name
result_abbr = parser.parse('Петрова C.Я.')
```

--------------------------------

### Supported Name Formats

Source: https://context7.com/datacoon/russiannames/llms.txt

Demonstrates the various Russian name formats supported by the `NamesParser` class, from single components to full names.

```APIDOC
## Supported Name Formats

### Description
The library automatically detects and parses 12 different Russian name writing formats.

### Usage
```python
from russiannames.parser import NamesParser

parser = NamesParser()

# Format 'f' - First name only
parser.parse('Ольга')
# Returns: {'format': 'f', 'fn': 'Ольга', ...}

# Format 's' - Surname only
parser.parse('Петров')
# Returns: {'format': 's', 'sn': 'Петров', ...}

# Format 'Fs' - Initial + Surname
parser.parse('О. Сидорова')
# Returns: {'format': 'Fs', 'fn_s': 'О', 'sn': 'Сидорова', ...}

# Format 'sF' - Surname + Initial
parser.parse('Николаев С.')
# Returns: {'format': 'sF', 'sn': 'Николаев', 'fn_s': 'С', ...}

# Format 'sf' - Surname + First name
parser.parse('Абрамов Семен')
# Returns: {'format': 'sf', 'sn': 'Абрамов', 'fn': 'Семен', ...}

# Format 'fs' - First name + Surname
parser.parse('Соня Камиуллина')
# Returns: {'format': 'fs', 'fn': 'Соня', 'sn': 'Камиуллина', ...}

# Format 'fm' - First name + Middle name
parser.parse('Иван Петрович')
# Returns: {'format': 'fm', 'fn': 'Иван', 'mn': 'Петрович', ...}

# Format 'SFM' - All initials
parser.parse('М.Д.М.')
# Returns: {'format': 'SFM', 'sn_s': 'М', 'fn_s': 'Д', 'mn_s': 'М', ...}

# Format 'FMs' - Initials + Surname
parser.parse('А.Н. Егорова')
# Returns: {'format': 'FMs', 'fn_s': 'А', 'mn_s': 'Н', 'sn': 'Егорова', ...}

# Format 'sFM' - Surname + Initials
parser.parse('Николаенко С.П.')
# Returns: {'format': 'sFM', 'sn': 'Николаенко', 'fn_s': 'С', 'mn_s': 'П', ...}

# Format 'sfM' - Surname + First name + Initial
parser.parse('Петракова Зинаида М.')
# Returns: {'format': 'sfM', 'sn': 'Петракова', 'fn': 'Зинаида', 'mn_s': 'М', ...}

# Format 'sfm' - Full: Surname + First name + Middle name
parser.parse('Казаков Ринат Артурович')
# Returns: {'format': 'sfm', 'sn': 'Казаков', 'fn': 'Ринат', 'mn': 'Артурович', ...}

# Format 'fms' - Full: First name + Middle name + Surname
parser.parse('Светлана Архиповна Волкова')
# Returns: {'format': 'fms', 'fn': 'Светлана', 'mn': 'Архиповна', 'sn': 'Волкова', ...}
```
```

--------------------------------

### Create a new development branch

Source: https://github.com/datacoon/russiannames/blob/master/CONTRIBUTING.rst

Command to create and switch to a new git branch for implementing a specific bug fix or feature.

```bash
$ git checkout -b name-of-your-bugfix-or-feature
```

--------------------------------

### Parse Russian Names via Command Line

Source: https://context7.com/datacoon/russiannames/llms.txt

Demonstrates how to use the rusnames.py script from the command line to parse full names or abbreviated names into structured JSON format.

```bash
python bin/rusnames.py "Исинбаев Иван Моисеевич"
python bin/rusnames.py "Акимов Б.В."
```

--------------------------------

### Commit and push changes

Source: https://github.com/datacoon/russiannames/blob/master/CONTRIBUTING.rst

Standard git commands to stage, commit, and push local changes to a remote repository.

```bash
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
```

--------------------------------

### Ethnic Identification (Experimental)

Source: https://github.com/datacoon/russiannames/blob/master/docs/index.md

This snippet shows how to use the NamesParser to perform experimental ethnic identification based on surname, first name, and middle name.

```APIDOC
## Ethnic Identification (Experimental)

### Description
Parses surname, first name, and middle name to identify the person's ethnic affiliation. This feature is experimental.

### Method
Python Function Call

### Endpoint
N/A (Python Library)

### Parameters
None

### Request Example
```python
from russiannames.parser import NamesParser
parser = NamesParser()
parser.classify('Нигматуллин', 'Ринат', 'Ахметович')
```

### Response
#### Success Response (200)
- **ethnics** (array of strings) - A list of identified ethnic affiliations (e.g., ['tur']).
- **gender** (string) - The identified gender ('m', 'f', 'u', or '-').

#### Response Example
```json
{
  "ethnics": ["tur"],
  "gender": "m"
}
```

#### Response Example 2
```json
{
  "ethnics": ["slav"],
  "gender": "f"
}
```
```

--------------------------------

### Parse Russian Name Formats in Python

Source: https://context7.com/datacoon/russiannames/llms.txt

Shows how to use the NamesParser class to identify and parse 12 distinct Russian name writing formats, ranging from single names to full name-middle-surname combinations.

```python
from russiannames.parser import NamesParser
parser = NamesParser()
parser.parse('Ольга')
parser.parse('Петров')
parser.parse('О. Сидорова')
parser.parse('Николаев С.')
parser.parse('Абрамов Семен')
parser.parse('Соня Камиуллина')
parser.parse('Иван Петрович')
parser.parse('М.Д.М.')
parser.parse('А.Н. Егорова')
parser.parse('Николаенко С.П.')
parser.parse('Петракова Зинаида М.')
parser.parse('Казаков Ринат Артурович')
parser.parse('Светлана Архиповна Волкова')
```

--------------------------------

### Ethnic Identification with NamesParser

Source: https://github.com/datacoon/russiannames/blob/master/README.md

Shows how to use the NamesParser's classify method to identify the ethnic affiliation and gender based on provided surname, first name, and middle name. This feature is experimental.

```python
from russiannames.parser import NamesParser
parser = NamesParser()
result = parser.classify('Нигматуллин', 'Ринат', 'Ахметович')
print(result)
```

```python
from russiannames.parser import NamesParser
parser = NamesParser()
result = parser.classify('Алексеева', 'Ольга', 'Ивановна')
print(result)
```

--------------------------------

### Classify Ethnicity with NamesParser

Source: https://context7.com/datacoon/russiannames/llms.txt

The classify() method analyzes name components (surname, first name, middle name) to determine ethnic affiliation and gender. It uses morphological patterns and database lookups to categorize names into one of 9 supported ethnic groups.

```python
from russiannames.parser import NamesParser

parser = NamesParser()

# Classify a Turkic name
result = parser.classify('Нигматуллин', 'Ринат', 'Ахметович')

# Classify a Slavic name
result = parser.classify('Алексеева', 'Ольга', 'Ивановна')
```

--------------------------------

### Parse Name and Identify Gender with NamesParser

Source: https://github.com/datacoon/russiannames/blob/master/README.md

Demonstrates how to use the NamesParser class from the russiannames library to parse a full Russian name and extract details like format, surname, first name, middle name, and gender. The gender can be 'm' (male), 'f' (female), 'u' (unknown), or '-' (unidentifiable).

```python
from russiannames.parser import NamesParser
parser = NamesParser()
result = parser.parse('Нигматуллин Ринат Ахметович')
print(result)
```

```python
from russiannames.parser import NamesParser
parser = NamesParser()
result = parser.parse('Петрова C.Я.')
print(result)
```

--------------------------------

### Manage Database with NamesProcessor

Source: https://context7.com/datacoon/russiannames/llms.txt

The NamesProcessor class handles administrative tasks for the MongoDB backend, including loading data from TSV files, performing batch gender recognition, mapping ethnic affiliations, and generating database statistics.

```python
from russiannames.processor import NamesProcessor

processor = NamesProcessor()

# Load data and process
processor.load_data(cname='surnames', filename='surnames.tsv', schema={'1': {'name': 'text', 'type': 'string'}, '2': {'name': 'count', 'type': 'int'}})
processor.midnames_gender_recognize()
processor.map_national_surnames()
processor.stats()
```

--------------------------------

### Parse Name and Identify Gender

Source: https://github.com/datacoon/russiannames/blob/master/docs/index.md

This snippet demonstrates how to use the NamesParser to parse a full Russian name and identify its components (surname, first name, middle name) along with the person's gender.

```APIDOC
## Parse Name and Identify Gender

### Description
Parses a full Russian name and returns the identified format, surname, first name, middle name, and gender.

### Method
Python Function Call

### Endpoint
N/A (Python Library)

### Parameters
None

### Request Example
```python
from russiannames.parser import NamesParser
parser = NamesParser()
parser.parse('Нигматуллин Ринат Ахметович')
```

### Response
#### Success Response (200)
- **format** (string) - The identified format of the name.
- **sn** (string) - The surname.
- **fn** (string) - The first name.
- **mn** (string) - The middle name (patronymic).
- **gender** (string) - The identified gender ('m', 'f', 'u', or '-').
- **text** (string) - The original input text.
- **parsed** (boolean) - Indicates if the name was successfully parsed.

#### Response Example
```json
{
  "format": "sfm",
  "sn": "Нигматуллин",
  "fn": "Ринат",
  "mn": "Ахметович",
  "gender": "m",
  "text": "Нигматуллин Ринат Ахметович",
  "parsed": true
}
```

#### Response Example 2
```json
{
  "format": "sFM",
  "sn": "Петрова",
  "fn_s": "C",
  "mn_s": "Я",
  "gender": "f",
  "text": "Петрова C.Я.",
  "parsed": true
}
```
```

--------------------------------

### Access Gender and Ethnic Constants

Source: https://context7.com/datacoon/russiannames/llms.txt

Provides access to the library's internal constants for gender identification and ethnic classification rules used for pattern matching.

```python
from russiannames.consts import (
    GENDER_MALE,
    GENDER_FEMALE,
    GENDER_BOTH,
    SURNAME_POSTRULES,
    MIDDLENAME_POSTRULES,
    SURN_NATIONAL_RULES
)
```

--------------------------------

### Gender and Ethnic Constants

Source: https://context7.com/datacoon/russiannames/llms.txt

Details the constants provided by the library for gender identification and ethnic classification rules.

```APIDOC
## Gender and Ethnic Constants

### Description
The library defines constants for gender identification and ethnic classification rules used internally for pattern matching.

### Usage
```python
from russiannames.consts import (
    GENDER_MALE,
    GENDER_FEMALE,
    GENDER_BOTH,
    SURNAME_POSTRULES,
    MIDDLENAME_POSTRULES,
    SURN_NATIONAL_RULES,
)

# Surname suffix rules for gender (examples):
# -ов/-ев/-ёв → Male
# -ова/-ева/-ёва → Female
# -ин/-ын → Male
# -ина/-ына → Female
# -ский → Male
# -енко → Universal
# -швили/-дзе → Universal (Georgian)

# Ethnic identification rules (suffix → ethnic group):
# -ян/-янц → Armenian
# -швили/-дзе → Georgian
# -берг/-бург/-ельд → German
# -иди/-ади → Greek
# -улла/-алла → Arabic
```
```

--------------------------------

### Processor Utility Functions

Source: https://github.com/datacoon/russiannames/blob/master/docs/modules.md

Utility functions for gender guessing and name recognition within the processor module.

```APIDOC
## Processor Utility Functions

### Description
Provides standalone functions for guessing gender and recognizing name patterns.

### Functions

#### `guess_by_rules(name)`
Guesses name components based on predefined rules.

- **Parameters**:
  - `name` (str) - The name string to analyze.

#### `guess_gender_by_name(name)`
Guesses the gender associated with a given first name.

- **Parameters**:
  - `name` (str) - The first name.

#### `guess_gender_by_surname(surname)`
Guesses the gender associated with a given surname.

- **Parameters**:
  - `surname` (str) - The surname.

#### `guess_name_to_middlename(name)`
Guesses the corresponding middle name for a given first name.

- **Parameters**:
  - `name` (str) - The first name.

#### `name_recognize(name)`
Recognizes patterns within a name string.

- **Parameters**:
  - `name` (str) - The name string to recognize.

#### `norm_name(name)`
Normalizes a name string, applying standard formatting.

- **Parameters**:
  - `name` (str) - The name string to normalize.

#### `use_rule(rule, name)`
Applies a specific rule to a name.

- **Parameters**:
  - `rule` (object) - The rule to apply.
  - `name` (str) - The name string to apply the rule to.
```

--------------------------------

### NamesParser API

Source: https://github.com/datacoon/russiannames/blob/master/docs/modules.md

Provides methods for parsing and classifying names using predefined rules and data.

```APIDOC
## NamesParser Class

### Description
Represents a parser for Russian names, capable of classifying and normalizing name components.

### Methods

#### `classify(name)`
Classifies a given name string.

- **Parameters**:
  - `name` (str) - The name string to classify.

#### `parse(name)`
Parses a full name into its components (first name, middle name, last name).

- **Parameters**:
  - `name` (str) - The full name string to parse.

### Request Example
```json
{
  "name": "Иван Петрович Сидоров"
}
```

### Response Example
```json
{
  "parsed_name": {
    "first_name": "Иван",
    "middle_name": "Петрович",
    "last_name": "Сидоров"
  }
}
```
```

--------------------------------

### Parser Utility Functions

Source: https://github.com/datacoon/russiannames/blob/master/docs/modules.md

Utility functions for name normalization and rule-based guessing within the parser module.

```APIDOC
## Parser Utility Functions

### Description
Provides standalone functions for name normalization and rule-based name guessing.

### Functions

#### `guess_by_rules(name)`
Guesses name components based on predefined rules.

- **Parameters**:
  - `name` (str) - The name string to analyze.

#### `norm_name(name)`
Normalizes a name string, applying standard formatting.

- **Parameters**:
  - `name` (str) - The name string to normalize.

#### `use_rule(rule, name)`
Applies a specific rule to a name.

- **Parameters**:
  - `rule` (object) - The rule to apply.
  - `name` (str) - The name string to apply the rule to.
```

--------------------------------

### NamesProcessor API

Source: https://github.com/datacoon/russiannames/blob/master/docs/modules.md

Handles advanced processing of names, including clustering, enrichment, and validation.

```APIDOC
## NamesProcessor Class

### Description
Manages complex name processing tasks, such as data loading, ethnic mapping, and gender recognition.

### Methods

#### `cleanup(names)`
Cleans a list of names.

- **Parameters**:
  - `names` (list) - A list of name strings.

#### `cluster_surnames(surnames)`
Clusters similar surnames together.

- **Parameters**:
  - `surnames` (list) - A list of surname strings.

#### `dump_midnames()`
Dumps processed middle names.

#### `dump_names()`
Dumps processed first names.

#### `dump_surnames()`
Dumps processed surnames.

#### `enrich_fullnames(fullnames)`
Enriches full names with additional information.

- **Parameters**:
  - `fullnames` (list) - A list of full name strings.

#### `enrich_surnames(surnames)`
Enriches surnames with additional information.

- **Parameters**:
  - `surnames` (list) - A list of surname strings.

#### `find_national_names(names)`
Finds national names from a given list.

- **Parameters**:
  - `names` (list) - A list of name strings.

#### `full_valid(fullname)`
Validates a full name.

- **Parameters**:
  - `fullname` (str) - The full name to validate.

#### `fullnames_map_gender(fullnames)`
Maps gender to full names.

- **Parameters**:
  - `fullnames` (list) - A list of full name strings.

#### `fullnames_parse(fullnames)`
Parses a list of full names.

- **Parameters**:
  - `fullnames` (list) - A list of full name strings.

#### `get_name_top()`
Retrieves the top names.

#### `import_new_names(names)`
Imports new names into the system.

- **Parameters**:
  - `names` (list) - A list of new name strings.

#### `load_data(filepath)`
Loads name data from a file.

- **Parameters**:
  - `filepath` (str) - The path to the data file.

#### `load_ethnic(filepath)`
Loads ethnic name data from a file.

- **Parameters**:
  - `filepath` (str) - The path to the ethnic data file.

#### `load_names(filepath)`
Loads name data from a file.

- **Parameters**:
  - `filepath` (str) - The path to the name data file.

#### `map_ethnic(names)`
Maps names to their ethnic origins.

- **Parameters**:
  - `names` (list) - A list of name strings.

#### `map_names_fullnames(names)`
Maps first names to full names.

- **Parameters**:
  - `names` (list) - A list of first name strings.

#### `map_names_midnames(names)`
Maps first names to middle names.

- **Parameters**:
  - `names` (list) - A list of first name strings.

#### `map_national(names)`
Maps names to their nationalities.

- **Parameters**:
  - `names` (list) - A list of name strings.

#### `map_national_surnames(surnames)`
Maps surnames to their national origins.

- **Parameters**:
  - `surnames` (list) - A list of surname strings.

#### `map_surnames_to_names(surnames)`
Maps surnames to corresponding first names.

- **Parameters**:
  - `surnames` (list) - A list of surname strings.

#### `midnames_gender_recognize(midnames)`
Recognizes gender from middle names.

- **Parameters**:
  - `midnames` (list) - A list of middle name strings.

#### `stats()`
Provides statistics on the loaded name data.

#### `surnames_gender_recognize(surnames)`
Recognizes gender from surnames.

- **Parameters**:
  - `surnames` (list) - A list of surname strings.

#### `validate(names)`
Validates a list of names.

- **Parameters**:
  - `names` (list) - A list of name strings.

#### `verify_names(names)`
Verifies the correctness of names.

- **Parameters**:
  - `names` (list) - A list of name strings.

### Request Example
```json
{
  "names": ["Иван", "Мария", "Петр"]
}
```

### Response Example
```json
{
  "processed_names": ["Ivan", "Maria", "Petr"]
}
```
```

--------------------------------

### Parse Russian Names with NamesParser

Source: https://context7.com/datacoon/russiannames/llms.txt

The parse() method identifies the format of a provided Russian name string and returns a dictionary containing parsed components, gender, and status. It supports various formats including full names, abbreviated initials, and partial name combinations.

```python
from russiannames.parser import NamesParser

parser = NamesParser()

# Parse full name
result = parser.parse('Нигматуллин Ринат Ахметович')

# Parse abbreviated name
result = parser.parse('Петрова C.Я.')

# Parse firstname middlename
result = parser.parse('Иван Петрович')
```

--------------------------------

### Perform Ethnic Identification

Source: https://github.com/datacoon/russiannames/blob/master/docs/index.md

Uses the NamesParser to classify the ethnic origin of a person based on their surname, first name, and patronymic. This feature is experimental and returns a list of identified ethnic keys.

```python
from russiannames.parser import NamesParser
parser = NamesParser()
# Classify by components
classification = parser.classify('Нигматуллин', 'Ринат', 'Ахметович')
```

--------------------------------

### NameReader API

Source: https://github.com/datacoon/russiannames/blob/master/docs/modules.md

Facilitates reading and processing name data from files and directories.

```APIDOC
## NameReader Class

### Description
Handles the reading and initial processing of name data from various sources.

### Methods

#### `process(filepath)`
Processes a single name data file.

- **Parameters**:
  - `filepath` (str) - The path to the name data file.

#### `process_dir(dirpath)`
Processes all name data files within a directory.

- **Parameters**:
  - `dirpath` (str) - The path to the directory containing name data files.

### Request Example
```json
{
  "filepath": "/path/to/names.txt"
}
```

### Response Example
```json
{
  "processed_count": 1500
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.