AlterAmendDelete

Amending or updating resources

The Connection methods all share the same type of parameters but need to be given different URIs to work on. You can either do this explicitly or you can pass in a deposit receipt object (returned by a previous transaction such as a create_resource one) and the correct URI will be found and used automatically.

General hint

Keeping track of which URI ("IRI" as the SWORD2 profile uses) to use for which type of request can be confusing at times. The deposit receipt is a great shortcut as this can be passed as a parameter to the update and append methods and the method will try to find the correct URI to use for what you are trying to accomplish automatically.

(in the following examples, the variable 'c' is a reference to a sword2.Connection instance.)

Replacing the content of a resource

'Connection.update' - uses the Edit-Media-IRI, (EM-IRI)

Like the Connection.create, this method alters the type of SWORD request it makes depending on what parameters you send it - in this case, passing just the file information parameters (payload, etc) will cause it to do a simple request on the Edit-Media-IRI, which must be supplied either as the 'edit_media_iri' parameter, or by passing the previous receipt as the 'dr' parameter.

• "replace the existing content of a resource by performing an HTTP PUT of some new binary content to the EM-IRI"
• Target IRI parameters:
  ** either set 'edit_media_iri' to the desired IRI or ** or set 'dr' to be the sword2.Deposit_Receipt instance returned from a previous transaction.
• File parameters: payload = data to upload, mimetype = data mimetype, filename = data filename, packaging = SWORD2 packaging type
• other parameters: in_progress =True/False, on_behalf_of="....", metadata_relevant=True/False

Example:

update_receipt = c.update(payload=data_bytestring, 
                          mimetype="application/zip", 
                          filename="foo.zip", 
                          packaging = "http://purl.org/net/sword/package/Binary", 
                          dr = receipt)
assert update_receipt.code == 200

Replacing the metadata record of a resource

Connection.update - uses the Edit-IRI

As above, but set the metadata_entry parameter, not the file-specific ones. Note that this requires the Edit-IRI, which can be set either by the 'edit_iri' parameter or as above, by passing the previous receipt as the 'dr' parameter.

• "replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI."
• Target IRI parameters: ** either set 'edit_iri' to the desired IRI or ** or set 'dr' to be the sword2.Deposit_Receipt instance returned from a previous transaction.
• parameters: metadata_entry = sword2.Entry instance with metadata

Example:

from sword2 import Entry
e = Entry(id = "atomid",
          title = ".....",
          updated = ".....",
          dcterms_identifier = "doi://.....")

updated_metadata_receipt = c.update(metadata_entry = e,
                                    dr = receipt)
assert added_file_receipt.code == 200

Replacing both the content and the metadata for a given resource

Connection.update - uses Edit-IRI (edit_iri)

Set both the metadata and the file-specific parameters as above and the method will automatically switch to a multipart-related request, as required by the SWORD2 profile.

Adding files, metadata or both to a resource

Connection.append -- uses the Sword-Edit-IRI or SE-IRI

• "add more content or metadata or both to the Resource itself"
• Like the 'create' method, this method can take either file parameters (payload, mimetype, etc) or a metadata_entry or both, and acts accordingly.

Example:

added_file_receipt = c.append(payload=data_bytestring, 
                              mimetype="application/zip", 
                              filename="foo.zip", 
                              packaging = "http://purl.org/net/sword/package/Binary", 
                              dr = receipt)
assert added_file_receipt.code == 201

Connection.add_file_to_resource

[uses the Edit-Media-IRI]

• "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."
• Uses the same parameters as 'update' above

Example:

added_file_receipt = c.add_file_to_resource(payload=data_bytestring, 
                                            mimetype="application/zip", 
                                            filename="foo.zip", 
                                            packaging = "http://purl.org/net/sword/package/Binary", 
                                            edit_media_iri = receipt.edit_media)
assert added_file_receipt.code == 201