"""

def __init__(self, service_document_iri=None,

user_name=None,

user_pass=None,

on_behalf_of=None,

download_service_document = False, # Don't automagically GET the SD_IRI by default

keep_history=True,

cache_deposit_receipts=True,

honour_receipts=True,

error_response_raises_exceptions=True,

# http layer implementation if different from default

http_impl=None,

ca_certs=None):

"""

self.sd_iri = service_document_iri

self.sd = None

# Client behaviour flags:

# Honour deposit receipts - eg raise exceptions if interactions are attempted that the service document

# does not allow without bothering the server - invalid packaging types, max upload sizes, etc

self.honour_receipts = honour_receipts

# When error_response_raises_exceptions == True:

# Error responses (HTTP codes >399) will raise exceptions (from sword2.exceptions) in response

# when False:

# Error Responses, if Content-Type is text/xml or application/xml, a sword2.error_document.Error_Document will be the

# return - No Exception will be raised!

# Check Error_Document.code to get the response code, regardless to whether a valid Sword2 error document was received.

self.raise_except = error_response_raises_exceptions

self.keep_cache = cache_deposit_receipts

# set the http layer

if http_impl is None:

conn_l.info("Loading default HTTP layer")

self.h = http_layer.HttpLib2Layer(".cache", timeout=30.0, ca_certs=ca_certs)

else:

conn_l.info("Using provided HTTP layer")

self.h = http_impl

self.user_name = user_name

self.on_behalf_of = on_behalf_of

# Cached Deposit Receipt 'indexes' *cough, cough*

self.edit_iris = {} # Key = IRI, Value = ref to latest Deposit Receipt for the resource

self.cont_iris = {} # Key = IRI, Value = ref to latest Deposit Receipt

self.se_iris = {} # Key = IRI, Value = ref to latest Deposit Receipt

self.cached_at = {} # Key = Edit-IRI, Value = Timestamp for when receipt was cached

# Transaction history hooks

self.history = None

self._t = Timer()

self.keep_history = keep_history

if keep_history:

conn_l.info("keep_history=True--> This instance will keep a JSON-compatible transaction log of all (SWORD/APP) activities in 'self.history'")

self.reset_transaction_history()

self.history.log('init',

sd_iri = self.sd_iri,

user_name = self.user_name,

on_behalf_of = self.on_behalf_of )

# Add credentials to http client

if user_name:

conn_l.info("Adding username/password credentials for the client to use.")

self.h.add_credentials(user_name, user_pass)

if self.sd_iri and download_service_document:

self._t.start("get_service_document")

self.get_service_document()

conn_l.debug("Getting service document and dealing with the response: %s s" % self._t.time_since_start("get_service_document")[1])

def _return_error_or_exception(self, cls, resp, content):

"""Internal method for reporting errors, behaving as the `self.raise_except` flag requires.

if self.raise_except:

raise cls(resp, content)

else:

# content type can contain both the mimetype and the charset (e.g. text/xml; charset=utf-8)

if resp.get('content-type', "").startswith("text/xml") or resp.get('content-type', "").startswith("application/xml"):

conn_l.info("Returning an error document, due to HTTP response code %s" % resp.status)

e = Error_Document(content, code=resp.status, resp = resp)

return e

else:

conn_l.info("Returning due to HTTP response code %s" % resp.status)

e = Error_Document(code=resp.status, resp = resp)

return e

def _handle_error_response(self, resp, content):

"""Catch a number of general HTTP error responses from the server, based on HTTP code

conn_l.debug("Error body received from server: {x}".format(x=str(content)))

if resp['status'] == 401:

conn_l.error("You are unauthorised (401) to access this document on the server. Check your username/password credentials and your 'On Behalf Of'")

return self._return_error_or_exception(NotAuthorised, resp, content)

elif resp['status'] == 403:

conn_l.error("You are Forbidden (403) to POST to '%s'. Check your username/password credentials and your 'On Behalf Of'")

return self._return_error_or_exception(Forbidden, resp, content)

elif resp['status'] == 406:

conn_l.error("Cannot negotiate for desired format/packaging on '%s'.")

return self._return_error_or_exception(NotAcceptable, resp, content)

elif resp['status'] == 408:

conn_l.error("Request Timeout (408) - error uploading.")

return self._return_error_or_exception(RequestTimeOut, resp, content)

elif int(resp['status']) > 499:

conn_l.error("Server error occured. Response headers from the server:\n%s" % resp)

return self._return_error_or_exception(ServerError, resp, content)

else:

conn_l.error("Unknown error occured. Response headers from the server:\n%s\n%s" % (resp, content))

return self._return_error_or_exception(HTTPResponseError, resp, content)

