eulfedora.api - Fedora API access

API wrapper

class eulfedora.api.ApiFacade(base_url, username=None, password=None)

Provide access to both REST_API and API_A_LITE.

REST API

class eulfedora.api.REST_API(base_url, username=None, password=None, retries=None)

Python object for accessing Fedora’s REST API.

Most methods return an HTTP requests.models.Response, which provides access to status code and headers as well as content. Many responses with XML content can be loaded using models in eulfedora.xml.

addDatastream(pid, dsID, dsLabel=None, mimeType=None, logMessage=None, controlGroup=None, dsLocation=None, altIDs=None, versionable=None, dsState=None, formatURI=None, checksumType=None, checksum=None, content=None)

Add a new datastream to an existing object. On success, the return response should have a status of 201 Created; if there is an error, the response body includes the error message.

Parameters:
  • pid – object pid
  • dsID – id for the new datastream
  • dslabel – label for the new datastream (optional)
  • mimeType – mimetype for the new datastream (optional)
  • logMessage – log message for the object history (optional)
  • controlGroup – control group for the new datastream (optional)
  • dsLocation – URL where the content should be ingested from
  • altIDs – alternate ids (optional)
  • versionable – configure datastream versioning (optional)
  • dsState – datastream state (optional)
  • formatURI – datastream format (optional)
  • checksumType – checksum type (optional)
  • checksum – checksum (optional)
  • content – datastream content, as a file-like object or characterdata (optional)
Return type:

requests.models.Response
addRelationship(pid, subject, predicate, object, isLiteral=False, datatype=None)

Wrapper function for Fedora REST API addRelationship

Parameters:
  • pid – persistent id for the object to add the new relationship to
  • subject – subject of the relationship; object or datastream URI
  • predicate – predicate of the new relationship
  • object – object of the relationship
  • isLiteral – true if object is literal, false if it is a URI; Fedora has no default; this method defaults to False
  • datatype – optional datatype for literal objects
Returns:

boolean success
compareDatastreamChecksum(pid, dsID, asOfDateTime=None)

Compare (validate) datastream checksum. This is a special case of getDatastream(), with validate checksum set to True. Fedora will recalculate the checksum and compare it to the stored value. Response is the same content returned by getDatastream(), with validation result included in the xml.

Return type:requests.models.Response
export(pid, context=None, format=None, encoding=None, stream=False)

Export an object to be migrated or archived.

Parameters:
  • pid – object pid
  • context – export context, one of: public, migrate, archive (default: public)
  • format – export format (Fedora default is foxml 1.1)
  • encoding – encoding (Fedora default is UTF-8)
  • stream – if True, request a streaming response to be read in chunks
Return type:

requests.models.Response
findObjects(query=None, terms=None, pid=True, chunksize=None, session_token=None)

Wrapper function for Fedora REST API findObjects and Fedora REST API resumeFindObjects

One and only one of query or terms must be specified.

Parameters:
  • query – string of fields and terms to search for
  • terms – phrase search across all fields
  • pid – include pid in search results
  • chunksize – number of objects to return at a time
  • session_token – get an additional chunk of results from a prior search
  • parse – optional data parser function; defaults to returning raw string data
Return type:

requests.models.Response
getDatastream(pid, dsID, asOfDateTime=None, validateChecksum=False)

Get information about a single datastream on a Fedora object; optionally, get information for the version of the datastream as of a particular date time.

Parameters:
  • pid – object pid
  • dsID – datastream id
  • asOfDateTime – optional datetime; must be a non-naive datetime so it can be converted to a date-time format Fedora can understand
  • validateChecksum – boolean; if True, request Fedora to recalculate and verify the stored checksum against actual data
Return type:

requests.models.Response
getDatastreamDissemination(pid, dsID, asOfDateTime=None, stream=False, head=False, rqst_headers=None)

Get a single datastream on a Fedora object; optionally, get the version as of a particular date time.

Parameters:
  • pid – object pid
  • dsID – datastream id
  • asOfDateTime – optional datetime; must be a non-naive datetime so it can be converted to a date-time format Fedora can understand
  • stream – return a streaming response (default: False); use is recommended for large datastreams
  • head – return a HEAD request instead of GET (default: False)
  • rqst_headers – request headers to be passed through to Fedora, such as http range requests
Return type:

requests.models.Response
getDatastreamHistory(pid, dsid, format=None)

