### Installation

Source: https://github.com/derek73/python-nameparser/blob/master/README.rst

Instructions on how to install the nameparser library using pip.

```APIDOC
## Install nameparser using pip

### Description
This section provides the command to install the nameparser library from the Python Package Index (PyPI).

### Method
pip install

### Endpoint
N/A (Package installation)

### Parameters
None

### Request Example
```bash
pip install nameparser
```

### Response
#### Success Response (Installation)
- **Package** (string) - The nameparser package is successfully installed.

### Install from GitHub (Latest Code)

### Description
Instructions to install the latest development version of nameparser directly from its GitHub repository.

### Method
pip install -e

### Endpoint
N/A (Package installation)

### Parameters
None

### Request Example
```bash
pip install -e git+git://github.com/derek73/python-nameparser.git#egg=nameparser
```

### Response
#### Success Response (Installation)
- **Package** (string) - The nameparser package is successfully installed in editable mode from GitHub.
```

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

### Install nameparser via pip

Source: https://github.com/derek73/python-nameparser/blob/master/README.rst

Instructions for installing the nameparser library using the Python package manager.

```bash
pip install nameparser
```

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

### Parser Customization Examples

Source: https://github.com/derek73/python-nameparser/blob/master/docs/customize.md

Provides practical examples of how to customize the nameparser, such as removing titles or adjusting capitalization settings.

```APIDOC
## Parser Customization Examples

### Description
Illustrates common scenarios for customizing the nameparser, including handling specific titles and adjusting capitalization rules.

### Method
Utilize the `remove()` method on constant sets and modify boolean attributes of the `CONSTANTS` object.

### Endpoint
N/A (Python module access)

### Parameters
N/A

### Request Example
```python
from nameparser import HumanName
from nameparser.config import CONSTANTS

# Example 1: Removing a title that might be a first name
hn_before = HumanName("Hon Solo")
print(f"Before removal: {hn_before}")

CONSTANTS.titles.remove('hon')

hn_after = HumanName("Hon Solo")
print(f"After removal: {hn_after}")

# Example 2: Disabling title detection entirely
CONSTANTS.titles.remove(*CONSTANTS.titles)

# Example 3: Forcing mixed-case capitalization
CONSTANTS.force_mixed_case_capitalization = True
```

### Response
#### Success Response (200)
- **HumanName objects** - Show the parsed name before and after customization.
- **Output of attribute modifications** - Confirmation of changes to constants or settings.

#### Response Example
```
Before removal: <HumanName : [
  title: 'Hon'
  first: ''
  middle: ''
  last: 'Solo'
  suffix: ''
  nickname: ''
]>
After removal: <HumanName : [
  title: ''
  first: 'Hon'
  middle: ''
  last: 'Solo'
  suffix: ''
  nickname: ''
]>
```
```

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

### Configure nameparser constants

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

Examples of how to define and structure the configuration sets for suffixes, prefixes, conjunctions, and capitalization exceptions used by the nameparser engine.

```python
from nameparser.config import suffixes, prefixes, conjunctions, capitalization

# Define post-nominal pieces that are not acronyms
suffixes.SUFFIX_NOT_ACRONYMS = {'2', 'dr', 'esq', 'esquire', 'i', 'ii', 'iii', 'iv', 'jnr', 'jr', 'junior', 'snr', 'sr', 'v'}

# Define name pieces that appear before a last name
prefixes.PREFIXES = {'abu', 'al', 'bin', 'bon', 'da', 'de', 'del', 'della', 'der', 'di', 'la', 'mac', 'mc', 'san', 'van', 'von'}

# Define pieces that join neighboring name parts
conjunctions.CONJUNCTIONS = {'&', 'and', 'e', 'et', 'of', 'the', 'und', 'y'}

# Define exceptions for standard capitalization rules
capitalization.CAPITALIZATION_EXCEPTIONS = (('ii', 'II'), ('md', 'M.D.'), ('phd', 'Ph.D.'))
```

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

### Python Human Name Parser - Usage

Source: https://github.com/derek73/python-nameparser/blob/master/docs/index.md

This section details how to use the HumanName parser, including examples for capitalization, nicknames, and string formatting.

```APIDOC
## Using the HumanName Parser

### Description
This section provides guidance on how to use the HumanName parser to break down human names into their constituent parts. It covers various features and provides examples.

### Method
N/A (Library Usage)

### Endpoint
N/A (Library Usage)

### Parameters
N/A (Library Usage)

### Request Example
```python
from nameparser import HumanName

