viapy Code Documentation

API

class viapy.api.SRUItem(items=None, sequence_type=<class 'tuple'>)

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

The VIAFCluster attribute was added to each property lookup in 2025 to match updates to the /search API’s JSON response.

property label

first main heading for this item

property nametype

type of name (personal, corporate, title, etc)

property uri

VIAF URI for this result

property viaf_id

VIAF numeric identifier

class viapy.api.SRUResult(data)

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

normalize_record(data)

Added in May 2025 to match updates to the /search API records, where the JSON response now uses namespaced keys that increase per result: ns2, ns3, ns4, and so on, applying to most subkeys (ns2:VIAFCluster, ns2:Document, etc). This method strips all nsX: prefixes recursively

records

List of results as SRUItem.

total_results

number of records matching the query

class viapy.api.ViafAPI

Wrapper for VIAF API.

https://platform.worldcat.org/api-explorer/apis/VIAF

api_base = 'https://www.viaf.org/viaf'

base url for VIAF API methods

find_corporate(name)

Search VIAF for local.corporateNames

find_person(name)

Search VIAF for local.personalNames

find_place(name)

Search VIAF for local.geographicNames

search(query)

Query VIAF search interface. Returns a list of SRUItem :param query: CQL query in viaf syntax (e.g., cql.any all "term")

suggest(term)

Query autosuggest API. Returns a list of results, or an empty list if no suggestions are found or if something went wrong

uri_base = 'http://viaf.org/viaf'

base url for VIAF URIs

classmethod uri_from_id(viaf_id)

Generate a canonical VIAF URI for the specified id

class viapy.api.ViafEntity(viaf_id)

Object for working with a single VIAF entity.

Parameters:

viaf_id – viaf identifier (either integer or uri)

property birthdate

schema birthdate as rdflib.Literal

property birthyear

birth year

property deathdate

schema deathdate as rdflib.Literal

property deathyear

death year

rdf

VIAF data for this entity as rdflib.Graph

property uriref

VIAF URI reference as instance of rdflib.URIRef

classmethod year_from_isodate(date)

Return just the year portion of an ISO8601 date. Expects a string, returns an integer. Supports negative dates.

Views

class viapy.views.ViafLookup(**kwargs)

View to provide VIAF suggestions for autocomplete lookup. Based on dal.autocompleteSelect2ListView. Expects search term as query string parameter q. Returns viaf URI as identifier and display form as text.

get(request, *args, **kwargs)

Return JSON with suggested VIAF ids and display names.

class viapy.views.ViafSearch(**kwargs)

View to provide VIAF suggestions for autocomplete lookup. Based on dal.autocompleteSelect2ListView. Expects search term as query string parameter q. Returns viaf URI as identifier and display form as text.

get(request, *args, **kwargs)

Return JSON with suggested VIAF ids and display names.

Widgets

class viapy.widgets.ViafWidget(url=None, forward=None, *args, **kwargs)

Custom autocomplete select widget that displays VIAF id as a link. Extends dal.autocomplete.Select2.

property media

Return JS/CSS resources for the widget.

render(name, value, renderer=None, attrs=None)

Call Django render together with render_forward_conf.