Python Human Name Parser

https://nameparser.readthedocs.io/en/latest/
Admin
A Python module that parses human names into their individual components including title, first,...
Tokens:37,609
Snippets:201
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Retrieve initials as a list

Source: https://nameparser.readthedocs.io/en/latest/_sources/usage.rst.txt

Use initials_list to get initials as a list, which remains unaffected by the initials_format configuration.

```python
>>> HumanName("Doe, John A. Kenneth, Jr.", initials_delimiter=";").initials_list()
["J", "A", "K", "D"]
```

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

### Configure Individual HumanName Instances

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Pass None as the second argument to HumanName to create an instance-specific configuration. Remember to re-parse the name after modifying instance configuration.

```python
>>> from nameparser import HumanName
>>> hn = HumanName("Dean Robert Johns", None)
>>> hn.C.titles.add('dean') 
SetManager(set([u'msgt', ..., u'adjutant']))
>>> hn.parse_full_name() # need to run this again after config changes
```

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

### Retrieve Initials as List

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Use initials_list() to get individual initials as a list of strings.

```python
>>> name = HumanName("Sir Bob Andrew Dole")
>>> name.initials_list()
["B", "A", "D"]
>>> name = HumanName("J. Doe")
>>> name.initials_list()
["J", "D"]
```

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

### Instantiate HumanName with Per-Instance Config

Source: https://nameparser.readthedocs.io/en/latest/customize.html

Pass `None` to the `constants` argument to create a HumanName instance with its own configuration, preventing shared configuration side effects.

```python
>>> from nameparser import HumanName
>>> instance = HumanName("Dean Robert Johns")
>>> instance.has_own_config
False
>>> instance.C.titles.add('dean')
SetManager({'right', ..., 'tax'})
```

```python
>>> other_instance = HumanName("Dean Robert Johns", None) # <-- pass None for per-instance config
>>> other_instance
<HumanName : [
  title: ''
  first: 'Dean'
  middle: 'Robert'
  last: 'Johns'
  suffix: ''
  nickname: ''
]>
>>> other_instance.has_own_config
True
```

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

### Configure Global Name Capitalization

Source: https://nameparser.readthedocs.io/en/latest/usage.html

Shows how to set global configuration options to automatically capitalize all names or to force capitalization of mixed-case names for all HumanName instances.

```python
>>> from nameparser.config import CONSTANTS
>>> CONSTANTS.capitalize_name = True
>>> name = HumanName("bob v. de la macdole-eisenhower phd")
>>> str(name)
'Bob V. de la MacDole-Eisenhower Ph.D.'
```

```python
>>> from nameparser.config import CONSTANTS
>>> CONSTANTS.force_mixed_case_capitalization = True
>>> name = HumanName('Shirley Maclaine')
>>> name.capitalize()
>>> str(name)
'Shirley MacLaine'
```

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

### Group Contiguous Integers in Python

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

This function identifies and returns the start and end indices of contiguous integer sequences within a list. It's useful for processing numerical data where consecutive numbers need to be grouped.

```python
def group_contiguous_integers(data):
    """
    return list of tuples containing first and last index
    position of contiguous numbers in a series
    """
    ranges = []
    for key, group in groupby(enumerate(data), lambda i: i[0] - i[1]):
        group = list(map(itemgetter(1), group))
        if len(group) > 1:
            ranges.append((group[0], group[-1]))
    return ranges
```

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

### HumanName Constructor

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Initializes a new HumanName instance. Parsing is triggered automatically if full_name is provided.

```APIDOC
## HumanName(full_name, ...)

### Description
Instantiates a HumanName object. If full_name is provided, it triggers the parsing process. Alternatively, individual name components can be passed as keywords to skip parsing.

### Parameters
- **full_name** (str) - Optional - The name string to be parsed.
- **constants** (constants) - Optional - A Constants instance.
- **encoding** (str) - Optional - Encoding of input.
- **first** (str) - Optional - First name.
- **middle** (str) - Optional - Middle name.
- **last** (str) - Optional - Last name.
- **title** (str) - Optional - Title or prenominal.
- **suffix** (str) - Optional - Suffix or postnominal.
- **nickname** (str) - Optional - Nicknames.
```

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

