people

PersonIndex

Bases: SlottedDict[Person]

Index object through which all persons (authors/editors) can be accessed.

Provides dictionary-like functionality mapping person IDs to Person objects.

Attributes:

Name	Type	Description
parent	Anthology	The parent Anthology instance to which this index belongs.
verbose	bool	If False, will not show progress bar when building the index from scratch.
name_to_ids	dict[Name, list[str]]	A mapping of Name instances to person IDs.
similar	DisjointSet	A disjoint-set structure of persons with similar names.
is_data_loaded	bool	A flag indicating whether the index has been constructed.

add_person

add_person(person)

Add a new person to the index.

Parameters:

Name	Type	Description	Default
person	Person	The person to add, which should not exist in the index yet.	required

build

build(show_progress=False)

Load the entire Anthology data and build an index of persons.

Important

Exceptions raised during the index creation are sent to the logger, and not re-raised. Use the SeverityTracker to check if an exception occurred.

find_coauthors

find_coauthors(person)

Find all persons who co-authored or co-edited items with the given person.

Parameters:

Name	Type	Description	Default
person	str | Person	A person ID or Person instance.	required

Returns:

Type	Description
list[Person]	A list of all persons who are co-authors; can be empty.

generate_id staticmethod

generate_id(name)

Generates and returns an ID from the given name.

Warning

This intentionally doesn't guarantee uniqueness of the generated ID. If two names generate identical IDs with this method, we assume they refer to the same person. This happens e.g. when there are missing accents in one version, or when we have an inconsistent first/last split for multiword names. These cases have in practice always referred to the same person.

get_by_name

get_by_name(name)

Access persons by their name.

Parameters:

Name	Type	Description	Default
name	Name	A personal name.	required

Returns:

Type	Description
list[Person]	A list of all persons with that name; can be empty.

get_by_namespec

get_by_namespec(name_spec)

Access persons by their name specification.

See get_or_create_person() for exceptions that can be raised by this function.

Parameters:

Name	Type	Description	Default
name_spec	NameSpecification	A name specification.	required

Returns:

Type	Description
Person	The person associated with this name specification.

get_or_create_person

get_or_create_person(name_spec, create=True)

Get the person represented by a name specification, or create a new one if needed.

Parameters:

Name	Type	Description	Default
name_spec	NameSpecification	The name specification on the paper, volume, etc.	required
create	bool	If False, will not create a new Person object, but instead raise NameIDUndefinedError if no person matching name_spec exists. Defaults to True.	True

Returns:

Type	Description
Person	The person represented by name_spec. This will try to use the id attribute if it is set, look up the name in the index otherwise, or try to find a matching person by way of an ID clash. If all of these fail, it will create a new person and return that.

Raises:

Type	Description
AmbiguousNameError	If there are multiple known IDs for the given name, but there is no explicit id attribute.
NameIDUndefinedError	If there is an explicit id attribute, but the ID has not been defined.

load

load()

Loads or builds the index.

reset

reset()

Resets the index.

save

save(path)

Save the entire index.

CURRENTLY UNTESTED; DO NOT USE.

Parameters:

Name	Type	Description	Default
path	PathLike[str]	The filename to save to.	required

Person

A natural person.

Attributes:

Name	Type	Description
id	str	A unique ID for this person.
parent	Anthology	The parent Anthology instance to which this person belongs.
names	list[Name]	A list of names under which this person has published.
item_ids	set[AnthologyIDTuple]	A set of volume and/or paper IDs this person has authored or edited.
comment	Optional[str]	A comment for disambiguation purposes; can be stored in name_variants.yaml.

canonical_name property writable

canonical_name

Returns:

Type	Description
Name	The canonical name for this person.

add_name

add_name(name)

Add a name for this person.

Parameters:

Name	Type	Description	Default
name	Name	Name that can refer to this person.	required

has_name

has_name(name)

Parameters:

Name	Type	Description	Default
name	Name	Name to be checked.	required

Returns:

Type	Description
bool	True if the given name can refer to this person.

papers

papers()

Returns an iterator over all papers associated with this person.

set_canonical_name

set_canonical_name(name)

Set the canonical name for this person.

Parameters:

Name	Type	Description	Default
name	Name	Name that should be treated as canonical for this person.	required

volumes

volumes()

Returns an iterator over all volumes this person has edited.

ConvertableIntoName module-attribute

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

A type that can be converted into a Name instance.

Name

A person's name.

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.

Examples:

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

as_bibtex

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_last_first

as_last_first()

Returns:

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

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 "first" and "last" 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().

score

score()

Returns:

Type	Description
int	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

slugify()

Returns:

Type	Description
str	A slugified string of the full 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
name	Name	The person's name.
id	Optional[str]	Unique ID for the person that this name refers to. Defaults to None.
affiliation	Optional[str]	Professional affiliation. Defaults to None.
variants	list[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).

first property

first

The first name component.

last property

last

The last name component.

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.

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.