The oaipmh module implements the OAI-PMH protocol. It encapsulates this protocol in Python, so that a request to the OAI-PMH server is just a method call from the Python perspective. The XML data that is returned from the server is processed as well, and returned as Python objects.
class ServerProxy(uri [, metadataSchemaRegistry])
A ServerProxy instance is an object that manages communication with the remote OAI-PMH server. The required first argument is the URI that accepts OAI-PMH requests.
The second optional argument is a MetadataSchemaRegistry instance. This registry contains the metadata schemas that are understood by client. If it isn't supplied, a default and global schema registry will be used, with at least support for the oai_dc metadata scheme.
The returned instance is a proxy object with methods that can be used to invoke the corresponding OAI-PMH requests to the server. The methods are named after the corresponding verbs of the OAI-PMH protocol, though start with a lowercase letter to follow Python camelCase conventions.
The methods take zero or more keyword arguments; non-keyword arguments are not supported. The methods do some automatic checking to determine whether the right combination of arguments is used.
The section Protocol Requests and Responses of the OAI-PMH standard describes the verbs (and thus methods) and the allowed arguments combinations.
getRecord(identifier, metadataPrefix)
Returns a header, metadata, about tuple for the identified item.identify()
Get server identification information. This returns a ServerIdentify instance.listIdentifiers(metadataPrefix [, from_ [, until [, set [, resumptionToken [, max]]]]])
Returns a lazy sequence of Header instances.
The result can be restricted using from_ and until arguments.
The result can be restricted for one particular set.
listMetadataFormats([identifier])
If identifier is not specified, returns a list of metadataPrefix, schema, metadataNamespace tuples for this OAI-PMH repository.
If identifier is specified, returns a list of tuples for the metadata associated with the identified item.
metadataPrefix is a short string to uniquely identify the metadata format for this OAI-PMH repository.
schema is a URI to the XML schema describing the metadata format.
metadataNamespace is a namespace URI used for to identify XML content in this metadata format.
listRecords(metadataPrefix [, from_ [, until [, set [, resumptionToken [, max]]]]])
Returns a lazy sequence of header, metadata, about tuples for items in the repository.
The result can be restricted using from_ and until arguments.
The result can be restricted for one particular set.
listSets([resumptionToken [, max]])
Returns a lazy sequence of setSpec, setName, setDescription tuples.
setSpec is the repository-unique name of a set. It may be partioned into a hierarchy using a colon. See the section Set of the OAI-PMH standard for more information.
setName is the name of the set as it should be displayed to end-users.
At the of writing setDescription is not yet supported by the oaipmh module, and this element of the tuple will always be None.
The following methods pertain to the metadata schema system.
addMetadataSchema(schema)
Add a MetadataSchema instance to the ServerProxy. The server will then be able to create Metadata instances for metadata in the format handled by the MetadataSchema instance.getMetadataSchemaRegistry()
Get the MetadataSchemaRegistry instance that handles metadata for this ServerProxy instance.
class Header(..)
identifier()
Returns the unique identifier of this item in this repository. The identifier must be in URI form. Some repositories may for instance implement this as handles (see www.handle.net).
See the Unique Identifier section of the OAI-PMH standard for more information.
datestamp()
Returns the time at which this item was added or last updated within the repository. This is in string form, in UTCdatetime format.setSpec()
Returns a list of the sets this item is in. The object may be in zero or more sets. Sets are represented as strings. See also the section Set of the OAI-PMH standard.isDeleted()
Returns true if this item is deleted from the server, and this is a delete notification.
class Metadata(..)
getMap()
Returns a dictionary with as key the metadata field names and as values the metadata values, as extracted from the XML.getField(name)
Returns the metadata value for metadata field name name.
There is also a dictionary API that is the equivalent of getField; metadata[name].
class SeverIdentify(..)
repositoryName()
Returns the human readable name of the repository.baseURL()
Returns the base URL for the repository (which can receive OAI-PMH requests).protocolVersion()
Returns the version of the OAI-PMH protocol supported by the repository.earliestDatestamp()
Returns a UTCdatetime that is the guaranteed earliest datestamp that can occur in headers.deletedRecord()
Returns an string indicating how the repository deals with deleted records.
no
The repository does not support deleted records in the protocol. If records are deleted they don't appear anymore, but no special information is returned about them.transient
Deleted records will be returned with isDeleted status in the header set as true but these will not be returned forever.persistent
Deleted record information is stored permanently by the server and will be returned with isDeleted status as true if the deleted item is accessed.granularity()
Returns either YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ. This determines the finest granularity of timestamps returned by the server.adminEmails()
Returns a list of one or more email addresses of server admins.compression()
Returns the compression encoding supported by the repository.description()
Not yet implemented.
class MetadataSchema(metadata_prefix, namespaces)
Instances of this class describe ways to turn an XML representation of metadata into python Metadata instances. Fields are described by a name, a type and a way to retrieve the field information (in the form of a string or a list of strings) from the XML representation. The latter is described by an XPath expression. This way other metadata schemas can be represented in Python by adding a new MetadataSchema to the ServerProxy's metadata schema registry.
addFieldDescription(field_name, field_type, xpath)
Add a field description to the metadata schema.
field_name
The name of the field in the Metadata instances generated according to this schema.field_type
A string indicating the data type of the metadata field. bytes indicates an 8-bit string, bytesList indicates a list of such strings, text indicates a unicode string and textList indicates a list of unicode strings.xpath
And XPath expression that is executed from the top of the particular metadata section in the retrieved XML. This expression indicates how to retrieve the metadata.
class MetadataSchemaRegistry()
Instances of this class store a number of MetadataSchema instances. These handle metadata found in OAI-PMH XML resultsets according to their metadata_prefix.
addMetadataSchema(metadata_schema)
Add a MetadataSchema instance to this registry.
header is a Header instance.
metadata is a Metadata instance if the metadataPrefix argument is in a registered format, or None if the metadataPrefix is not recognized.
At the time of writing about support has not yet been implemented and will always be returned as None.
The from_ and until arguments are optional and can be used to restrict the result to information about items which were added or modified after from_ and before until. from_ is spelled with the extra _ because from (without underscore) is a reserved keyword in Python. If only from_ is used there is no lower limit, it only until is used there is no upper limit. Both arguments should be strings in OAI-PMH datestamp format (i.e. YYY-MM-DDDThh:mm:ssZ). See the UTCdatetime section of the OAI-PMH standard for more information.
The list is lazy in that while you can loop through it, it behaves more like an iterator than a real list (it would be a real Python 2.2+ iterator if Python 2.1 did not need to be supported by this module). The system automatically asks for the next resumptionToken if one was in the reply. While you can explicitly pass a resumptionToken this is therefore not very useful as the lazy lists take care of resumptionTokens automatically.
The optional max argument is not part of the OAI-PMH protocol, but a coarse way to control how many items are read before stopping. If the amount of items exceeds max after reading a resumptionToken, the method will halt.