### Nameparser Configuration and Constants

Source: https://nameparser.readthedocs.io/en/latest/genindex.html

Details on configuration classes, constants, and modules within the nameparser library.

```APIDOC
## Nameparser Configuration

### Modules

- **nameparser.config**: Main configuration module.
- **nameparser.config.capitalization**: Module for capitalization rules.
- **nameparser.config.conjunctions**: Module for conjunctions.
- **nameparser.config.prefixes**: Module for name prefixes.
- **nameparser.config.regexes**: Module for regular expressions used in parsing.
- **nameparser.config.suffixes**: Module for name suffixes.
- **nameparser.config.titles**: Module for name titles.
- **nameparser.parser**: Module containing the HumanName class.

### Classes

- **nameparser.config.SetManager**: Manages sets of items.
- **nameparser.config.Constants**: Holds various constants used by the parser.
- **nameparser.config.TupleManager**: Manages tuple-related operations.

### Constants

- **CAPITALIZATION_EXCEPTIONS**: Exceptions for capitalization rules.
- **capitalize_name**: Constant related to name capitalization.
- **CONJUNCTIONS**: List of conjunctions.
- **CONSTANTS**: General constants module.
- **empty_attribute_default**: Default value for empty attributes.
- **FIRST_NAME_TITLES**: List of titles for first names.
- **force_mixed_case_capitalization**: Flag to force mixed-case capitalization.
- **initials_delimiter**: Delimiter for initials.
- **initials_format**: Format for initials.
- **PREFIXES**: List of name prefixes.
- **REGEXES**: Regular expressions used in parsing.
- **string_format**: String formatting constant.
- **SUFFIX_ACRONYMS**: List of suffix acronyms.
- **SUFFIX_NOT_ACRONYMS**: List of suffixes that are not acronyms.
- **TITLES**: List of titles.
```

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

### Initialize HumanName with Components in Python

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

Instantiate the HumanName class by providing individual name components directly. This bypasses the automatic parsing of a full name string.

```python
def __init__(self, full_name="", constants=CONSTANTS, encoding=DEFAULT_ENCODING,
                 string_format=None, initials_format=None, initials_delimiter=None,
                 first=None, middle=None, last=None, title=None, suffix=None,
                 nickname=None):
        self.C = constants
        if type(self.C) is not type(CONSTANTS):
            self.C = Constants()

        self.encoding = encoding
        self.string_format = string_format or self.C.string_format
        self.initials_format = initials_format or self.C.initials_format
        self.initials_delimiter = initials_delimiter or self.C.initials_delimiter
        if (first or middle or last or title or suffix or nickname):
            self.first = first
            self.middle = middle
            self.last = last
            self.title = title
            self.suffix = suffix
            self.nickname = nickname
            self.unparsable = False
        else:
            # full_name setter triggers the parse
            self.full_name = full_name
```

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

### Parse and Access Human Name Components

Source: https://nameparser.readthedocs.io/en/latest/usage.html

Demonstrates parsing a full name string and accessing individual components like title, first, middle, last, suffix, and surnames. Shows how to modify name components and view the updated full name.

```python
>>> from nameparser import HumanName
>>> name = HumanName("Dr. Juan Q. Xavier de la Vega III")
>>> name.title
'Dr.'
>>> name["title"]
'Dr.'
>>> name.first
'Juan'
>>> name.middle
'Q. Xavier'
>>> name.last
'de la Vega'
>>> name.suffix
'III'
>>> name.surnames
'Q. Xavier de la Vega'
```

```python
>>> name.full_name = "Juan Q. Xavier Velasquez y Garcia, Jr."
>>> name
<HumanName : [
    title: ''
    first: 'Juan'
    middle: 'Q. Xavier'
    last: 'Velasquez y Garcia'
    suffix: 'Jr.'
    nickname: ''
]>
```

