people.name¶

ConvertableIntoName `module-attribute` ¶

ConvertableIntoName = (
    Name | str | tuple[Optional[str], str] | dict[str, str]
)

A type that can be converted into a Name instance.

LAST_NAME_CAPITALIZATION_RULES `module-attribute` ¶

LAST_NAME_CAPITALIZATION_RULES = (
    ("^Mc([a-z])", lambda p: "Mc" + p.group(1).upper()),
)

Regex rules for heuristically normalizing last names; used for acl_anthology.people.name.Name.case_normalize.

LAST_NAME_LOWERCASE_PREFIXES `module-attribute` ¶

LAST_NAME_LOWERCASE_PREFIXES = {
    "al",
    "bin",
    "bint",
    "da",
    "de",
    "del",
    "de la",
    "dela",
    "della",
    "di",
    "dos",
    "du",
    "el",
    "la",
    "le",
    "van",
    "van den",
    "van der",
    "von",
    "von der",
}

Strings that tend to be lowercased when prefixing a last name; used for Name.case_normalize().

RE_NAME_OVERSPACED `module-attribute` ¶

RE_NAME_OVERSPACED = re.compile(
    "( |^)[a-z] [a-z]( |$)| -|- "
)

Regex that checks for overspacing of characters in a name. Detects hyphens bordering spaces, and multiple isolated lowercase characters in sequence.

RE_NAME_UNDERCAPITALIZED `module-attribute` ¶

RE_NAME_UNDERCAPITALIZED = re.compile(
    "\\.[a-z]|\\. [a-z]\\b|\\b[a-uw-z]\\."
)

Regex that checks for spurious lowercase characters in a name.

First and last names should not contain a lowercase initial after/before a dot, or any lowercase character immediately following a dot. (Exception: "v."--"v. Hahn" short for "von Hahn" is attested.)

RE_NAME_VALID `module-attribute` ¶

RE_NAME_VALID = re.compile(
    "[^ \\'\\\",.:;!@#$%^&*()=+/?<>\\[\\]`\\\\–-](\\S*( \\S+)* ?[^ ,-])?"
)

Regex that partially checks validity of first and last names.

First and last names should not start with punctuation, should not end with a comma or hyphen, and should not contain whitespace unless it is a space surrounded on both sides by non-whitespace. (It would be better to use the regex module with \p{P} for all Unicode punctuation, but that would add an extra dependency.)

Used by Name.is_valid().

SLUGIFY_REPLACEMENTS `module-attribute` ¶

SLUGIFY_REPLACEMENTS = (['ʼ', '-'], ['’', '-'])

Custom replacement rules for name slugs.

VALID_NAME_PUNCT `module-attribute` ¶

VALID_NAME_PUNCT = (
    "'’.,‘\"“”„-" + EN_DASH + EM_DASH + "&/()"
)

Punctuation characters allowed in names.

Name ¶

A person's name.

Note

Name objects are frozen, meaning they are immutable. This allows them to be used as dictionary keys, but means that in order to change a name somewhere, you need to replace it with a new Name instance.

Attributes:

Name	Type	Description
`first`	`Optional[str]`	First name part. Can be given as `None` for people who only have a single name, but cannot be omitted.
`last`	`str`	Last name part.
`script`	`Optional[str]`	The script in which the name is written; only used for non-Latin script name variants.

It is recommended to check basic validity of the name strings by calling is_valid(). Impermissible punctuation or digits, excessive whitespace, or lowercase characters in a few contexts are considered invalid.

Examples:

>>> Name("Yang", "Liu")
Name('Yang', 'Liu')
>>> Name(last="Liu", first="Yang")
Name('Yang', 'Liu')
>>> Name(None, "Mausam")
Name(None, 'Mausam')

as_bibtex `cached` ¶

as_bibtex()

Returns:

Type	Description
`str`	The person's full name as formatted in a BibTeX entry.

as_first_last ¶

as_first_last()

Returns:

Type	Description
`str`	The person's full name in the form '{first} {last}'.

as_full ¶

as_full()

Builds the full name, determining the appropriate format based on the script.

Returns:

Type	Description
`str`	For Han names, this will be '{last}{first}'; for other scripts (or if no script is given), this will be '{first} {last}'.