def _cache_deposit_receipt(self, d):

"""Method for storing the deposit receipts, and also for providing lookup dictionaries that

if self.keep_cache:

timestamp = self._t.get_timestamp()

conn_l.debug("Caching document (Edit-IRI:%s) - at %s" % (d.edit, timestamp))

self.edit_iris[d.edit] = d

if d.cont_iri: # SHOULD exist within receipt

self.cont_iris[d.cont_iri] = d

if d.se_iri:

# MUST exist according to the spec, but as it can be the same as the Edit-IRI

# it seems likely that a server implementation might ignore the 'MUST' part.

self.se_iris[d.se_iri] = d

self.cached_at[d.edit] = self._t.get_timestamp()

else:

conn_l.debug("Caching request denied - deposit receipt caching is set to 'False'")

def load_service_document(self, xml_document):

"""Load the Service Document XML from bytestring, `xml_document`

self._t.start("SD Parse")

self.sd = ServiceDocument(xml_document)

_, took_time = self._t.time_since_start("SD Parse")

# Set up some convenience references

self.workspaces = self.sd.workspaces

self.maxUploadSize = self.sd.maxUploadSize

if self.history:

if self.sd.valid:

self.history.log('SD Parse',

sd_iri = self.sd_iri,

valid = self.sd.valid,

workspaces_found = [k for k,v in self.sd.workspaces],

sword_version = self.sd.version,

maxUploadSize = self.sd.maxUploadSize,

process_duration = took_time)

else:

self.history.log('SD Parse',

sd_iri = self.sd_iri,

valid = self.sd.valid,

process_duration = took_time)

def get_service_document(self):

"""Perform an HTTP GET on the Service Document IRI (SD-IRI) and attempt to parse the result as

headers = {}

if self.on_behalf_of:

headers['on-behalf-of'] = self.on_behalf_of

self._t.start("SD_URI request")

resp, content = self.h.request(self.sd_iri, "GET", headers=headers)

_, took_time = self._t.time_since_start("SD_URI request")

if self.history:

self.history.log('SD_IRI GET',

sd_iri = self.sd_iri,

response = resp,

process_duration = took_time)

if resp['status'] == 200:

conn_l.info("Received a document for %s" % self.sd_iri)

self.load_service_document(content)

elif resp['status'] == 401:

conn_l.error("You are unauthorised (401) to access this document on the server. Check your username/password credentials")

else:

conn_l.error("Unexpected response status: " + str(resp['status']))

def reset_transaction_history(self):

""" Clear the transaction history - `self.history`"""

del self.history

self.history = Transaction_History()

def _make_request(self,

target_iri,

payload=None, # These need to be set to upload a file

mimetype=None,

filename=None,

packaging=None,

md5sum=None,

metadata_entry=None, # a sword2.Entry needs to be here, if

# a metadata entry is to be uploaded

entry_content_type="application/atom+xml; type=entry", # content type to use for the atom entry

# which means it can be overridden if the server has some special

# requirements (see: EPrints)

# Only works for singlepart deposit, multipart will have atom-specified mimetype in all cases

# Set both a file and a metadata entry for the method to perform a multipart

# related upload.

suggested_identifier=None, # 'slug'

in_progress=True,

on_behalf_of=None,

metadata_relevant=False,

# flags:

empty = None, # If this is True, then the POST/PUT is sent with an empty body

# and the 'Content-Length' header explicitly set to 0

method = "POST",

request_type="" # text label for transaction history reports

):

"""Performs an HTTP request, as defined by the parameters. This is an internally used method and it is best that it

if payload:

md5, f_size = get_md5(payload)

# this allows the user to pass in their own md5sum (this doesn't save

# any time, though, because of the above operation - useful mainly for

# testing at this stage

if md5sum is None:

md5sum = md5

# request-level headers

headers = {}

headers['In-Progress'] = str(in_progress).lower()

if on_behalf_of:

headers['On-Behalf-Of'] = on_behalf_of

elif self.on_behalf_of:

headers['On-Behalf-Of'] = self.on_behalf_of

if suggested_identifier:

headers['Slug'] = str(suggested_identifier)

if metadata_relevant:

headers['Metadata-Relevant'] = str(metadata_relevant).lower()

self._t.start(request_type)

if empty:

# NULL body with explicit zero length.

headers['Content-Length'] = "0"

resp, content = self.h.request(target_iri, method, headers=headers)

_, took_time = self._t.time_since_start(request_type)

if self.history:

self.history.log(request_type + ": Empty request",

sd_iri = self.sd_iri,

target_iri = target_iri,

method = method,

response = resp,

headers = headers,

process_duration = took_time)

elif method == "DELETE":