```python
>>> name.middle = "Jason Alexander"
>>> name.middle
'Jason Alexander'
>>> name
<HumanName : [
    title: ''
    first: 'Juan'
    middle: 'Jason Alexander'
    last: 'Velasquez y Garcia'
    suffix: 'Jr.'
    nickname: ''
]>
```

```python
>>> name.middle = ["custom","values"]
>>> name.middle
'custom values'
```

```python
>>> name.full_name = 'Doe-Ray, Jonathan "John" A. Harris'
>>> name.as_dict()
{'last': 'Doe-Ray', 'suffix': '', 'title': '', 'middle': 'A. Harris', 'nickname': 'John', 'first': 'Jonathan'}
```

```python
>>> name.as_dict(False) # add False to hide keys with empty values
{'middle': 'A. Harris', 'nickname': 'John', 'last': 'Doe-Ray', 'first': 'Jonathan'}
```

```python
>>> name = HumanName("Dr. Juan Q. Xavier de la Vega III")
>>> name2 = HumanName("de la vega, dr. juan Q. xavier III")
>>> name == name2
True
```

```python
>>> len(name)
5
>>> list(name)
['Dr.', 'Juan', 'Q. Xavier', 'de la Vega', 'III']
```

```python
>>> name[1:-2]
['Juan', 'Q. Xavier', 'de la Vega']
```

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

### Instance-Level Configuration

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Customize the configuration for a specific HumanName instance by passing `None` during instantiation.

```APIDOC
## Instance-Level Configuration

### Description
Customize the configuration for an individual `HumanName` instance by passing `None` as the second argument during instantiation. This creates an independent configuration for that specific instance.

### Method
Instantiation with `None` for configuration, followed by modification of the instance's `C` attribute.

### Endpoint
`nameparser.HumanName(name, None)`

### Parameters
- **name** (string) - Required - The full name to parse.
- **None** (null) - Required - Indicates that a separate configuration should be used for this instance.

### Request Example
```python
from nameparser import HumanName
hn = HumanName("Dean Robert Johns", None)
hn.C.titles.add('dean')
hn.parse_full_name() # Re-parse after configuration change
```

### Response
#### Success Response (200)
Modifications to the instance's configuration are applied directly.

#### Response Example
```
SetManager(set([u'msgt', ..., u'adjutant']))
```

### Potential Gotcha
If `None` is not passed as the second argument during instantiation, `hn.C` will reference the module's global `CONSTANTS`, potentially leading to unexpected results.
```

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

### HumanName Class Initialization

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

Initializes a new HumanName instance. If a full_name string is provided, it triggers the parsing process. Alternatively, individual name components can be passed as keyword arguments to skip parsing.

```APIDOC
## HumanName.__init__

### Description
Initializes the HumanName object. If no components are provided, the full_name string is parsed into its constituent parts.

### Parameters
#### Request Body
- **full_name** (str) - Optional - The name string to be parsed.
- **constants** (Constants) - Optional - A configuration instance.
- **encoding** (str) - Optional - Encoding of the input.
- **first** (str) - Optional - First name.
- **middle** (str) - Optional - Middle name.
- **last** (str) - Optional - Last name.
- **title** (str) - Optional - The title or prenominal.
- **suffix** (str) - Optional - The suffix or postnominal.
- **nickname** (str) - Optional - Nicknames.
```

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

### Parse and Manipulate Names with HumanName

Source: https://nameparser.readthedocs.io/en/latest/_sources/usage.rst.txt

Demonstrates basic parsing, attribute access, updating name components, and dictionary conversion.

