API¶

class loc_authorities.api.LocAPI¶

Wrapper for Library of Congress API.

https://id.loc.gov/

classmethod uri_from_id(loc_id)¶: Generate a URL for performing initial queries

classmethod dataset_uri_from_id(loc_id)¶: Generate a URI for RDF triples based on LoC dataset

classmethod rwo_uri_from_id(loc_id)¶: Generate RWO URI for linked data queries

suggest(query, authority: Literal[None, 'names', 'subjects'] = None)¶

Query LoC’s suggest service API using left-anchored search. Returns a list of results, or an empty list for no results or an error.

Querying the older Suggest 1.0 is not implemented.

Parameters:

query – Search query (string)
authority – LoC authority to search. Supports names or subjects

search(query, authority: Literal[None, 'names', 'subjects'])¶

Query LoC’s suggest service API using keyword search. Returns a list of search results, or an empty list for an error.

Parameters:

query – Search query (string)
authority – Authority to search (‘names’ or ‘subjects’)

retrieve_label(label, authority=None)¶

Query LoC’s label retrieval API to return a URI from a known label

Parameters:

label – The label to retrieve (string)
authority – the name of the authority to query. Defaults to None

class loc_authorities.api.LocEntity(loc_id)¶

Object to represent single LoC entity

Parameters:: loc_id – LoC identifier (string)

property uriref¶: LoC URI reference as instance of rdflib.URIRef

property dataset_uriref¶: LoC URI reference that includes LCNAF dataset marker as instance of rdflib.URIRef

property rdf¶: LoC data for this entity as rdflib.Graph

property authoritative_label¶: Authoritative entity label in English

property scheme_membership¶: LoC scheme that represents this entity as instance of rdflib.URIRef

property instance_of¶: Linked Data authorities that describe this entity as list of instances of rdflib.URIRef

class loc_authorities.api.NameEntity(loc_id)¶

Object to represent single entity from the LoC Name Authority File. Inherits LocEntity.

Parameters:: loc_id – LoC identifier (string)

property rwo_uriref¶: LoC RWO URI reference as instance of rdflib.URIRef

property birthdate¶: MADS birthday as rdflib.term.Literal

property deathdate¶: MADS deathdate as rdflib.term.Literal

property birthyear¶: birth year as int

property deathyear¶: death year as int

classmethod year_from_edtf(date)¶: Return just the year from EDTF date. Expects a string, returns an integer. Normalizes uncertain years. Supports negative dates. No support for partially unknown years.

class loc_authorities.api.TemporalEntity(label)¶

Container to representa temporal subject. Most temporal subjects are not indexed in LoC, so this container provides minimal RDF to capture the schema. Temporal entities that are indexed should be instantiated as SubjectEntity.

Overrides LocEntity methods to return None where the property does not exist.

Parameters:: label – the text of the authoritative label (string)

property uriref¶: LoC URI reference as instance of rdflib.URIRef

property dataset_uriref¶: LoC URI reference that includes LCNAF dataset marker as instance of rdflib.URIRef

property rdf¶: Basic linked data for this entity as rdflib.Graph

property authoritative_label¶: Authoritative entity label in English

property scheme_membership¶: Since temporal entities are not indexed, returns None.

class loc_authorities.api.SubjectEntity(loc_id)¶

Object to represent single entity from the LoC Subject Headings authority. Inherits LocEntity.

Parameters:: loc_id – LoC identifier (string)

property components¶: Components for LoC Complex subjects. If subject is complex, returns a list of SubjectEntity and NameEntity objects. If subject is simple, returns TemporalEntity.

class loc_authorities.api.DummyComplexEntity(components)¶

Container to represent a complex topic that does not have a URI but contains all valid subcomponents.

Parameters:: components – URIs or tempoal labels for subcomponents (list)

property uriref¶: LoC URI reference as instance of rdflib.URIRef

property dataset_uriref¶

LoC URI reference that includes LCNAF dataset marker as instance of rdflib.BNode

For queries to work, this is a cached property. It persists during one session, but not between sessions.

property rdf¶: Basic linked data for this entity as rdflib.Graph

property components¶: Components for LoC Complex subjects. If subject is complex, returns a list of SubjectEntity and NameEntity objects. If subject is simple, returns TemporalEntity.

property authoritative_label¶: Authoritative entity label in English

property scheme_membership¶: Since entities are not indexed, returns None.

class loc_authorities.api.SRUResult(data)¶

SRU search result object, for use with LocAPI.search().

property records¶: List of results as SRUItem.

class loc_authorities.api.SRUItem(data)¶

Single item returned by a SRU search, for use with LocAPI.search() and SRUResult.

property uri¶: LoC URI for this result

property loc_id¶: LoC ID string for this result

property label¶: Authoritative label for this result

Forms¶

class loc_authorities.forms.LocWidget(url=None, forward=None, *args, **kwargs)¶: Wrapper for dal widget. Expects a URL parameter that matches the namespace for loc-authorities and one of the loc-authorities views (suggest, name-suggest, subject-suggest, name-search, subject-search).

class loc_authorities.forms.LocField(choice_list=[], *args, **kwargs)¶

Wrapper for dal field as it requires a predefined choice-list, which for this use case is always empty.

Pass LocWidget as this field’s widget to specify the URL you would like to query.

Views¶

class loc_authorities.views.LocLookup(**kwargs)¶: View to provide Library of Congress suggestions for autocomplete lookup. Based on dal.autocomplete.AlightListView. Expects search term as query string parameter `q. Returns the LoC identifier and displays the label as text.

class loc_authorities.views.LocNameLookup(**kwargs)¶: View to provide Library of Congress suggestions from the Name Authority File for autocomplete lookup. Behaves like LocLookup but only returns name authority records.

class loc_authorities.views.LocSubjectLookup(**kwargs)¶: View to provide Library of Congress suggestions from the LC Subject Headings for autocomplete lookup. Behaves like LocLookup but only returns subject heading records.

class loc_authorities.views.LocSearch(**kwargs)¶: View to perform keyword search from Library of Congress to provide autocomplete suggestions. As searching without a authority is unsupported in loc-authorities, this is an abstract class to provide functionality for specific authorities. Based on dal.autocomplete.AlightListView. Expects search term as query string parameter `q. Returns the LoC identifier and displays the label as text.

class loc_authorities.views.LocNameSearch(**kwargs)¶: View to perform keyword search from the Library of Congress Name Authority File for autocomplete lookup. Inherits from LocSearch and only returns name authority records.

class loc_authorities.views.LocSubjectSearch(**kwargs)¶: View to perform keyword search from the Library of Congress Subject Headings for autocomplete lookup. Inherits from LocSearch and only returns subject heading records.