resp, content = self.h.request(target_iri, method, headers=headers)

_, took_time = self._t.time_since_start(request_type)

if self.history:

self.history.log(request_type + ": DELETE request",

sd_iri = self.sd_iri,

target_iri = target_iri,

method = method,

response = resp,

headers = headers,

process_duration = took_time)

elif metadata_entry and not (filename and payload):

# Metadata-only resource creation

headers['Content-Type'] = entry_content_type # "application/atom+xml;type=entry"

data = str(metadata_entry)

headers['Content-Length'] = str(len(data))

resp, content = self.h.request(target_iri, method, headers=headers, payload=data)

_, took_time = self._t.time_since_start(request_type)

if self.history:

self.history.log(request_type + ": Metadata-only resource request",

sd_iri = self.sd_iri,

target_iri = target_iri,

method = method,

response = resp,

headers = headers,

process_duration = took_time)

elif metadata_entry and filename and payload:

# Multipart resource creation

my_headers = {"Content-MD5" : str(md5sum)}

if packaging is not None:

my_headers['Packaging'] = str(packaging)

multicontent_type, payload_data = create_multipart_related([{'key':'atom',

'type':'application/atom+xml; charset="utf-8"',

'data':str(metadata_entry), # etree default is utf-8

},

{'key':'payload',

'type':str(mimetype),

'filename':filename,

'data':payload,

'headers':my_headers

}

])

headers['Content-Type'] = multicontent_type + '; type="application/atom+xml"'

headers['Content-Length'] = str(len(payload_data)) # must be str, not int type

resp, content = self.h.request(target_iri, method, headers=headers, payload=payload_data)

_, took_time = self._t.time_since_start(request_type)

if self.history:

self.history.log(request_type + ": Multipart resource request",

sd_iri = self.sd_iri,

target_iri = target_iri,

response = resp,

headers = headers,

method = method,

multipart = [{'key':'atom',

'type':'application/atom+xml; charset="utf-8"'

},

{'key':'payload',

'type':str(mimetype),

'filename':filename,

'headers':{'Content-MD5':str(md5sum),

'Packaging':str(packaging),

}

}], # record just the headers used in multipart construction

process_duration = took_time)

elif filename and payload:

headers['Content-Type'] = str(mimetype)

headers['Content-MD5'] = str(md5sum)

headers['Content-Length'] = str(f_size)

headers['Content-Disposition'] = "attachment; filename=%s" % urllib.parse.quote(filename)

if packaging is not None:

headers['Packaging'] = str(packaging)

resp, content = self.h.request(target_iri, method, headers=headers, payload=payload)

_, took_time = self._t.time_since_start(request_type)

if self.history:

self.history.log(request_type + ": simple resource request",

sd_iri = self.sd_iri,

target_iri = target_iri,

method = method,

response = resp,

headers = headers,

process_duration = took_time)

else:

conn_l.error("Parameters were not complete: requires a metadata_entry, or a payload/filename/packaging or both")

raise Exception("Parameters were not complete: requires a metadata_entry, or a payload/filename/packaging or both")

if resp['status'] == 201:

# Deposit receipt in content

conn_l.info("Received a Resource Created (201) response.")

# Check response headers for updated Location IRI

location = resp.get('location', None)

if len(content) > 0:

# Fighting chance that this is a deposit receipt

d = Deposit_Receipt(xml_deposit_receipt = content)

if d.parsed:

conn_l.info("Server response included a Deposit Receipt. Caching a copy in .resources['%s']" % d.edit)

d.response_headers = dict(resp)

if location is not None:

d.location = location

d.edit = location

d.code = 201

self._cache_deposit_receipt(d)

return d

else:

# No body...

d = Deposit_Receipt()

conn_l.info("Server response dir not include a Deposit Receipt.")

d.response_headers = dict(resp)

d.code = 201

d.location = location

return d

elif resp['status'] == 204:

# Deposit receipt in content

conn_l.info("Received a valid 'No Content' (204) response.")

location = resp.get('location', None)

# Check response headers for updated Locatio

return Deposit_Receipt(response_headers = dict(resp), location=location, code=204)

elif resp['status'] == 200:

# Deposit receipt in content

conn_l.info("Received a valid (200) OK response.")

content_type = resp.get('content-type')

location = resp.get('location', None)

# content type header may also includ charset

if self._normalise_mime(content_type).startswith("application/atom+xml;type=entry") and len(content) > 0:

d = Deposit_Receipt(content)

if d.parsed:

conn_l.info("Server response included a Deposit Receipt. Caching a copy in .resources['%s']" % d.edit)

d.response_headers = dict(resp)

d.location = location

d.code = 200

self._cache_deposit_receipt(d)

