prepare for PyPi publication

Author: kshepherd

LICENSE LICENSE.txtLICENSE renamed to LICENSE.txt

@@ -1,6 +1,6 @@
 # This software is licenced under the BSD 3-Clause licence
 # available at https://opensource.org/licenses/BSD-3-Clause
-# and described in the LICENSE file in the root of this project
+# and described in the LICENSE.txt file in the root of this project
 
 """
 DSpace REST API client library. Intended to make interacting with DSpace in Python 3 easier, particularly
@@ -14,8 +14,10 @@
 
 @author Kim Shepherd <kim@shepherd.nz>
 """
-
+import code
 import json
+import logging
+
 import requests
 from requests import Request
 import os
@@ -329,11 +331,88 @@ def parse_json(response):
     return response_json
 
 
+class Group(DSpaceObject):
+    """
+    Extends DSpaceObject to implement specific attributes and methods for groups (aka. EPersonGroups)
+    """
+    type = 'group'
+    name = None
+    permanent = False
+
+    def __init__(self, api_resource=None):
+        """
+        Default constructor. Call DSpaceObject init then set group-specific attributes
+        @param api_resource: API result object to use as initial data
+        """
+        super(Group, self).__init__(api_resource)
+        self.type = 'group'
+        if 'name' in api_resource:
+            self.name = api_resource['name']
+        if 'permanent' in api_resource:
+            self.permanent = api_resource['permanent']
+
+    def as_dict(self):
+        """
+        Return a dict representation of this Group, based on super with group-specific attributes added
+        @return: dict of Group for API use
+        """
+        dso_dict = super(Group, self).as_dict()
+        group_dict = {'name': self.name, 'permanent': self.permanent}
+        return {**dso_dict, **group_dict}
+
+
+class User(SimpleDSpaceObject):
+    """
+    Extends DSpaceObject to implement specific attributes and methods for users (aka. EPersons)
+    """
+    type = 'user'
+    name = None,
+    netid = None,
+    lastActive = None,
+    canLogIn = False,
+    email = None,
+    requireCertificate = False,
+    selfRegistered = False
+
+    def __init__(self, api_resource=None):
+        """
+        Default constructor. Call DSpaceObject init then set user-specific attributes
+        @param api_resource: API result object to use as initial data
+        """
+        super(User, self).__init__(api_resource)
+        self.type = 'user'
+        if 'name' in api_resource:
+            self.name = api_resource['name']
+        if 'netid' in api_resource:
+            self.netid = api_resource['netid']
+        if 'lastActive' in api_resource:
+            self.lastActive = api_resource['lastActive']
+        if 'canLogIn' in api_resource:
+            self.canLogIn = api_resource['canLogIn']
+        if 'email' in api_resource:
+            self.email = api_resource['email']
+        if 'requireCertificate' in api_resource:
+            self.requireCertificate = api_resource['requireCertificate']
+        if 'selfRegistered' in api_resource:
+            self.selfRegistered = api_resource['selfRegistered']
+
+    def as_dict(self):
+        """
+        Return a dict representation of this User, based on super with user-specific attributes added
+        @return: dict of User for API use
+        """
+        dso_dict = super(User, self).as_dict()
+        user_dict = {'name': self.name, 'netid': self.netid, 'lastActive': self.lastActive, 'canLogIn': self.canLogIn,
+                     'email': self.email, 'requireCertificate': self.requireCertificate,
+                     'selfRegistered': self.selfRegistered}
+        return {**dso_dict, **user_dict}
+
+
 class DSpaceClient:
     """
     Main class of the API client itself. This client uses request sessions to connect and authenticate to
     the REST API, maintain XSRF tokens, and all GET, POST, PUT, PATCH operations.
-    Low-level api_get, api_post, api_put, api_patch functions are defined to handle the requests and do
+    Low-level api_get, api_post, api_put, api_delete, api_patch functions are defined to handle the requests and do
     retries / XSRF refreshes where necessary.
     Higher level get, create, update, partial_update (patch) functions are implemented for each DSO type
     """