as_last_first ¶

as_last_first()

Returns:

Type	Description
`str`	The person's full name in the form '{last}, {first}'.

case_normalize ¶

case_normalize(force=False)

Try to heuristically normalize the casing of the name.

By default, this changes the name if it is currently all-lowercased or all-uppercased. Lowercase initials are also normalized in otherwise mixed-case names.

Examples:

Normalize a name that is entirely uppercase:

>>> Name("MARCEL", "BOLLMANN").case_normalize()
Name('Marcel', 'Bollmann')

Repair initials in an otherwise mixed-case name:

>>> Name("John C.s.", "Lui").case_normalize()
Name('John C.S.', 'Lui')

Parameters:

Name	Type	Description	Default
`force`	`bool`	Apply title-casing even when the full name is mixed-case. Initial normalization is always applied.	`False`

Returns:

Type	Description
`Name`	The original object when no changes are needed; otherwise, a new instance of the same concrete class with normalized name parts.

Note

Names with a script attribute are returned unchanged.

from_ `classmethod` ¶

from_(name)

Instantiate a Name dynamically from any type that can be converted into a Name.

Parameters:

Name	Type	Description	Default
`name`	`ConvertableIntoName`	A name as a string, dict, tuple, or Name instance.	required

Returns:

Type	Description
`Name`	A corresponding Name object.

Raises:

Type	Description
`ValueError`
`TypeError`

from_dict `classmethod` ¶

from_dict(name)

Parameters:

Name	Type	Description	Default
`name`	`dict[str, str]`	A dictionary with at least a "last" key, and optionally "first" and "script" keys.	required

Returns:

Type	Description
`Name`	A corresponding Name object.

from_string `classmethod` ¶

from_string(name)

Instantiate a Name from a single string.

Parameters:

Name	Type	Description	Default
`name`	`str`	A name string given as either "{first} {last}" or "{last}, {first}".	required

Returns:

Type	Description
`Name`	A corresponding Name object.

Raises:

Type	Description
`ValueError`	If `name` cannot be unambiguously parsed into first/last components; in this case, you should instantiate Name directly instead.

from_xml `classmethod` ¶

from_xml(variant)

Parameters:

Name	Type	Description	Default
`variant`	`_Element`	An XML element of a `<variant>` block.	required

Returns:

Type	Description
`Name`	A corresponding Name object.

Note

This will work for <author> and <editor> tags as well, but those are more efficiently parsed within NameSpecification.from_xml().

is_valid ¶

is_valid(error=False)

Check if the name has valid first and last names. (The first name is allowed to be None.) If error is True, raises a ValueError.

Returns:

Type	Description
`bool`	True iff the name parts match `RE_NAME_VALID`, do not contain punctuation/symbols apart from the ones in `VALID_NAME_PUNCT`, do not contain digits (except '3^rd' in a last name), and do not contain a lowercase initial with a dot or a lowercase character immediately after a dot (exception: 'v.' which can be short for 'von').

latex_normalize ¶

latex_normalize()

Normalize LaTeX commands in the name.

Returns:

Type	Description
`Name`	The LaTeX-normalized Name.

score ¶

score()

Returns:

Type	Description
`float`	A score for this name that is intended for comparing different names that generate the same ID. Names that are more likely to be the correct canonical variant should return higher scores via this function.

slugify `cached` ¶

slugify()

Returns:

Type	Description
`str`	A slugified string of the full name.

to_dict ¶

to_dict()

Returns:

Type	Description
`dict[str, str]`	A dictionary representing this name.

to_xml ¶

to_xml(tag='variant')

Parameters:

Name	Type	Description	Default
`tag`	`str`	Name of outer tag in which the name should be wrapped.	`'variant'`

Returns:

Type	Description
`_Element`	A serialization of this name in Anthology XML format.

NameSpecification ¶

A name specification on a paper etc., containing additional data fields for information or disambiguation besides just the name.

Attributes:

Name	Type	Description
`parent`	`Optional[Paper \| Volume \| Talk]`	The Anthology item that this name specification belongs to.
`orcid`	`Optional[str]`	An ORCID that was supplied together with this name.
`openreview`	`Optional[str]`	An OpenReview profile ID that was supplied together with this name. (This is not used for resolving author identities.)
`affiliation`	`Optional[str]`	Professional affiliation. (This is not used for resolving author identities.)
`variants`	`tuple[Name, ...]`	Variant spellings of this name in different scripts.

Note

The variants attribute is only intended for name variants stored via the <variant> tag in the XML, i.e., for a name that has a variant in a different script. It is not used when an author has published under different names (for this functionality, see Person).

citeproc_dict `cached` `property` ¶

citeproc_dict

A citation object corresponding to this name for use with CiteProcJSON.

first `property` ¶

first

The first name component.

id `property` `writable` ¶

id

Unique ID for the person that this NameSpecification refers to.

last `property` ¶

last

The last name component.

name `property` `writable` ¶

name

The person's name.

root `property` ¶

root

The Anthology instance to which this object belongs.

from_xml `classmethod` ¶

from_xml(person)

Parameters:

Name	Type	Description	Default
`person`	`_Element`	An XML element of an `<author>` or `<editor>` block.	required

Returns:

Type	Description
`NameSpecification`	A corresponding NameSpecification object.

normalize ¶

normalize(casing=True, latex=True, skip_setter=False)

Heuristically normalize the name.

Parameters:

Name	Type	Description	Default
`casing`	`bool`	If set to False, do not case-normalize.	`True`
`latex`	`bool`	If set to False, do not LaTeX-normalize.	`True`
`skip_setter`	`bool`	If True, bypass the setter which dynamically updates affected objects. Set during ingestion; you probably do not want to set this manually.	`False`

resolve ¶

resolve()

Resolve this name specification to a natural person.

Returns:

Type	Description
`Person`	The Person object that this name specification resolves to.

Raises:

Type	Description
`AnthologyException`	If this name specification is not attached to an Anthology item (i.e., `parent` is not set).

to_xml ¶

to_xml(tag='author')

Parameters:

Name	Type	Description	Default
`tag`	`str`	Name of outer tag in which the name should be wrapped.	`'author'`

Returns:

Type	Description
`_Element`	A serialization of this name in Anthology XML format.

people.name¶

ConvertableIntoName module-attribute ¶

LAST_NAME_CAPITALIZATION_RULES module-attribute ¶

LAST_NAME_LOWERCASE_PREFIXES module-attribute ¶

RE_NAME_OVERSPACED module-attribute ¶

RE_NAME_UNDERCAPITALIZED module-attribute ¶

RE_NAME_VALID module-attribute ¶

SLUGIFY_REPLACEMENTS module-attribute ¶

VALID_NAME_PUNCT module-attribute ¶

Name ¶

as_bibtex cached ¶

as_first_last ¶

as_full ¶

as_last_first ¶

case_normalize ¶

from_ classmethod ¶

from_dict classmethod ¶

from_string classmethod ¶

from_xml classmethod ¶

is_valid ¶

latex_normalize ¶

score ¶

slugify cached ¶

to_dict ¶

to_xml ¶

NameSpecification ¶

citeproc_dict cached property ¶

first property ¶

id property writable ¶

last property ¶

name property writable ¶

root property ¶

from_xml classmethod ¶

normalize ¶

resolve ¶

to_xml ¶

ConvertableIntoName `module-attribute` ¶

LAST_NAME_CAPITALIZATION_RULES `module-attribute` ¶

LAST_NAME_LOWERCASE_PREFIXES `module-attribute` ¶

RE_NAME_OVERSPACED `module-attribute` ¶

RE_NAME_UNDERCAPITALIZED `module-attribute` ¶

RE_NAME_VALID `module-attribute` ¶

SLUGIFY_REPLACEMENTS `module-attribute` ¶

VALID_NAME_PUNCT `module-attribute` ¶

as_bibtex `cached` ¶

from_ `classmethod` ¶

from_dict `classmethod` ¶

from_string `classmethod` ¶

from_xml `classmethod` ¶

slugify `cached` ¶

citeproc_dict `cached` `property` ¶

first `property` ¶

id `property` `writable` ¶

last `property` ¶

name `property` `writable` ¶

root `property` ¶

from_xml `classmethod` ¶