eulfedora.api
- Fedora API access¶
API wrapper¶
-
class
eulfedora.api.
ApiFacade
(base_url, username=None, password=None)¶ Provide access to both
REST_API
andAPI_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 ineulfedora.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 bygetDatastream()
, 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 istriples
; list of dictionaries (keys based on return fields) when type istuples
-
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
-
spo_search
(subject=None, predicate=None, object=None)¶ 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
-