@@ -468,7 +547,7 @@ def api_post(self, url, params, json, retry=False):
     def api_put(self, url, params, json, retry=False):
         """
         Perform a PUT request. Refresh XSRF token if necessary.
-        PUTs are tupically used to update objects.
+        PUTs are typically used to update objects.
         @param url:     DSpace REST API URL
         @param params:  Any parameters to include (eg ?parent=abbc-....)
         @param json:    Data in json-ready form (dict) to send as PUT body (eg. item.as_dict())
@@ -499,6 +578,39 @@ def api_put(self, url, params, json, retry=False):
 
         return r
 
+    def api_delete(self, url, params, retry=False):
+        """
+        Perform a DELETE request. Refresh XSRF token if necessary.
+        DELETES are typically used to update objects.
+        @param url:     DSpace REST API URL
+        @param params:  Any parameters to include (eg ?parent=abbc-....)
+        @param retry:   Has this method already been retried? Used if we need to refresh XSRF.
+        @return:        Response from API
+        """
+        h = {'Content-type': 'application/json'}
+        r = self.session.delete(url, params=params, headers=h)
+        if 'DSPACE-XSRF-TOKEN' in r.headers:
+            t = r.headers['DSPACE-XSRF-TOKEN']
+            print('Updating token to ' + t)
+            self.session.headers.update({'X-XSRF-Token': t})
+            self.session.cookies.update({'X-XSRF-Token': t})
+
+        if r.status_code == 403:
+            # 403 Forbidden
+            # If we had a CSRF failure, retry the request with the updated token
+            # After speaking in #dev it seems that these do need occasional refreshes but I suspect
+            # it's happening too often for me, so check for accidentally triggering it
+            print(r.text)
+            r_json = r.json()
+            if 'message' in r_json and 'CSRF token' in r_json['message']:
+                if retry:
+                    print('Already retried... something must be wrong')
+                else:
+                    print("Retrying request with updated CSRF token")
+                    return self.api_delete(url, params=params, retry=True)
+
+        return r
+
     def api_patch(self, url, operation, path, value, retry=False):
         """
         @param url: DSpace REST API URL
@@ -693,6 +805,42 @@ def update_dso(self, dso, params=None):
             print(f'{e}')
             return None
 
+    def delete_dso(self, dso=None, url=None, params=None):
+        """
+        Delete DSpaceObject. Takes a DSpaceObject and any optional parameters. Will send a PUT update to the remote
+        object and return the updated object, typed correctly.
+        :param dso:     DSpaceObject from which to parse self link
+        :param params:  Optional parameters
+        :param url:     URI if not deleting from DSO
+        :return:
+
+        """
+        if dso is None:
+            if url is None:
+                print(f'Need a DSO or a URL to delete')
+                return None
+        else:
+            if not isinstance(dso, SimpleDSpaceObject):
+                print(f'Only SimpleDSpaceObject types (eg Item, Collection, Community, EPerson) '
+                      f'are supported by generic update_dso PUT.')
+                return dso
+            # Get self URI from HAL links
+            url = dso.links['self']['href']
+
+        try:
+            r = self.api_delete(url, params=params)
+            if r.status_code == 204:
+                # 204 No Content - success!
+                print(f'{url} was deleted sucessfully!')
+                return r
+            else:
+                print(f'update operation failed: {r.status_code}: {r.text} ({url})')
+                return None
+
+        except ValueError as e:
+            print(f'{e}')
+            return None
+
     def get_bundles(self, parent=None, uuid=None):
         """
         Get bundles for an item
@@ -950,7 +1098,7 @@ def create_item(self, parent, item):
         Create an item beneath the given parent collection
         @param parent:  UUID of parent collection to pass as a parameter to create_dso
         @param item:    python Item object containing all the data and links expected by the REST API
-        @return:        Item object construcuted from the API response
+        @return:        Item object constructed from the API response
         """
         url = f'{self.API_ENDPOINT}/core/items'
         if parent is None:
@@ -1008,3 +1156,52 @@ def add_metadata(self, dso, field, value, language=None, authority=None, confide
             url=url, operation=self.PatchOperation.ADD, path=path, value=patch_value)
 
         return dso_type(api_resource=parse_json(r))
+
+    def create_user(self, user, token=None):
+        """
+        Create a user
+        @param user:    python User object or Python dict containing all the data and links expected by the REST API
+        :param token:   Token if creating new user (optional) from the link in a registration email
+        @return:        User object constructed from the API response
+        """
+        url = f'{self.API_ENDPOINT}/eperson/epersons'
+        data = user
+        if isinstance(user, User):
+            data = user.as_dict()
+            # TODO: Validation. Note, at least here I will just allow a dict instead of the pointless cast<->cast
+            # that you see for other DSO types - still figuring out the best way
+        params = None
+        if token is not None:
+            params = {'token': token}
+        return User(api_resource=parse_json(self.create_dso(url, params=params, data=data)))
+
+    def delete_user(self, user):
+        if not isinstance(user, User):
+            print(f'Must be a valid user')
+            return None
+        return self.delete_dso(user)
+
+    def get_users(self):
+        url = f'{self.API_ENDPOINT}/eperson/epersons'
+        users = list()
+        r = self.api_get(url)
+        r_json = parse_json(response=r)
+        if '_embedded' in r_json:
+            if 'epersons' in r_json['_embedded']:
+                for user_resource in r_json['_embedded']['epersons']:
+                    users.append(User(user_resource))
+        return users
+
+    def create_group(self, group):
+        """
+        Create a group
+        @param group:    python Group object or Python dict containing all the data and links expected by the REST API
+        @return:         User object constructed from the API response
+        """
+        url = f'{self.API_ENDPOINT}/eperson/groups'
+        data = group
+        if isinstance(group, Group):
+            data = group.as_dict()
+            # TODO: Validation. Note, at least here I will just allow a dict instead of the pointless cast<->cast
+            # that you see for other DSO types - still figuring out the best way
+        return Group(api_resource=parse_json(self.create_dso(url, params=None, data=data)))