```python
>>> from nameparser import HumanName
>>> name = HumanName("Dr. Juan Q. Xavier de la Vega III")
>>> name.title
'Dr.'
>>> name["title"]
'Dr.'
>>> name.first
'Juan'
>>> name.middle
'Q. Xavier'
>>> name.last
'de la Vega'
>>> name.suffix
'III'
>>> name.surnames
'Q. Xavier de la Vega'
>>> name.full_name = "Juan Q. Xavier Velasquez y Garcia, Jr."
>>> name
<HumanName : [
	title: '' 
	first: 'Juan'
	middle: 'Q. Xavier'
	last: 'Velasquez y Garcia'
	suffix: 'Jr.'
	nickname: ''
]>
>>> name.middle = "Jason Alexander"
>>> name.middle
'Jason Alexander'
>>> name
<HumanName : [
    title: '' 
    first: 'Juan'
    middle: 'Jason Alexander'
    last: 'Velasquez y Garcia'
    suffix: 'Jr.'
    nickname: ''
]>
>>> name.middle = ["custom","values"]
>>> name.middle
'custom values'
>>> name.full_name = 'Doe-Ray, Jonathan "John" A. Harris'
>>> name.as_dict()
{'last': 'Doe-Ray', 'suffix': '', 'title': '', 'middle': 'A. Harris', 'nickname': 'John', 'first': 'Jonathan'}
>>> name.as_dict(False) # add False to hide keys with empty values
{'middle': 'A. Harris', 'nickname': 'John', 'last': 'Doe-Ray', 'first': 'Jonathan'}
>>> name = HumanName("Dr. Juan Q. Xavier de la Vega III")
>>> name2 = HumanName("de la vega, dr. juan Q. xavier III")
>>> name == name2
True
>>> len(name)
5
>>> list(name)
['Dr.', 'Juan', 'Q. Xavier', 'de la Vega', 'III']
>>> name[1:-2]
['Juan', 'Q. Xavier', 'de la Vega']
```

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

### Configure Individual HumanName Instances

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/config.html

Customize the configuration for a specific HumanName instance by passing None as the second argument during initialization. This prevents changes from affecting the module-level constants.

```python
>>> from nameparser import HumanName
>>> hn = HumanName("Dean Robert Johns", None)
>>> hn.C.titles.add('dean') # doctest: +ELLIPSIS
SetManager(set([u'msgt', ..., u'adjutant']))
>>> hn.parse_full_name() # need to run this again after config changes
```

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

### Verify Shared Configuration Impact

Source: https://nameparser.readthedocs.io/en/latest/customize.html

Demonstrates how changes to the shared configuration instance affect other HumanName instances.

```python
>>> other_instance = HumanName("Dean Robert Johns")
>>> other_instance # Dean parses as title
<HumanName : [
  title: 'Dean'
  first: 'Robert'
  middle: ''
  last: 'Johns'
  suffix: ''
  nickname: ''
]>
```

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

### SetManager Class

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Manages configuration variables, allowing additions and removals with normalization.

```APIDOC
## SetManager Class

### Description
Easily add and remove configuration variables per module or instance. This class is a subclass of `collections.abc.Set`.
It normalizes constants for comparison (lower case, no periods) when they are added or removed, and allows passing multiple string arguments to the `add()` and `remove()` methods.

### Methods

#### `add(*strings)`
- **Description**: Adds the lower case and no-period version of the string arguments to the set. Can accept a list of strings. Returns `self` for chaining.

#### `add_with_encoding(s, encoding=None)`
- **Description**: Adds the lower case and no-period version of the string to the set. An explicit `encoding` parameter can be passed to specify the encoding of binary strings that are not `DEFAULT_ENCODING` (UTF-8).

#### `remove(*strings)`
- **Description**: Removes the lower case and no-period version of the string arguments from the set. Returns `self` for chaining.
```

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

### Configuration Modules

Source: https://nameparser.readthedocs.io/en/latest/_sources/modules.rst.txt

Configuration modules define the rules and datasets used by the parser for titles, suffixes, prefixes, and other name components.

```APIDOC
## Configuration Modules

### Description
These modules contain the default configurations and datasets used by the parser.

### Modules
- **nameparser.config.titles**: Defines recognized titles.
- **nameparser.config.suffixes**: Defines recognized name suffixes.
- **nameparser.config.prefixes**: Defines recognized name prefixes.
- **nameparser.config.conjunctions**: Defines recognized conjunctions.
- **nameparser.config.capitalization**: Defines capitalization rules.
- **nameparser.config.regexes**: Defines the regular expressions used for parsing.
```

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

