people.person

NameLink

Bases: StrEnum

How a Name was connected to a Person.

EXPLICIT class-attribute instance-attribute

EXPLICIT = 'explicit'

Name is explicitly listed in people.yaml file.

INFERRED class-attribute instance-attribute

INFERRED = 'inferred'

Name was connected to this Person via slug matching heuristic.

Person

A natural person.

Info

The connection between persons and Anthology items is derived from name specifications on volumes and papers, and not stored explicitly. This means that Person objects cannot be used to make changes to paper metadata, e.g. which person a paper is associated with or under which name; change the information on papers instead.

Person objects can be used to make changes to metadata that appears in people.yaml, such as ORCID, comment, degree, and alternative names for this person.

Attributes:

Name	Type	Description
id	str	A unique ID for this person. Do not change this attribute directly; use change_id(), make_explicit(), or merge_into() instead.
parent	PersonIndex	The parent Anthology instance to which this person belongs.
item_ids	set[AnthologyIDTuple]	An unordered set of volume and/or paper IDs this person has authored or edited.
orcid	Optional[str]	The person's ORCID.
comment	Optional[str]	A comment for disambiguation purposes.
degree	Optional[str]	The person's institution of highest degree, for disambiguation purposes.
similar_ids	list[str]	A list of person IDs with names that should be considered similar to this one. Do not use this to find people with similar names; that should be done via PersonIndex.similar. This attribute can be used to explicitly add more "similar IDs" that are not automatically derived via similar names.
is_explicit	Optional[bool]	If True, this person's ID is explicitly defined in people.yaml. You probably want to use make_explicit() rather than change this attribute.

canonical_name property writable

canonical_name

The canonical name for this person.

disable_name_matching property writable

disable_name_matching

Flag to indicate if items can be assigned to this person via name matching.

If True, no items should be assigned to this person unless they explicitly specify this person's ID.

names property writable

names

A list of all names associated with this person.

root property

root

The Anthology instance to which this object belongs.

add_name

add_name(name, inferred=False)

Add a name for this person.

Parameters:

Name	Type	Description	Default
name	ConvertableIntoName	Name that can refer to this person.	required
inferred	bool	If True, will be marked as NameLinkingType.INFERRED, which will e.g. cause this name to not be written to people.yaml. Used when building the PersonIndex from the XML data; you probably don't want to set this manually. Defaults to False.	False

anthology_items

anthology_items()

Returns an iterator over all Anthology items associated with this person, regardless of their type.

change_id

change_id(new_id)

Change this person's ID.

This updates self.id, but also ensures that all papers/items with the old ID are updated to the new one.

Parameters:

Name	Type	Description	Default
new_id	str	The new ID for this person, which must match RE_VERIFIED_PERSON_ID.	required

Raises:

Type	Description
AnthologyException	If self.explicit is False.
AnthologyInvalidIDError	If the supplied ID is not well-formed, or if it already exists in the PersonIndex.

has_name

has_name(name)

Parameters:

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

Returns:

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

make_explicit

make_explicit(new_id=None, skip_setting_ids=False)

Turn this person that was implicitly created into an explicitly-represented one.

This will result in this person having an explicit entry in people.yaml with all names that are currently associated with this person. It will also add their new explicit ID to all papers and volumes currently associated with this person.

Parameters:

Name	Type	Description	Default
new_id	Optional[str]	The new ID for this person, which must match RE_VERIFIED_PERSON_ID. If not specified, will try to generate one automatically based on this person's canonical name (and, potentially, ORCID).	None
skip_setting_ids	bool	If True, will skip setting IDs on name specifications that previously resolved to this person. This means that some or all of the items in self.item_ids might disappear if they no longer resolve to this person.	False

Raises:

Type	Description
AnthologyException	If self.explicit is already True, or if the ID already exists in the PersonIndex (both if it was supplied or auto-generated).
AnthologyInvalidIDError	If the supplied ID is not valid.

merge_into

merge_into(other)

Merge this person and all their publications into another person.

This will move all attributes, papers, and volumes currently associated with this person over to the other person. The other person's ID will be explicitly set on all items currently associated with this person. If an attribute (e.g. ORCID iD, comment) is already set on the other person, it will not be changed.

This Person object should no longer be used after calling this function.

Parameters:

Name	Type	Description	Default
other	Person	A person to merge this person into. Must be explicit.	required

Raises:

Type	Description
AnthologyException	If other.explicit is False.

namespecs

namespecs()

Returns an iterator over all NameSpecifications that resolve to this person.

papers

papers()

Returns an iterator over all papers associated with this person.

Note

This will return papers where this person is an author, as well as frontmatter of volumes where they are an editor. It will not include all other papers in volumes they have edited.

remove_name

remove_name(name)

Remove an explicit name for this person.

Warning

If the name is still used on a paper or volume with the ID of this person, this may result in an Exception during index building. Names that were implicitly linked to this person cannot be removed this way, as the name would simply reappear on next load.

Parameters:

Name	Type	Description	Default
name	ConvertableIntoName	Name that should be removed from this person.	required

Raises:

Type	Description
ValueError	If this name was not explicitly linked to this person.

set_id_on_items

set_id_on_items(exclude=None)

Set this person's ID explicitly on all Anthology items associated with them.

Parameters:

Name	Type	Description	Default
exclude	Optional[list[AnthologyID | Paper | Volume]]	An optional list of Anthology items or IDs that should be excluded.	None

Warning

This should only be done if it is certain that all papers currently linked to this person actually belong to them, including those that were implicitly linked (i.e. via name matching).

Raises:

Type	Description
AnthologyException	If self.explicit is False.

volumes

volumes()

Returns an iterator over all volumes this person has edited.