tessl/pypi-nameparser

A simple Python module for parsing human names into their individual components.

—

Pending

Overview

Eval results

Files

Core Name Parsing

Name: tessl/pypi-nameparser
Author: tessl

Main functionality for parsing human names into individual components and accessing the parsed results through various interfaces.

Capabilities

HumanName Class

The primary class for parsing human names. Automatically parses names on instantiation or when the full_name property is set.

class HumanName:
    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):
        """
        Parse a person's name into individual components.

        Args:
            full_name (str): The name string to be parsed
            constants: Constants instance for configuration (None for per-instance config)
            encoding (str): String encoding (default: UTF-8)
            string_format (str): Python string formatting template
            initials_format (str): Python initials string formatting template
            initials_delimiter (str): String delimiter for initials
            first (str): Pre-set first name (bypasses parsing)
            middle (str): Pre-set middle name (bypasses parsing)
            last (str): Pre-set last name (bypasses parsing)
            title (str): Pre-set title (bypasses parsing)
            suffix (str): Pre-set suffix (bypasses parsing)
            nickname (str): Pre-set nickname (bypasses parsing)
        """

Usage Examples:

from nameparser import HumanName

# Basic parsing
name = HumanName("Dr. Martin Luther King Jr.")
print(name.title)   # 'Dr.'
print(name.first)   # 'Martin'
print(name.middle)  # 'Luther'
print(name.last)    # 'King'
print(name.suffix)  # 'Jr.'

# Comma-separated format
name = HumanName("King Jr., Dr. Martin Luther")
print(name.title)   # 'Dr.'
print(name.first)   # 'Martin'
print(name.middle)  # 'Luther'
print(name.last)    # 'King'
print(name.suffix)  # 'Jr.'

# Name with nickname in quotes
name = HumanName('Robert "Bob" Johnson')
print(name.first)    # 'Robert'
print(name.nickname) # 'Bob'
print(name.last)     # 'Johnson'

# Name with nickname in parentheses
name = HumanName('William (Bill) Gates III')
print(name.first)    # 'William'
print(name.nickname) # 'Bill'
print(name.last)     # 'Gates'
print(name.suffix)   # 'III'

# Complex titles and prefixes
name = HumanName("The Right Honorable Jane van der Berg-Smith")
print(name.title)   # 'The Right Honorable'
print(name.first)   # 'Jane'
print(name.last)    # 'van der Berg-Smith'

Name Component Properties

Access individual components of the parsed name as string properties.

@property
def title(self) -> str:
    """
    The person's titles. Any string of consecutive pieces in titles or
    conjunctions at the beginning of full_name.
    """

@property
def first(self) -> str:
    """
    The person's first name. The first name piece after any known
    title pieces parsed from full_name.
    """

@property
def middle(self) -> str:
    """
    The person's middle names. All name pieces after the first name and
    before the last name parsed from full_name.
    """

@property
def last(self) -> str:
    """
    The person's last name. The last name piece parsed from full_name.
    """

@property
def suffix(self) -> str:
    """
    The person's suffixes. Pieces at the end of the name that are found in 
    suffixes, or pieces that are at the end of comma separated formats.
    """

@property
def nickname(self) -> str:
    """
    The person's nicknames. Any text found inside of quotes ("") or
    parenthesis (()).
    """

@property
def surnames(self) -> str:
    """
    A string of all middle names followed by the last name.
    """

@property
def full_name(self) -> str:
    """The string output of the HumanName instance."""

@property
def original(self) -> str:
    """The original string, untouched by the parser."""

@property
def unparsable(self) -> bool:
    """Whether the name could be parsed successfully."""

@property
def has_own_config(self) -> bool:
    """
    True if this instance is not using the shared module-level
    configuration.
    """

Dictionary Conversion

Convert parsed names to dictionary format for serialization or processing.

def as_dict(self, include_empty: bool = True) -> dict:
    """
    Return the parsed name as a dictionary of its attributes.

    Parameters:
    - include_empty: Include keys in the dictionary for empty name attributes

    Returns:
    Dictionary containing name components
    """

Usage Examples:

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'}

Name Component Setters

Set individual name components programmatically, with automatic list handling.

@title.setter
def title(self, value: str | list | None) -> None:
    """Set the title component."""

@first.setter
def first(self, value: str | list | None) -> None:
    """Set the first name component."""

@middle.setter
def middle(self, value: str | list | None) -> None:
    """Set the middle name component."""