### Capitalize Human Names

Source: https://nameparser.readthedocs.io/en/latest/usage.html

Demonstrates how to capitalize names, including handling of all uppercase, all lowercase, and mixed-case inputs. The `force=True` parameter can be used to override default mixed-case handling.

```python
>>> name = HumanName("bob v. de la macdole-eisenhower phd")
>>> name.capitalize()
>>> str(name)
'Bob V. de la MacDole-Eisenhower Ph.D.'
```

```python
>>> name = HumanName('Shirley Maclaine') # Don't change mixed case names
>>> name.capitalize()
>>> str(name)
'Shirley Maclaine'
```

```python
>>> name.capitalize(force=True)
>>> str(name)
'Shirley MacLaine'
```

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

### Configure String Formatting

Source: https://nameparser.readthedocs.io/en/latest/_sources/usage.rst.txt

Customizes the string representation of HumanName instances by modifying the global string_format configuration.

```python
>>> from nameparser.config import CONSTANTS
>>> CONSTANTS.string_format = "{title} {first} ({nickname}) {middle} {last} {suffix}"
>>> name = HumanName('Robert Johnson')
>>> str(name)
'Robert Johnson'
>>> name = HumanName('Robert "Rob" Johnson')
>>> str(name)
'Robert (Rob) Johnson'
```

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

### Configure initials format

Source: https://nameparser.readthedocs.io/en/latest/_sources/usage.rst.txt

Adjust the initials_format string to specify which name parts are included in the initials output.

```python
>>> from nameparser.config import CONSTANTS
>>> CONSTANTS.initials_format = "{first} {middle}"
>>> HumanName("Doe, John A. Kenneth, Jr.").initials()
'J. A. K.'
>>> HumanName("Doe, John A. Kenneth, Jr.", initials_format="{last}, {first}).initials()
'D., J.'
```

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

### Check if a value is an initial

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

Identifies if a value represents an initial. This is determined by checking if the value matches the 'initial' regular expression defined in the configuration.

```python
def is_an_initial(self, value):
        """
        Words with a single period at the end, or a single uppercase letter.

        Matches the ``initial`` regular expression in
        :py:data:`~nameparser.config.regexes.REGEXES`.
        """
        return bool(self.C.regexes.initial.match(value))
```

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

### as_dict

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Converts the parsed name components into a dictionary.

```APIDOC
## as_dict(include_empty=True)

### Description
Returns the parsed name as a dictionary of its attributes.

### Parameters
- **include_empty** (bool) - Optional - Include keys in the dictionary for empty name attributes.

### Response
- **Return type** (dict) - A dictionary containing 'first', 'middle', 'last', 'title', 'suffix', and 'nickname'.
```

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

### Manage module-level configuration

Source: https://nameparser.readthedocs.io/en/latest/_sources/customize.rst.txt

Modifying the configuration on a HumanName instance affects all instances by default.

```python
>>> from nameparser import HumanName
>>> instance = HumanName("")
>>> instance.C.titles.add('dean')
SetManager({'right', ..., 'tax'})
>>> other_instance = HumanName("Dean Robert Johns")
>>> other_instance # Dean parses as title
<HumanName : [
  title: 'Dean'
  first: 'Robert'
  middle: ''
  last: 'Johns'
  suffix: ''
  nickname: ''
]>
```

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

### Helper Predicates

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Utility methods to check specific properties of name pieces.

