diff --git a/setup.py b/setup.py index eae82d4..3501c66 100644 --- a/setup.py +++ b/setup.py @@ -1,10 +1,10 @@ from setuptools import setup, find_packages import sys, os -version = '0.2.1' +version = "0.3.1" setup( - name='sword2', + name="sword2", version=version, description="SWORD v2 python client", long_description="""\ @@ -20,13 +20,13 @@ "License :: OSI Approved :: Apache Software License", "Natural Language :: English", "Operating System :: OS Independent", - "Programming Language :: Python :: 2", - "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", - "Programming Language :: Python :: 3.6", - "Programming Language :: Python :: 3.7", - "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", "Topic :: Communications", "Topic :: Internet", "Topic :: Internet :: WWW/HTTP", @@ -34,10 +34,10 @@ ], keywords="sword-app atom sword2 http", author="Ben O'Steen, Cottage Labs", - author_email='us@cottagelabs.com', + author_email="us@cottagelabs.com", url="http://swordapp.org/", - license='Apache', - packages=find_packages(exclude=['ez_setup', 'examples', 'tests']), + license="Apache", + packages=find_packages(exclude=["ez_setup", "examples", "tests"]), include_package_data=True, zip_safe=False, install_requires=[ @@ -45,9 +45,9 @@ "lxml", ], # Following left in as a memory aid for later- - #entry_points=""" + # entry_points=""" # # -*- Entry points: -*- # [console_scripts] # cmd=module.path:func_name - #""", + # """, ) diff --git a/sword2/__init__.py b/sword2/__init__.py index 0f3b3b8..c1f9e04 100644 --- a/sword2/__init__.py +++ b/sword2/__init__.py @@ -1,6 +1,7 @@ """ SWORD2 Python Client blurb """ + from .service_document import ServiceDocument from .collection import SDCollection, Collection_Feed from .statement import Atom_Sword_Statement, Ore_Sword_Statement diff --git a/sword2/atom_objects.py b/sword2/atom_objects.py index 12a97bd..344eefd 100644 --- a/sword2/atom_objects.py +++ b/sword2/atom_objects.py @@ -1,9 +1,9 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- -"""Non-SWORD2 specific Atom/APP helper classes. +"""Non-SWORD2 specific Atom/APP helper classes. -Most often used class will be 'Entry' - it provides an easy means to make an atom:entry +Most often used class will be 'Entry' - it provides an easy means to make an atom:entry document which can be used directly as the metadata entry. Also provides Category, which is a convenience function to simplify reading in category information from an atom:entry @@ -14,6 +14,7 @@ from .sword2_logging import logging from .implementation_info import __version__ + coll_l = logging.getLogger(__name__) @@ -22,37 +23,34 @@ class Category(object): """Convenience class to aid in the intepreting of atom:category elements in XML. Currently, this is read-only. - + Usage: - + >>> from sword2 import Category - + ... # `Category` expects an etree.SubElement node (`c_node` in this example) referencing an element: .... - + # Load a `Category` instance: >>> c = Category(dom = c_node) - + # Overrides `__str__` to provide a simple means to view the content >>> print c "Category scheme:http://purl.org/net/sword/terms/ term:http://purl.org/net/sword/terms/originalDeposit label:Orignal Deposit text:'None'" - + # Element attributes appear as object attibutes: >>> c.scheme 'http://purl.org/net/sword/terms/' - + # Element text will be in the text attribute, if text is present >>> c.text None - + """ - def __init__(self, term=None, - scheme=None, - label=None, - text=None, - dom=None): + + def __init__(self, term=None, scheme=None, label=None, text=None, dom=None): """Init a `Category` class - 99% of the time, this will be done by setting the dom parameter. - + However, if (for testing) there is a need to 'fake' a `Category`, all the attributes can be set in the constructor.""" self.term = term self.scheme = scheme @@ -61,11 +59,9 @@ def __init__(self, term=None, if dom != None: self.dom = dom self._from_element(self.dom) - + def _from_element(self, e): - """ Load the `Category`'s internal attributes using the information within an `etree.SubElement` - - """ + """Load the `Category`'s internal attributes using the information within an `etree.SubElement`""" for item in list(e.attrib.keys()): if item.endswith("scheme"): self.scheme = e.attrib[item] @@ -78,16 +74,18 @@ def _from_element(self, e): def __str__(self): """Rudimentary way to display the data held, in a way amenable to stdout.""" - return "Category scheme:%s term:%s label:%s text:'%s'" % (self.scheme, - self.term, - self.label, - self.text) + return "Category scheme:%s term:%s label:%s text:'%s'" % ( + self.scheme, + self.term, + self.label, + self.text, + ) class Entry(object): """Used to create `Entry`s - for multipart/metadata submission. Has a simple and extendable way to add in namespace-aware key-value pairs. - + Example of use: >>> from sword2 import Entry @@ -104,7 +102,7 @@ class Entry(object): # Adding fields to the metadata entry - # dcterms (and other, non-atom fields) can be used by passing in a parameter with an underscore between the + # dcterms (and other, non-atom fields) can be used by passing in a parameter with an underscore between the # prefix and element name, eg: >>> e.add_fields(dcterms_title= "dcterms title", dcterms_some_other_field = "other") @@ -125,7 +123,7 @@ class Entry(object): other dcterms title - >>> + >>> # Other namespaces - use `Entry.register_namespace` to add them to the list of those considered (prefix, URL): >>> e.register_namespace("myschema", "http://example.org") @@ -150,30 +148,40 @@ class Entry(object): >>> len(e.entry.getchildren()) 14 -""" - atom_fields = ['title','id','updated','summary'] - add_ns = ['dcterms', 'atom', 'app'] - bootstrap = """ + """ + + atom_fields = ["title", "id", "updated", "summary"] + add_ns = ["dcterms", "atom", "app"] + bootstrap = ( + """ -""" % __version__ +""" + % __version__ + ) + def __init__(self, atomEntryXml=None, **kw): """Create a basic `Entry` document, setting the generator and a timestamp for the updated element value. - + Any keyword parameters passed in will be passed to the add_fields method and added to the entry bootstrap document. It's currently not possible to add a namespace and use it within the init call.""" - + # create a namespace map which we'll use in all of the elements - self.nsmap = {"dcterms" : "http://purl.org/dc/terms/", "atom" : "http://www.w3.org/2005/Atom"} - self.entry = etree.fromstring(self.bootstrap if not atomEntryXml else atomEntryXml) - if not 'updated' in list(kw.keys()): - kw['updated'] = datetime.now().isoformat() + self.nsmap = { + "dcterms": "http://purl.org/dc/terms/", + "atom": "http://www.w3.org/2005/Atom", + } + self.entry = etree.fromstring( + self.bootstrap if not atomEntryXml else atomEntryXml + ) + if not "updated" in list(kw.keys()): + kw["updated"] = datetime.now().isoformat() self.add_fields(**kw) - + def register_namespace(self, prefix, uri): """Registers a namespace,, making it available for use when adding subsequent fields to the entry. - + Registration will also affect the XML export, adding in the xmlns:prefix="url" attribute when required.""" try: etree.register_namespace(prefix, uri) @@ -184,33 +192,35 @@ def register_namespace(self, prefix, uri): self.add_ns.append(prefix) if prefix not in list(NS.keys()): NS[prefix] = "{%s}%%s" % uri - + # we also have to handle namespaces internally, for etree implementations which # don't support register_namespace if prefix not in list(self.nsmap.keys()): self.nsmap[prefix] = uri - + def add_field(self, k, v, attrs=None): - """Append a single key-value pair to the `Entry` document. - + """Append a single key-value pair to the `Entry` document. + eg - + >>> e.add_field("myprefix_fooo", "value") - + It is advisable to use the `Entry.add_fields` method instead as this is neater and simplifies element entry. - + Note that the atom:author field is handled differently, as it requires certain fields from the author: - + >>> e.add_field("author", {'name':".....", 'email':"....", 'uri':"...."} ) - + Note that this means of entry is not supported for other elements.""" if k in self.atom_fields: # These should be unique! - old_e = self.entry.find(NS['atom'] % k) + old_e = self.entry.find(NS["atom"] % k) if old_e == None: - e = etree.SubElement(self.entry, NS['atom'] % k, nsmap=self.nsmap) # Notice we explicitly declare the nsmap + e = etree.SubElement( + self.entry, NS["atom"] % k, nsmap=self.nsmap + ) # Notice we explicitly declare the nsmap e.text = v else: old_e.text = v @@ -218,7 +228,9 @@ def add_field(self, k, v, attrs=None): # possible XML namespace, eg 'dcterms_title' nmsp, tag = k.split("_", 1) if nmsp in self.add_ns: - e = etree.SubElement(self.entry, NS[nmsp] % tag, nsmap=self.nsmap) # Notice we explicitly declare the nsmap + e = etree.SubElement( + self.entry, NS[nmsp] % tag, nsmap=self.nsmap + ) # Notice we explicitly declare the nsmap e.text = v if attrs is not None: for an, av in attrs.items(): @@ -227,40 +239,40 @@ def add_field(self, k, v, attrs=None): self.add_author(**v) def add_fields(self, **kw): - """Add in multiple elements in one method call. - + """Add in multiple elements in one method call. + Eg: - + >>> e.add_fields(dcterms_title="Origin of the Species", dcterms_contributor="Darwin, Charles") """ - for k,v in kw.items(): - self.add_field(k,v) + for k, v in kw.items(): + self.add_field(k, v) def add_author(self, name, uri=None, email=None): """Convenience function to add in the atom:author elements in the fashion required for Atom""" - a = etree.SubElement(self.entry, NS['atom'] % 'author', nsmap=self.nsmap) - n = etree.SubElement(a, NS['atom'] % 'name', nsmap=self.nsmap) + a = etree.SubElement(self.entry, NS["atom"] % "author", nsmap=self.nsmap) + n = etree.SubElement(a, NS["atom"] % "name", nsmap=self.nsmap) n.text = name if uri: - u = etree.SubElement(a, NS['atom'] % 'uri', nsmap=self.nsmap) + u = etree.SubElement(a, NS["atom"] % "uri", nsmap=self.nsmap) u.text = uri if email: - e = etree.SubElement(a, NS['atom'] % 'email', nsmap=self.nsmap) + e = etree.SubElement(a, NS["atom"] % "email", nsmap=self.nsmap) e.text = email def add_contributor(self, name, uri=None, email=None): """Convenience function to add in the atom:contributor elements in the fashion required for Atom""" - a = etree.SubElement(self.entry, NS['atom'] % 'contributor', nsmap=self.nsmap) - n = etree.SubElement(a, NS['atom'] % 'name', nsmap=self.nsmap) + a = etree.SubElement(self.entry, NS["atom"] % "contributor", nsmap=self.nsmap) + n = etree.SubElement(a, NS["atom"] % "name", nsmap=self.nsmap) n.text = name if uri: - u = etree.SubElement(a, NS['atom'] % 'uri', nsmap=self.nsmap) + u = etree.SubElement(a, NS["atom"] % "uri", nsmap=self.nsmap) u.text = uri if email: - e = etree.SubElement(a, NS['atom'] % 'email', nsmap=self.nsmap) + e = etree.SubElement(a, NS["atom"] % "email", nsmap=self.nsmap) e.text = email def __str__(self): diff --git a/sword2/auto_discovery.py b/sword2/auto_discovery.py index 449b81e..54779c7 100644 --- a/sword2/auto_discovery.py +++ b/sword2/auto_discovery.py @@ -1,4 +1,5 @@ from .sword2_logging import logging + ad_l = logging.getLogger(__name__) # FIXME: sgmllib is deprecated, and removed from Python 3. If moving to @@ -6,11 +7,11 @@ from . import http_layer from html.parser import HTMLParser -class AutoDiscovery(HTMLParser): +class AutoDiscovery(HTMLParser): def __init__(self, url=None, http_impl=None): HTMLParser.__init__(self) - + self.url = url self.service_document = None self.collection = None @@ -18,14 +19,14 @@ def __init__(self, url=None, http_impl=None): self.statement = [] self.data = None self.response = None - + if http_impl is None: ad_l.info("Loading default HTTP layer") self.http = http_layer.HttpLib2Layer(".cache", timeout=30.0) else: ad_l.info("Using provided HTTP layer") self.http = http_impl - + if url is not None: self.discover(url) @@ -57,20 +58,29 @@ def start_link(self, attributes): # we're looking up the rel value first if name != "rel": continue - - if (value == "http://purl.org/net/sword/discovery/service-document" or - value == "sword"): + + if ( + value == "http://purl.org/net/sword/discovery/service-document" + or value == "sword" + ): # we have found the service document link - self.service_document = self._expand_href(self._extract_attribute("href", attributes)) + self.service_document = self._expand_href( + self._extract_attribute("href", attributes) + ) elif value == "http://purl.org/net/sword/terms/deposit": # we have found the collection link - self.collection = self._expand_href(self._extract_attribute("href", attributes)) + self.collection = self._expand_href( + self._extract_attribute("href", attributes) + ) elif value == "http://purl.org/net/sword/terms/edit": # we have found the entry link - self.entry = self._expand_href(self._extract_attribute("href", attributes)) + self.entry = self._expand_href( + self._extract_attribute("href", attributes) + ) elif value == "http://purl.org/net/sword/terms/statement": # we have found the statement link - state_url = self._expand_href(self._extract_attribute("href", attributes)) + state_url = self._expand_href( + self._extract_attribute("href", attributes) + ) state_type = self._extract_attribute("type", attributes) self.statement.append((state_url, state_type)) - diff --git a/sword2/collection.py b/sword2/collection.py index 27d2318..96f563f 100644 --- a/sword2/collection.py +++ b/sword2/collection.py @@ -1,7 +1,7 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- -""" Collection classes +"""Collection classes These classes are used in their documented manner but most collect or group various other items to make them suitable for use. @@ -13,6 +13,7 @@ for the things they logically handle. """ + import json from .sword2_logging import logging @@ -49,18 +50,21 @@ class SDCollection(object): "Thesis Deposit" """ - def __init__(self, title=None, - href=None, - accept=[], - accept_multipart=[], - categories=[], - collectionPolicy=None, - description=None, - mediation=None, - treatment=None, - acceptPackaging=[], - service=[], - dom=None): + def __init__( + self, + title=None, + href=None, + accept=[], + accept_multipart=[], + categories=[], + collectionPolicy=None, + description=None, + mediation=None, + treatment=None, + acceptPackaging=[], + service=[], + dom=None, + ): """ Creates a `Collection` object - as used by `sword2.Service_Document` @@ -172,36 +176,40 @@ def load_from_etree(self, collection): """ self._reset() self.dom = collection - self.title = get_text(collection, NS['atom'] % 'title') + self.title = get_text(collection, NS["atom"] % "title") # MUST have href attribute - self.href = collection.attrib.get('href', None) + self.href = collection.attrib.get("href", None) # Accept and Accept multipart - for accept in collection.findall(NS['app'] % 'accept'): + for accept in collection.findall(NS["app"] % "accept"): if accept.attrib.get("alternate", None) == "multipart-related": self.accept_multipart.append(accept.text) else: self.accept.append(accept.text) # Categories - for category_element in collection.findall(NS['atom'] % 'category'): + for category_element in collection.findall(NS["atom"] % "category"): self.categories.append(Category(dom=category_element)) # SWORD extensions: - self.collectionPolicy = get_text(collection, NS['sword'] % 'collectionPolicy') + self.collectionPolicy = get_text(collection, NS["sword"] % "collectionPolicy") # Mediation: True/False - mediation = get_text(collection, NS['sword'] % 'mediation') + mediation = get_text(collection, NS["sword"] % "mediation") self.mediation = mediation.lower() == "true" - self.treatment = get_text(collection, NS['sword'] % 'treatment') - self.description = get_text(collection, NS['dcterms'] % 'abstract') - self.service = get_text(collection, NS['sword'] % 'service', plural = True) - self.acceptPackaging = get_text(collection, NS['sword'] % 'acceptPackaging', plural = True) + self.treatment = get_text(collection, NS["sword"] % "treatment") + self.description = get_text(collection, NS["dcterms"] % "abstract") + self.service = get_text(collection, NS["sword"] % "service", plural=True) + self.acceptPackaging = get_text( + collection, NS["sword"] % "acceptPackaging", plural=True + ) # Log collection details: coll_l.debug(str(self)) def __str__(self): """Provides a simple display of the pertinent information in this object suitable for CLI logging.""" - _s = ["Collection: '%s' @ '%s'. Accept:%s" % (self.title, self.href, self.accept)] + _s = [ + "Collection: '%s' @ '%s'. Accept:%s" % (self.title, self.href, self.accept) + ] if self.description: _s.append("SWORD: Description - '%s'" % self.description) if self.collectionPolicy: @@ -227,17 +235,21 @@ def to_json(self): NB this uses the attributes of the object, not the cached DOM object, so information can be altered/added on the fly.""" - return json.dumps({'title': self.title, - 'href': self.href, - 'description': self.description, - 'accept': self.accept, - 'accept_multipart': self.accept_multipart, - 'mediation': self.mediation, - 'treatment': self.treatment, - 'collectionPolicy': self.collectionPolicy, - 'acceptPackaging': self.acceptPackaging, - 'service': self.service, - 'categories': self.categories}) + return json.dumps( + { + "title": self.title, + "href": self.href, + "description": self.description, + "accept": self.accept, + "accept_multipart": self.accept_multipart, + "mediation": self.mediation, + "treatment": self.treatment, + "collectionPolicy": self.collectionPolicy, + "acceptPackaging": self.acceptPackaging, + "service": self.service, + "categories": self.categories, + } + ) class Collection_Feed(object): diff --git a/sword2/connection.py b/sword2/connection.py index d2eea65..28a99e1 100644 --- a/sword2/connection.py +++ b/sword2/connection.py @@ -7,9 +7,11 @@ #BETASWORD2URL See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD for information about the SWORD2 AtomPub profile. - + """ + from .sword2_logging import logging + conn_l = logging.getLogger(__name__) from .utils import Timer, NS, get_md5, create_multipart_related @@ -27,193 +29,196 @@ from . import http_layer import urllib.request, urllib.parse, urllib.error + class Connection(object): """ -`Connection` - SWORD2 client - -This connection is predicated on having a Service Document (SD), preferably by an instance being constructed with -the Service Document IRI (SD-IRI) which can dereference to the XML document itself. - - -Contructor parameters: - -There are a number of flags that can be set when getting an instance of this class that affect the behaviour -of the client. See the help for `self.__init__` for more details. - -Example usage: - ->>> from sword2 import Connection ->>> conn = Connection("http://example.org/service-doc") # An SD-IRI is required. - - - - -# Get, validate and parse the document at the SD_IRI: ->>> conn.get_service_document() - -# Load a Service Document from a string: ->>> conn.load_service_document(xml_service_doc) -2011-05-30 01:06:13,251 - sword2.service_document - INFO - Initial SWORD2 validation checks on service document - Valid document? True - -# View transaction history (if enabled) ->>> print conn.history.to_pretty_json() -[ - { - "sd_iri": "http://example.org/service-doc", - "timestamp": "2011-05-30T01:05:54.071042", - "on_behalf_of": null, - "type": "init", - "user_name": null - }, - { - "IRI": "http://example.org/service-doc", - "valid": true, - "sword_version": "2.0", - "duration": 0.0029349327087402344, - "timestamp": "2011-05-30T01:06:13.253907", - "workspaces_found": [ - "Main Site", - "Sub-site" - ], - "type": "SD Parse", - "maxUploadSize": 16777216 - } -] - -# Start a connection and do not maintain a transaction history -# Useful for bulk-testing where the history might grow exponentially ->>> conn = Connection(...... , keep_history=False, ....) - -# Initialise a connection and get the document at the SD IRI: -# (Uses the Simple Sword Server as an endpoint - sss.py - ->>> from sword2 import Connection ->>> c = Connection("http://localhost:8080/sd-uri", download_service_document=True) -2011-05-30 02:04:24,179 - sword2.connection - INFO - keep_history=True--> This instance will keep a JSON-compatible transaction log of all (SWORD/APP) activities in 'self.history' -2011-05-30 02:04:24,215 - sword2.connection - INFO - Received a document for http://localhost:8080/sd-uri -2011-05-30 02:04:24,216 - sword2.service_document - INFO - Initial SWORD2 validation checks on service document - Valid document? True ->>> print c.history --------------------- -Type: 'init' [2011-05-30T02:04:24.180182] -Data: -user_name: None -on_behalf_of: None -sd_iri: http://localhost:8080/sd-uri --------------------- -Type: 'SD_IRI GET' [2011-05-30T02:04:24.215661] -Data: -sd_iri: http://localhost:8080/sd-uri -response: {'status': '200', 'content-location': 'http://localhost:8080/sd-uri', 'transfer-encoding': 'chunked', 'server': 'CherryPy/3.1.2 WSGI Server', 'date': 'Mon, 30 May 2011 01:04:24 GMT', 'content-type': 'text/xml'} -process_duration: 0.0354170799255 --------------------- -Type: 'SD Parse' [2011-05-30T02:04:24.220798] -Data: -maxUploadSize: 16777216 -sd_iri: http://localhost:8080/sd-uri -valid: True -sword_version: 2.0 -workspaces_found: ['Main Site'] -process_duration: 0.00482511520386 - -Please see the testsuite for this class for more examples of the sorts of transactions that can be done. (tests/test_connection*.py) -""" + `Connection` - SWORD2 client + + This connection is predicated on having a Service Document (SD), preferably by an instance being constructed with + the Service Document IRI (SD-IRI) which can dereference to the XML document itself. + + + Contructor parameters: + + There are a number of flags that can be set when getting an instance of this class that affect the behaviour + of the client. See the help for `self.__init__` for more details. + + Example usage: + + >>> from sword2 import Connection + >>> conn = Connection("http://example.org/service-doc") # An SD-IRI is required. + + + + + # Get, validate and parse the document at the SD_IRI: + >>> conn.get_service_document() + + # Load a Service Document from a string: + >>> conn.load_service_document(xml_service_doc) + 2011-05-30 01:06:13,251 - sword2.service_document - INFO - Initial SWORD2 validation checks on service document - Valid document? True + + # View transaction history (if enabled) + >>> print conn.history.to_pretty_json() + [ + { + "sd_iri": "http://example.org/service-doc", + "timestamp": "2011-05-30T01:05:54.071042", + "on_behalf_of": null, + "type": "init", + "user_name": null + }, + { + "IRI": "http://example.org/service-doc", + "valid": true, + "sword_version": "2.0", + "duration": 0.0029349327087402344, + "timestamp": "2011-05-30T01:06:13.253907", + "workspaces_found": [ + "Main Site", + "Sub-site" + ], + "type": "SD Parse", + "maxUploadSize": 16777216 + } + ] + + # Start a connection and do not maintain a transaction history + # Useful for bulk-testing where the history might grow exponentially + >>> conn = Connection(...... , keep_history=False, ....) + + # Initialise a connection and get the document at the SD IRI: + # (Uses the Simple Sword Server as an endpoint - sss.py + + >>> from sword2 import Connection + >>> c = Connection("http://localhost:8080/sd-uri", download_service_document=True) + 2011-05-30 02:04:24,179 - sword2.connection - INFO - keep_history=True--> This instance will keep a JSON-compatible transaction log of all (SWORD/APP) activities in 'self.history' + 2011-05-30 02:04:24,215 - sword2.connection - INFO - Received a document for http://localhost:8080/sd-uri + 2011-05-30 02:04:24,216 - sword2.service_document - INFO - Initial SWORD2 validation checks on service document - Valid document? True + >>> print c.history + -------------------- + Type: 'init' [2011-05-30T02:04:24.180182] + Data: + user_name: None + on_behalf_of: None + sd_iri: http://localhost:8080/sd-uri + -------------------- + Type: 'SD_IRI GET' [2011-05-30T02:04:24.215661] + Data: + sd_iri: http://localhost:8080/sd-uri + response: {'status': '200', 'content-location': 'http://localhost:8080/sd-uri', 'transfer-encoding': 'chunked', 'server': 'CherryPy/3.1.2 WSGI Server', 'date': 'Mon, 30 May 2011 01:04:24 GMT', 'content-type': 'text/xml'} + process_duration: 0.0354170799255 + -------------------- + Type: 'SD Parse' [2011-05-30T02:04:24.220798] + Data: + maxUploadSize: 16777216 + sd_iri: http://localhost:8080/sd-uri + valid: True + sword_version: 2.0 + workspaces_found: ['Main Site'] + process_duration: 0.00482511520386 + + Please see the testsuite for this class for more examples of the sorts of transactions that can be done. (tests/test_connection*.py) + """ - 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): + 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, + ): """ -Creates a new Connection object. - -Parameters: - - Connection(service_document_iri, <--- REQUIRED - use a dummy string here if the SD is local only. - - # OPTIONAL parameters (default values are shown below) - - # Authentication parameters: (can use any method that `httplib2` provides) - - user_name=None, - user_pass=None, - - # Set the SWORD2 On Behalf Of value here, for it to be included as part of every transaction - # Can be passed to every transaction method (update resource, delete deposit, etc) otherwise - - on_behalf_of=None, - - ## Behaviour Flags - # Try to GET the service document from the provided SD-IRI in `service_document_iri` if True - - download_service_document = False, # Don't automagically GET the SD_IRI by default - - # Keep a history of all transactions made with the SWORD2 Server - # Records details like the response headers, sent headers, times taken and so forth - # Kept in a `sword2.transaction_history:Transaction_History` object but can be treated like an ordinary `list` - keep_history=True, - - # Keep a cache of all deposit receipt responses from the server and provide an 'index' to these `sword2.Deposit_Receipt` objects - # by Edit-IRI, Content-IRI and Sword-Edit-IRI. (ie given an Edit-IRI, find the deposit receipt for the last received response containing - # that IRI. - # If the following flag, `honour_receipts` is set to True, packaging checks and other limits set in these receipts will be - # honoured. - # For example, a request for an item with an invalid packaging type will never reach the server, but throw an exception. - - cache_deposit_receipts=True, - - # Make sure to behave as required by the SWORD2 server - not sending too large a file, not asking for invalid packaging types and so on. - - honour_receipts=True, - - # Two means of handling server error responses: - # If set to True - An exception will be thrown from `sword2.exceptions` (caused by any server error response w/ - # HTTP code greater than or equal to 400) - # OR - # If set to False - A `sword2.error_document:Error_Document` object will be returned. - - error_response_raises_exceptions=True - ) - -If a `Connection` is created with the parameter `download_service_document` set to `False`, then no attempt -to dereference the `service_document_iri` (SD-IRI) will be made at this stage. + Creates a new Connection object. + + Parameters: + + Connection(service_document_iri, <--- REQUIRED - use a dummy string here if the SD is local only. + + # OPTIONAL parameters (default values are shown below) + + # Authentication parameters: (can use any method that `httplib2` provides) + + user_name=None, + user_pass=None, + + # Set the SWORD2 On Behalf Of value here, for it to be included as part of every transaction + # Can be passed to every transaction method (update resource, delete deposit, etc) otherwise + + on_behalf_of=None, + + ## Behaviour Flags + # Try to GET the service document from the provided SD-IRI in `service_document_iri` if True + + download_service_document = False, # Don't automagically GET the SD_IRI by default + + # Keep a history of all transactions made with the SWORD2 Server + # Records details like the response headers, sent headers, times taken and so forth + # Kept in a `sword2.transaction_history:Transaction_History` object but can be treated like an ordinary `list` + keep_history=True, + + # Keep a cache of all deposit receipt responses from the server and provide an 'index' to these `sword2.Deposit_Receipt` objects + # by Edit-IRI, Content-IRI and Sword-Edit-IRI. (ie given an Edit-IRI, find the deposit receipt for the last received response containing + # that IRI. + # If the following flag, `honour_receipts` is set to True, packaging checks and other limits set in these receipts will be + # honoured. + # For example, a request for an item with an invalid packaging type will never reach the server, but throw an exception. + + cache_deposit_receipts=True, -To cause it to get or refresh the service document from this IRI, call `self.get_service_document()` + # Make sure to behave as required by the SWORD2 server - not sending too large a file, not asking for invalid packaging types and so on. -Loading in a locally held Service Document: - ->>> conn = Connection(....) + honour_receipts=True, ->>> with open("service_doc.xml", "r") as f: -... conn.load_service_document(f.read()) + # Two means of handling server error responses: + # If set to True - An exception will be thrown from `sword2.exceptions` (caused by any server error response w/ + # HTTP code greater than or equal to 400) + # OR + # If set to False - A `sword2.error_document:Error_Document` object will be returned. - - """ + error_response_raises_exceptions=True + ) + + If a `Connection` is created with the parameter `download_service_document` set to `False`, then no attempt + to dereference the `service_document_iri` (SD-IRI) will be made at this stage. + + To cause it to get or refresh the service document from this IRI, call `self.get_service_document()` + + Loading in a locally held Service Document: + + >>> conn = Connection(....) + + >>> with open("service_doc.xml", "r") as f: + ... conn.load_service_document(f.read()) + + + """ 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 - + 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 + # 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") @@ -221,141 +226,164 @@ def __init__(self, service_document_iri=None, 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 - + 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'") + 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 ) + 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]) - + 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. - + `self.raise_except` can be altered at any time to affect this methods behaviour.""" 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) + 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) + 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 - + 401 - Unauthorised. Will throw a `sword2.exceptions.NotAuthorised` exception, if exceptions are set to be on. Otherwise will return a `sword2.Error_Document` (likewise for the rest of these) - + 403 - Forbidden. Will throw a `sword2.exceptions.Forbidden` exception - + 404 - Not Found. Will throw a `sword2.exceptions.NotFound` exception - + 406 - Not Acceptable. Will throw a `sword2.exceptions.NotAcceptable` exception - + 408 - Request Timeout Will throw a `sword2.exceptions.RequestTimeOut` exception - + 500-599 errors: Will throw a general `sword2.exceptions.ServerError` exception - + 4XX not listed: Will throw a general `sword2.exceptions.HTTPResponseError` exception """ 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'") + + 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'") + 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: + 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: + 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) + 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)) + 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 reference these objects. - + (only provides cache if `self.keep_cache` is `True` [via the `cache_deposit_receipts` init parameter flag]) - + Provides and maintains: self.edit_iris -- a `dict`, keys: Edit-IRI hrefs, values: `sword2.Deposit_Receipt` objects they appear in - + self.cont_iris -- a `dict`, keys: Content-IRI hrefs, values: `sword2.Deposit_Receipt` objects they appear in - + self.se_iris -- a `dict`, keys: Sword-Edit-IRI hrefs, values: `sword2.Deposit_Receipt` objects they appear in - + self.cached_at -- a `dict`, keys: Edit-IRIs, values: timestamp when receipt was last cached. """ 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 + if d.cont_iri: # SHOULD exist within receipt self.cont_iris[d.cont_iri] = d - if d.se_iri: + 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'") - + 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` - + Useful if SD-IRI is non-existant or invalid. - + Will set the following convenience attributes: - + `self.sd` -- the `sword2.ServiceDocument` instance - + `self.workspaces` -- a `list` of workspace tuples, of the form: ('Workspace atom:title', [<`sword2.Collection` object>, ....]), - + `self.maxUploadSize` -- the maximum filesize for a deposit, if given in the service document """ self._t.start("SD Parse") @@ -364,122 +392,128 @@ def load_service_document(self, xml_document): # 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) + 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) - + 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 a SWORD2 Service Document (using `self.load_service_document`) """ headers = {} if self.on_behalf_of: - headers['on-behalf-of'] = 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: + 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") + 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'])) - + conn_l.error("Unexpected response status: " + str(resp["status"])) + def reset_transaction_history(self): - """ Clear the transaction history - `self.history`""" + """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 - ): + 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 is not called directly. - + target_iri -- IRI that will be the target of the HTTP call - + # File upload parameters: payload - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` mimetype - MIMEType of the payload filename - filename. Most SWORD2 uploads have this as being mandatory. - packaging - the SWORD2 packaging type of the payload. + packaging - the SWORD2 packaging type of the payload. eg packaging = 'http://purl.org/net/sword/package/Binary' - + # NB to work around a possible bug in httplib2 0.6.0, the file-like object is read into memory rather than streamed - # from disc, so is not as efficient as it should be. That said, it is recommended that file handles are passed to + # from disc, so is not as efficient as it should be. That said, it is recommended that file handles are passed to # the _make_request method, as this is hoped to be a temporary situation. - + metadata_entry - a `sword2.Entry` to be uploaded with metadata fields set as desired. - + # If there is both a payload and a metadata_entry, then the request will be made as a Multipart-related request # Otherwise, it will be a normal request for whicever type of upload. - + empty - a flag to specify that an empty request should be made. A blank body and a 'Content-Length:0' header will be explicitly added and any payload or metadata_entry passed in will be ignored. - - + + # Header flags: suggested_identifier -- set the 'Slug' header in_progress -- 'In-Progress' - on_behalf_of -- 'On-Behalf-Of' + on_behalf_of -- 'On-Behalf-Of' metadata_relevant -- 'Metadata-Relevant' - + # HTTP settings: method -- "GET", "POST", etc - request_type -- A label to be used in the transaction history for this particular operation. - + request_type -- A label to be used in the transaction history for this particular operation. + Response: - - A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or not a Deposit Response, then only a few attributes will be populated: - + `code` -- HTTP code of the response `response_headers` -- `dict` of the reponse headers `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, response_headers, etc) @@ -491,135 +525,176 @@ def _make_request(self, # testing at this stage if md5sum is None: md5sum = md5 - + # request-level headers headers = {} - headers['In-Progress'] = str(in_progress).lower() + headers["In-Progress"] = str(in_progress).lower() if on_behalf_of: - headers['On-Behalf-Of'] = on_behalf_of + headers["On-Behalf-Of"] = on_behalf_of elif self.on_behalf_of: - headers['On-Behalf-Of'] = self.on_behalf_of - + headers["On-Behalf-Of"] = self.on_behalf_of + if suggested_identifier: - headers['Slug'] = str(suggested_identifier) - + headers["Slug"] = str(suggested_identifier) + if metadata_relevant: - headers['Metadata-Relevant'] = str(metadata_relevant).lower() - + headers["Metadata-Relevant"] = str(metadata_relevant).lower() + self._t.start(request_type) if empty: # NULL body with explicit zero length. - headers['Content-Length'] = "0" + 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) + 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) - + 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" + 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) + 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) - + 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)} + 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) + 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) + 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) + 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) + 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) + 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: + 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) + location = resp.get("location", None) if len(content) > 0: # Fighting chance that this is a deposit receipt - d = Deposit_Receipt(xml_deposit_receipt = content) + 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) + 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 @@ -635,22 +710,32 @@ def _make_request(self, d.code = 201 d.location = location return d - elif resp['status'] == 204: + elif resp["status"] == 204: # Deposit receipt in content conn_l.info("Received a valid 'No Content' (204) response.") - location = resp.get('location', None) + 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: + 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 = 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: + 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) + 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 @@ -667,155 +752,150 @@ def _make_request(self, 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, - ): + + 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, + ): """ -Creating a Resource -=================== - -#BETASWORD2URL -See 6.3 Creating a Resource http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_creatingresource - -Basic parameters: - -This method can create a new resource in a Collection on a SWORD2 server, given suitable authentication to do so. - -Select a collection to send a request to by either: - - setting the param `col_iri` to its Collection-IRI or Col-IRI - - or - - setting 'workspace' and 'collection' to the labels for the desired workspace and collection. - -SWORD2 request parameters: - - `suggested_identifier` -- the suggested identifier of this resource (HTTP header of 'Slug'), - - `in_progress` (`True` or `False`) -- whether or not the deposit should be considered by the - server to be in progress ('In-Progress') - `on_behalf_of` -- if this is a mediated deposit ('On-Behalf-Of') - (the client-wide setting `self.on_behalf_of will be used otherwise) - - -1. "Binary File Deposit in a given Collection" ----------------------------------------------- - -Set the following parameters in addition to the basic parameters: - - `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` - `mimetype` - MIMEType of the payload - `filename` - filename. Most SWORD2 uploads have this as being mandatory. - `packaging` - the SWORD2 packaging type of the payload. - eg packaging = 'http://purl.org/net/sword/package/Binary' - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) - -2. "Creating a Resource with an Atom Entry" -------------------------------------------- - -create a container within a SWORD server and optionally provide it with metadata without adding any binary content to it. - -Set the following parameters in addition to the basic parameters: - - `metadata_entry` - An instance of `sword2.Entry`, set with the metadata required. - -for example: - # conn = `sword2.Connection`, collection_iri = Collection-IRI - >>> from sword2 import Entry - >>> entry = Entry(title = "My new deposit", - ... id = "foo:id", - ... dcterms_abstract = "My Thesis", - ... dcterms_author = "Me", - ... dcterms_issued = "2009") - - >>> conn.create(col_iri = collection_iri, - ... metadata_entry = entry, - ... in_progress = True) - # likely to want to add the thesis files later for example but get the identifier for the deposit now - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) - -3. "Creating a Resource with a Multipart Deposit" -------------------------------------------------- - -Create a resource in a given collection by uploading a file AND the metadata about this resource. - -To make this sort of request, just set the parameters as shown for both the binary upload and the metadata upload. - -eg: - - >>> conn.create(col_iri = collection_iri, - ... metadata_entry = entry, - ... payload = open("foo.zip", "r"), - ... mimetype = - .... and so on - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) - -(under the hood, this request uses Atom Multipart-related) - -From the spec: - -"In order to ensure that all SWORD clients and servers can exchange a full range of file content and metadata, the use of Atom Multipart [AtomMultipart] is permitted to combine a package (possibly a simple ZIP) with a set of Dublin Core metadata terms [DublinCore] embedded in an Atom Entry. - -The SWORD server is not required to support packaging formats, but this profile RECOMMENDS that the server be able to accept a ZIP file as the Media Part of an Atom Multipart request (See Section 5: IRIs and Section 7: Packaging for more details)." + Creating a Resource + =================== + + #BETASWORD2URL + See 6.3 Creating a Resource http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_creatingresource + + Basic parameters: + + This method can create a new resource in a Collection on a SWORD2 server, given suitable authentication to do so. + + Select a collection to send a request to by either: + + setting the param `col_iri` to its Collection-IRI or Col-IRI + + or + + setting 'workspace' and 'collection' to the labels for the desired workspace and collection. + + SWORD2 request parameters: + + `suggested_identifier` -- the suggested identifier of this resource (HTTP header of 'Slug'), + + `in_progress` (`True` or `False`) -- whether or not the deposit should be considered by the + server to be in progress ('In-Progress') + `on_behalf_of` -- if this is a mediated deposit ('On-Behalf-Of') + (the client-wide setting `self.on_behalf_of will be used otherwise) + + + 1. "Binary File Deposit in a given Collection" + ---------------------------------------------- + + Set the following parameters in addition to the basic parameters: + + `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` + `mimetype` - MIMEType of the payload + `filename` - filename. Most SWORD2 uploads have this as being mandatory. + `packaging` - the SWORD2 packaging type of the payload. + eg packaging = 'http://purl.org/net/sword/package/Binary' + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) + + 2. "Creating a Resource with an Atom Entry" + ------------------------------------------- + + create a container within a SWORD server and optionally provide it with metadata without adding any binary content to it. + + Set the following parameters in addition to the basic parameters: + + `metadata_entry` - An instance of `sword2.Entry`, set with the metadata required. + + for example: + # conn = `sword2.Connection`, collection_iri = Collection-IRI + >>> from sword2 import Entry + >>> entry = Entry(title = "My new deposit", + ... id = "foo:id", + ... dcterms_abstract = "My Thesis", + ... dcterms_author = "Me", + ... dcterms_issued = "2009") + + >>> conn.create(col_iri = collection_iri, + ... metadata_entry = entry, + ... in_progress = True) + # likely to want to add the thesis files later for example but get the identifier for the deposit now + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) + + 3. "Creating a Resource with a Multipart Deposit" + ------------------------------------------------- + + Create a resource in a given collection by uploading a file AND the metadata about this resource. + + To make this sort of request, just set the parameters as shown for both the binary upload and the metadata upload. + + eg: + + >>> conn.create(col_iri = collection_iri, + ... metadata_entry = entry, + ... payload = open("foo.zip", "r"), + ... mimetype = + .... and so on + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) + + (under the hood, this request uses Atom Multipart-related) + + From the spec: + + "In order to ensure that all SWORD clients and servers can exchange a full range of file content and metadata, the use of Atom Multipart [AtomMultipart] is permitted to combine a package (possibly a simple ZIP) with a set of Dublin Core metadata terms [DublinCore] embedded in an Atom Entry. + + The SWORD server is not required to support packaging formats, but this profile RECOMMENDS that the server be able to accept a ZIP file as the Media Part of an Atom Multipart request (See Section 5: IRIs and Section 7: Packaging for more details)." """ conn_l.debug("Create Resource") if not col_iri: @@ -823,349 +903,369 @@ def create(self, 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)) + 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 + 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, - ): + + 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, + ): """ -Replacing the Metadata and/or Files of a Resource + Replacing the Metadata and/or Files of a Resource -#BETASWORD2URL -See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_editingcontent_multipart + #BETASWORD2URL + See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_editingcontent_multipart -Replace the metadata and/or files of a resource. + Replace the metadata and/or files of a resource. -This wraps a number of methods and relies on being passed the Deposit Receipt, as the target IRI changes depending -on whether the metadata, the files or both are to be updated by the request. + This wraps a number of methods and relies on being passed the Deposit Receipt, as the target IRI changes depending + on whether the metadata, the files or both are to be updated by the request. -This method has the same functionality as the following methods: - update_files_for_resource - update_metadata_for_resource - update_metadata_and_files_for_resource + This method has the same functionality as the following methods: + update_files_for_resource + update_metadata_for_resource + update_metadata_and_files_for_resource -Usage: ------- + Usage: + ------ -Set the target for this request: --------------------------------- + Set the target for this request: + -------------------------------- -You MUST pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, -and the correct IRI will automatically be chosen based on what combination of files you want to upload. + You MUST pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, + and the correct IRI will automatically be chosen based on what combination of files you want to upload. -Then, add in the metadata and/or file information as desired: -------------------------------------------------------------- + Then, add in the metadata and/or file information as desired: + ------------------------------------------------------------- -File information requires: + File information requires: - `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` - `mimetype` - MIMEType of the payload - `filename` - filename. Most SWORD2 uploads have this as being mandatory. - `packaging` - the SWORD2 packaging type of the payload. - eg packaging = 'http://purl.org/net/sword/package/Binary' - - `metadata_relevant` - This should be set to `True` if the server should consider the file a potential source of metadata extraction, - or `False` if the server should not attempt to extract any metadata from the deposi - -Metadata information requires: - - `metadata_entry` - An instance of `sword2.Entry`, set with the metadata required. - -for example, to create a metadata entry - >>> from sword2 import Entry - >>> entry = Entry(title = "My new deposit", - ... id = "new:id", # atom:id - ... dcterms_abstract = "My Thesis", - ... dcterms_author = "Ben", - ... dcterms_issued = "2010") - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) + `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` + `mimetype` - MIMEType of the payload + `filename` - filename. Most SWORD2 uploads have this as being mandatory. + `packaging` - the SWORD2 packaging type of the payload. + eg packaging = 'http://purl.org/net/sword/package/Binary' + + `metadata_relevant` - This should be set to `True` if the server should consider the file a potential source of metadata extraction, + or `False` if the server should not attempt to extract any metadata from the deposi + + Metadata information requires: + + `metadata_entry` - An instance of `sword2.Entry`, set with the metadata required. + + for example, to create a metadata entry + >>> from sword2 import Entry + >>> entry = Entry(title = "My new deposit", + ... id = "new:id", # atom:id + ... dcterms_abstract = "My Thesis", + ... dcterms_author = "Ben", + ... dcterms_issued = "2010") + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) """ 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_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") + 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) + 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.") + 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") + 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) + 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) + 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.") - + 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 - ): + 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, + ): """ -Adding Files to the Media Resource + Adding Files to the Media Resource -From the spec, paraphrased: - - "This feature is for use when clients wish to send individual files to the server and to receive back the IRI for the created resource. [Adding new items to the deposit container] will not give back the location of the deposited resources, so in cases where the server does not provide the (optional) Deposit Receipt, it is not possible for the client to ascertain the location of the file actually deposited - the Location header in that operation is the Edit-IRI. By POSTing to the EM-IRI, the Location header will return the IRI of the deposited file itself, rather than that of the container. + From the spec, paraphrased: -As the EM-IRI represents the Media Resource itself, rather than the Container, this operation will not formally support metadata handling, and therefore also offers no explicit support for packaging either since packages may be both content and metadata. Nonetheless, for files which may contain extractable metadata, there is a Metadata-Relevant header which can be defined to indicate whether the deposit can be used to augment the metadata of the container." + "This feature is for use when clients wish to send individual files to the server and to receive back the IRI for the created resource. [Adding new items to the deposit container] will not give back the location of the deposited resources, so in cases where the server does not provide the (optional) Deposit Receipt, it is not possible for the client to ascertain the location of the file actually deposited - the Location header in that operation is the Edit-IRI. By POSTing to the EM-IRI, the Location header will return the IRI of the deposited file itself, rather than that of the container. -#BETASWORD2URL -See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_addingcontent_mediaresource + As the EM-IRI represents the Media Resource itself, rather than the Container, this operation will not formally support metadata handling, and therefore also offers no explicit support for packaging either since packages may be both content and metadata. Nonetheless, for files which may contain extractable metadata, there is a Metadata-Relevant header which can be defined to indicate whether the deposit can be used to augment the metadata of the container." + #BETASWORD2URL + See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_addingcontent_mediaresource -Set the following parameters in addition to the basic parameters: - `edit_media_iri` - The Edit-Media-IRI - - `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` - `mimetype` - MIMEType of the payload - `filename` - filename. Most SWORD2 uploads have this as being mandatory. - `packaging` - the SWORD2 packaging type of the payload. - eg packaging = 'http://purl.org/net/sword/package/Binary' - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) + Set the following parameters in addition to the basic parameters: + + `edit_media_iri` - The Edit-Media-IRI + + `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` + `mimetype` - MIMEType of the payload + `filename` - filename. Most SWORD2 uploads have this as being mandatory. + `packaging` - the SWORD2 packaging type of the payload. + eg packaging = 'http://purl.org/net/sword/package/Binary' + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) """ - conn_l.info("Appending file to a deposit via Edit-Media-IRI %s" % edit_media_iri) - return self._make_request(target_iri = edit_media_iri, - payload=payload, - mimetype=mimetype, - packaging=packaging, - filename=filename, - on_behalf_of=on_behalf_of, - in_progress=in_progress, - method="POST", - metadata_relevant=metadata_relevant, - request_type='EM_IRI POST (APPEND)', - md5sum=md5sum) - - def append(self, - se_iri = None, - - payload = None, # These need to be set to upload a file - filename = None, # 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, - metadata_entry = None, - metadata_relevant = False, - in_progress = False, - dr = None - ): + conn_l.info( + "Appending file to a deposit via Edit-Media-IRI %s" % edit_media_iri + ) + return self._make_request( + target_iri=edit_media_iri, + payload=payload, + mimetype=mimetype, + packaging=packaging, + filename=filename, + on_behalf_of=on_behalf_of, + in_progress=in_progress, + method="POST", + metadata_relevant=metadata_relevant, + request_type="EM_IRI POST (APPEND)", + md5sum=md5sum, + ) + + def append( + self, + se_iri=None, + payload=None, # These need to be set to upload a file + filename=None, # 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, + metadata_entry=None, + metadata_relevant=False, + in_progress=False, + dr=None, + ): """ -Adding Content to a Resource + Adding Content to a Resource -#BETASWORD2URL -See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_addingcontent + #BETASWORD2URL + See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_addingcontent -Usage: ------- + Usage: + ------ -Set the target for this request: --------------------------------- + Set the target for this request: + -------------------------------- -Set `se_iri` to be the SWORD2-Edit-IRI for a given deposit. (This can be found in `sword2.Deposit_Receipt.se_iri`) + Set `se_iri` to be the SWORD2-Edit-IRI for a given deposit. (This can be found in `sword2.Deposit_Receipt.se_iri`) - OR + OR -you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, -and the correct IRI will automatically be chosen. + you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, + and the correct IRI will automatically be chosen. -Then: ------ + Then: + ----- -1. "Adding New Packages or Files to a Container" ------------------------------------------------- - -Set the following parameters in addition to the basic parameters: + 1. "Adding New Packages or Files to a Container" + ------------------------------------------------ - `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` - `mimetype` - MIMEType of the payload - `filename` - filename. Most SWORD2 uploads have this as being mandatory. - `packaging` - the SWORD2 packaging type of the payload. - eg packaging = 'http://purl.org/net/sword/package/Binary' - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) - - -2. "Adding New Metadata to a Container" --------------------------------------def _normalise_mime(self, mime): - if mime is None: - return None - return mime.lower().replace(" ", "")-- - -NB SWORD2 does not instruct the server on the best way to handle metadata, only that metadata SHOULD be -added and not overwritten; in certain circumstances this may not produce the desired behaviour. - -Set the following parameters in addition to the basic parameters: - - `metadata_entry` - An instance of `sword2.Entry`, set with the metadata required. - -for example: - # conn = `sword2.Connection`, se_iri = SWORD2-Edit-IRI - >>> from sword2 import Entry - >>> entry = Entry(dcterms:identifier = "doi://......") - >>> conn.add_new_item_to_container(se_iri = se_iri, - ... metadata_entry = entry) - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) - -3. "Adding New Metadata and Packages or Files to a Container with Multipart" ----------------------------------------------------------------------------- - -Create a resource in a given collection by uploading a file AND the metadata about this resource. - -To make this sort of request, just set the parameters as shown for both the binary upload and the metadata upload. - -eg: - - >>> conn.add_new_item_to_container(se_iri = se_iri, - ... metadata_entry = entry, - ... payload = open("foo.zip", "r"), - ... mimetype = - .... and so on - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) + Set the following parameters in addition to the basic parameters: + + `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` + `mimetype` - MIMEType of the payload + `filename` - filename. Most SWORD2 uploads have this as being mandatory. + `packaging` - the SWORD2 packaging type of the payload. + eg packaging = 'http://purl.org/net/sword/package/Binary' + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) + + + 2. "Adding New Metadata to a Container" + -------------------------------------def _normalise_mime(self, mime): + if mime is None: + return None + return mime.lower().replace(" ", "")-- + + NB SWORD2 does not instruct the server on the best way to handle metadata, only that metadata SHOULD be + added and not overwritten; in certain circumstances this may not produce the desired behaviour. + + Set the following parameters in addition to the basic parameters: + + `metadata_entry` - An instance of `sword2.Entry`, set with the metadata required. + + for example: + # conn = `sword2.Connection`, se_iri = SWORD2-Edit-IRI + >>> from sword2 import Entry + >>> entry = Entry(dcterms:identifier = "doi://......") + >>> conn.add_new_item_to_container(se_iri = se_iri, + ... metadata_entry = entry) + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) + + 3. "Adding New Metadata and Packages or Files to a Container with Multipart" + ---------------------------------------------------------------------------- + + Create a resource in a given collection by uploading a file AND the metadata about this resource. + + To make this sort of request, just set the parameters as shown for both the binary upload and the metadata upload. + + eg: + + >>> conn.add_new_item_to_container(se_iri = se_iri, + ... metadata_entry = entry, + ... payload = open("foo.zip", "r"), + ... mimetype = + .... and so on + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) """ - + if not se_iri: if dr != None: conn_l.info("Using the deposit receipt to get the SWORD2-Edit-IRI") @@ -1176,117 +1276,121 @@ def append(self, # we could try the edit IRI although technically that's not what it's for se_iri = dr.edit if se_iri: - conn_l.info("Complete deposit using the Edit-IRI %s as SWORD2-Edit-IRI not available" % se_iri) + conn_l.info( + "Complete deposit using the Edit-IRI %s as SWORD2-Edit-IRI not available" + % se_iri + ) else: - raise Exception("No SWORD2-Edit-IRI was given and no suitable IRI was found in the deposit receipt.") + raise Exception( + "No SWORD2-Edit-IRI was given and no suitable IRI was found in the deposit receipt." + ) else: raise Exception("No SWORD2-Edit-IRI was given") else: conn_l.info("Update Resource via SWORD2-Edit-IRI %s" % se_iri) - conn_l.info("Adding new file, metadata or both to a SWORD deposit via SWORD-Edit-IRI %s" % se_iri) - return self._make_request(target_iri = se_iri, - payload=payload, - mimetype=mimetype, - packaging=packaging, - filename=filename, - metadata_entry=metadata_entry, - on_behalf_of=on_behalf_of, - in_progress=in_progress, - method="POST", - metadata_relevant=metadata_relevant, - request_type='SE_IRI POST (APPEND PKG)', - md5sum=md5sum) - - - def delete(self, - resource_iri, - on_behalf_of=None): + conn_l.info( + "Adding new file, metadata or both to a SWORD deposit via SWORD-Edit-IRI %s" + % se_iri + ) + return self._make_request( + target_iri=se_iri, + payload=payload, + mimetype=mimetype, + packaging=packaging, + filename=filename, + metadata_entry=metadata_entry, + on_behalf_of=on_behalf_of, + in_progress=in_progress, + method="POST", + metadata_relevant=metadata_relevant, + request_type="SE_IRI POST (APPEND PKG)", + md5sum=md5sum, + ) + + def delete(self, resource_iri, on_behalf_of=None): """ -Delete resource + Delete resource -Generic method to send an HTTP DELETE request to a given IRI. + Generic method to send an HTTP DELETE request to a given IRI. -Can be given the optional parameter of `on_behalf_of`. + Can be given the optional parameter of `on_behalf_of`. """ conn_l.info("Deleting resource %s" % resource_iri) - return self._make_request(target_iri = resource_iri, - on_behalf_of=on_behalf_of, - method="DELETE", - request_type='IRI DELETE', - in_progress=False) - - def delete_content_of_resource(self, edit_media_iri = None, - on_behalf_of = None, - dr = None): - + return self._make_request( + target_iri=resource_iri, + on_behalf_of=on_behalf_of, + method="DELETE", + request_type="IRI DELETE", + in_progress=False, + ) + + def delete_content_of_resource( + self, edit_media_iri=None, on_behalf_of=None, dr=None + ): """ -Deleting the Content of a Resource - -Remove all the content of a resource without removing the resource itself + Deleting the Content of a Resource -#BETASWORD2URL -See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_deletingcontent + Remove all the content of a resource without removing the resource itself -Usage: ------- + #BETASWORD2URL + See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_deletingcontent -Set the target for this request: --------------------------------- + Usage: + ------ -Set `edit_media_iri` to be the Edit-Media-IRI for a given resource. + Set the target for this request: + -------------------------------- + Set `edit_media_iri` to be the Edit-Media-IRI for a given resource. - OR -you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, -and the correct IRI will automatically be chosen. + OR + + you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, + and the correct IRI will automatically be chosen. """ if not edit_media_iri: if dr != None: conn_l.info("Using the deposit receipt to get the Edit-Media-IRI") edit_media_iri = dr.edit_media if edit_media_iri: - conn_l.info("Deleting Resource via Edit-Media-IRI %s" % edit_media_iri) + conn_l.info( + "Deleting Resource via Edit-Media-IRI %s" % edit_media_iri + ) else: - raise Exception("No Edit-Media-IRI was given and no suitable IRI was found in the deposit receipt.") + raise Exception( + "No Edit-Media-IRI was given and no suitable IRI was found in the deposit receipt." + ) else: raise Exception("No Edit-Media-IRI was given") else: conn_l.info("Deleting Resource via Edit-Media-IRI %s" % edit_media_iri) - return self.delete(edit_media_iri, - on_behalf_of = on_behalf_of) - + return self.delete(edit_media_iri, on_behalf_of=on_behalf_of) - - - - def delete_container(self, edit_iri = None, - on_behalf_of = None, - dr = None): - + def delete_container(self, edit_iri=None, on_behalf_of=None, dr=None): """ -Deleting the Container - -Delete the entire object on the server, effectively removing the deposit entirely. + Deleting the Container -#BETASWORD2URL -See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_deleteconteiner + Delete the entire object on the server, effectively removing the deposit entirely. + + #BETASWORD2URL + See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_deleteconteiner -Usage: ------- + Usage: + ------ -Set the target for this request: --------------------------------- + Set the target for this request: + -------------------------------- -Set `edit_iri` to be the Edit-IRI for a given resource. + Set `edit_iri` to be the Edit-IRI for a given resource. - OR + OR -you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, -and the correct IRI will automatically be chosen. + you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, + and the correct IRI will automatically be chosen. """ if not edit_iri: @@ -1296,220 +1400,234 @@ def delete_container(self, edit_iri = None, if edit_iri: conn_l.info("Deleting Container via Edit-IRI %s" % edit_iri) else: - raise Exception("No Edit-IRI was given and no suitable IRI was found in the deposit receipt.") + raise Exception( + "No Edit-IRI was given and no suitable IRI was found in the deposit receipt." + ) else: raise Exception("No Edit-IRI was given") else: conn_l.info("Deleting Container via Edit-IRI %s" % edit_iri) - return self.delete(edit_iri, - on_behalf_of = on_behalf_of) - - def complete_deposit(self, - se_iri = None, - on_behalf_of=None, - dr = None): + return self.delete(edit_iri, on_behalf_of=on_behalf_of) + + def complete_deposit(self, se_iri=None, on_behalf_of=None, dr=None): """ -Completing a Previously Incomplete Deposit + Completing a Previously Incomplete Deposit -Use this method to indicate to a server that a deposit which was 'in progress' is now complete. In other words, complete a deposit -which had the 'In-Progress' flag set to True. + Use this method to indicate to a server that a deposit which was 'in progress' is now complete. In other words, complete a deposit + which had the 'In-Progress' flag set to True. -#BETASWORD2URL -http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#continueddeposit_complete + #BETASWORD2URL + http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#continueddeposit_complete -Usage: ------- + Usage: + ------ -Set the target for this request: --------------------------------- + Set the target for this request: + -------------------------------- -Set `se_iri` to be the SWORD2-Edit-IRI for a given resource. + Set `se_iri` to be the SWORD2-Edit-IRI for a given resource. - OR + OR -you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, -and the correct IRI will automatically be chosen. + you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, + and the correct IRI will automatically be chosen. """ - + if not se_iri: if dr != None: conn_l.info("Using the deposit receipt to get the SWORD2-Edit-IRI") se_iri = dr.se_iri if se_iri: - conn_l.info("Complete deposit using the SWORD2-Edit-IRI %s" % se_iri) + conn_l.info( + "Complete deposit using the SWORD2-Edit-IRI %s" % se_iri + ) else: # we could try the edit-media IRI although technically that's not what it's for se_iri = dr.edit if se_iri: - conn_l.info("Complete deposit using the Edit-IRI %s as SWORD2-Edit-IRI not available" % se_iri) + conn_l.info( + "Complete deposit using the Edit-IRI %s as SWORD2-Edit-IRI not available" + % se_iri + ) else: - raise Exception("No SWORD2-Edit-IRI was given and no suitable IRI was found in the deposit receipt.") + raise Exception( + "No SWORD2-Edit-IRI was given and no suitable IRI was found in the deposit receipt." + ) else: raise Exception("No SWORD2-Edit-IRI was given") else: conn_l.info("Complete deposit using the SWORD2-Edit-IRI %s" % se_iri) - - return self._make_request(target_iri = se_iri, - on_behalf_of=on_behalf_of, - in_progress='false', - method="POST", - empty=True, - request_type='SE_IRI Complete Deposit') - - def update_files_for_resource(self, - 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 - - edit_media_iri = None, - - on_behalf_of=None, - in_progress=False, - metadata_relevant=False, - # Pass back the deposit receipt to automatically get the right IRI to use - dr = None - ): + + return self._make_request( + target_iri=se_iri, + on_behalf_of=on_behalf_of, + in_progress="false", + method="POST", + empty=True, + request_type="SE_IRI Complete Deposit", + ) + + def update_files_for_resource( + self, + 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 + edit_media_iri=None, + on_behalf_of=None, + in_progress=False, + metadata_relevant=False, + # Pass back the deposit receipt to automatically get the right IRI to use + dr=None, + ): """ -Replacing the File Content of a Resource + Replacing the File Content of a Resource -#BETASWORD2URL -See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_editingcontent_binary + #BETASWORD2URL + See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_editingcontent_binary -The `Connection` can replace the file content of a resource, given the Edit-Media-IRI for this resource. This can be found -from the `sword2.Deposit_Receipt.edit_media` attribute of a previous deposit, or directly from the deposit receipt XML response. + The `Connection` can replace the file content of a resource, given the Edit-Media-IRI for this resource. This can be found + from the `sword2.Deposit_Receipt.edit_media` attribute of a previous deposit, or directly from the deposit receipt XML response. -Usage: ------- + Usage: + ------ -Set the target for this request: --------------------------------- + Set the target for this request: + -------------------------------- -Set the `edit_media_iri` parameter to the Edit-Media-IRI. + Set the `edit_media_iri` parameter to the Edit-Media-IRI. - OR + OR -you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, -and the correct IRI will automatically be chosen. + you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, + and the correct IRI will automatically be chosen. -Then, add in the payload: -------------------------- + Then, add in the payload: + ------------------------- -Set the following parameters in addition to the basic parameters (see `self.create_resource`): + Set the following parameters in addition to the basic parameters (see `self.create_resource`): - `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` - `mimetype` - MIMEType of the payload - `filename` - filename. Most SWORD2 uploads have this as being mandatory. - `packaging` - the SWORD2 packaging type of the payload. - eg packaging = 'http://purl.org/net/sword/package/Binary' - - `metadata_relevant` - This should be set to `True` if the server should consider the file a potential source of metadata extraction, - or `False` if the server should not attempt to extract any metadata from the deposi - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) + `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` + `mimetype` - MIMEType of the payload + `filename` - filename. Most SWORD2 uploads have this as being mandatory. + `packaging` - the SWORD2 packaging type of the payload. + eg packaging = 'http://purl.org/net/sword/package/Binary' + + `metadata_relevant` - This should be set to `True` if the server should consider the file a potential source of metadata extraction, + or `False` if the server should not attempt to extract any metadata from the deposi + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) """ if not edit_media_iri: if dr != None: conn_l.info("Using the deposit receipt to get the Edit-Media-IRI") edit_media_iri = dr.edit_media if edit_media_iri: - conn_l.info("Update Resource via Edit-Media-IRI %s" % edit_media_iri) + conn_l.info( + "Update Resource via Edit-Media-IRI %s" % edit_media_iri + ) else: - raise Exception("No Edit-Media-IRI was given and no suitable IRI was found in the deposit receipt.") + raise Exception( + "No Edit-Media-IRI was given and no suitable IRI was found in the deposit receipt." + ) else: raise Exception("No Edit-Media-IRI was given") else: conn_l.info("Update Resource via Edit-Media-IRI %s" % edit_media_iri) - - return self._make_request(target_iri = edit_media_iri, - payload=payload, - mimetype=mimetype, - filename=filename, - in_progress=in_progress, - packaging=packaging, - on_behalf_of=on_behalf_of, - method="PUT", - metadata_relevant=str(metadata_relevant), - request_type='EM_IRI PUT', - md5sum=md5sum) - - def update_metadata_for_resource(self, metadata_entry, # required - edit_iri = None, - in_progress=False, - on_behalf_of=None, - dr = None - ): + + return self._make_request( + target_iri=edit_media_iri, + payload=payload, + mimetype=mimetype, + filename=filename, + in_progress=in_progress, + packaging=packaging, + on_behalf_of=on_behalf_of, + method="PUT", + metadata_relevant=str(metadata_relevant), + request_type="EM_IRI PUT", + md5sum=md5sum, + ) + + def update_metadata_for_resource( + self, + metadata_entry, # required + edit_iri=None, + in_progress=False, + on_behalf_of=None, + dr=None, + ): """ -Replacing the Metadata of a Resource + Replacing the Metadata of a Resource -#BETASWORD2URL -See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_editingcontent_metadata - -Replace the metadata of a resource as identified by its Edit-IRI. - -Note, from the specification: "The client can only be sure that the server will support this process when using the default format supported by SWORD: Qualified Dublin Core XML embedded directly in the atom:entry. Other metadata formats MAY be supported by a particular server, but this is not covered by the SWORD profile" - -Usage: ------- - -Set the target for this request: --------------------------------- - -Set the `edit_iri` parameter to the Edit-IRI. - - OR - -you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, -and the correct IRI will automatically be chosen. - -Then, add in the metadata: --------------------------- - -Set the following in addition to the basic parameters: - - `metadata_entry` - An instance of `sword2.Entry`, set with the metadata required. - -for example, to replace the metadata for a given: - # conn = `sword2.Connection`, edit_iri = Edit-IRI - - >>> from sword2 import Entry - >>> entry = Entry(title = "My new deposit", - ... id = "new:id", # atom:id - ... dcterms_abstract = "My Thesis", - ... dcterms_author = "Ben", - ... dcterms_issued = "2010") - - >>> conn.update_metadata_for_resource(edit_iri = edit_iri, - ... metadata_entry = entry) - - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) + #BETASWORD2URL + See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_editingcontent_metadata + + Replace the metadata of a resource as identified by its Edit-IRI. + + Note, from the specification: "The client can only be sure that the server will support this process when using the default format supported by SWORD: Qualified Dublin Core XML embedded directly in the atom:entry. Other metadata formats MAY be supported by a particular server, but this is not covered by the SWORD profile" + + Usage: + ------ + + Set the target for this request: + -------------------------------- + + Set the `edit_iri` parameter to the Edit-IRI. + + OR + + you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, + and the correct IRI will automatically be chosen. + + Then, add in the metadata: + -------------------------- + + Set the following in addition to the basic parameters: + + `metadata_entry` - An instance of `sword2.Entry`, set with the metadata required. + + for example, to replace the metadata for a given: + # conn = `sword2.Connection`, edit_iri = Edit-IRI + + >>> from sword2 import Entry + >>> entry = Entry(title = "My new deposit", + ... id = "new:id", # atom:id + ... dcterms_abstract = "My Thesis", + ... dcterms_author = "Ben", + ... dcterms_issued = "2010") + + >>> conn.update_metadata_for_resource(edit_iri = edit_iri, + ... metadata_entry = entry) + + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) """ if not edit_iri: if dr != None: @@ -1518,94 +1636,98 @@ def update_metadata_for_resource(self, metadata_entry, # required if edit_iri: conn_l.info("Update Resource via Edit-IRI %s" % edit_iri) else: - raise Exception("No Edit-IRI was given and no suitable IRI was found in the deposit receipt.") + raise Exception( + "No Edit-IRI was given and no suitable IRI was found in the deposit receipt." + ) else: raise Exception("No Edit-IRI was given") else: conn_l.info("Update Resource via Edit-IRI %s" % edit_iri) - return self._make_request(target_iri = edit_iri, - metadata_entry=metadata_entry, - on_behalf_of=on_behalf_of, - in_progress=in_progress, - method="PUT", - request_type='Edit_IRI PUT') - - def update_metadata_and_files_for_resource(self, metadata_entry, # required - 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 - - edit_iri = None, - - metadata_relevant=False, - in_progress=False, - on_behalf_of=None, - dr = None - ): + return self._make_request( + target_iri=edit_iri, + metadata_entry=metadata_entry, + on_behalf_of=on_behalf_of, + in_progress=in_progress, + method="PUT", + request_type="Edit_IRI PUT", + ) + + def update_metadata_and_files_for_resource( + self, + metadata_entry, # required + 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 + edit_iri=None, + metadata_relevant=False, + in_progress=False, + on_behalf_of=None, + dr=None, + ): """ -Replacing the Metadata and Files of a Resource + Replacing the Metadata and Files of a Resource -#BETASWORD2URL -See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_editingcontent_multipart + #BETASWORD2URL + See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_editingcontent_multipart -Replace the metadata and files of a resource as identified by its Edit-IRI. + Replace the metadata and files of a resource as identified by its Edit-IRI. -Usage: ------- + Usage: + ------ -Set the target for this request: --------------------------------- + Set the target for this request: + -------------------------------- -Set the `edit_iri` parameter to the Edit-IRI. + Set the `edit_iri` parameter to the Edit-IRI. - OR + OR -you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, -and the correct IRI will automatically be chosen. + you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, + and the correct IRI will automatically be chosen. -Then, add in the file and metadata information: ------------------------------------------------ -Set the following in addition to the basic parameters: + Then, add in the file and metadata information: + ----------------------------------------------- + Set the following in addition to the basic parameters: -File information: + File information: - `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` - `mimetype` - MIMEType of the payload - `filename` - filename. Most SWORD2 uploads have this as being mandatory. - `packaging` - the SWORD2 packaging type of the payload. - eg packaging = 'http://purl.org/net/sword/package/Binary' - - `metadata_relevant` - This should be set to `True` if the server should consider the file a potential source of metadata extraction, - or `False` if the server should not attempt to extract any metadata from the deposi - -Metadata information: - - `metadata_entry` - An instance of `sword2.Entry`, set with the metadata required. - -for example, to create a metadata entry - >>> from sword2 import Entry - >>> entry = Entry(title = "My new deposit", - ... id = "new:id", # atom:id - ... dcterms_abstract = "My Thesis", - ... dcterms_author = "Ben", - ... dcterms_issued = "2010") - -Response: - -A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or -not a Deposit Response, then only a few attributes will be populated: - - `code` -- HTTP code of the response - `response_headers` -- `dict` of the reponse headers - `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt - -If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) -then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, -response_headers, etc) + `payload` - the payload to send. Can be either a bytestring or a File-like object that supports `payload.read()` + `mimetype` - MIMEType of the payload + `filename` - filename. Most SWORD2 uploads have this as being mandatory. + `packaging` - the SWORD2 packaging type of the payload. + eg packaging = 'http://purl.org/net/sword/package/Binary' + + `metadata_relevant` - This should be set to `True` if the server should consider the file a potential source of metadata extraction, + or `False` if the server should not attempt to extract any metadata from the deposi + + Metadata information: + + `metadata_entry` - An instance of `sword2.Entry`, set with the metadata required. + + for example, to create a metadata entry + >>> from sword2 import Entry + >>> entry = Entry(title = "My new deposit", + ... id = "new:id", # atom:id + ... dcterms_abstract = "My Thesis", + ... dcterms_author = "Ben", + ... dcterms_issued = "2010") + + Response: + + A `sword2.Deposit_Receipt` object containing the deposit receipt data. If the response was blank or + not a Deposit Response, then only a few attributes will be populated: + + `code` -- HTTP code of the response + `response_headers` -- `dict` of the reponse headers + `content` -- (Optional) in case the response body is not empty but the response is not a Deposit Receipt + + If exception-throwing is turned off (`error_response_raises_exceptions = False` or `self.raise_except = False`) + then the response will be a `sword2.Error_Document`, but will still have the aforementioned attributes set, (code, + response_headers, etc) """ if not edit_iri: if dr != None: @@ -1614,44 +1736,50 @@ def update_metadata_and_files_for_resource(self, metadata_entry, # required if edit_iri: conn_l.info("Update Resource via Edit-IRI %s" % edit_iri) else: - raise Exception("No Edit-IRI was given and no suitable IRI was found in the deposit receipt.") + raise Exception( + "No Edit-IRI was given and no suitable IRI was found in the deposit receipt." + ) else: raise Exception("No Edit-IRI was given") else: conn_l.info("Update Resource via Edit-IRI %s" % edit_iri) - return self._make_request(target_iri = edit_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='Edit_IRI PUT', - md5sum=md5sum) - + return self._make_request( + target_iri=edit_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="Edit_IRI PUT", + md5sum=md5sum, + ) def get_deposit_receipt(self, edit_iri): """ -Getting a copy of the Entry Document/Deposit Receipt + Getting a copy of the Entry Document/Deposit Receipt -FIXME: this explicitly requests the receipt from the server, but there is a -cache of deposit receipts - how should we access this? + FIXME: this explicitly requests the receipt from the server, but there is a + cache of deposit receipts - how should we access this? -FIXME: there's also something funny going on with get_resource remembering -old headers, but not quite sure where that's coming from. Have to pass in -packaging and headers explicitly to overcome + FIXME: there's also something funny going on with get_resource remembering + old headers, but not quite sure where that's coming from. Have to pass in + packaging and headers explicitly to overcome """ conn_l.debug("Trying to GET the ATOM Entry Document at %s." % edit_iri) response = self.get_resource(edit_iri, packaging=None, headers={}) if response.code == 200: conn_l.debug("Attempting to parse the response as a Deposit Receipt") - d = Deposit_Receipt(xml_deposit_receipt = response.content) + d = Deposit_Receipt(xml_deposit_receipt=response.content) if d.parsed: - conn_l.info("Server responsed with a Deposit Receipt. Caching a copy in .resources['%s']" % d.edit) + conn_l.info( + "Server responsed with a Deposit Receipt. Caching a copy in .resources['%s']" + % d.edit + ) d.response_headers = dict(response.response_headers) d.code = 200 self._cache_deposit_receipt(d) @@ -1663,76 +1791,86 @@ def get_deposit_receipt(self, edit_iri): def get_ore_sword_statement(self, sword_statement_iri): """ -Getting the Sword Statement. + Getting the Sword Statement. """ # get the statement first - conn_l.debug("Trying to GET the ORE Sword Statement at %s." % sword_statement_iri) - response = self.get_resource(sword_statement_iri, headers = {'Accept':'application/rdf+xml'}) + conn_l.debug( + "Trying to GET the ORE Sword Statement at %s." % sword_statement_iri + ) + response = self.get_resource( + sword_statement_iri, headers={"Accept": "application/rdf+xml"} + ) if response.code == 200: - #try: + # try: if True: - conn_l.debug("Attempting to parse the response as a ORE Sword Statement") + conn_l.debug( + "Attempting to parse the response as a ORE Sword Statement" + ) s = Ore_Sword_Statement(response.content) conn_l.debug("Parsed SWORD2 Statement, returning") return s - #except Exception, e: + # except Exception, e: # # Any error here is to do with the parsing # return response.content def get_atom_sword_statement(self, sword_statement_iri): """ -Getting the Sword Statement. + Getting the Sword Statement. """ # get the statement first - conn_l.debug("Trying to GET the ATOM Sword Statement at %s." % sword_statement_iri) - response = self.get_resource(sword_statement_iri, headers = {'Accept':'application/atom+xml;type=feed'}) + conn_l.debug( + "Trying to GET the ATOM Sword Statement at %s." % sword_statement_iri + ) + response = self.get_resource( + sword_statement_iri, headers={"Accept": "application/atom+xml;type=feed"} + ) if response.code == 200: - #try: + # try: if True: - conn_l.debug("Attempting to parse the response as a ATOM Sword Statement") + conn_l.debug( + "Attempting to parse the response as a ATOM Sword Statement" + ) s = Atom_Sword_Statement(response.content) conn_l.debug("Parsed SWORD2 Statement, returning") return s - #except Exception, e: + # except Exception, e: # # Any error here is to do with the parsing # return response.content - def get_resource(self, content_iri = None, - packaging=None, - on_behalf_of=None, - headers = {}, - dr = None): + def get_resource( + self, content_iri=None, packaging=None, on_behalf_of=None, headers={}, dr=None + ): """ -Retrieving the content + Retrieving the content -Get the file or package from the SWORD2 server. + Get the file or package from the SWORD2 server. -From the specification: - "The Deposit Receipt contains two IRIs which can be used to retrieve content from the server: Cont-IRI and EM-IRI. These are provided in the atom:content@src element and the atom:link@rel="edit-media" elements respectively. Their only functional difference is that the client MUST NOT carry out any HTTP operations other than GET on the Cont-IRI, while all operations are permitted on the EM-IRI. It is acceptable, but not required, that both IRIs to be the same, and in this section we refer only to the EM-IRI but in all cases it can be substituted for the Cont-IRI." + From the specification: + "The Deposit Receipt contains two IRIs which can be used to retrieve content from the server: Cont-IRI and EM-IRI. These are provided in the atom:content@src element and the atom:link@rel="edit-media" elements respectively. Their only functional difference is that the client MUST NOT carry out any HTTP operations other than GET on the Cont-IRI, while all operations are permitted on the EM-IRI. It is acceptable, but not required, that both IRIs to be the same, and in this section we refer only to the EM-IRI but in all cases it can be substituted for the Cont-IRI." -#BETASWORD2URL -See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_retrievingcontent + #BETASWORD2URL + See http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#protocoloperations_retrievingcontent -Usage: ------- + Usage: + ------ -Set the target for this request: --------------------------------- + Set the target for this request: + -------------------------------- -Set `content_iri` to be the Content-IRI for a given resource (or to the IRI of any resource you wish to HTTP GET) + Set `content_iri` to be the Content-IRI for a given resource (or to the IRI of any resource you wish to HTTP GET) - OR + OR -you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, -and the correct IRI will automatically be chosen. + you can pass back the `sword2.Deposit_Receipt` object you got from a previous transaction as the `dr` parameter, + and the correct IRI will automatically be chosen. -Response: - - A `ContentWrapper` - - `ContentWrapper.response_headers` -- response headers - `ContentWrapper.content` -- body of response from server (the file or package) - `ContentWrapper.code` -- status code ('200' on success.) + Response: + + A `ContentWrapper` - + `ContentWrapper.response_headers` -- response headers + `ContentWrapper.content` -- body of response from server (the file or package) + `ContentWrapper.code` -- status code ('200' on success.) """ if not content_iri: @@ -1742,80 +1880,114 @@ def get_resource(self, content_iri = None, if content_iri: conn_l.info("Getting the resource at Content-IRI %s" % content_iri) else: - raise Exception("No Content-IRI was given and no suitable IRI was found in the deposit receipt.") + raise Exception( + "No Content-IRI was given and no suitable IRI was found in the deposit receipt." + ) else: raise Exception("No Content-IRI was given") else: conn_l.info("Getting the resource at Content-IRI %s" % content_iri) - + # 406 - PackagingFormatNotAvailable if self.honour_receipts and packaging: # Make sure that the packaging format is available from the deposit receipt, if loaded - conn_l.debug("Checking that the packaging format '%s' is available." % content_iri) + conn_l.debug( + "Checking that the packaging format '%s' is available." % content_iri + ) conn_l.debug("Cached Cont-IRI Receipts: %s" % list(self.cont_iris.keys())) if content_iri in list(self.cont_iris.keys()): if not (packaging in self.cont_iris[content_iri].packaging): - conn_l.error("Desired packaging format '%' not available from the server, according to the deposit receipt. Change the client parameter 'honour_receipts' to False to avoid this check.") - return self._return_error_or_exception(PackagingFormatNotAvailable, {}, "") + conn_l.error( + "Desired packaging format '%' not available from the server, according to the deposit receipt. Change the client parameter 'honour_receipts' to False to avoid this check." + ) + return self._return_error_or_exception( + PackagingFormatNotAvailable, {}, "" + ) if on_behalf_of: - headers['On-Behalf-Of'] = on_behalf_of + headers["On-Behalf-Of"] = on_behalf_of elif self.on_behalf_of: - headers['On-Behalf-Of'] = self.on_behalf_of + headers["On-Behalf-Of"] = self.on_behalf_of if packaging: - headers['Accept-Packaging'] = packaging - + headers["Accept-Packaging"] = packaging + self._t.start("IRI GET resource") if packaging: - conn_l.info("IRI GET resource '%s' with Accept-Packaging:%s" % (content_iri, packaging)) + conn_l.info( + "IRI GET resource '%s' with Accept-Packaging:%s" + % (content_iri, packaging) + ) else: conn_l.info("IRI GET resource '%s'" % content_iri) conn_l.debug("Using headers: " + str(headers)) resp, content = self.h.request(content_iri, "GET", headers=headers) _, took_time = self._t.time_since_start("IRI GET resource") if self.history: - self.history.log('Cont_IRI GET resource', - sd_iri = self.sd_iri, - content_iri = content_iri, - packaging = packaging, - on_behalf_of = self.on_behalf_of, - response = resp, - headers = headers, - process_duration = took_time) - conn_l.info("Server response: %s" % resp['status']) + self.history.log( + "Cont_IRI GET resource", + sd_iri=self.sd_iri, + content_iri=content_iri, + packaging=packaging, + on_behalf_of=self.on_behalf_of, + response=resp, + headers=headers, + process_duration=took_time, + ) + conn_l.info("Server response: %s" % resp["status"]) conn_l.debug(dict(resp)) - if resp['status'] == 200: - conn_l.debug("Cont_IRI GET resource successful - got %s bytes from %s" % (len(content), content_iri)) + if resp["status"] == 200: + conn_l.debug( + "Cont_IRI GET resource successful - got %s bytes from %s" + % (len(content), content_iri) + ) + class ContentWrapper(object): def __init__(self, resp, content): self.response_headers = dict(resp) self.content = content self.code = resp.status + return ContentWrapper(resp, content) # NOTE: let the core error handling deal with this - #elif resp['status'] == 406: # Unavailable packaging format + # elif resp['status'] == 406: # Unavailable packaging format # conn_l.error("Desired packaging format '%' not available from the server.") # return self._return_error_or_exception(PackagingFormatNotAvailable, resp, content) else: return self._handle_error_response(resp, content) - - def replace_file(self, file_edit_media, payload, mimetype, packaging=None, on_behalf_of=None, metadata_relevant=False): + + def replace_file( + self, + file_edit_media, + payload, + mimetype, + packaging=None, + on_behalf_of=None, + metadata_relevant=False, + ): """ API Sugar for replacing any given file (such as that retrieved from a feed of the media resource) This supports all the headers required by 6.11 of the spec """ - return self._make_request(file_edit_media, payload=payload, mimetype=mimetype, filename="unnamed", - packaging=packaging, on_behalf_of=on_behalf_of, metadata_relevant=metadata_relevant, - method="PUT") - + return self._make_request( + file_edit_media, + payload=payload, + mimetype=mimetype, + filename="unnamed", + packaging=packaging, + on_behalf_of=on_behalf_of, + metadata_relevant=metadata_relevant, + method="PUT", + ) + def delete_file(self, file_edit_media, on_behalf_of=None): """ API sugar for deleting a given file (such as that retrieved from a feed of the media resource). This supports all the headers required by 6.11 of the spec """ - return self._make_request(file_edit_media, on_behalf_of=on_behalf_of, method="DELETE") - + return self._make_request( + file_edit_media, on_behalf_of=on_behalf_of, method="DELETE" + ) + def _normalise_mime(self, mime): if mime is None: return None return mime.lower().replace(" ", "") - diff --git a/sword2/deposit_receipt.py b/sword2/deposit_receipt.py index 77114b9..8e2815b 100644 --- a/sword2/deposit_receipt.py +++ b/sword2/deposit_receipt.py @@ -2,7 +2,7 @@ # -*- coding: utf-8 -*- """ -This module provides `Deposit_Receipt`, a convenient class for extracting information from the Deposit Receipts sent back by the +This module provides `Deposit_Receipt`, a convenient class for extracting information from the Deposit Receipts sent back by the SWORD2-compliant server for many transactions. #BETASWORD2URL @@ -11,6 +11,7 @@ """ from .sword2_logging import logging + d_l = logging.getLogger(__name__) from .atom_objects import Category @@ -18,100 +19,108 @@ from lxml import etree from .utils import NS, get_text + class Deposit_Receipt(object): - def __init__(self, xml_deposit_receipt=None, dom=None, response_headers={}, location=None, code=0): + def __init__( + self, + xml_deposit_receipt=None, + dom=None, + response_headers={}, + location=None, + code=0, + ): """ -`Deposit_Receipt` - provides convenience methods for extracting information from the Deposit Receipts sent back by the -SWORD2-compliant server for many transactions. + `Deposit_Receipt` - provides convenience methods for extracting information from the Deposit Receipts sent back by the + SWORD2-compliant server for many transactions. -#BETASWORD2URL -See Section 10. Deposit Receipt: http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#depositreceipt + #BETASWORD2URL + See Section 10. Deposit Receipt: http://sword-app.svn.sourceforge.net/viewvc/sword-app/spec/trunk/SWORDProfile.html?revision=HEAD#depositreceipt + + Transactions carried out by `sword2.Connection` will return a `Deposit_Receipt` object, if a deposit receipt document is sent back by the server. + + Usage: + + >>> from sword2 import Deposit_Receipt + + .... get the XML text for a Deposit Receipt in the variable `doc` + + # Parse the response: + >>> dr = Deposit_Receipt(xml_deposit_receipt = doc) + + # Check that the response is parsable (valid XML) and is SWORD2-compliant + >>> assert dr.parsed == True + >>> assert dr.valid == True + + Availible attributes: + + Atom convenience attribs -- corresponds to (type of object that is held) + `self.title` -- (`str`) + `self.id` -- (`str`) + `self.updated` -- (`str`) + `self.summary` -- (`str`) + `self.categories` -- (`list` of `sword2.Category`) + + IRI/URIs + `self.edit` -- The Edit-IRI (`str`) + + `self.edit_media` -- The Edit-Media-IRI (`str`) + + `self.edit_media_feed` -- The Edit-Media-IRI [Atom Feed] (`str`) + + `self.alternate` -- A link which, according to the spec, (`str`) + "points to the splash page of the item on the server" + `self.se_iri` -- The SWORD2 Edit IRI (SE-IRI), defined by (`str`) + + which MAY be the same as the Edit-IRI + + `self.cont_iri` -- The Content-IRI (`str`) + eg `src` from + `self.content` -- All Content-IRIs (`dict` with the src or Content-IRI as the key, with a `dict` of the other attributes as its value + + `self.links` -- All links elements in a `dict`, with the 'rel' value being used as its key. The values of this are `list`s + with a `dict` of attributes for each item, corresponding to the information in a single element. + + SWORD2 links for "http://purl.org/net/sword/terms/originalDeposit" and "http://purl.org.net/sword/terms/derivedResource" + are to be found in `self.links` + + eg + >>> dr.links.get("http://purl.org.net/sword/terms/derivedResource") + {'href': "....", 'type':'application/pdf'} + + + General metadata: + `self.metadata` -- Simple metadata access. + A `dict` where the keys are equivalent to the prefixed element names, with an underscore(_) replacing the colon (:) + eg "" in the deposit receipt would be accessible in this attribute, under + the key of 'dcterms_title' + + eg + >>> dr.metadata.get("dcterms_title") + "The Origin of Species" + + >>> dr.metadata.get("dcterms_madeupelement") + `None` + + `self.packaging` -- sword:packaging elements declaring the formats that the Media Resource can be retrieved in (`list` of `str`) -Transactions carried out by `sword2.Connection` will return a `Deposit_Receipt` object, if a deposit receipt document is sent back by the server. - -Usage: - ->>> from sword2 import Deposit_Receipt - -.... get the XML text for a Deposit Receipt in the variable `doc` - -# Parse the response: ->>> dr = Deposit_Receipt(xml_deposit_receipt = doc) - -# Check that the response is parsable (valid XML) and is SWORD2-compliant ->>> assert dr.parsed == True ->>> assert dr.valid == True - -Availible attributes: - - Atom convenience attribs -- corresponds to (type of object that is held) - `self.title` -- (`str`) - `self.id` -- (`str`) - `self.updated` -- (`str`) - `self.summary` -- (`str`) - `self.categories` -- (`list` of `sword2.Category`) - - IRI/URIs - `self.edit` -- The Edit-IRI (`str`) - - `self.edit_media` -- The Edit-Media-IRI (`str`) - - `self.edit_media_feed` -- The Edit-Media-IRI [Atom Feed] (`str`) - - `self.alternate` -- A link which, according to the spec, (`str`) - "points to the splash page of the item on the server" - `self.se_iri` -- The SWORD2 Edit IRI (SE-IRI), defined by (`str`) - - which MAY be the same as the Edit-IRI - - `self.cont_iri` -- The Content-IRI (`str`) - eg `src` from - `self.content` -- All Content-IRIs (`dict` with the src or Content-IRI as the key, with a `dict` of the other attributes as its value - - `self.links` -- All links elements in a `dict`, with the 'rel' value being used as its key. The values of this are `list`s - with a `dict` of attributes for each item, corresponding to the information in a single element. - - SWORD2 links for "http://purl.org/net/sword/terms/originalDeposit" and "http://purl.org.net/sword/terms/derivedResource" - are to be found in `self.links` - - eg - >>> dr.links.get("http://purl.org.net/sword/terms/derivedResource") - {'href': "....", 'type':'application/pdf'} - - - General metadata: - `self.metadata` -- Simple metadata access. - A `dict` where the keys are equivalent to the prefixed element names, with an underscore(_) replacing the colon (:) - eg "" in the deposit receipt would be accessible in this attribute, under - the key of 'dcterms_title' - - eg - >>> dr.metadata.get("dcterms_title") - "The Origin of Species" - - >>> dr.metadata.get("dcterms_madeupelement") - `None` - - `self.packaging` -- sword:packaging elements declaring the formats that the Media Resource can be retrieved in (`list` of `str`) - - `self.response_headers` -- The HTTP response headers that accompanied this receipt - - `self.location` -- The location, if given (from HTTP Header: "Location: ....") - """ - self.dom = None # this will be populated below + `self.response_headers` -- The HTTP response headers that accompanied this receipt + + `self.location` -- The location, if given (from HTTP Header: "Location: ....") + """ + self.dom = None # this will be populated below self.parsed = False self.valid = False - self.response_headers=response_headers + self.response_headers = response_headers self.location = location self.content = None self.code = code self.metadata = {} self.links = {} - self.edit = location # default to the location, which should always be the same as the edit-iri + self.edit = location # default to the location, which should always be the same as the edit-iri self.edit_media = None self.edit_media_feed = None self.alternate = None - self.se_iri = None + self.se_iri = None self.atom_statement_iri = None self.ore_statement_iri = None # Atom convenience attribs @@ -119,12 +128,12 @@ def __init__(self, xml_deposit_receipt=None, dom=None, response_headers={}, loca self.id = None self.updated = None self.summary = None - + self.packaging = [] self.categories = [] self.content = {} self.cont_iri = None - + # first construct or set the dom if xml_deposit_receipt: try: @@ -137,15 +146,15 @@ def __init__(self, xml_deposit_receipt=None, dom=None, response_headers={}, loca self.dom = etree.fromstring(xml_deposit_receipt.encode("utf-8")) else: self.dom = etree.fromstring(bytes(xml_deposit_receipt)) - self.parsed = True + self.parsed = True except Exception as e: d_l.error("Was not able to parse the deposit receipt as XML.") return - + elif dom != None: self.dom = dom self.parsed = True - + # allow for the possibility that we are not given a body for the deposit # receipt (explicitly allowed by the spec) if self.dom != None: @@ -154,25 +163,28 @@ def __init__(self, xml_deposit_receipt=None, dom=None, response_headers={}, loca # user know what to expect (note that Error_Document sub classes Deposit_Receipt # and that will almost always fail the validation) self.valid = self.validate() - d_l.info("Initial SWORD2 validation checks on deposit receipt - Valid document? %s" % self.valid) - + d_l.info( + "Initial SWORD2 validation checks on deposit receipt - Valid document? %s" + % self.valid + ) + # finally, handle the metadata self.handle_metadata() - + def validate(self): valid = True - + # LINK REQUIREMENTS - + # It MUST contain a Media Entry IRI (Edit-IRI), defined by atom:link@rel="edit" has_edit = False # It MUST contain a Media Resource IRI (EM-IRI), defined by atom:link@rel="edit-media" has_em = False - # It MUST contain a SWORD Edit IRI (SE-IRI), defined by atom:link@rel=""" + # It MUST contain a SWORD Edit IRI (SE-IRI), defined by atom:link@rel=""" # which MAY be the same as the Edit-IRI has_se = False - - links = self.dom.findall(NS['atom'] % "link") + + links = self.dom.findall(NS["atom"] % "link") for link in links: rel = link.get("rel") if rel == "edit": @@ -181,20 +193,29 @@ def validate(self): has_em = True elif rel == "http://purl.org/net/sword/terms/add": has_se = True - + if not has_edit or not has_em or not has_se: - d_l.debug("Validation Fail: has_edit: " + str(has_edit) + "; has_em: " + str(has_em) + "; has_se: " + str(has_se)) + d_l.debug( + "Validation Fail: has_edit: " + + str(has_edit) + + "; has_em: " + + str(has_em) + + "; has_se: " + + str(has_se) + ) valid = False - - # It MUST contain a single sword:treatment element [SWORD003] which contains either a human-readable + + # It MUST contain a single sword:treatment element [SWORD003] which contains either a human-readable # statement describing treatment the deposited resource has received or a IRI that dereferences to such a description. - treatment = self.dom.findall(NS['sword'] % "treatment") + treatment = self.dom.findall(NS["sword"] % "treatment") if treatment == None or len(treatment) == 0: - d_l.debug("Validation Fail: no treatment or treatment invalid: " + str(treatment)) + d_l.debug( + "Validation Fail: no treatment or treatment invalid: " + str(treatment) + ) valid = False - + return valid - + def handle_metadata(self): """Method that walks the `etree.SubElement`, assigning the information to the objects attributes.""" for e in self.dom.getchildren(): @@ -208,10 +229,10 @@ def handle_metadata(self): elif field == "atom_content": self.handle_content(e) elif field == "atom_generator": - for ak,av in e.attrib.items(): + for ak, av in e.attrib.items(): if not e.text: e.text = "" - e.text += " %s:\"%s\"" % (ak, av) + e.text += ' %s:"%s"' % (ak, av) self.metadata[field] = [e.text.strip()] elif field == "sword_packaging": self.packaging.append(e.text) @@ -233,65 +254,68 @@ def handle_metadata(self): self.metadata[field] += [e.text] else: self.metadata[field] = [e.text] - + def handle_link(self, e): """Method that handles the intepreting of element information and placing it into the anticipated attributes.""" # MUST have rel - rel = e.attrib.get('rel', None) + rel = e.attrib.get("rel", None) if rel: if rel == "edit": - self.edit = e.attrib.get('href', None) + self.edit = e.attrib.get("href", None) elif rel == "edit-media": # only put the edit-media iri in the convenience attribute if # there is no 'type' - if self._normalise_mime(e.attrib.get('type')) == "application/atom+xml;type=feed": - self.edit_media_feed = e.attrib.get('href', None) + if ( + self._normalise_mime(e.attrib.get("type")) + == "application/atom+xml;type=feed" + ): + self.edit_media_feed = e.attrib.get("href", None) else: - self.edit_media = e.attrib.get('href', None) + self.edit_media = e.attrib.get("href", None) elif rel == "http://purl.org/net/sword/terms/add": - self.se_iri = e.attrib.get('href', None) + self.se_iri = e.attrib.get("href", None) elif rel == "alternate": - self.alternate = e.attrib.get('href', None) + self.alternate = e.attrib.get("href", None) elif rel == "http://purl.org/net/sword/terms/statement": t = self._normalise_mime(e.attrib.get("type")) if t is not None and t == "application/atom+xml;type=feed": - self.atom_statement_iri = e.attrib.get('href', None) + self.atom_statement_iri = e.attrib.get("href", None) elif t is not None and t == "application/rdf+xml": - self.ore_statement_iri = e.attrib.get('href', None) - + self.ore_statement_iri = e.attrib.get("href", None) + # Put all links into .links attribute, with all element attribs attribs = {} - for k,v in e.attrib.items(): + for k, v in e.attrib.items(): if k != "rel": attribs[k] = v - if rel in self.links: + if rel in self.links: self.links[rel].append(attribs) else: - self.links[rel] = [attribs] - + self.links[rel] = [attribs] + def _normalise_mime(self, mime): if mime is None: return None return mime.lower().replace(" ", "") - + def handle_content(self, e): """Method to intepret the elements.""" # eg if "src" in e.attrib: - src = e.attrib['src'] + src = e.attrib["src"] info = dict(e.attrib).copy() - del info['src'] + del info["src"] self.content[src] = info self.cont_iri = src - + def to_xml(self): """Convenience method for outputing the DOM as a (byte)string.""" return etree.tostring(self.dom) - + def __str__(self): """Method for producing a human-readable report about the information in this object, suitable for CLI or other logging. - + NB does not report all information, just key parts.""" _s = [] for k in sorted(self.metadata.keys()): diff --git a/sword2/error_document.py b/sword2/error_document.py index 1cd0b9c..c1cabfd 100644 --- a/sword2/error_document.py +++ b/sword2/error_document.py @@ -8,51 +8,56 @@ from .server_errors import SWORD2ERRORSBYIRI, get_error from .sword2_logging import logging + ed_l = logging.getLogger(__name__) + class Error_Document(Deposit_Receipt): """ -Example Error document: + Example Error document: - - - - Example repository - - ERROR - 2008-02-19T09:34:27Z + + + + Example repository + + ERROR + 2008-02-19T09:34:27Z - sword@example.org + sword@example.org - The manifest could be parsed, but was not valid - - no technical metadata was provided. - processing failed - - Exception at [ ... ] - - + The manifest could be parsed, but was not valid - + no technical metadata was provided. + processing failed + + Exception at [ ... ] + + - + -Error document is an AtomPub extension: + Error document is an AtomPub extension: -The sword:error element MAY contain any of the elements normally used in the Deposit Receipt, but all fields are OPTIONAL. + The sword:error element MAY contain any of the elements normally used in the Deposit Receipt, but all fields are OPTIONAL. -The error document SHOULD contain an atom:summary element with a short description of the error. + The error document SHOULD contain an atom:summary element with a short description of the error. -The error document MAY contain a sword:verboseDescription element with a long description of the problem or any other appropriate software-level debugging output (e.g. a stack trace). Server implementations may wish to provide this for client developers' convenience, but may wish to disable such output in any production systems. + The error document MAY contain a sword:verboseDescription element with a long description of the problem or any other appropriate software-level debugging output (e.g. a stack trace). Server implementations may wish to provide this for client developers' convenience, but may wish to disable such output in any production systems. -The server SHOULD specify that the Content-Type of the is text/xml or application/xml. + The server SHOULD specify that the Content-Type of the is text/xml or application/xml. """ + def __init__(self, xml_deposit_receipt=None, code=None, resp=None): ed_l.debug("Constructing Error Document Representation") if xml_deposit_receipt: - super(Error_Document, self).__init__(xml_deposit_receipt=xml_deposit_receipt, code=code) + super(Error_Document, self).__init__( + xml_deposit_receipt=xml_deposit_receipt, code=code + ) else: super(Error_Document, self).__init__(code=code) self.error_href = None @@ -61,15 +66,15 @@ def __init__(self, xml_deposit_receipt=None, code=None, resp=None): self.content = None # for parity with the ContentWrapper self.response_headers = resp self._characterise_error() - + def _characterise_error(self): if "sword_verboseDescription" in list(self.metadata.keys()): - self.verbose_description = self.metadata['sword_verboseDescription'] - + self.verbose_description = self.metadata["sword_verboseDescription"] + if self.dom != None: ed_l.debug("Error response contains document content") if "href" in list(self.dom.attrib.keys()): - self.error_href = self.dom.attrib['href'] + self.error_href = self.dom.attrib["href"] self.error_info = get_error(self.error_href, self.code) else: ed_l.debug("Error response does NOT contain document content") diff --git a/sword2/exceptions.py b/sword2/exceptions.py index a10775b..282eba4 100644 --- a/sword2/exceptions.py +++ b/sword2/exceptions.py @@ -4,30 +4,40 @@ Provides various Exception classes to match HTTP error code responses. """ + class HTTPResponseError(Exception): - """Generic exception for http codes greater than 399 and less than 599 """ + """Generic exception for http codes greater than 399 and less than 599""" + def __init__(self, response=None, content=None): self.response = response self.content = content - + + class ServerError(HTTPResponseError): - """ for http error codes 500 and up """ + """for http error codes 500 and up""" + pass + class NotAuthorised(HTTPResponseError): pass + class Forbidden(HTTPResponseError): pass + class RequestTimeOut(HTTPResponseError): pass + class NotFound(HTTPResponseError): pass + class PackagingFormatNotAvailable(HTTPResponseError): pass + class NotAcceptable(HTTPResponseError): pass diff --git a/sword2/http_layer.py b/sword2/http_layer.py index deb2c25..700bece 100644 --- a/sword2/http_layer.py +++ b/sword2/http_layer.py @@ -1,7 +1,9 @@ import json from .sword2_logging import logging + http_l = logging.getLogger(__name__) + class HttpResponse(object): def __init__(self, *args, **kwargs): pass @@ -27,18 +29,24 @@ def keys(self): class HttpLayer(object): - def __init__(self, *args, **kwargs): pass - def add_credentials(self, username, password): pass + def __init__(self, *args, **kwargs): + pass + + def add_credentials(self, username, password): + pass + def request(self, uri, method, headers=None, payload=None): # should return a tuple of an HttpResponse object and the content pass + ################################################################################ # Default httplib2 implementation ################################################################################ import httplib2 + class HttpLib2Response(HttpResponse): def __init__(self, response): self.resp = response @@ -57,6 +65,7 @@ def get(self, att, default=None): def keys(self): return list(self.resp.keys()) + class HttpLib2Layer(HttpLayer): def __init__(self, cache_dir=".cache", timeout=30.0, ca_certs=None): self.h = httplib2.Http(cache_dir, timeout=timeout, ca_certs=ca_certs) @@ -65,7 +74,7 @@ def add_credentials(self, username, password): self.h.add_credentials(username, password) def request(self, uri, method, headers=None, payload=None): - if hasattr(payload, 'read'): + if hasattr(payload, "read"): # Need to work out why a 401 challenge will stop httplib2 from sending the file... # likely need to make it re-seek to 0... # FIXME: In the meantime, read the file into memory... *sigh* @@ -73,23 +82,29 @@ def request(self, uri, method, headers=None, payload=None): resp, content = self.h.request(uri, method, headers=headers, body=payload) return (HttpLib2Response(resp), content) -################################################################################ + +################################################################################ # Guest urllib2 implementation ################################################################################ import urllib.request, urllib.error, urllib.parse, base64 + class PreemptiveBasicAuthHandler(urllib.request.HTTPBasicAuthHandler): def __init__(self, username, password): self.username = username self.password = password def http_request(self, request): - request.add_header(self.auth_header, 'Basic %s' % base64.b64encode(self.username + ':' + self.password)) + request.add_header( + self.auth_header, + "Basic %s" % base64.b64encode(self.username + ":" + self.password), + ) return request https_request = http_request + class UrlLib2Response(HttpResponse): def __init__(self, response): self.response = response @@ -116,6 +131,7 @@ def get(self, att, default=None): def keys(self): return list(self.headers.keys()) + ["status"] + # http://stackoverflow.com/questions/2502596/python-http-post-a-large-file-with-streaming """ import urllib2 @@ -136,6 +152,7 @@ def keys(self): f.close() """ + class UrlLib2Layer(HttpLayer): def __init__(self, opener=None): self.opener = opener @@ -167,14 +184,14 @@ def request(self, uri, method, headers=None, payload=None): req = urllib.request.Request(uri, payload, headers) # monkey-patch the request method (which seems to be the fastest # way to do this) - req.get_method = lambda: 'PUT' + req.get_method = lambda: "PUT" response = self.opener.open(req) return UrlLib2Response(response), response.read() elif method == "DELETE": req = urllib.request.Request(uri, None, headers) # monkey-patch the request method (which seems to be the fastest # way to do this) - req.get_method = lambda: 'DELETE' + req.get_method = lambda: "DELETE" response = self.opener.open(req) return UrlLib2Response(response), response.read() else: @@ -186,4 +203,3 @@ def request(self, uri, method, headers=None, payload=None): except Exception as e: # unable to read() return UrlLib2Response(e), None - diff --git a/sword2/server_errors.py b/sword2/server_errors.py index 476bdf2..ed2627b 100644 --- a/sword2/server_errors.py +++ b/sword2/server_errors.py @@ -5,74 +5,98 @@ """ from .sword2_logging import logging + sworderror_l = logging.getLogger(__name__) SWORD2ERRORSBYNAME = {} SWORD2ERRORSBYIRI = {} -SWORD2ERRORSBYNAME["ErrorContent"] = { "name":"ErrorContent", - "IRI":"http://purl.org/net/sword/error/ErrorContent", - "description": "The supplied format is not the same as that identified in the Packaging header and/or that supported by the server", - "codes": [406, 415] } +SWORD2ERRORSBYNAME["ErrorContent"] = { + "name": "ErrorContent", + "IRI": "http://purl.org/net/sword/error/ErrorContent", + "description": "The supplied format is not the same as that identified in the Packaging header and/or that supported by the server", + "codes": [406, 415], +} + + +SWORD2ERRORSBYNAME["ErrorChecksumMismatch"] = { + "name": "ErrorChecksumMismatch", + "IRI": "http://purl.org/net/sword/error/ErrorChecksumMismatch", + "description": "Checksum sent does not match the calculated checksum.", + "codes": [412], +} +SWORD2ERRORSBYNAME["ErrorBadRequest"] = { + "name": "ErrorBadRequest", + "IRI": "http://purl.org/net/sword/error/ErrorBadRequest", + "description": "Some parameters sent with the POST were not understood. ", + "codes": [400], +} -SWORD2ERRORSBYNAME["ErrorChecksumMismatch"] = { "name":"ErrorChecksumMismatch", - "IRI":"http://purl.org/net/sword/error/ErrorChecksumMismatch", - "description": "Checksum sent does not match the calculated checksum.", - "codes":[412] } +SWORD2ERRORSBYNAME["TargetOwnerUnknown"] = { + "name": "TargetOwnerUnknown", + "IRI": "http://purl.org/net/sword/error/TargetOwnerUnknown", + "description": "Used in mediated deposit when the server does not know the identity of the On-Behalf-Of user.", + "codes": [403], +} -SWORD2ERRORSBYNAME["ErrorBadRequest"] = { "name":"ErrorBadRequest", - "IRI":"http://purl.org/net/sword/error/ErrorBadRequest", - "description":"Some parameters sent with the POST were not understood. ", - "codes":[400] } - -SWORD2ERRORSBYNAME["TargetOwnerUnknown"] = {"name":"TargetOwnerUnknown", - "IRI":"http://purl.org/net/sword/error/TargetOwnerUnknown", - "description":"Used in mediated deposit when the server does not know the identity of the On-Behalf-Of user.", - "codes":[403] } +SWORD2ERRORSBYNAME["MediationNotAllowed"] = { + "name": "MediationNotAllowed", + "IRI": "http://purl.org/net/sword/error/MediationNotAllowed", + "description": "Used where a client has attempted a mediated deposit, but this is not supported by the server. ", + "codes": [412], +} -SWORD2ERRORSBYNAME["MediationNotAllowed"] = { "name":"MediationNotAllowed", - "IRI":"http://purl.org/net/sword/error/MediationNotAllowed", - "description":"Used where a client has attempted a mediated deposit, but this is not supported by the server. ", - "codes":[412] } +SWORD2ERRORSBYNAME["MethodNotAllowed"] = { + "name": "MethodNotAllowed", + "IRI": "http://purl.org/net/sword/error/MethodNotAllowed", + "description": "Used when the client has attempted one of the HTTP update verbs (POST, PUT, DELETE) but the server has decided not to respond to such requests on the specified resource at that time. ", + "codes": [405], +} -SWORD2ERRORSBYNAME["MethodNotAllowed"] = { "name":"MethodNotAllowed", - "IRI":"http://purl.org/net/sword/error/MethodNotAllowed", - "description":"Used when the client has attempted one of the HTTP update verbs (POST, PUT, DELETE) but the server has decided not to respond to such requests on the specified resource at that time. ", - "codes":[405] } +SWORD2ERRORSBYNAME["MaxUploadSizeExceeded"] = { + "name": "MaxUploadSizeExceeded", + "IRI": "http://purl.org/net/sword/error/MaxUploadSizeExceeded", + "description": "Used when the client has attempted to supply to the server a file which exceeds the server's maximum upload size limit.", + "codes": [413], +} -SWORD2ERRORSBYNAME["MaxUploadSizeExceeded"] = { "name":"MaxUploadSizeExceeded", - "IRI":"http://purl.org/net/sword/error/MaxUploadSizeExceeded", - "description":"Used when the client has attempted to supply to the server a file which exceeds the server's maximum upload size limit.", - "codes":[413] } +SWORD2ERRORSBYNAME["UNKNOWNERROR"] = { + "name": "UNKNOWNERROR", + "IRI": "", + "description": "Error IRI is not within the SWORD2 specification and so, is not enumerated by this constant", + "codes": [], +} -SWORD2ERRORSBYNAME["UNKNOWNERROR"] = { "name":"UNKNOWNERROR", - "IRI":"", - "description":"Error IRI is not within the SWORD2 specification and so, is not enumerated by this constant", - "codes":[] } +for k, v in SWORD2ERRORSBYNAME.items(): + SWORD2ERRORSBYIRI[v["IRI"]] = v -for k,v in SWORD2ERRORSBYNAME.items(): - SWORD2ERRORSBYIRI[v['IRI']] = v def get_error(iri, code=None): sworderror_l.debug("Attempting to match %s to a known SWORD2 error IRI" % iri) if iri in list(SWORD2ERRORSBYIRI.keys()): if code != None: - if code in SWORD2ERRORSBYIRI[iri]['codes']: - sworderror_l.info("Matched '%s' to a known SWORD2 error IRI, and HTTP response code is one of the IRI's' expected response codes." % iri) + if code in SWORD2ERRORSBYIRI[iri]["codes"]: + sworderror_l.info( + "Matched '%s' to a known SWORD2 error IRI, and HTTP response code is one of the IRI's' expected response codes." + % iri + ) return SWORD2ERRORSBYIRI[iri] else: - sworderror_l.error("Matched '%s' to a known SWORD2 error IRI, but the HTTP response code is NOT one of the IRI's' expected response codes." % iri) + sworderror_l.error( + "Matched '%s' to a known SWORD2 error IRI, but the HTTP response code is NOT one of the IRI's' expected response codes." + % iri + ) ue = SWORD2ERRORSBYNAME["UNKNOWNERROR"].copy() - ue['IRI'] = iri - ue['codes'] = [code] + ue["IRI"] = iri + ue["codes"] = [code] return ue sworderror_l.info("Matched '%s' to a known error IRI." % iri) return SWORD2ERRORSBYIRI[iri] else: sworderror_l.info("Could not match '%s' to a known SWORD2 error IRI." % iri) ue = SWORD2ERRORSBYNAME["UNKNOWNERROR"].copy() - ue['IRI'] = iri - ue['codes'] = [code] + ue["IRI"] = iri + ue["codes"] = [code] return ue diff --git a/sword2/service_document.py b/sword2/service_document.py index 69a10c9..504a314 100644 --- a/sword2/service_document.py +++ b/sword2/service_document.py @@ -41,7 +41,7 @@ [('Main Site', [])] >>> for c in s.workspaces[0][1]: print c -... +... Collection: 'Collection 43' @ 'http://swordapp.org/col-iri/43'. Accept:[] SWORD: Collection Policy - 'Collection Policy' SWORD: Treatment - 'Treatment description' @@ -51,6 +51,7 @@ """ from .sword2_logging import logging + sd_l = logging.getLogger(__name__) from .collection import SDCollection @@ -58,15 +59,16 @@ from lxml import etree from .utils import NS, get_text + class ServiceDocument(object): def __init__(self, xml_response=None, sd_uri=None): - self.sd_uri = sd_uri # Used mainly for debugging and logging + self.sd_uri = sd_uri # Used mainly for debugging and logging self.parsed = False self.valid = False - self.maxUploadSize = 0 # Zero implies no limit as default, as per spec - self.version = None # Default to an empty string before attempting to parse - self.workspaces = [] # Once enumerated, this will be a list of tuples, - # of the form: ("Workspace Title", [list of SDCollection instances]) + self.maxUploadSize = 0 # Zero implies no limit as default, as per spec + self.version = None # Default to an empty string before attempting to parse + self.workspaces = [] # Once enumerated, this will be a list of tuples, + # of the form: ("Workspace Title", [list of SDCollection instances]) if xml_response: self.load_document(xml_response) @@ -80,12 +82,17 @@ def load_document(self, xml_response): self.service_dom = etree.fromstring(xml_response) self.parsed = True self.valid = self.validate() - sd_l.info("Initial SWORD2 validation checks on service document - Valid document? %s" % self.valid) + sd_l.info( + "Initial SWORD2 validation checks on service document - Valid document? %s" + % self.valid + ) self._enumerate_workspaces() except Exception as e: # Due to variability of underlying etree implementations, catching all # exceptions... - sd_l.error("Could not parse the Service Document response from the server - %s" % e) + sd_l.error( + "Could not parse the Service Document response from the server - %s" % e + ) sd_l.debug("Received the following raw response:") sd_l.debug(self.raw_response) @@ -96,91 +103,112 @@ def validate(self): # The SWORD server MUST specify the sword:version element with a value of 2.0 # -- MUST have sword:version element # -- MUST have value of '2.0' - self.version = get_text(self.service_dom, NS['sword'] % "version") + self.version = get_text(self.service_dom, NS["sword"] % "version") if self.version: if self.version != "2.0": # Not a SWORD2 server... # Fail here? - sd_l.error("The service document states that the server's endpoint is not SWORD 2.0 - stated version:%s" % self.version) + sd_l.error( + "The service document states that the server's endpoint is not SWORD 2.0 - stated version:%s" + % self.version + ) valid = False else: sd_l.error("The service document did not have a sword:version") valid = False - + # The SWORD server MAY specify the sword:maxUploadSize (in kB) of content that can be uploaded in one request [SWORD003] as a child of the app:service element. If provided this MUST contain an integer. - maxupload = get_text(self.service_dom, NS['sword'] % "maxUploadSize") + maxupload = get_text(self.service_dom, NS["sword"] % "maxUploadSize") if maxupload: try: self.maxUploadSize = int(maxupload) except ValueError: # Unparsable as an integer. Enough to fail a validation? # Strictly... yep - sd_l.error("The service document did not have maximum upload size parseable as an integer.") + sd_l.error( + "The service document did not have maximum upload size parseable as an integer." + ) valid = False - + # Check for the first workspace for a collection element, just to make sure there is something there. - test_workspace = self.service_dom.find(NS['app'] % "workspace") + test_workspace = self.service_dom.find(NS["app"] % "workspace") if test_workspace != None: - sd_l.debug("At least one app:workspace found, with at least one app:collection within it.") + sd_l.debug( + "At least one app:workspace found, with at least one app:collection within it." + ) else: valid = False - sd_l.error("Could not find a app:workspace element in the service document.") - - # The SWORD server MUST specify the app:accept element for the app:collection element. - # If the Collection can take any format content type, it should specify */* as its - # value [AtomPub]. It MUST also specify an app:accept element with an alternate attribute - # set to multipart-related as required by [AtomMultipart]. The formats specified by + sd_l.error( + "Could not find a app:workspace element in the service document." + ) + + # The SWORD server MUST specify the app:accept element for the app:collection element. + # If the Collection can take any format content type, it should specify */* as its + # value [AtomPub]. It MUST also specify an app:accept element with an alternate attribute + # set to multipart-related as required by [AtomMultipart]. The formats specified by # app:accept and app:accept@alternate="multipart-related" are RECOMMENDED to be the same. - workspaces = self.service_dom.findall(NS['app'] % "workspace") + workspaces = self.service_dom.findall(NS["app"] % "workspace") if workspaces is not None: for workspace in workspaces: - cols = workspace.findall(NS['app'] % "collection") + cols = workspace.findall(NS["app"] % "collection") for col in cols: # the collection may contain a sub-service document, which means it is not # beholden to the rules above - service = col.find(NS['sword'] % "service") + service = col.find(NS["sword"] % "service") if service is not None: continue - + # since we have no sub-service document, we must validate accept_valid = True multipart_accept_valid = True - accepts = col.findall(NS['app'] % "accept") + accepts = col.findall(NS["app"] % "accept") for accept in accepts: multipart = accept.get("alternate") if multipart is not None: - if multipart != "multipart-related" and multipart != "multipart/related": + if ( + multipart != "multipart-related" + and multipart != "multipart/related" + ): multipart_accept_valid = False - sd_l.debug("Multipart accept alternate is incorrect: " + str(multipart)) + sd_l.debug( + "Multipart accept alternate is incorrect: " + + str(multipart) + ) else: # FIXME: we could test to see if the content is viable, but probably that's pointless pass - + if not multipart_accept_valid or not accept_valid: - sd_l.debug("Either the multipart accept or the accept fields were invalid (see above debug)") + sd_l.debug( + "Either the multipart accept or the accept fields were invalid (see above debug)" + ) valid = False - + return valid def _enumerate_workspaces(self): if not self.valid: - sd_l.error("The service document didn't pass the SWORD2 validation steps ('MUST' statements in spec). The workspaces and collections will not be enumerated.") + sd_l.error( + "The service document didn't pass the SWORD2 validation steps ('MUST' statements in spec). The workspaces and collections will not be enumerated." + ) return - + if self.sd_uri: - sd_l.info("Enumerating workspaces and collections from the service document for %s" % self.sd_uri) - + sd_l.info( + "Enumerating workspaces and collections from the service document for %s" + % self.sd_uri + ) + # Reset the internally cached set self.workspaces = [] - for workspace in self.service_dom.findall(NS['app'] % "workspace"): - workspace_title = get_text(workspace, NS['atom'] % 'title') + for workspace in self.service_dom.findall(NS["app"] % "workspace"): + workspace_title = get_text(workspace, NS["atom"] % "title") sd_l.debug("Found workspace '%s'" % workspace_title) collections = [] - for collection_element in workspace.findall(NS['app'] % 'collection'): + for collection_element in workspace.findall(NS["app"] % "collection"): # app:collection + sword extensions c = SDCollection() c.load_from_etree(collection_element) - - collections.append(c) - self.workspaces.append( (workspace_title, collections) ) # Add tuple + collections.append(c) + self.workspaces.append((workspace_title, collections)) # Add tuple diff --git a/sword2/statement.py b/sword2/statement.py index d54ac89..568da1b 100644 --- a/sword2/statement.py +++ b/sword2/statement.py @@ -7,6 +7,7 @@ s_l = logging.getLogger(__name__) + class Sword_Statement(object): def __init__(self, xml_document=None): self.xml_document = xml_document @@ -16,10 +17,10 @@ def __init__(self, xml_document=None): self.original_deposits = [] self.states = [] self.resources = [] - + self._parse_xml_document() self._validate() - + def _parse_xml_document(self): if self.xml_document is not None: try: @@ -29,68 +30,82 @@ def _parse_xml_document(self): except Exception as e: s_l.error("Failed to parse document - %s" % e) s_l.error("XML document begins:\n %s" % self.xml_document[:300]) - - def _validate(self): pass + + def _validate(self): + pass + class Statement_Resource(object): - def __init__(self, uri=None, is_original_deposit=False, deposited_on=None, - deposited_by=None, deposited_on_behalf_of=None): + def __init__( + self, + uri=None, + is_original_deposit=False, + deposited_on=None, + deposited_by=None, + deposited_on_behalf_of=None, + ): self.uri = uri self.is_original_deposit = is_original_deposit self.deposited_on = deposited_on self.deposited_by = deposited_by self.deposited_on_behalf_of = deposited_on_behalf_of - + + class Atom_Statement_Entry(Deposit_Receipt, Statement_Resource): def __init__(self, dom): Deposit_Receipt.__init__(self, dom=dom) Statement_Resource.__init__(self) - + self.is_original_deposit = self._is_original_deposit() self._parse_depositors() - + # to provide a stable interface, use the content iri as the uri self.uri = self.cont_iri - + def _is_original_deposit(self): # is this an original deposit? is_original_deposit = False - for cat in self.dom.findall(NS['atom'] % 'category'): + for cat in self.dom.findall(NS["atom"] % "category"): if cat.get("term") == "http://purl.org/net/sword/terms/originalDeposit": is_original_deposit = True break return is_original_deposit - + def _parse_depositors(self): - do = self.dom.find(NS['sword'] % "depositedOn") + do = self.dom.find(NS["sword"] % "depositedOn") if do is not None and do.text is not None and do.text.strip() != "": try: - self.deposited_on = datetime.strptime(do.text.strip(), "%Y-%m-%dT%H:%M:%SZ") # e.g. 2011-03-02T20:50:06Z + self.deposited_on = datetime.strptime( + do.text.strip(), "%Y-%m-%dT%H:%M:%SZ" + ) # e.g. 2011-03-02T20:50:06Z except Exception as e: s_l.error("Failed to parse date - %s" % e) s_l.error("Supplied date as string was: %s" % do.text.strip()) - db = self.dom.find(NS['sword'] % "depositedBy") + db = self.dom.find(NS["sword"] % "depositedBy") if db is not None and db.text is not None and db.text.strip() != "": self.deposited_by = db.text.strip() - - dobo = self.dom.find(NS['sword'] % "depositedOnBehalfOf") + + dobo = self.dom.find(NS["sword"] % "depositedOnBehalfOf") if dobo is not None and dobo.text is not None and db.text.strip() != "": self.deposited_on_behalf_of = dobo.text.strip() - + def validate(self): # don't validate statement entries return True + class Atom_Sword_Statement(Sword_Statement): def __init__(self, xml_document=None): Sword_Statement.__init__(self, xml_document) if self.valid: self._enumerate_feed() else: - s_l.warn("Statement did not parse as valid, so the content will" + - " not be examined further; see the 'dom' attribute for the xml") - + s_l.warning( + "Statement did not parse as valid, so the content will" + + " not be examined further; see the 'dom' attribute for the xml" + ) + """ FIXME: this implementation assumes that the atom document is a single page, but Ben's original implementation at least started to make some @@ -111,39 +126,39 @@ def __init__(self, xml_document=None): coll_l.error("XML document begins:\n %s" % xml_document[:300]) self.enumerate_feed() """ - + def _enumerate_feed(self): if self.dom is None: return - + # Handle Categories - for cat in self.dom.findall(NS['atom'] % 'category'): + for cat in self.dom.findall(NS["atom"] % "category"): if cat.get("scheme") == "http://purl.org/net/sword/terms/state": self.states.append((cat.get("term"), cat.text.strip())) - + # Handle Entries - for entry in self.dom.findall(NS['atom'] % 'entry'): + for entry in self.dom.findall(NS["atom"] % "entry"): ase = Atom_Statement_Entry(entry) if ase.is_original_deposit: self.original_deposits.append(ase) self.resources.append(ase) - + def _validate(self): valid = True - + if self.dom is None: return - + # MUST be an ATOM Feed document - if self.dom.tag != NS['atom'] % "feed" and self.dom.tag != "feed": + if self.dom.tag != NS["atom"] % "feed" and self.dom.tag != "feed": valid = False - + self.valid = valid - - # The Feed MUST represent files contained in the item as an atom:entry element (this does not + + # The Feed MUST represent files contained in the item as an atom:entry element (this does not # mandate that all files in the item are listed, though) - # Each atom:entry which is an original deposit file MUST have an atom:category element with + # Each atom:entry which is an original deposit file MUST have an atom:category element with # the term sword:originalDeposit (this does not mandate that all original deposits are listed as entries) # NOTE: neither of these requirements can easily be used to validate, since @@ -152,19 +167,33 @@ def _validate(self): # that this is a feed, and be done with it. - - class Ore_Statement_Resource(Statement_Resource): - def __init__(self, uri, is_original_deposit=False, packaging_uris=[], - deposited_on=None, deposited_by=None, deposited_on_behalf_of=None): - Statement_Resource.__init__(self, uri, is_original_deposit, deposited_on, - deposited_by, deposited_on_behalf_of) + def __init__( + self, + uri, + is_original_deposit=False, + packaging_uris=[], + deposited_on=None, + deposited_by=None, + deposited_on_behalf_of=None, + ): + Statement_Resource.__init__( + self, + uri, + is_original_deposit, + deposited_on, + deposited_by, + deposited_on_behalf_of, + ) self.uri = uri self.packaging = packaging_uris - + def __str__(self): # FIXME: unfinished ... - return "URI: %s ; is_original_deposit: %s ; packaging_uris: %s ; deposited_on: %s" + return ( + "URI: %s ; is_original_deposit: %s ; packaging_uris: %s ; deposited_on: %s" + ) + class Ore_Sword_Statement(Sword_Statement): def __init__(self, xml_document=None): @@ -172,48 +201,63 @@ def __init__(self, xml_document=None): if self.valid: self._enumerate_descriptions() else: - s_l.warn("Statement did not parse as valid, so the content will" + - " not be examined further; see the 'dom' attribute for the xml") - + s_l.warning( + "Statement did not parse as valid, so the content will" + + " not be examined further; see the 'dom' attribute for the xml" + ) + def _enumerate_descriptions(self): if self.dom is None: return - + aggregated_resource_uris = [] original_deposit_uris = [] state_uris = [] - + # first pass gets me the uris of all the things I care about - for desc in self.dom.findall(NS['rdf'] % "Description"): + for desc in self.dom.findall(NS["rdf"] % "Description"): # look for the aggregation - ore_idb = desc.findall(NS['ore'] % "isDescribedBy") + ore_idb = desc.findall(NS["ore"] % "isDescribedBy") if ore_idb is None: continue - + # we are looking at the aggregation Describes itself - for agg_uri in desc.findall(NS['ore'] % "aggregates"): - aggregated_resource_uris.append(agg_uri.get(NS['rdf'] % "resource")) - - for od_uri in desc.findall(NS['sword'] % "originalDeposit"): - original_deposit_uris.append(od_uri.get(NS['rdf'] % "resource")) - - for state_uri in desc.findall(NS['sword'] % "state"): - state_uris.append(state_uri.get(NS['rdf'] % "resource")) - - s_l.debug("First pass on ORE statement yielded the following Aggregated Resources: " + str(aggregated_resource_uris)) - s_l.debug("First pass on ORE statement yielded the following Original Deposits: " + str(original_deposit_uris)) - s_l.debug("First pass on ORE statement yielded the following States: " + str(state_uris)) - + for agg_uri in desc.findall(NS["ore"] % "aggregates"): + aggregated_resource_uris.append(agg_uri.get(NS["rdf"] % "resource")) + + for od_uri in desc.findall(NS["sword"] % "originalDeposit"): + original_deposit_uris.append(od_uri.get(NS["rdf"] % "resource")) + + for state_uri in desc.findall(NS["sword"] % "state"): + state_uris.append(state_uri.get(NS["rdf"] % "resource")) + + s_l.debug( + "First pass on ORE statement yielded the following Aggregated Resources: " + + str(aggregated_resource_uris) + ) + s_l.debug( + "First pass on ORE statement yielded the following Original Deposits: " + + str(original_deposit_uris) + ) + s_l.debug( + "First pass on ORE statement yielded the following States: " + + str(state_uris) + ) + # second pass, sort out the different descriptions - for desc in self.dom.findall(NS['rdf'] % "Description"): - about = desc.get(NS['rdf'] % "about") + for desc in self.dom.findall(NS["rdf"] % "Description"): + about = desc.get(NS["rdf"] % "about") s_l.debug("Examining Described Resource: " + str(about)) if about in state_uris: s_l.debug(str(about) + " is a State URI") # read and store the state information description_text = None - sdesc = desc.find(NS['sword'] % "stateDescription") - if sdesc is not None and sdesc.text is not None and sdesc.text.strip() != "": + sdesc = desc.find(NS["sword"] % "stateDescription") + if ( + sdesc is not None + and sdesc.text is not None + and sdesc.text.strip() != "" + ): description_text = sdesc.text.strip() self.states.append((about, description_text)) # remove this uri from the list of state_uris, so that we can @@ -221,138 +265,128 @@ def _enumerate_descriptions(self): state_uris.remove(about) elif about in aggregated_resource_uris: s_l.debug(str(about) + " is an Aggregated Resource") - + is_original_deposit = about in original_deposit_uris - s_l.debug("Is Aggregated Resource an original deposit? " + str(is_original_deposit)) - + s_l.debug( + "Is Aggregated Resource an original deposit? " + + str(is_original_deposit) + ) + packaging_uris = [] - for pack in desc.findall(NS['sword'] % "packaging"): - pack_uri = pack.get(NS['rdf'] % "resource") + for pack in desc.findall(NS["sword"] % "packaging"): + pack_uri = pack.get(NS["rdf"] % "resource") packaging_uris.append(pack_uri) s_l.debug("Registering Packaging URI: " + pack_uri) - + deposited_on = None - do = desc.find(NS['sword'] % "depositedOn") + do = desc.find(NS["sword"] % "depositedOn") if do is not None and do.text is not None and do.text.strip() != "": try: - deposited_on = datetime.strptime(do.text.strip(), "%Y-%m-%dT%H:%M:%SZ") # e.g. 2011-03-02T20:50:06Z + deposited_on = datetime.strptime( + do.text.strip(), "%Y-%m-%dT%H:%M:%SZ" + ) # e.g. 2011-03-02T20:50:06Z s_l.debug("Registering Deposited On: " + do.text.strip()) except Exception as e: s_l.error("Failed to parse date - %s" % e) s_l.error("Supplied date as string was: %s" % do.text.strip()) deposited_by = None - db = desc.find(NS['sword'] % "depositedBy") + db = desc.find(NS["sword"] % "depositedBy") if db is not None and db.text is not None and db.text.strip() != "": deposited_by = db.text.strip() s_l.debug("Registering Deposited By: " + deposited_by) - + deposited_on_behalf_of = None - dobo = desc.find(NS['sword'] % "depositedOnBehalfOf") + dobo = desc.find(NS["sword"] % "depositedOnBehalfOf") if dobo is not None and dobo.text is not None and db.text.strip() != "": deposited_on_behalf_of = dobo.text.strip() - s_l.debug("Registering Deposited On Behalf Of: " + deposited_on_behalf_of) - - ose = Ore_Statement_Resource(about, is_original_deposit, packaging_uris, - deposited_on, deposited_by, deposited_on_behalf_of) + s_l.debug( + "Registering Deposited On Behalf Of: " + deposited_on_behalf_of + ) + + ose = Ore_Statement_Resource( + about, + is_original_deposit, + packaging_uris, + deposited_on, + deposited_by, + deposited_on_behalf_of, + ) if is_original_deposit: s_l.debug("Registering Aggregated Resource as an Original Deposit") self.original_deposits.append(ose) self.resources.append(ose) - + # remove this uri from the list of resource_uris, so that we can # deal with any left over later aggregated_resource_uris.remove(about) - + # finally, we may have aggregated resources and states which did not # have rdf:Description elements associated with them. We do the minimum # possible here to accommodate them s_l.debug("Undescribed State URIs: " + str(state_uris)) for state in state_uris: self.states.append((state, None)) - - s_l.debug("Undescribed Aggregated Resource URIs: " + str(aggregated_resource_uris)) + + s_l.debug( + "Undescribed Aggregated Resource URIs: " + str(aggregated_resource_uris) + ) for ar in aggregated_resource_uris: ose = Ore_Statement_Resource(ar) self.resources.append(ose) - + def _validate(self): valid = True - + if self.dom is None: return - + # MUST be an RDF/XML resource map - + # is this rdf xml: - if self.dom.tag.lower() != NS['rdf'] % "rdf" and self.dom.tag.lower() != "rdf": - s_l.info("Validation of Ore Statement failed, as root tag is not RDF: " + self.dom.tag) + if self.dom.tag.lower() != NS["rdf"] % "rdf" and self.dom.tag.lower() != "rdf": + s_l.info( + "Validation of Ore Statement failed, as root tag is not RDF: " + + self.dom.tag + ) valid = False - - # does it meet the basic requirements of being a resource map, which + + # does it meet the basic requirements of being a resource map, which # is to have an ore:describes and and ore:isDescribedBy describes_uri = None rem_uri = None aggregation_uri = None is_described_by_uris = [] - for desc in self.dom.findall(NS['rdf'] % "Description"): + for desc in self.dom.findall(NS["rdf"] % "Description"): # look for the describes tag - ore_desc = desc.find(NS['ore'] % "describes") + ore_desc = desc.find(NS["ore"] % "describes") if ore_desc is not None: - describes_uri = ore_desc.get(NS['rdf'] % "resource") - rem_uri = desc.get(NS['rdf'] % "about") + describes_uri = ore_desc.get(NS["rdf"] % "resource") + rem_uri = desc.get(NS["rdf"] % "about") # look for the isDescribedBy tag - ore_idb = desc.findall(NS['ore'] % "isDescribedBy") + ore_idb = desc.findall(NS["ore"] % "isDescribedBy") if len(ore_idb) > 0: - aggregation_uri = desc.get(NS['rdf'] % "about") + aggregation_uri = desc.get(NS["rdf"] % "about") for idb in ore_idb: - is_described_by_uris.append(idb.get(NS['rdf'] % "resource")) - + is_described_by_uris.append(idb.get(NS["rdf"] % "resource")) + # now check that all those uris tie up: if describes_uri != aggregation_uri: - s_l.info("Validation of Ore Statement failed; ore:describes URI does not match Aggregation URI: " + - describes_uri + " != " + aggregation_uri) + s_l.info( + "Validation of Ore Statement failed; ore:describes URI does not match Aggregation URI: " + + describes_uri + + " != " + + aggregation_uri + ) valid = False if rem_uri not in is_described_by_uris: - s_l.info("Validation of Ore Statement failed; Resource Map URI does not match one of ore:isDescribedBy URIs: " + - rem_uri + " not in " + str(is_described_by_uris)) + s_l.info( + "Validation of Ore Statement failed; Resource Map URI does not match one of ore:isDescribedBy URIs: " + + rem_uri + + " not in " + + str(is_described_by_uris) + ) valid = False - + s_l.info("Statement validation; was it a success? " + str(valid)) self.valid = valid - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/sword2/sword2_logging.py b/sword2/sword2_logging.py index 3a26965..19e82a6 100644 --- a/sword2/sword2_logging.py +++ b/sword2/sword2_logging.py @@ -5,16 +5,19 @@ `sword2` logging """ -import imp +import importlib.util import os import logging import logging.config try: - _, sword2_path, _ = imp.find_module('sword2') -except ImportError: + spec = importlib.util.find_spec("sword2") + sword2_path = os.path.dirname(spec.origin) if spec and spec.origin else "" +except (ImportError, AttributeError): sword2_path = "" -SWORD2_LOGGING_CONFIG = os.path.join(sword2_path, 'data', 'sword2_logging.conf') # default +SWORD2_LOGGING_CONFIG = os.path.join( + sword2_path, "data", "sword2_logging.conf" +) # default BASIC_CONFIG = """[loggers] keys=root @@ -39,6 +42,7 @@ format=%(asctime)s - %(name)s - %(levelname)s - %(message)s """ + def create_logging_config(pathtologgingconf=None): """ If you want to use the sword logging configuration, you should call this to create the @@ -49,22 +53,21 @@ def create_logging_config(pathtologgingconf=None): # set the path to default if none is provided if pathtologgingconf is None: pathtologgingconf = SWORD2_LOGGING_CONFIG - + # ensure that the path exists d = os.path.dirname(pathtologgingconf) os.makedirs(d) - + # write the basic config to the file - fn = open(pathtologgingconf, "wb") - fn.write(BASIC_CONFIG) - fn.close() + with open(pathtologgingconf, "w") as fn: + fn.write(BASIC_CONFIG) -#if not os.path.isfile(SWORD2_LOGGING_CONFIG): + +# if not os.path.isfile(SWORD2_LOGGING_CONFIG): # create_logging_config(SWORD2_LOGGING_CONFIG) # -#logging.config.fileConfig(SWORD2_LOGGING_CONFIG) +# logging.config.fileConfig(SWORD2_LOGGING_CONFIG) # when we call this module, load the logging configuration if it exists if os.path.isfile(SWORD2_LOGGING_CONFIG): - logging.config.fileConfig(SWORD2_LOGGING_CONFIG) - + logging.config.fileConfig(SWORD2_LOGGING_CONFIG) diff --git a/sword2/transaction_history.py b/sword2/transaction_history.py index fcebfd9..e3f75fc 100644 --- a/sword2/transaction_history.py +++ b/sword2/transaction_history.py @@ -15,18 +15,18 @@ class Transaction_History(list): def log(self, event_type, **kw): - self.append({'type':event_type, - 'timestamp':datetime.now().isoformat(), - 'payload':kw}) + self.append( + {"type": event_type, "timestamp": datetime.now().isoformat(), "payload": kw} + ) def __str__(self): _s = [] for item in self: - _s.append("-"*20) - _s.append("Type: '%s' [%s]\nData:" % (item['type'], item['timestamp'])) - for key, value in item['payload'].items(): + _s.append("-" * 20) + _s.append("Type: '%s' [%s]\nData:" % (item["type"], item["timestamp"])) + for key, value in item["payload"].items(): _s.append("%s: %s" % (key, value)) - + return "\n".join(_s) def to_json(self): @@ -34,6 +34,7 @@ def to_json(self): return json.dumps(self) def to_pretty_json(self): - th_l.debug("Attempting to dump %s history items to indented, readable JSON" % len(self)) + th_l.debug( + "Attempting to dump %s history items to indented, readable JSON" % len(self) + ) return json.dumps(self, indent=True) - diff --git a/sword2/utils.py b/sword2/utils.py index 46b52ec..33dd3f4 100644 --- a/sword2/utils.py +++ b/sword2/utils.py @@ -6,6 +6,7 @@ """ from .sword2_logging import logging + utils_l = logging.getLogger(__name__) from time import time @@ -21,17 +22,18 @@ import mimetypes NS = {} -NS['dcterms'] = "{http://purl.org/dc/terms/}%s" -NS['sword'] ="{http://purl.org/net/sword/terms/}%s" -NS['atom'] = "{http://www.w3.org/2005/Atom}%s" -NS['app'] = "{http://www.w3.org/2007/app}%s" -NS['rdf'] = "{http://www.w3.org/1999/02/22-rdf-syntax-ns#}%s" -NS['ore'] = "{http://www.openarchives.org/ore/terms/}%s" - -def get_text(parent, tag, plural = False): +NS["dcterms"] = "{http://purl.org/dc/terms/}%s" +NS["sword"] = "{http://purl.org/net/sword/terms/}%s" +NS["atom"] = "{http://www.w3.org/2005/Atom}%s" +NS["app"] = "{http://www.w3.org/2007/app}%s" +NS["rdf"] = "{http://www.w3.org/1999/02/22-rdf-syntax-ns#}%s" +NS["ore"] = "{http://www.openarchives.org/ore/terms/}%s" + + +def get_text(parent, tag, plural=False): """Takes an `etree.Element` and a tag name to search for and retrieves the text attribute from any of the parent element's direct children. - + Returns a simple `str` if only a single element is found, or a list if multiple elements with the same tag. Ignores element attributes, returning only the text.""" text = None @@ -48,33 +50,34 @@ def get_text(parent, tag, plural = False): text = [text, t] return text + def get_md5(data): """Takes either a `str` or a file-like object and passes back a tuple containing (md5sum, filesize) - + The file is streamed as 1Mb chunks so should work for large files. File-like object must support `seek()` """ - if hasattr(data, "read") and hasattr(data, 'seek'): + if hasattr(data, "read") and hasattr(data, "seek"): m = md5() - chunk = data.read(1024*1024) # 1Mb + chunk = data.read(1024 * 1024) # 1Mb f_size = 0 - while(chunk): + while chunk: f_size += len(chunk) m.update(chunk) - chunk = data.read(1024*1024) + chunk = data.read(1024 * 1024) data.seek(0) return m.hexdigest(), f_size - else: # normal str + else: # normal str m = md5() f_size = len(data) m.update(data) return m.hexdigest(), f_size - + class Timer(object): """Simple timer, providing a 'stopwatch' mechanism. - + Usage example: - + >>> from sword2.utils import Timer >>> from time import sleep >>> t = Timer() @@ -90,7 +93,7 @@ class Timer(object): (0, 3.0048139095306396) # tuple -> (index of the logged .duration, time since the .start method was called) - # eg 't.duration['kaylee'][0]' would equal 3.00481.... + # eg 't.duration['kaylee'][0]' would equal 3.00481.... >>> sleep(2) >>> t.time_since_start("kaylee", "inara") @@ -101,9 +104,9 @@ class Timer(object): >>> sleep(4) >>> t.time_since_start("kaylee", "inara", "river") [(3, 14.021538972854614), (1, 14.021538972854614), (1, 14.021538972854614)] - + # The order of the response is the same as the order of the names in the method call. - + >>> # report back ... t.duration['kaylee'] [3.0048139095306396, 5.00858998298645, 10.015379905700684, 14.021538972854614] @@ -111,23 +114,24 @@ class Timer(object): [5.00858998298645, 14.021538972854614] >>> t.duration['river'] [10.015379905700684, 14.021538972854614] - >>> + >>> """ + def __init__(self): self.reset_all() - + def reset_all(self): - self.counts = {} + self.counts = {} self.duration = {} self.stop = {} def reset(self, name): if name in self.counts: self.counts[name] = 0 - + def read_raw(self, name): return self.counts.get(name, None) - + def read(self, name): if name in self.counts: return datetime.fromtimestamp(self.counts[name]) @@ -143,15 +147,15 @@ def stop(self, *args): st_time = time() for arg in args: self.stop[arg] = st_time - + def get_timestamp(self): # Convenience function return datetime.now() - + def get_loggable_timestamp(self): """Human-readable by intent""" return datetime.now().isoformat() - + def time_since_start(self, *args): r = [] st_time = time() @@ -168,62 +172,68 @@ def time_since_start(self, *args): return r.pop() else: return r - + def get_content_type(filename): # Does a simple .ext -> mimetype mapping. # Generally better to specify the mimetype upfront. - return mimetypes.guess_type(filename)[0] or 'application/octet-stream' + return mimetypes.guess_type(filename)[0] or "application/octet-stream" + def create_multipart_related(payloads): - """ Expected: list of dicts with keys 'key', 'type'='content type','filename'=optional,'data'=payload, 'headers'={} - + """Expected: list of dicts with keys 'key', 'type'='content type','filename'=optional,'data'=payload, 'headers'={} + TODO: More mem-efficient to spool this to disc rather than hold in RAM, but until Httplib2 bug gets fixed (issue 151) this might be in vain. - - Can handle more than just two files. - + + Can handle more than just two files. + SWORD2 multipart POST/PUT expects two attachments - key = 'atom' w/ Atom Entry (metadata) key = 'payload' (file) """ # Generate random boundary code # TODO check that it does not occur in the payload data - bhash = md5(datetime.now().isoformat()).hexdigest() # eg 'd8bb3ea6f4e0a4b4682be0cfb4e0a24e' - BOUNDARY = '===========%s_$' % bhash - CRLF = '\r\n' # As some servers might barf without this. + bhash = md5( + datetime.now().isoformat() + ).hexdigest() # eg 'd8bb3ea6f4e0a4b4682be0cfb4e0a24e' + BOUNDARY = "===========%s_$" % bhash + CRLF = "\r\n" # As some servers might barf without this. body = [] - for payload in payloads: # predicatable ordering... - body.append('--' + BOUNDARY) - if payload.get('type', None): - body.append('Content-Type: %(type)s' % payload) + for payload in payloads: # predicatable ordering... + body.append("--" + BOUNDARY) + if payload.get("type", None): + body.append("Content-Type: %(type)s" % payload) else: - body.append('Content-Type: %s' % get_content_type(payload.get("filename"))) - - if payload.get('filename', None): - body.append('Content-Disposition: attachment; name="%(key)s"; filename="%(filename)s"' % (payload)) + body.append("Content-Type: %s" % get_content_type(payload.get("filename"))) + + if payload.get("filename", None): + body.append( + 'Content-Disposition: attachment; name="%(key)s"; filename="%(filename)s"' + % (payload) + ) else: body.append('Content-Disposition: attachment; name="%(key)s"' % (payload)) - + if "headers" in payload: - for f,v in payload['headers'].items(): - body.append("%s: %s" % (f, v)) # TODO force ASCII? - - body.append('MIME-Version: 1.0') - if payload['key'] == 'payload': - body.append('Content-Transfer-Encoding: base64') - body.append('') - if hasattr(payload['data'], 'read'): - body.append(b64encode(payload['data'].read())) + for f, v in payload["headers"].items(): + body.append("%s: %s" % (f, v)) # TODO force ASCII? + + body.append("MIME-Version: 1.0") + if payload["key"] == "payload": + body.append("Content-Transfer-Encoding: base64") + body.append("") + if hasattr(payload["data"], "read"): + body.append(b64encode(payload["data"].read())) else: - body.append(b64encode(payload['data'])) + body.append(b64encode(payload["data"])) else: - body.append('') - if hasattr(payload['data'], 'read'): - body.append(b64encode(payload['data'].read())) + body.append("") + if hasattr(payload["data"], "read"): + body.append(b64encode(payload["data"].read())) else: - body.append(b64encode(payload['data'])) - body.append('--' + BOUNDARY + '--') - body.append('') + body.append(b64encode(payload["data"])) + body.append("--" + BOUNDARY + "--") + body.append("") body_bytes = CRLF.join(body) content_type = 'multipart/related; boundary="%s"' % BOUNDARY return content_type, body_bytes diff --git a/tests/http/__init__.py b/tests/http_tests/__init__.py similarity index 100% rename from tests/http/__init__.py rename to tests/http_tests/__init__.py diff --git a/tests/http/test_sss.py b/tests/http_tests/test_sss.py similarity index 100% rename from tests/http/test_sss.py rename to tests/http_tests/test_sss.py diff --git a/tox.ini b/tox.ini index 01201b6..b96f4d6 100644 --- a/tox.ini +++ b/tox.ini @@ -1,9 +1,7 @@ [tox] -envlist = py{36,37,38,39} +envlist = py{39,310,311,312,313,314} [testenv] deps=httplib2 lxml - nose - web.py -# Only run functional tests, until sss.py drops the lxml dep -commands=nosetests tests/functional --with-xunit + pytest +commands=pytest tests/functional