name = HumanName("Dr. John \"Johnny\" Fitzgerald Kennedy Jr.")
print(name.full_name)
print(name.first)
print(name.middle)
print(name.last)
print(name.suffix)
print(name.nickname)
print(name.title)
```

### Response
#### Success Response (Output)
- **full_name** (string) - The complete parsed name.
- **first** (string) - The first name.
- **middle** (string) - The middle name(s).
- **last** (string) - The last name.
- **suffix** (string) - The suffix (e.g., Jr., Sr.).
- **nickname** (string) - The nickname.
- **title** (string) - The title (e.g., Dr., Mr.).

#### Response Example
```
Dr. John Fitzgerald Kennedy Jr.
John
Fitzgerald
Kennedy
Jr.
Johnny
Dr.
```

### Further Details
- [Example Usage](usage.md#example-usage)
- [Capitalization Support](usage.md#capitalization-support)
- [Nickname Handling](usage.md#nickname-handling)
- [Change the output string with string formatting](usage.md#change-the-output-string-with-string-formatting)
- [Initials Support](usage.md#initials-support)
```

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

### HumanName Helper Methods for Name Piece Identification

Source: https://context7.com/derek73/python-nameparser/llms.txt

Provides examples of utility methods available in HumanName for checking the type of a name piece, such as title, suffix, prefix, conjunction, initial, or Roman numeral.

```python
from nameparser import HumanName

name = HumanName("Dr. Juan Q. Xavier de la Vega III")

# Check if a piece is a title
print(name.is_title("Dr."))     # True
print(name.is_title("Juan"))    # False

# Check if a piece is a suffix
print(name.is_suffix("III"))    # True
print(name.is_suffix("Ph.D."))  # True

# Check if a piece is a prefix (joins to following name)
print(name.is_prefix("de"))     # True
print(name.is_prefix("van"))    # True

# Check if a piece is a conjunction
print(name.is_conjunction("and"))  # True
print(name.is_conjunction("of"))   # True

# Check if a piece is an initial
print(name.is_an_initial("Q."))    # True
print(name.is_an_initial("Q"))     # True
print(name.is_an_initial("Juan"))  # False

# Check if a piece is a Roman numeral
print(name.is_roman_numeral("III"))  # True
print(name.is_roman_numeral("IV"))   # True
```

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

### HumanName Instantiation and Configuration

Source: https://context7.com/derek73/python-nameparser/llms.txt

Demonstrates how to instantiate HumanName with default or custom configurations, and how changes to per-instance configurations affect parsing.

```APIDOC
## HumanName Instantiation and Configuration

### Description
This section shows how to create `HumanName` objects, either by parsing a full name string or by providing individual name components. It also illustrates how to apply per-instance configurations and how these affect the parsing process.

### Method
`HumanName(name_string, config=None)` or `HumanName(first='...', middle='...', ...)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name_string** (str) - The full name string to parse.
- **config** (object, optional) - A configuration object for parsing rules. If None, default configurations are used.
- **first** (str, optional) - The first name component.
- **middle** (str, optional) - The middle name component(s).
- **last** (str, optional) - The last name component.
- **title** (str, optional) - The title component (e.g., 'Dr.').
- **suffix** (str, optional) - The suffix component (e.g., 'Jr.').
- **nickname** (str, optional) - The nickname component.

### Request Example
```python
from nameparser import HumanName

# Instantiate with a full name string and default configuration
name = HumanName("Dean Robert Johns", None)
name.parse_full_name()
print(name.title)  # Output: 'Dean'
print(name.first)  # Output: 'Robert'

# Instantiate with individual components
name_components = HumanName(
    first="John",
    middle="William",
    last="Smith",
    title="Dr.",
    suffix="Jr.",
    nickname="Johnny"
)
print(name_components.first)   # Output: 'John'
print(str(name_components))    # Output: 'Dr. John William Smith Jr. (Johnny)'
print(name_components.unparsable)  # Output: False
```

### Response
#### Success Response (200)
- **HumanName object**: An object representing the parsed name with attributes like `title`, `first`, `middle`, `last`, `suffix`, `nickname`, `unparsable`, etc.