```APIDOC
## `is_roman_numeral()`

### Description
Matches the `roman_numeral` regular expression in `REGEXES`.

### Method
`is_roman_numeral(value)`

### Endpoint
N/A (Helper Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **value** (string) - The string to check.

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** (boolean) - True if the value is a Roman numeral, False otherwise.

#### Response Example
N/A

## `is_title()`

### Description
Checks if a piece is a known title.

### Method
`is_title(value)`

### Endpoint
N/A (Helper Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **value** (string) - The string to check.

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** (boolean) - True if the value is a title, False otherwise.

#### Response Example
N/A

## `is_suffix()`

### Description
Checks if a piece is a known suffix. It handles suffixes that may be acronyms (e.g., M.B.A) by removing periods before checking against the suffix set.

### Method
`is_suffix(piece)`

### Endpoint
N/A (Helper Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **piece** (string) - The string to check.

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** (boolean) - True if the piece is a suffix, False otherwise.

#### Response Example
N/A

## `is_prefix()`

### Description
Checks if a piece is a known prefix. It converts the piece to lowercase and removes periods before checking against the prefix set.

### Method
`is_prefix(piece)`

### Endpoint
N/A (Helper Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **piece** (string) - The string to check.

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** (boolean) - True if the piece is a prefix, False otherwise.

#### Response Example
N/A

## `is_conjunction()`

### Description
Checks if a piece is a conjunction and not an initial.

### Method
`is_conjunction(piece)`

### Endpoint
N/A (Helper Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **piece** (string) - The string to check.

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** (boolean) - True if the piece is a conjunction and not an initial, False otherwise.

#### Response Example
N/A

## `is_rootname()`

### Description
Checks if a piece is a root name, meaning it's not a known title, suffix, or prefix. It is considered a first, middle, or last name.

### Method
`is_rootname(piece)`

### Endpoint
N/A (Helper Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **piece** (string) - The string to check.

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** (boolean) - True if the piece is a root name, False otherwise.

#### Response Example
N/A
```

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

### TupleManager Class

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Provides dictionary-like access with dot notation for tuple constants.

```APIDOC
## TupleManager Class

### Description
A dictionary with dot notation access. This class is a subclass of `dict`. It makes tuple constants more user-friendly.
```

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

### Module-Level Configuration

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Adjust the global configuration for all HumanName instances by modifying the module-level CONSTANTS instance.

```APIDOC
## Module-Level Configuration

### Description
Modify the global configuration for all `HumanName` instances by interacting with the module-level `CONSTANTS` instance.

### Method
Direct modification of the `CONSTANTS` object.

### Endpoint
`nameparser.config.CONSTANTS`

### Parameters
None

### Request Example
```python
from nameparser.config import CONSTANTS
CONSTANTS.titles.remove('hon').add('chemistry', 'dean')
```

### Response
#### Success Response (200)
Returns a `SetManager` object after modification.

#### Response Example
```
SetManager(set([u'msgt', ..., u'adjutant']))
```
```

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

### Set HumanName Attributes by Index in Python

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

Enables setting HumanName attributes using integer indices, provided the index corresponds to a valid member attribute. Raises a KeyError for invalid indices.

```python
def __setitem__(self, key, value):
        if key in self._members:
            self._set_list(key, value)
        else:
            raise KeyError("Not a valid HumanName attribute", key)
```

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

### Compare HumanName Instances in Python

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

Compares two HumanName instances for equality based on their lowercase, unicode string representations. This allows for case-insensitive and accent-insensitive comparisons.

```python
def __eq__(self, other):
        """
        HumanName instances are equal to other objects whose
        lower case unicode representation is the same.
        """
        return (u(self)).lower() == (u(other)).lower()
```

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

### Define string_format

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Sets the default string representation format for HumanName instances.

```python
string_format = '{title} {first} {middle} {last} {suffix} ({nickname})'
```

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

### Configure Global Nameparser Constants

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Modify the module-level CONSTANTS instance to update configuration for all HumanName instances.

```python
>>> from nameparser.config import CONSTANTS
>>> CONSTANTS.titles.remove('hon').add('chemistry','dean') 
SetManager(set([u'msgt', ..., u'adjutant']))
```

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

### HumanName.handle_capitalization() Method

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

This method applies capitalization rules based on the `capitalize_name` setting in the `CONSTANTS` configuration.