Get history information for a datastream.

Parameters:
  • pid – object pid
  • dsid – datastream id
  • format – format
Return type:

requests.models.Response
getDissemination(pid, sdefPid, method, method_params=None)

Get a service dissemination.

Parameters:
  • pid – object pid
  • sDefPid – service definition pid
  • method – service method name
  • method_params – method parameters
Return type:

requests.models.Response
getNextPID(numPIDs=None, namespace=None)

Wrapper function for Fedora REST API getNextPid

Parameters:
  • numPIDs – (optional) get the specified number of pids; by default, returns 1
  • namespace – (optional) get the next pid in the specified pid namespace; otherwise, Fedora will return the next pid in the configured default namespace.
Return type:

string (if only 1 pid requested) or list of strings (multiple pids)
getObjectHistory(pid)

Get the history for an object in XML format.

Parameters:pid – object pid
Return type:requests.models.Response
getObjectProfile(pid, asOfDateTime=None)

Get top-level information aboug a single Fedora object; optionally, retrieve information as of a particular date-time.

Parameters:
  • pid – object pid
  • asOfDateTime – optional datetime; must be a non-naive datetime so it can be converted to a date-time format Fedora can understand
Return type:

requests.models.Response
getObjectXML(pid)

Return the entire xml for the specified object.

Parameters:pid – pid of the object to retrieve
Return type:requests.models.Response
getRelationships(pid, subject=None, predicate=None, format=None)

Get information about relationships on an object.

Wrapper function for
Fedora REST API getRelationships
Parameters:
  • pid – object pid
  • subject – subject (optional)
  • predicate – predicate (optional)
  • format – format
Return type:

requests.models.Response
ingest(text, logMessage=None)

Ingest a new object into Fedora. Returns the pid of the new object on success. Return response should have a status of 201 Created on success, and the content of the response will be the newly created pid.

Wrapper function for Fedora REST API ingest

Parameters:
  • text – full text content of the object to be ingested
  • logMessage – optional log message
Return type:

requests.models.Response
listDatastreams(pid)

Get a list of all datastreams for a specified object.

Wrapper function for Fedora REST API listDatastreams

Parameters:
  • pid – string object pid
  • parse – optional data parser function; defaults to returning raw string data
Return type:

requests.models.Response
listMethods(pid, sdefpid=None)

List available service methods.

Parameters:
  • pid – object pid
  • sDefPid – service definition pid
Return type:

requests.models.Response
modifyDatastream(pid, dsID, dsLabel=None, mimeType=None, logMessage=None, dsLocation=None, altIDs=None, versionable=None, dsState=None, formatURI=None, checksumType=None, checksum=None, content=None, force=False)

Modify an existing datastream, similar to addDatastraem(). Content can be specified by either a URI location or as string content or file-like object; if content is not specified, datastream metadata will be updated without modifying the content.

On success, the returned response should have a status code 200; on failure, the response body may include an error message.

Parameters:
  • pid – object pid
  • dsID – id for the new datastream
  • dslabel – label for the new datastream (optional)
  • mimeType – mimetype for the new datastream (optional)
  • logMessage – log message for the object history (optional)
  • dsLocation – URL where the content should be ingested from (optional)
  • altIDs – alternate ids (optional)
  • versionable – configure datastream versioning (optional)
  • dsState – datastream state (optional)
  • formatURI – datastream format (optional)
  • checksumType – checksum type (optional)
  • checksum – checksum (optional)
  • content – datastream content, as a file-like object or characterdata (optional)
  • force – force the update (default: False)
Return type:

requests.models.Response
modifyObject(pid, label, ownerId, state, logMessage=None)

Modify object properties. Returned response should have a status of 200 on succuss.

Parameters:
  • pid – object pid
  • label – object label
  • ownerId – object owner
  • state – object state
  • logMessage – optional log message
Return type:

requests.models.Response
purgeDatastream(pid, dsID, startDT=None, endDT=None, logMessage=None, force=False)

Purge a datastream, or specific versions of a dastream, from a Fedora object. On success, response content will include a list of timestamps for the purged datastream versions; on failure, response content may contain an error message.

Parameters:
  • pid – object pid
  • dsID – datastream ID
  • startDT – optional start datetime (when purging specific versions)
  • endDT – optional end datetime (when purging specific versions)
  • logMessage – optional log message
Return type:

requests.models.Response
purgeObject(pid, logMessage=None)

Purge an object from Fedora. Returned response shoudl have a status of 200 on success; response content is a timestamp.

Wrapper function for REST API purgeObject

Parameters:
  • pid – pid of the object to be purged
  • logMessage – optional log message
Return type:

requests.models.Response
purgeRelationship(pid, subject, predicate, object, isLiteral=False, datatype=None)

Remove a relationship from an object.

Wrapper function for Fedora REST API purgeRelationship

Parameters:
  • pid – object pid
  • subject – relationship subject
  • predicate – relationship predicate
  • object – relationship object
  • isLiteral – boolean (default: false)
  • datatype – optional datatype
Returns:

boolean; indicates whether or not a relationship was removed
setDatastreamState(pid, dsID, dsState)

Update datastream state.

Parameters:
  • pid – object pid
  • dsID – datastream id
  • dsState – datastream state
Returns:

boolean success
setDatastreamVersionable(pid, dsID, versionable)

Update datastream versionable setting.

Parameters:
  • pid – object pid
  • dsID – datastream id
  • versionable – boolean
Returns:

boolean success
upload(data, callback=None, content_type=None, size=None)

Upload a multi-part file for content to ingest. Returns a temporary upload id that can be used as a datstream location.

Parameters:
  • data – content string, file-like object, or iterable with content to be uploaded
  • callback – optional callback method to monitor the upload; see requests-toolbelt documentation for more details: https://toolbelt.readthedocs.org/en/latest/user.html#uploading-data
  • content_type – optional content type of the data
  • size – optional size of the data; required when using an iterable for the data
Returns:

upload id on success

API_A_LITE

class eulfedora.api.API_A_LITE(base_url, username=None, password=None, retries=None)
Python object for accessing Fedora’s API-A-LITE.

Note

As of Fedora 3.4, the previous “LITE” APIs are deprecated; this APIis maintained because the REST API covers all functionality except describeRepository.

describeRepository()

Get information about a Fedora repository.

Return type:requests.models.Response

Resource Index

class eulfedora.api.ResourceIndex(base_url, username=None, password=None, retries=None)

Python object for accessing Fedora’s Resource Index.

RISEARCH_FLUSH_ON_QUERY = False

Specify whether or not RI search queries should specify flush=true to obtain the most recent results. If flush is specified to the query method, that takes precedence.

Irrelevant if Fedora RIsearch is configured with syncUpdates = True.

count_statements(query, language=u'spo', type=u'triples', flush=None)

Run a query in a format supported by the Fedora Resource Index (e.g., SPO or Sparql) and return the count of the results.

Parameters:
  • query – query as a string
  • language – query language to use; defaults to ‘spo’
  • flush – flush results to get recent changes; defaults to False
Return type:

integer
find_statements(query, language=u'spo', type=u'triples', flush=None, limit=None)

Run a query in a format supported by the Fedora Resource Index (e.g., SPO or Sparql) and return the results.

Parameters:
  • query – query as a string
  • language – query language to use; defaults to ‘spo’
  • type – type of query - tuples or triples; defaults to ‘triples’
  • flush – flush results to get recent changes; defaults to False
Return type:

rdflib.ConjunctiveGraph when type is triples; list of dictionaries (keys based on return fields) when type is tuples
get_objects(subject, predicate)

Search for all subjects related to the specified subject and predicate.

Parameters:
  • subject –
  • object –
Return type:

generator of RDF statements
get_predicates(subject, object)

Search for all subjects related to the specified subject and object.

Parameters:
  • subject –
  • object –
Return type:

generator of RDF statements
get_subjects(predicate, object)

Search for all subjects related to the specified predicate and object.

Parameters:
  • predicate –
  • object –
Return type:

generator of RDF statements
sparql_count(query, flush=None)

Count results for a Sparql query.

Parameters:query – sparql query string
Return type:int
sparql_query(query, flush=None, limit=None)

Run a Sparql query.

Parameters:query – sparql query string
Return type:list of dictionary

Create and run a subject-predicate-object (SPO) search. Any search terms that are not specified will be replaced as a wildcard in the query.

Parameters:
  • subject – optional subject to search
  • predicate – optional predicate to search
  • object – optional object to search
Return type:

rdflib.ConjunctiveGraph
spoencode(val)

Encode search terms for an SPO query.

Parameters:val – string to be encoded
Return type:string