#### Response Example
```json
{
  "title": "Dean",
  "first": "Robert",
  "middle": "",
  "last": "Johns",
  "suffix": "",
  "nickname": "",
  "display_name": "Dean Robert Johns",
  "first_name": "Robert",
  "last_name": "Johns",
  "full_name": "Dean Robert Johns",
  "preferred_first_name": "Dean",
  "unparsable": false
}
```
```

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

### Configuring HumanName Instance

Source: https://context7.com/derek73/python-nameparser/llms.txt

Demonstrates how to configure a HumanName instance with specific settings or use default configurations. Changes to one instance do not affect others.

```python
from nameparser import HumanName

# Pass None for per-instance config (fresh defaults)
name = HumanName("Dean Robert Johns", None)
name.C.titles.add('dean')
name.parse_full_name()  # Re-parse after config change
print(name.title)  # 'Dean'
print(name.first)  # 'Robert'

# Other instances remain unaffected
other = HumanName("Dean Robert Johns", None)
print(other.first)  # 'Dean' (parsed as first name with fresh config)
```

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

### GET /initials

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

Returns the period-delimited initials of the name components.

```APIDOC
## GET /initials

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

### Method
GET

### Endpoint
/initials

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

### Response
#### Success Response (200)
- **initials** (string) - The formatted initials string

### Response Example
"B. A. D."
```

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

### Per-Instance Configuration

Source: https://context7.com/derek73/python-nameparser/llms.txt

Demonstrates how to create HumanName instances with isolated configurations.

```APIDOC
## Per-Instance Configuration

### Description
Create HumanName instances with isolated configuration that doesn't affect other instances.

### Method
N/A (Illustrative Code)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from nameparser import HumanName
from nameparser.config import Constants

# Create a custom Constants instance
constants = Constants()
constants.titles.add('dean', 'chemistry')

# Use custom constants for specific parsing
name = HumanName("Assoc Dean of Chemistry Robert Johns", constants=constants)
print(name.title)  # 'Assoc Dean of Chemistry'
print(name.first)  # 'Robert'
print(name.has_own_config)  # True
```

### Response
N/A

### Response Example
N/A
```

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

### GET /initials_list

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

Returns the initials of the name as a list of strings.

```APIDOC
## GET /initials_list

### Description
Returns the initials as a list of individual characters.

### Method
GET

### Endpoint
/initials_list

### Response
#### Success Response (200)
- **initials** (list) - List of string initials

### Response Example
["B", "A", "D"]
```

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

### Get Initials of Human Name (Python)

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

Retrieves the period-delimited initials of the first, middle, and optionally last name from a HumanName object. The format can be customized.

```python
>>> from nameparser import HumanName
>>> 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."
```

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

### Configure Initials Format and Delimiter

Source: https://github.com/derek73/python-nameparser/blob/master/docs/usage.md

Demonstrates how to customize the initials output format using placeholders like {first}, {middle}, and {last}, and how to set a custom delimiter for the resulting string.

```python
from nameparser import HumanName
from nameparser.config import CONSTANTS

# Set format and extract
CONSTANTS.initials_format = "{first} {middle}"
print(HumanName("Doe, John A. Kenneth, Jr.").initials())

# Set custom delimiter
name = HumanName("Doe, John A. Kenneth, Jr.", initials_delimiter=";")
print(name.initials())
```

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

### Customizing NameParser Configuration

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

Demonstrates how to modify the global configuration for name parsing, such as adding or removing titles. It also shows how to create an instance with a custom configuration.

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

```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
```

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

### Get Initials as a List (Python)

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

Returns the initials of a HumanName object as a list of strings. This method is useful for programmatic access to individual initial components.

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

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

### Capitalization Handling

Source: https://context7.com/derek73/python-nameparser/llms.txt

Demonstrates how to capitalize names, including handling mixed cases and setting global capitalization preferences.

```APIDOC
## Capitalization Handling

### Description
Demonstrates how to capitalize names, including handling mixed cases and setting global capitalization preferences.

### Method
N/A (Illustrative Code)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from nameparser import HumanName
from nameparser.config import CONSTANTS

# Default behavior
name = HumanName('Shirley Maclaine')
name.capitalize()
print(str(name))  # 'Shirley Maclaine' (unchanged)

# Force capitalization on mixed case names
name.capitalize(force=True)
print(str(name))  # 'Shirley MacLaine'

# Enable automatic capitalization for all instances
CONSTANTS.capitalize_name = True
name = HumanName("bob v. de la macdole-eisenhower phd")
print(str(name))  # 'Bob V. de la MacDole-Eisenhower Ph.D.'

# Force mixed case capitalization globally
CONSTANTS.force_mixed_case_capitalization = True
name = HumanName('Shirley Maclaine')
name.capitalize()
print(str(name))  # 'Shirley MacLaine'
```

