Names API

This is the API reference for all functions designed to be used on names. You can find usage examples here.

hh.format_name

format_name(text: str, errors: str = 'raise') -> str | None

Cleans the formatting of names. Strips extra whitespaces, converts to title case (with exceptions for names like McDonald) and removes any spaces around hyphens. Converting to title case will make any letters following an apostrophe capitals so names like O'Reilly are preserved. There is no rule for names which begin with 'Mac' as following letter capitalisation is inconsistent and cannot be inferred.

Parameters:

Name	Type	Description	Default
`text`	`str`	The name you wish to clean.	required
`errors`	`optional`	Default = 'raise' which raises all errors. 'ignore' ignores errors and returns original value, 'coerce' returns None.	`'raise'`

Raises:

Type	Description
`TypeError`	Raised if text is not a string.

Returns:

Type	Description
`str \| None`	Cleaned text.

hh.create_full_name

create_full_name(
    first_name: str | Series,
    last_name: str | Series,
    middle_name: str | Series | None = None,
) -> str | pd.Series | None

Join first, (optional) middle, and last names into a full name.

Two mutually exclusive modes

DataFrame mode: first_name, last_name AND (if given) middle_name are all pd.Series of equal length and shared index. Returns a Series; rows where every part is empty become pd.NA.
Scalar mode: first_name and last_name are str, and (if given) middle_name is str. Returns a str, or None if the result is empty.

A missing middle name (omitted, None, or NaN) is always treated as "" and a usable full name is built from first + last. Mixing Series and str across arguments is not allowed.

Parameters:

Name	Type	Description	Default
`first_name`	`str \| Series`	First name. str (scalar mode) or pd.Series (DataFrame mode).	required
`last_name`	`str \| Series`	Last name. Must be the same type as first_name.	required
`middle_name`	`optional`	Middle name. May be omitted or passed as None/NaN to mean "no middle name". Otherwise must match the mode.	`None`

Returns:

Type	Description
`str \| Series \| None`	A joined full name: a str (or None if empty) in scalar mode, or a
`str \| Series \| None`	Series of strings (empty rows as pd.NA) in DataFrame mode.

Raises:

Type	Description
`TypeError`	On mixed argument types, or if first_name/last_name are not both str or both pd.Series.
`ValueError`	If Series arguments differ in length or index.

hh.find_numbers_in_text

find_numbers_in_text(
    text: str, errors: str = "raise", convert_to_string: bool = False
) -> bool | str | None

Checks if one or more numbers are present in a string. Numbers do not have to be consecutive.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to check for numbers.	required
`errors`	`optional`	Default = 'raise' which raises all errors. 'ignore' ignores errors and returns original value, 'coerce' returns None.	`'raise'`
`convert_to_string`	`optional`	Tells the function to convert text datatype to string, if possible. Defaults to False.	`False`

Raises:

Type	Description
`TypeError`	Raised if text datatype is not string.

Returns:

Type	Description
`bool \| str \| None`	True if string contains one or more numbers (0-9) or False if no numbers present.

hh.remove_numbers

remove_numbers(
    text: str, errors: str = "raise", convert_to_string: bool = False
) -> str | None

Removes one or more numbers from a string (text). Numbers do not have to be consecutive.

Parameters:

Name	Type	Description	Default
`text`	`str`	The string you want to remove numbers from e.g. 'Jane Doe 43'	required
`errors`	`optional`	Default = 'raise' which raises all errors. 'ignore' ignores errors and returns original value, 'coerce' returns None.	`'raise'`
`convert_to_string`	`optional`	Tells the function to convert text datatype to string, if possible. Defaults to False.	`False`

Raises:

Type	Description
`TypeError`	Raised if text is not a string.

Returns:

Type	Description
`str \| None`	Text with numbers removed.

hh.remove_diacritics

remove_diacritics(
    input_text: str, errors: str = "raise"
) -> str | None

Removes diacritics (accented letters) from text. Uses python's built-in unicodedata library and normalises to NFKD before removal.

Parameters:

Name	Type	Description	Default
`input_text`	`str`	The text you want to remove diacritics from.	required
`errors`	`optional`	Default = 'raise' which raises all errors. 'ignore' ignores errors and returns original value, 'coerce' returns None.	`'raise'`

Raises:

Type	Description
`TypeError`	Raised if input_text is not a string.

Returns:

Type	Description
`str \| None`	Text with accents removed e.g. 'Chloë' -> 'Chloe'.

hh.remove_punctuation

remove_punctuation(
    text: str, punctuation: str = PUNCTUATION, errors: str = "raise"
) -> str | None

Removes all punctuation except for hyphens and apostrophes from text. Useful for cleaning names.

Parameters:

Name	Type	Description	Default
`text`	`str`	Text you wish to remove punctuation from.	required
`punctuation`	`optional`	String containing all punctuation except for hyphens and apostrophes. Can be overridden with your own version if you want to exclude other types of punctuation. Should be one string of all chars to remove. Default includes the following chars: !@#£$%^&*()_=+`~,.<>/?;:"\|[]	`PUNCTUATION`
`errors`	`optional`	Default = 'raise' which raises all errors. 'ignore' ignores errors and returns original value, 'coerce' returns None.	`'raise'`

Raises:

Type	Description
`TypeError`	Raised if text is not a string.

Returns:

Type	Description
`str \| None`	Text with all punctuation except hyphens and apostrophes removed e.g. 'Jane! Doe.' -> 'Jane Doe'