fairdm.contrib.contributors.services.registries

Look people up in ORCID and organizations up in ROR, and make profiles from what is found.

Module Contents

Classes

Orcid	Search ORCID for people, fetch one record, and make a profile from it.
Ror	Search ROR for organizations, fetch one record, and make a profile from it.

Functions

ask	Request an address from a registry and read its answer, unless it is kept.

Data

RESULTS_SHOWN	The most matches a search returns.
TIMEOUT	The seconds a registry has to answer.
KEPT	The seconds an answer is kept, so that a repeated lookup asks the registry once.
JSON

API

RESULTS_SHOWN

10

The most matches a search returns.

TIMEOUT

5

The seconds a registry has to answer.

KEPT

300

The seconds an answer is kept, so that a repeated lookup asks the registry once.

JSON

None

exception RegistryUnavailable

Bases: Exception

Signal that a registry could not be asked or its answer could not be read.

Raised for a network error, a timeout, an answer that is not a success and an answer that is not in the form the registry documents.

Initialization

Initialize self. See help(type(self)) for accurate signature.

ask(address, parse, *, params=None, headers=None, missing_ok=False)

Request an address from a registry and read its answer, unless it is kept.

What a registry answers is kept for KEPT seconds in the default cache, under the address, the parameters and the active language, since an answer is read into text in that language. “There is no such record” is an answer and is kept. A failure is not, so the next request asks again.

Args: address: The address, which no search term is ever part of. parse: A function that turns the decoded answer into what the caller wants. params: Query parameters, which requests encodes. headers: Request headers. missing_ok: Whether a 404 is an answer (“there is no such record”) rather than a failure.

Returns: What parse returns, or None for a 404 when missing_ok is true.

Raises: RegistryUnavailable: The request failed, the answer was not a 200, or parse could not read it.

class Orcid

Search ORCID for people, fetch one record, and make a profile from it.

A record is a dictionary with id and shown_id (the ORCID iD), name, given, family, employer (the first current employer, or an empty string) and detail (what tells namesakes apart).

SEARCH

‘https://pub.orcid.org/v3.0/expanded-search/’

RECORD

‘https://pub.orcid.org/v3.0/{}/record’

identifier_in(text)

Pick an ORCID iD out of text that is one, or an address of one.

Args: text: A search term or an identifier.

Returns: The bare iD, or None when the text is not in the form of one.

search(term)

Search by name, or by iD when the term is one.

Args: term: A name, an ORCID iD or the address of one.

Returns: {"results": [...], "more": bool}: at most RESULTS_SHOWN records of people with a public name, and whether the registry holds more matches than that.

Raises: RegistryUnavailable: ORCID could not be asked or answered badly.

results_from(body)

Read a search answer, leaving out records with no public name.

Args: body: The decoded answer of the search.

Returns: The results and the flag, as search returns them.

found_in(entry)

Shape one search result.

Args: entry: One item of the answer’s expanded-result.

Returns: The record, or None when the person has no public name.

record_of(orcid_id, given, family, employer, place='')

Shape a person for the templates, or return None when there is no name.

Args: orcid_id: The bare ORCID iD. given: The given names, possibly empty. family: The family name, possibly empty. employer: The name of the current employer, possibly empty. place: Where the employer is, possibly empty.

Returns: The record, or None when both names are empty.

fetch(identifier)

Fetch one person’s public record.

An identifier that is not in the form of an ORCID iD is refused before any request is made.

Args: identifier: The bare ORCID iD, or its address.

Returns: The record, or None when the identifier is malformed, ORCID has no such record, or the record has no public name.

Raises: RegistryUnavailable: ORCID could not be asked or answered badly.

read_record(orcid_id, body)

Read a record answer: the public name and the first current employer.

Args: orcid_id: The iD that was asked for. body: The decoded answer.

Returns: The record, or None when the person has no public name.

known(record)

Find the person the portal already holds under the record’s ORCID iD.

Args: record: A record from search or fetch.

Returns: The person, or None.

profile(record)

Return the person the portal holds under the iD, or make one.

A person made here has the name and the iD, no email address, an unusable password and no account.

Args: record: A record from search or fetch.

Returns: The person.

class Ror

Search ROR for organizations, fetch one record, and make a profile from it.

A record is a dictionary with id (the ROR address), shown_id (the address without its scheme), name (ROR’s display name) and detail (its kind and where it is).

SEARCH

‘https://api.ror.org/v2/organizations’

RECORD

‘https://api.ror.org/v2/organizations/{}’

identifier_in(text)

Pick a ROR ID out of text that is one, or an address of one.

Args: text: A search term or an identifier.

Returns: The bare ID, or None when the text is not in the form of one.

search(term)

Search by name, or by ID when the term is one.

Args: term: A name, a ROR ID or the address of one.

Returns: {"results": [...], "more": bool}: at most RESULTS_SHOWN active organizations, and whether the registry holds more matches than that.

Raises: RegistryUnavailable: ROR could not be asked or answered badly.

results_from(body)

Read a search answer, leaving out organizations that are not active.

Args: body: The decoded answer of the search.

Returns: The results and the flag, as search returns them.

record_of(item)

Shape one organization for the templates, or return None when it cannot be chosen.

Args: item: An organization as ROR describes it.

Returns: The record, or None when the organization is not active or has no display name.

fetch(identifier)

Fetch one organization’s record.

An identifier that is not in the form of a ROR ID is refused before any request is made.

Args: identifier: The bare ROR ID, or its address.

Returns: The record, or None when the identifier is malformed, ROR has no such record, or the organization is not active.

Raises: RegistryUnavailable: ROR could not be asked or answered badly.

known(record)

Find the organization the portal already holds under the record’s ROR ID.

Args: record: A record from search or fetch.

Returns: The organization, or None.

profile(record)

Return the organization the portal holds under the ID, or make one.

An organization made here has the name and the ID.

Args: record: A record from search or fetch.

Returns: The organization.