### Response
N/A

### Response Example
N/A
```

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

### Configuration with CONSTANTS

Source: https://context7.com/derek73/python-nameparser/llms.txt

Shows how to customize the parser's behavior globally using the CONSTANTS object.

```APIDOC
## Configuration with CONSTANTS

### Description
Customize parser behavior globally by modifying the shared CONSTANTS instance.

### Method
N/A (Illustrative Code)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from nameparser import HumanName
from nameparser.config import CONSTANTS

# Add custom titles
CONSTANTS.titles.add('dean', 'chemistry')
name = HumanName("Assoc Dean of Chemistry Robert Johns")
print(name.title)  # 'Assoc Dean of Chemistry'
print(name.first)  # 'Robert'
print(name.last)   # 'Johns'

# Remove a title (so it can be parsed as a first name)
CONSTANTS.titles.remove('hon')
name = HumanName("Hon Solo")
print(name.first)  # 'Hon'
print(name.last)   # 'Solo'

# Disable all titles
CONSTANTS.titles.remove(*CONSTANTS.titles)

# Change default return value for empty attributes
CONSTANTS.empty_attribute_default = None
name = HumanName("John Doe")
print(name.title)  # None
print(name.first)  # 'John'

# Editable configuration sets:
# - CONSTANTS.titles           - Titles like Dr., Mr., Prof.
# - CONSTANTS.first_name_titles - Titles where following name is first (Sir, King)
# - CONSTANTS.suffix_acronyms  - Suffix acronyms like M.D., Ph.D.
# - CONSTANTS.suffix_not_acronyms - Non-acronym suffixes like Jr., Sr.
# - CONSTANTS.conjunctions     - Words like "and", "of", "the"
# - CONSTANTS.prefixes         - Last name prefixes like de, van, von
```

### Response
N/A

### Response Example
N/A
```

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

### Per-Instance Configuration in Python NameParser

Source: https://context7.com/derek73/python-nameparser/llms.txt

Demonstrates how to create HumanName instances with isolated configurations that do not affect other instances. This is achieved by creating a custom Constants instance and passing it during HumanName object creation.

```python
from nameparser import HumanName
from nameparser.config import Constants

# Create a custom Constants instance
constants = Constants()
constants.titles.add('dean', 'chemistry')

# Use custom constants for specific parsing
name = HumanName("Assoc Dean of Chemistry Robert Johns", constants=constants)
print(name.title)  # 'Assoc Dean of Chemistry'
print(name.first)  # 'Robert'
print(name.has_own_config)  # True
```

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

### Parsing Names with HumanName

Source: https://context7.com/derek73/python-nameparser/llms.txt

Demonstrates basic instantiation of the HumanName class to parse full name strings. Shows how to access individual components, convert to dictionaries, and perform comparisons or iterations.

```python
from nameparser import HumanName

name = HumanName("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
print(name.title)
print(name.first)
print(name.middle)
print(name.last)
print(name.suffix)
print(name.nickname)

# Dictionary-style access
print(name["title"])

# Convert to dictionary
print(name.as_dict())

# Comparison
name1 = HumanName("Dr. Juan Q. Xavier de la Vega III")
name2 = HumanName("de la vega, dr. juan Q. xavier III")
print(name1 == name2)
```

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

### Parsing and Exporting Names with HumanName

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

Demonstrates how to instantiate a HumanName object to parse a string and export the results as a dictionary. The as_dict method allows filtering out empty fields.

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

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

### Apply Name Capitalization

Source: https://github.com/derek73/python-nameparser/blob/master/docs/usage.md

Shows how to normalize name casing using the capitalize method or by configuring global constants for automatic capitalization.

```python
from nameparser import HumanName
from nameparser.config import CONSTANTS

name = HumanName("bob v. de la macdole-eisenhower phd")
name.capitalize()

# Global configuration
CONSTANTS.capitalize_name = True
CONSTANTS.force_mixed_case_capitalization = True
```

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

### Parse and Format Human Names

Source: https://github.com/derek73/python-nameparser/blob/master/README.rst

Demonstrates how to instantiate the HumanName class to parse a string into name components, access specific parts, convert to a dictionary, and apply custom string formatting.

```python
from nameparser import HumanName
name = HumanName("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
# Access components
print(name.last)
# Convert to dict
print(name.as_dict())
# Custom formatting
name.string_format = "{first} {last}"
print(str(name))
```

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

### Configuration Management

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