return d

else:

# No atom entry...

d = Deposit_Receipt()

conn_l.info("Server response dir not include a Deposit Receipt Entry.")

d.response_headers = dict(resp)

d.location = location

d.content = content

d.code = 200

return d

else:

return self._handle_error_response(resp, content)

def create(self,

workspace=None, # Either provide workspace/collection or

collection=None, # the exact Col-IRI itself

col_iri=None,

payload=None, # These need to be set to upload a file

mimetype=None,

filename=None,

packaging=None,

md5sum=None, # optional; will be calculated for you otherwise

metadata_entry=None, # a sword2.Entry needs to be here, if

# a metadata entry is to be uploaded

entry_content_type="application/atom+xml; type=entry", # atom mimetype to use for singlepart deposit

# Set both a file and a metadata entry for the method to perform a multipart

# related upload.

suggested_identifier=None,

in_progress=False,

on_behalf_of=None,

):

"""

conn_l.debug("Create Resource")

if not col_iri:

for w, collections in self.workspaces:

if w == workspace:

for c in collections:

if c.title == collection:

conn_l.debug("Matched: Workspace='%s', Collection='%s' ==> Col-IRI='%s'" % (workspace,

collection,

c.href))

col_iri = c.href

break

if not col_iri: # no col_iri provided and no valid workspace/collection given

conn_l.error("No suitable Col-IRI was found, with the given parameters.")

return

return self._make_request(target_iri = col_iri,

payload=payload,

mimetype=mimetype,

filename=filename,

packaging=packaging,

metadata_entry=metadata_entry,

suggested_identifier=suggested_identifier,

in_progress=in_progress,

on_behalf_of=on_behalf_of,

method="POST",

request_type='Col_IRI POST',

md5sum=md5sum,

entry_content_type=entry_content_type)

def update(self, metadata_entry = None, # required for a metadata update

payload = None, # required for a file update

filename = None, # required for a file update

mimetype=None, # required for a file update

packaging=None, # required for a file update

md5sum=None, # optional; will be calculated for you otherwise

dr = None, # Important! Without this, you will have to set the edit_iri AND the edit_media_iri parameters.

edit_iri = None,

edit_media_iri = None,

metadata_relevant=False,

in_progress=False,

on_behalf_of=None,

):

"""

target_iri = None

request_type = "Update PUT"

if metadata_entry != None:

metadata_relevant = True # set this definitively, although the server shouldn't actually care

# Metadata or Metadata + file --> Edit-IRI

conn_l.info("Using the Edit-IRI - Metadata or Metadata + file multipart-related uses a PUT request to the Edit-IRI")

if payload != None and filename != None:

request_type = "Update Multipart PUT"

else:

request_type = "Update Metadata PUT"

if dr != None and dr.edit != None:

conn_l.info("Using the deposit receipt to get the Edit-IRI: %s" % dr.edit)

target_iri = dr.edit

elif edit_iri != None:

conn_l.info("Using the %s receipt as the Edit-IRI" % edit_iri)

target_iri = edit_iri

else:

conn_l.error("Metadata or Metadata + file multipart-related update: Cannot find the Edit-IRI from the parameters supplied.")

elif payload != None and filename != None:

# File-only --> Edit-Media-IRI

conn_l.info("Using the Edit-Media-IRI - File update uses a PUT request to the Edit-Media-IRI")

request_type = "Update File PUT"

if dr != None and dr.edit_media != None:

conn_l.info("Using the deposit receipt to get the Edit-Media-IRI: %s" % dr.edit_media)

target_iri = dr.edit_media

elif edit_media_iri != None:

conn_l.info("Using the %s receipt as the Edit-Media-IRI" % edit_media_iri)

target_iri = edit_media_iri

else:

conn_l.error("File update: Cannot find the Edit-Media-IRI from the parameters supplied.")

if target_iri == None:

raise Exception("No suitable IRI was found for the request needed.")

return self._make_request(target_iri = target_iri,

metadata_entry=metadata_entry,

payload=payload,

mimetype=mimetype,

filename=filename,

packaging=packaging,

on_behalf_of=on_behalf_of,

in_progress=in_progress,

metadata_relevant=str(metadata_relevant),

method="PUT",

request_type=request_type,

md5sum=md5sum)

def add_file_to_resource(self,

edit_media_iri,

payload, # These need to be set to upload a file

filename, # According to spec, "The client MUST supply a Content-Disposition header with a filename parameter

# (note that this requires the filename be expressed in ASCII)."

mimetype=None,

packaging=None,

md5sum=None, # optional; will be calculated for you otherwise

on_behalf_of=None,

in_progress=False,

metadata_relevant=False

):

"""