people.index

UNVERIFIED_PID_FORMAT module-attribute

UNVERIFIED_PID_FORMAT = '{pid}/unverified'

Format string for unverified person IDs.

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.

Info

All information about persons is currently derived from name specifications on volumes and papers, and not stored explicitly. This means:

1. Loading this index requires parsing the entire Anthology data.
2. Nothing in this index should be modified to make changes to Anthology data; change the information on papers instead.

See the guide on accessing author/editor information for more information.

Attributes:

Name	Type	Description
parent	Anthology	The parent Anthology instance to which this index belongs.
path	Path	The path to people.yaml.
by_orcid	dict[str, str]	A mapping of ORCIDs (as strings) to person IDs.
by_name	dict[Name, list[str]]	A mapping of Name instances to lists of person IDs.
slugs_to_verified_ids	dict[str, set[str]]	A mapping of strings (representing slugified names) to lists of 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

Raises:

Type	Description
AnthologyInvalidIDError	If a person with the same ID or ORCID already exists in the index.

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 only a generic exception is raised at the end.

create

create(id, names, **kwargs)

Create a new explicit person and add it to the index.

Parameters:

Name	Type	Description	Default
id	str	The ID of the new person.	required
names	list[Name]	A list of names for the new person; must contain at least one.	required
**kwargs	Any	Any valid list or optional attribute of Person.	{}

Returns:

Type	Description
Person	The created Person object.

Raises:

Type	Description
AnthologyInvalidIDError	If a person with the given ID already exists, or the ID is not a well-formed verified-person ID.
ValueError	If the list of names is empty.

find_coauthors

find_coauthors(person, include_volumes=True)

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
include_volumes	bool	If set to False, will not consider co-editorship on volumes, unless they have frontmatter.	True

Returns:

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

find_coauthors_counter

find_coauthors_counter(person, include_volumes=True)

Find the count of co-authored or co-edited items per person.

Parameters:

Name	Type	Description	Default
person	str | Person	A person ID or Person instance.	required
include_volumes	bool	If set to False, will not consider co-editorship on volumes, unless they have frontmatter.	True

Returns:

Type	Description
Counter[str]	A Counter mapping IDs of other persons Y to the number of papers this person has co-authored with Y.

generate_person_id

generate_person_id(person_or_name, suffix=None, orcid=None)

Generate a verified person ID that does not exist yet in the index.

This does not modify the index or a supplied Person instance in any way.

Parameters:

Name	Type	Description	Default
person_or_name	Person | Name	A Person or Name instance to use as the basis for generating the ID. If given a Person, their canonical name will be used, and potentially their ORCID iD (if set).	required
suffix	Optional[str]	A suffix to append to the ID in case the generated ID is already taken.	None
orcid	Optional[str]	An ORCID iD whose last four characters can be appended to the ID in case the generated ID is already taken. If None and the first argument is a Person, the Person's ORCID iD will be used instead.	None

Returns:

Type	Description
str	A valid verified person ID that doesn't exist yet.

Raises:

Type	Description
AnthologyException	If all generated IDs already exist in the index.

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.

Parameters:

Name	Type	Description	Default
name_spec	NameSpecification	A name specification.	required

Returns:

Type	Description
Person	The person associated with this name specification.

Raises:

Type	Description
NameSpecResolutionError	If name_spec cannot be resolved to a Person.
PersonDefinitionError	If name_spec.id is set, but either the ID or the name used with the ID has not been defined in people.yaml. (Inherits from NameSpecResolutionError)

get_by_orcid

get_by_orcid(orcid)

Access persons by their ORCID.

Parameters:

Name	Type	Description	Default
orcid	str	A string representing an ORCID.	required

Returns:

Type	Description
Person | None	The person with that ORCID, if it exists, otherwise None.

ingest_namespec

ingest_namespec(name_spec)

Update a name specification for ingestion, potentially filling in the ID field.

If the name specification contains an ORCID but doesn't have an ID yet, this will find the person with this ORCID and fill in their ID; if it doesn't exist yet, it will create a new person with a "verified" ID and fill in the new, generated ID. The supplied name specification will be modified in-place, but also returned.

Warning

If you add new material via create_paper() or create_volume() and supply an author/editor list at that time, there is no need to call this function manually.

Parameters:

Name	Type	Description	Default
name_spec	NameSpecification	The name specification on the paper, volume, etc.	required

Returns:

Type	Description
NameSpecification	The name specification as it should be used for the new ingestion material.

load

load()

Loads or builds the index.

remove_person

remove_person(person)

Remove a person from the index.

Warning

The person object should not be used in any way after this operation.

Parameters:

Name	Type	Description	Default
person	Person	The person to remove, which must be explicit.	required

Raises:

Type	Description
ValueError	If the person does not exist in in the index, is not explicit, or if there are still NameSpecifications associated with this person.

reset

reset()

Resets the index.

save

save(path=None)

Save the people.yaml file.

Parameters:

Name	Type	Description	Default
path	Optional[StrPath]	The filename to save to. If None, defaults to the parent Anthology's people.yaml file.	None