API for managing the global or instance-specific configuration constants for the parser.

```APIDOC
## PATCH /config/constants

### Description
Updates the module-level or instance-level configuration constants for name parsing.

### Method
PATCH

### Endpoint
/config/constants

### Request Body
- **titles** (array) - List of strings to add or remove from title set.
- **conjunctions** (array) - List of strings to add or remove from conjunction set.

### Request Example
{
  "titles": {"add": ["dean"], "remove": ["hon"]}
}
```

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

### Direct Instantiation of HumanName

Source: https://context7.com/derek73/python-nameparser/llms.txt

Shows how to create a HumanName object by directly providing name components (first, middle, last, title, suffix, nickname) to the constructor, bypassing the parsing step.

```python
from nameparser import HumanName

# Create name from components (no parsing)
name = HumanName(
    first="John",
    middle="William",
    last="Smith",
    title="Dr.",
    suffix="Jr.",
    nickname="Johnny"
)

print(name.first)   # 'John'
print(name.last)    # 'Smith'
print(str(name))    # 'Dr. John William Smith Jr. (Johnny)'
print(name.unparsable)  # False
```

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

### Name Parser Usage

Source: https://github.com/derek73/python-nameparser/blob/master/README.rst

Demonstrates how to use the HumanName class to parse a full name string and access its components.

```APIDOC
## Instantiate and Parse Human Name

### Description
This section shows how to instantiate the `HumanName` class with a string representing a full name and how to access the parsed components.

### Method
Instantiation and attribute access

### Endpoint
N/A (Python library usage)

### Parameters
None

### Request Example
```python
from nameparser import HumanName

name_string = "Dr. Juan Q. Xavier de la Vega III (Doc Vega)"
name = HumanName(name_string)

print(name.title)
print(name.first)
print(name.middle)
print(name.last)
print(name.suffix)
print(name.nickname)
```

### Response
#### Success Response (Output)
- **title** (string) - The title part of the name (e.g., 'Dr.').
- **first** (string) - The first name part.
- **middle** (string) - The middle name(s) or initial(s).
- **last** (string) - The last name or surname(s).
- **suffix** (string) - The suffix part of the name (e.g., 'III').
- **nickname** (string) - The nickname, often in parentheses.

#### Response Example
```
Dr.
Juan
Q. Xavier
de la Vega
III
Doc Vega
```

## Accessing Name Components as Dictionary

### Description
Demonstrates how to get a dictionary representation of the parsed name components.

### Method
`as_dict()` method

### Endpoint
N/A (Python library usage)

### Parameters
None

### Request Example
```python
from nameparser import HumanName