```APIDOC
## HumanName.handle_capitalization()

### Description
Handles capitalization configurations set within :py:class:`~nameparser.config.CONSTANTS`.

### Method
`handle_capitalization(self)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Assuming self.C.capitalize_name is True
name = HumanName('john doe')
name.handle_capitalization()
print(str(name))
# Output: John Doe
```

### Response
#### Success Response (200)
Modifies the `HumanName` object in place if `self.C.capitalize_name` is `True`.

#### Response Example
None (modifies object in place)
```

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

### SetManager: Add and Remove Configuration Items

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/config.html

The SetManager class provides methods to add and remove configuration items, normalizing them to lowercase and removing periods. It supports adding multiple strings at once and chaining operations.

```python
>>> from nameparser.config import CONSTANTS
>>> CONSTANTS.titles.remove('hon').add('chemistry','dean') # doctest: +ELLIPSIS
SetManager(set([u'msgt', ..., u'adjutant']))
```

```python
>>> from nameparser import HumanName
>>> hn = HumanName("Dean Robert Johns", None)
>>> hn.C.titles.add('dean') # doctest: +ELLIPSIS
SetManager(set([u'msgt', ..., u'adjutant']))
>>> hn.parse_full_name() # need to run this again after config changes
```

```python
    def add_with_encoding(self, s, encoding=None):
        """
        Add the lower case and no-period version of the string to the set. Pass an
        explicit `encoding` parameter to specify the encoding of binary strings that
        are not DEFAULT_ENCODING (UTF-8).
        """
        stdin_encoding = None
        if sys.stdin:
            stdin_encoding = sys.stdin.encoding
        encoding = encoding or stdin_encoding or DEFAULT_ENCODING
        if type(s) == binary_type:
            s = s.decode(encoding)
        self.elements.add(lc(s))
```

```python
    def add(self, *strings):
        """
        Add the lower case and no-period version of the string arguments to the set.
        Can pass a list of strings. Returns ``self`` for chaining.
        """
        [self.add_with_encoding(s) for s in strings]
        return self
```

```python
    def remove(self, *strings):
        """
        Remove the lower case and no-period version of the string arguments from the set.
        Returns ``self`` for chaining.
        """
        [self.elements.remove(lc(s)) for s in strings if lc(s) in self.elements]
        return self
```

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

### Convert HumanName to Dictionary

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Use as_dict to export name components. Setting include_empty to False excludes keys with empty values.

```python
>>> name = HumanName("Bob Dole")
>>> name.as_dict()
{'last': 'Dole', 'suffix': '', 'title': '', 'middle': '', 'nickname': '', 'first': 'Bob'}
>>> name.as_dict(False)
{'last': 'Dole', 'first': 'Bob'}
```

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

### Initial Extraction

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

Methods for extracting and formatting initials from a name.

```APIDOC
## initials_list

### Description
Returns the initials of the name as a list.

### Method
`initials_list()`

### Endpoint
N/A (Python method)

### Request Example
```json
{
  "example": "name.initials_list()"
}
```

### Response
#### Success Response (200)
- **list** (list) - A list of initials.

#### Response Example
```json
{
  "example": "['B', 'A', 'D']"
}
```

## initials

### Description
Returns period-delimited initials of the first, middle, and optionally last name. The format can be customized.

### Method
`initials(include_last_name=True)`

### Parameters
#### Query Parameters
- **include_last_name** (bool) - Optional - Include the last name as part of the initials.

### Request Example
```json
{
  "example": "name.initials()"
}
```

### Response
#### Success Response (200)
- **str** (str) - A string of period-delimited initials.

#### Response Example
```json
{
  "example": "B. A. D."
}
```
```

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

### Configure string output format

Source: https://nameparser.readthedocs.io/en/latest/_sources/usage.rst.txt

Modify the string_format attribute to control which name parts are included in the string representation.

```python
>>> from nameparser.config import CONSTANTS
>>> CONSTANTS.string_format = "{title} {first} {last}"
>>> name = HumanName("Dr. Juan Ruiz de la Vega III (Doc Vega)")
>>> str(name)
'Dr. Juan de la Vega'
```

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

### Join Prefixes to Last Names

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

Identifies and joins name prefixes with following name parts until a suffix or next prefix is encountered.