@last.setter
def last(self, value: str | list | None) -> None:
    """Set the last name component."""

@suffix.setter
def suffix(self, value: str | list | None) -> None:
    """Set the suffix component."""

@nickname.setter
def nickname(self, value: str | list | None) -> None:
    """Set the nickname component."""

Usage Examples:

name = HumanName()
name.first = "John"
name.last = "Doe"
name.title = "Dr."
print(str(name))  # 'Dr. John Doe'

# Setting with lists
name.middle = ["James", "Robert"]
print(name.middle)  # 'James Robert'

Parsing Control

Manual parsing control and re-parsing after configuration changes.

def parse_full_name(self) -> None:
    """
    The main parse method. Run upon assignment to full_name or instantiation.
    Can be called manually after configuration changes.
    """

Usage Examples:

from nameparser import HumanName
from nameparser.config import CONSTANTS

name = HumanName("Dean Robert Johns", None)  # Per-instance config
name.C.titles.add('dean')
name.parse_full_name()  # Re-parse after config change

Magic Methods

Standard Python object interface methods for comparison, iteration, and indexing.

def __str__(self) -> str:
    """String representation using string_format template."""

def __repr__(self) -> str:
    """Developer-friendly representation showing all components."""

def __eq__(self, other) -> bool:
    """Equality comparison (case-insensitive)."""

def __ne__(self, other) -> bool:
    """Inequality comparison."""

def __iter__(self):
    """Iterate over non-empty name components."""

def __len__(self) -> int:
    """Number of non-empty name components."""

def __getitem__(self, key: int | slice) -> str | list:
    """Access name components by index or slice."""

def __setitem__(self, key: str, value: str | list | None) -> None:
    """Set name components by key."""

def __hash__(self) -> int:
    """Hash based on string representation."""

Usage Examples:

name1 = HumanName("John Doe")
name2 = HumanName("JOHN DOE")
print(name1 == name2)  # True (case-insensitive)

# Iteration
for component in name1:
    print(component)  # Prints non-empty components

# Length
print(len(name1))  # 2 (first and last)

# Indexing
print(name1[0])  # 'John' (first component)
print(name1[-1]) # 'Doe' (last component)

# Slicing
print(name1[0:2]) # ['John', 'Doe']

Additional Parsing Methods

Methods for manual parsing control and parsing utilities.

def parse_full_name(self):
    """
    The main parse method. Run upon assignment to full_name or instantiation.
    Can be called manually after configuration changes.
    """

def collapse_whitespace(self, string):
    """
    Collapse multiple spaces into single space and handle trailing commas.
    
    Args:
        string (str): String to clean up
        
    Returns:
        str: Cleaned string with normalized whitespace
    """

Usage Examples:

from nameparser import HumanName
from nameparser.config import CONSTANTS

# Manual re-parsing after config changes
name = HumanName("Dean Robert Johns", None)  # Per-instance config
name.C.titles.add('dean')
name.parse_full_name()  # Re-parse after config change
print(name.title)  # 'Dean'

# Utility function for whitespace handling
name = HumanName("John Smith")
cleaned = name.collapse_whitespace("  John   Smith  ")
print(cleaned)  # 'John Smith'

Name Classification Helpers

Methods for testing whether name components belong to specific categories.

def is_title(self, value):
    """Check if value is in the titles set."""

def is_conjunction(self, piece):
    """Check if piece is a conjunction and not an initial."""

def is_prefix(self, piece):
    """Check if piece is in the prefixes set."""

def is_suffix(self, piece):
    """Check if piece is in the suffixes set and not an initial."""

def is_roman_numeral(self, value):
    """Check if value matches roman numeral pattern."""

def is_rootname(self, piece):
    """Check if piece is a core name part (not title, suffix, or prefix)."""

def is_an_initial(self, value):
    """Check if value is a single letter or letter with period."""

def are_suffixes(self, pieces):
    """Check if all pieces in list are suffixes."""

Usage Examples:

from nameparser import HumanName

name = HumanName("Dr. John van der Berg III")

# Test individual components
print(name.is_title("Dr."))         # True
print(name.is_prefix("van"))        # True  
print(name.is_conjunction("der"))   # True
print(name.is_suffix("III"))        # True
print(name.is_roman_numeral("III")) # True
print(name.is_an_initial("J."))     # True
print(name.is_rootname("John"))     # True

# Test with lists
print(name.is_suffix(["Jr", "Sr"]))    # True
print(name.are_suffixes(["III", "Jr"])) # True

Install with Tessl CLI