name = HumanName("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
print(name.as_dict())
```

### Response
#### Success Response (200)
- **dict** (object) - A dictionary where keys are name components (title, first, middle, last, suffix, nickname) and values are the parsed strings.

#### Response Example
```json
{
    "last": "de la Vega",
    "suffix": "III",
    "title": "Dr.",
    "middle": "Q. Xavier",
    "nickname": "Doc Vega",
    "first": "Juan"
}
```

## Customizing String Formatting

### Description
Shows how to change the default string representation of a `HumanName` object.

### Method
Attribute assignment (`string_format`)

### Endpoint
N/A (Python library usage)

### Parameters
- **string_format** (string) - A format string to define the output structure. Uses placeholders like `{first}`, `{last}`, etc.

### Request Example
```python
from nameparser import HumanName

name = HumanName("Dr. Juan Q. Xavier de la Vega III (Doc Vega)")
name.string_format = "{first} {last}"
print(str(name))
```

### Response
#### Success Response (Output)
- **string** (string) - The name formatted according to the `string_format`.

#### Response Example
```
Juan de la Vega
```

## Handling Comma-Separated Names

### Description
Illustrates how the parser handles names with comma-separated components, such as "Last, First".

### Method
Instantiation

### Endpoint
N/A (Python library usage)

### Parameters
None

### Request Example
```python
from nameparser import HumanName

name = HumanName("1 & 2, 3 4 5, Mr.")
print(name.title)
print(name.first)
print(name.middle)
print(name.last)
print(name.suffix)
```

### Response
#### Success Response (Output)
- **title** (string) - The title part.
- **first** (string) - The first name part.
- **middle** (string) - The middle name(s).
- **last** (string) - The last name or surname(s).
- **suffix** (string) - The suffix part.

#### Response Example
```

3
4 5
1 & 2
Mr.
```
```

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

### Handle Nicknames and Custom Formatting

Source: https://github.com/derek73/python-nameparser/blob/master/docs/usage.md

Explains how the parser automatically detects nicknames in quotes or parentheses and how to customize the string representation of name objects.

```python
from nameparser import HumanName
from nameparser.config import CONSTANTS

name = HumanName('Jonathan "John" A. Smith')
print(name.nickname)

# Customizing output format
CONSTANTS.string_format = "{title} {first} ({nickname}) {middle} {last} {suffix}"
```

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

### Capitalization Control in Python NameParser

Source: https://context7.com/derek73/python-nameparser/llms.txt

Demonstrates how to control name capitalization, including default behavior, forcing capitalization on mixed-case names, and enabling automatic capitalization globally. It also shows how to force mixed-case capitalization globally.

```python
from nameparser.config import CONSTANTS
from nameparser import HumanName

# Default capitalization (no change)
name = HumanName('Shirley Maclaine')
name.capitalize()
print(str(name))  # 'Shirley Maclaine'

# Force capitalization on mixed case names
name.capitalize(force=True)
print(str(name))  # 'Shirley MacLaine'

# Enable automatic capitalization globally
CONSTANTS.capitalize_name = True
name = HumanName("bob v. de la macdole-eisenhower phd")
print(str(name))  # 'Bob V. de la MacDole-Eisenhower Ph.D.'

# Force mixed case capitalization globally
CONSTANTS.force_mixed_case_capitalization = True
name = HumanName('Shirley Maclaine')
name.capitalize()
print(str(name))  # 'Shirley MacLaine'
```

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

### Initials Support

Source: https://context7.com/derek73/python-nameparser/llms.txt

Illustrates how to generate initials from parsed names with customizable formatting and delimiters.

```APIDOC
## Initials Support

### Description
Generate initials from parsed names with customizable formatting.

### Method
N/A (Illustrative Code)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from nameparser import HumanName
from nameparser.config import CONSTANTS

# Default initials (first, middle, last)
name = HumanName("Sir Bob Andrew Dole")
print(name.initials())      # 'B. A. D.'
print(name.initials_list()) # ['B', 'A', 'D']

# Exclude last name from initials
name = HumanName("Doe, John A. Kenneth, Jr.", initials_format="{first} {middle}")
print(name.initials())  # 'J. A. K.'

# Custom format per instance
name = HumanName("Doe, John A. Kenneth, Jr.", initials_format="{last}, {first}")
print(name.initials())  # 'D., J.'

# Custom delimiter
name = HumanName("Doe, John A. Kenneth, Jr.", initials_delimiter=";")
print(name.initials())  # 'J; A; K;'

# Global settings
CONSTANTS.initials_delimiter = "."
CONSTANTS.initials_format = "{first}{middle}{last}"
name = HumanName("Doe, John A. Kenneth, Jr.")
print(name.initials())  # 'J.A.K.D.'
```

### Response
N/A

### Response Example
N/A
```

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

### Parse and Manipulate Names with HumanName

Source: https://github.com/derek73/python-nameparser/blob/master/docs/usage.md

Demonstrates initializing a HumanName object, accessing individual name components, modifying fields, and exporting data as a dictionary.

```python
from nameparser import HumanName
name = HumanName("Dr. Juan Q. Xavier de la Vega III")
print(name.first)
name.full_name = "Juan Q. Xavier Velasquez y Garcia, Jr."
print(name.as_dict())
```

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

### HumanName Class Initialization

Source: https://context7.com/derek73/python-nameparser/llms.txt

Instantiate the HumanName class to parse a full name string into individual components like title, first, middle, last, suffix, and nickname.

```APIDOC
## HumanName Initialization

### Description
Parses a raw name string into structured components upon object creation.

### Method
Constructor (Class Instantiation)

### Parameters
#### Request Body
- **name_string** (string) - Required - The full name string to be parsed.

### Request Example
"Dr. Juan Q. Xavier de la Vega III"

### Response
#### Success Response (Object)
- **title** (string) - Extracted title
- **first** (string) - Extracted first name
- **middle** (string) - Extracted middle name
- **last** (string) - Extracted last name
- **suffix** (string) - Extracted suffix
- **nickname** (string) - Extracted nickname

#### Response Example
{
  "title": "Dr.",
  "first": "Juan",
  "middle": "Q. Xavier",
  "last": "de la Vega",
  "suffix": "III",
  "nickname": ""
}
```

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

### Manage HumanName Configuration Scope

Source: https://github.com/derek73/python-nameparser/blob/master/docs/customize.md

Explains how to manage the configuration scope for HumanName instances. By default, configuration changes affect all instances. This snippet shows how to create instances with their own independent configurations by passing `None` during instantiation.

```python
from nameparser import HumanName

# Modifies global config
instance = HumanName("")
instance.C.titles.add('dean')

# Instance with its own config
other_instance = HumanName("Dean Robert Johns", None)
print(other_instance.has_own_config)
```

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

### Python Human Name Parser - Developer Documentation

Source: https://github.com/derek73/python-nameparser/blob/master/docs/index.md

Provides links to developer-focused documentation, including class details, configuration, and contributing guidelines.

```APIDOC
## Developer Documentation

### Description
This section directs developers to detailed documentation regarding the internal structure of the python-nameparser library, including class specifics and contributing information.

### Method
N/A (Documentation Links)

### Endpoint
N/A (Documentation Links)

### Parameters
N/A (Documentation Links)

### Request Example
N/A

### Response
N/A

### Links to Developer Resources:
- [HumanName Class Documentation](modules.md)
- [HumanName.parser](modules.md#module-nameparser.parser)
- [HumanName.config](modules.md#module-nameparser.config)
- [HumanName.config Defaults](modules.md#module-nameparser.config.titles)
- [Naming Practices and Resources](resources.md)
- [Release Log](release_log.md)
- [Contributing](contributing.md)
```

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

### Configure Mixed Case Capitalization

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

Demonstrates how to enable force_mixed_case_capitalization to ensure specific name formatting during the capitalize() process. This setting affects how the HumanName object processes input strings.

```python
from nameparser.config import CONSTANTS
from nameparser import HumanName

CONSTANTS.force_mixed_case_capitalization = True
name = HumanName('Shirley Maclaine')
name.capitalize()
print(str(name))
```

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

### String Format Customization

Source: https://context7.com/derek73/python-nameparser/llms.txt

Details how to control the output string format of parsed names globally or per instance.

```APIDOC
## String Format Customization

### Description
Control how parsed names are output as strings using format templates.

### Method
N/A (Illustrative Code)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from nameparser import HumanName
from nameparser.config import CONSTANTS

# Default format includes nickname in parentheses
name = HumanName('Robert "Rob" Johnson')
print(str(name))  # 'Robert Johnson (Rob)'

# Change global string format
CONSTANTS.string_format = "{title} {first} ({nickname}) {middle} {last} {suffix}"
name = HumanName('Robert "Rob" Johnson')
print(str(name))  # 'Robert (Rob) Johnson'

# Omit fields from output
CONSTANTS.string_format = "{title} {first} {last}"
name = HumanName("Dr. Juan Ruiz de la Vega III (Doc Vega)")
print(str(name))  # 'Dr. Juan de la Vega'

# Per-instance string format
name = HumanName("Dr. Juan Q. Xavier de la Vega III")
name.string_format = "{first} {last}"
print(str(name))  # 'Juan de la Vega'
```

### Response
N/A

### Response Example
N/A
```

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

### Capitalizing Names with HumanName

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

Shows how to use the capitalize method to correct the casing of name strings. The force parameter can be used to override default capitalization logic.

```python
from nameparser import HumanName
name = HumanName('bob v. de la macdole-eisenhower phd')
name.capitalize()
print(str(name))
# 'Bob V. de la MacDole-Eisenhower Ph.D.'

name = HumanName('Shirley Maclaine')
name.capitalize(force=True)
print(str(name))
# 'Shirley MacLaine'
```

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

### Using SetManager for Configuration

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

The SetManager class provides a way to manage configuration sets with automatic normalization. It supports adding or removing multiple strings at once while ensuring consistency.

```python
from nameparser.config import SetManager

manager = SetManager(['mr', 'mrs'])
manager.add('dr', 'prof')
manager.remove('mrs')
```

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

### POST /parser/human-name

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

Initializes a HumanName object to parse a string into name components or retrieve a dictionary representation.

```APIDOC
## POST /parser/human-name

### Description
Parses a full name string into structured components or returns the object as a dictionary.

### Method
POST

### Endpoint
/parser/human-name

### Parameters
#### Request Body
- **full_name** (string) - Required - The full name string to be parsed.
- **include_empty** (boolean) - Optional - Whether to include empty attributes in the dictionary response.

### Request Example
{
  "full_name": "Bob Dole",
  "include_empty": true
}

### Response
#### Success Response (200)
- **first** (string) - The parsed first name.
- **last** (string) - The parsed last name.
- **middle** (string) - The parsed middle name.
- **title** (string) - The parsed title.
- **suffix** (string) - The parsed suffix.
- **nickname** (string) - The parsed nickname.

#### Response Example
{
  "last": "Dole",
  "suffix": "",
  "title": "",
  "middle": "",
  "nickname": "",
  "first": "Bob"
}
```

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

### NameParser Configuration Constants

Source: https://github.com/derek73/python-nameparser/blob/master/docs/modules.md

This section details the configuration constants available for the NameParser library and how to modify them.

```APIDOC
## NameParser Configuration Constants

An instance of this class hold all of the configuration constants for the parser.

### Parameters

*   **prefixes** (*set*) – [`prefixes`](#module-nameparser.config.prefixes) wrapped with [`SetManager`](#nameparser.config.SetManager).
*   **titles** (*set*) – [`titles`](#module-nameparser.config.titles) wrapped with [`SetManager`](#nameparser.config.SetManager).
*   **first_name_titles** (*set*) – [`FIRST_NAME_TITLES`](#nameparser.config.titles.FIRST_NAME_TITLES) wrapped with [`SetManager`](#nameparser.config.SetManager).
*   **suffix_acronyms** (*set*) – [`SUFFIX_ACRONYMS`](#nameparser.config.suffixes.SUFFIX_ACRONYMS)  wrapped with [`SetManager`](#nameparser.config.SetManager).
*   **suffix_not_acronyms** (*set*) – [`SUFFIX_NOT_ACRONYMS`](#nameparser.config.suffixes.SUFFIX_NOT_ACRONYMS)  wrapped with [`SetManager`](#nameparser.config.SetManager).
*   **conjunctions** (*set*) – [`conjunctions`](#module-nameparser.config.conjunctions)  wrapped with [`SetManager`](#nameparser.config.SetManager).
*   **capitalization_exceptions** (*tuple* *or* *dict*) – [`CAPITALIZATION_EXCEPTIONS`](#nameparser.config.capitalization.CAPITALIZATION_EXCEPTIONS) wrapped with [`TupleManager`](#nameparser.config.TupleManager).
*   **regexes** (*tuple* *or* *dict*) – [`regexes`](#module-nameparser.config.regexes)  wrapped with [`TupleManager`](#nameparser.config.TupleManager).

#### capitalize_name *= False*

If set, applies [`capitalize()`](#nameparser.parser.HumanName.capitalize) to
[`HumanName`](#nameparser.parser.HumanName) instance.

```pycon
>>> 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.'
```

#### empty_attribute_default *= ''*

Default return value for empty attributes.

```pycon
>>> from nameparser.config import CONSTANTS
>>> CONSTANTS.empty_attribute_default = None
>>> name = HumanName("John Doe")
>>> name.title
None
>>>name.first
'John'
```
```

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

### Capitalizing Name Strings

Source: https://context7.com/derek73/python-nameparser/llms.txt

Demonstrates the capitalize method, which automatically fixes casing for names, including handling of specific prefixes and suffixes.

```python
from nameparser import HumanName

name = HumanName("bob v. de la macdole-eisenhower phd")
name.capitalize()
print(str(name))
```

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

### Initials Generation in Python NameParser

Source: https://context7.com/derek73/python-nameparser/llms.txt

Explains how to generate initials from parsed names with customizable formatting. Covers default initials, excluding parts of the name, custom formats per instance, custom delimiters, and global settings.

```python
from nameparser import HumanName
from nameparser.config import CONSTANTS

# Default initials
name = HumanName("Sir Bob Andrew Dole")
print(name.initials())      # 'B. A. D.'
print(name.initials_list()) # ['B', 'A', 'D']

# Exclude last name from initials
name = HumanName("Doe, John A. Kenneth, Jr.", initials_format="{first} {middle}")
print(name.initials())  # 'J. A. K.'

# Custom format per instance
name = HumanName("Doe, John A. Kenneth, Jr.", initials_format="{last}, {first}")
print(name.initials())  # 'D., J.'

# Custom delimiter
name = HumanName("Doe, John A. Kenneth, Jr.", initials_delimiter=";")
print(name.initials())  # 'J; A; K;'

# Global settings
CONSTANTS.initials_delimiter = "."
CONSTANTS.initials_format = "{first}{middle}{last}"
name = HumanName("Doe, John A. Kenneth, Jr.")
print(name.initials())  # 'J.A.K.D.'
```