```python
prefixes = list(filter(self.is_prefix, pieces))
if prefixes:
    for prefix in prefixes:
        try:
            i = pieces.index(prefix)
        except ValueError:
            # If the prefix is no longer in pieces, it's because it has been
            # combined with the prefix that appears right before (or before that when
            # chained together) in the last loop, so the index of that newly created
            # piece is the same as in the last loop, i==i still, and we want to join
            # it to the next piece.
            pass

        new_piece = ''

        # join everything after the prefix until the next prefix or suffix

        try:
            if i == 0 and total_length >= 1:
                # If it's the first piece and there are more than 1 rootnames, assume it's a first name
                continue
            next_prefix = next(iter(filter(self.is_prefix, pieces[i + 1:])))
            j = pieces.index(next_prefix, i + 1)
            if j == i + 1:
                # if there are two prefixes in sequence, join to the following piece
                j += 1
            new_piece = ' '.join(pieces[i:j])
            pieces = pieces[:i] + [new_piece] + pieces[j:]
        except StopIteration:
            try:
                # if there are no more prefixes, look for a suffix to stop at
                stop_at = next(iter(filter(self.is_suffix, pieces[i + 1:])))
                j = pieces.index(stop_at)
                new_piece = ' '.join(pieces[i:j])
                pieces = pieces[:i] + [new_piece] + pieces[j:]
            except StopIteration:
                # if there were no suffixes, nothing to stop at so join all
                # remaining pieces
                new_piece = ' '.join(pieces[i:])
```

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

### Handle Capitalization - HumanName Class

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

Applies capitalization rules based on the `capitalize_name` setting in the `CONSTANTS` configuration. If `capitalize_name` is true, it calls the `capitalize()` method.

```python
def handle_capitalization(self):
        """
        Handles capitalization configurations set within
        :py:class:`~nameparser.config.CONSTANTS`.
        """
        if self.C.capitalize_name:
            self.capitalize()
```

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

### Helper Methods for Name Component Identification

Source: https://nameparser.readthedocs.io/en/latest/_modules/nameparser/parser.html

Utility methods used internally to identify different types of name components.

```APIDOC
## Helper Methods for Name Component Identification

Utility methods used internally to identify different types of name components.

### Methods

- **is_title(value)**: Checks if a value is present in the `nameparser.config.titles` set.
- **is_conjunction(piece)**: Checks if a piece is a conjunction and not an initial.
- **is_prefix(piece)**: Checks if a piece (lowercase, no periods) is present in the `nameparser.config.prefixes.PREFIXES` set.
- **is_roman_numeral(value)**: Checks if a value matches the `roman_numeral` regular expression defined in `nameparser.config.regexes.REGEXES`.
- **is_suffix(piece)**: Checks if a piece is a suffix and not an initial.
```

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

### Accessing Parser Constants

Source: https://nameparser.readthedocs.io/en/latest/customize.html

Retrieve the shared configuration constants either from the module level or via a HumanName instance.

```python
>>> from nameparser.config import CONSTANTS
>>> CONSTANTS
<Constants() instance>
```

```python
>>> from nameparser import HumanName
>>> hn = HumanName("Dean Robert Johns")
>>> hn.C
<Constants() instance>
```

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

### initials

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Generates initials from the parsed name components.

```APIDOC
## initials(include_last_name)

### Description
Returns period-delimited initials of the first, middle and optionally last name.

### Parameters
- **include_last_name** (bool) - Optional - Include the last name as part of the initials.

### Response
- **Return type** (str) - The formatted initials string.
```

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

### Generate Initials

Source: https://nameparser.readthedocs.io/en/latest/modules.html

Retrieve initials as a string using initials(). The format can be customized via the initials_format parameter.

```python
>>> name = HumanName("Sir Bob Andrew Dole")
>>> name.initials()
"B. A. D."
>>> name = HumanName("Sir Bob Andrew Dole", initials_format="{first} {middle}")
>>> name.initials()
"B. A."
```
Tokens:
Raw