Add Event class (#139)

Added an `Event` class, edited `Events.get_event()` to return a list of them.

This creates a new branch in the object class hierarchy, with a distinction between REST objects (instances of `BaseObject` and its subclasses) and non-REST (objects that are not addressable / queryable in the API) objects (instances of `APIJSONObject` and its subclasses). `BaseObject` and `APIJSONObject` inherit from a common baseclass, `BaseAPIJSONObject`, which is now the base for translation.

To maintain backwards-compatibility with methods that used to return `dict`, `APIJSONObject` implements the `Mapping` interface.

Fixes #15.

Author: kelseymorris95

boxsdk/object/__init__.py

@@ -5,4 +5,4 @@
 from six.moves import map   # pylint:disable=redefined-builtin
 
 
-__all__ = list(map(str, ['collaboration', 'events', 'file', 'folder', 'group', 'group_membership', 'search', 'user']))
+__all__ = list(map(str, ['collaboration', 'events', 'event', 'file', 'folder', 'group', 'group_membership', 'search', 'user']))

boxsdk/object/api_json_object.py

@@ -0,0 +1,26 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+from collections import Mapping
+from abc import ABCMeta
+import six
+
+from .base_api_json_object import BaseAPIJSONObject, BaseAPIJSONObjectMeta
+
+
+class APIJSONObjectMeta(BaseAPIJSONObjectMeta, ABCMeta):
+    """
+    Avoid conflicting metaclass definitions for APIJSONObject.
+    http://code.activestate.com/recipes/204197-solving-the-metaclass-conflict/
+    """
+    pass
+
+
+class APIJSONObject(six.with_metaclass(APIJSONObjectMeta, BaseAPIJSONObject, Mapping)):
+    """Class representing objects that are not part of the REST API."""
+
+    def __len__(self):
+        return len(self._response_object)
+
+    def __iter__(self):
+        return iter(self._response_object)

boxsdk/object/base_api_json_object.py

@@ -0,0 +1,63 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+import six
+
+from ..util.translator import Translator
+
+
+class BaseAPIJSONObjectMeta(type):
+    """
+    Metaclass for Box API objects. Registers classes so that API responses can be translated to the correct type.
+    Relies on the _item_type field defined on the classes to match the type property of the response json.
+    But the type-class mapping will only be registered if the module of the class is imported.
+    So it's also important to add the module name to __all__ in object/__init__.py.
+    """
+    def __init__(cls, name, bases, attrs):
+        super(BaseAPIJSONObjectMeta, cls).__init__(name, bases, attrs)
+        item_type = attrs.get('_item_type', None)
+        if item_type is not None:
+            Translator().register(item_type, cls)
+
+
+@six.add_metaclass(BaseAPIJSONObjectMeta)
+class BaseAPIJSONObject(object):
+    """Base class containing basic logic shared between true REST objects and other objects (such as an Event)"""
+
+    _item_type = None
+
+    def __init__(self, response_object=None, **kwargs):
+        """
+        :param response_object:
+            A JSON object representing the object returned from a Box API request.
+        :type response_object:
+            `dict`
+        """
+        super(BaseAPIJSONObject, self).__init__(**kwargs)
+        self._response_object = response_object or {}
+        self.__dict__.update(self._response_object)
+
+    def __getitem__(self, item):
+        """
+        Try to get the attribute from the API response object.
+
+        :param item:
+            The attribute to retrieve from the API response object.
+        :type item:
+            `unicode`
+        """
+        return self._response_object[item]
+
+    def __repr__(self):
+        """Base class override. Return a human-readable representation using the Box ID or name of the object."""
+        extra_description = ' - {0}'.format(self._description) if self._description else ''
+        description = '<Box {0}{1}>'.format(self.__class__.__name__, extra_description)
+        if six.PY2:
+            return description.encode('utf-8')
+        else:
+            return description
+
+    @property
+    def _description(self):
+        """Return a description of the object if one exists."""
+        return ""

boxsdk/object/base_endpoint.py

@@ -1,19 +1,23 @@
 # coding: utf-8
 
-from __future__ import unicode_literals
+from __future__ import unicode_literals, absolute_import
 
 
 class BaseEndpoint(object):
     """A Box API endpoint."""
 
-    def __init__(self, session):
+    def __init__(self, session, **kwargs):
         """
-
         :param session:
             The Box session used to make requests.
         :type session:
             :class:`BoxSession`
+        :param kwargs:
+            Keyword arguments for base class constructors.
+        :type kwargs:
+            `dict`
         """
+        super(BaseEndpoint, self).__init__(**kwargs)
         self._session = session
 
     def get_url(self, endpoint, *args):

boxsdk/object/base_object.py

@@ -1,35 +1,15 @@
 # coding: utf-8
 
-from __future__ import unicode_literals
-from abc import ABCMeta
+from __future__ import unicode_literals, absolute_import
 import json
 
-import six
+from .base_endpoint import BaseEndpoint
+from .base_api_json_object import BaseAPIJSONObject
+from ..util.translator import Translator
 
-from boxsdk.object.base_endpoint import BaseEndpoint
-from boxsdk.util.translator import Translator
 
-
-class ObjectMeta(ABCMeta):
-    """
-    Metaclass for Box API objects. Registers classes so that API responses can be translated to the correct type.
-    Relies on the _item_type field defined on the classes to match the type property of the response json.
-    But the type-class mapping will only be registered if the module of the class is imported.
-    So it's also important to add the module name to __all__ in object/__init__.py.
-    """
-    def __init__(cls, name, bases, attrs):
-        super(ObjectMeta, cls).__init__(name, bases, attrs)
-        item_type = attrs.get('_item_type', None)
-        if item_type is not None:
-            Translator().register(item_type, cls)
-
-
-@six.add_metaclass(ObjectMeta)
-class BaseObject(BaseEndpoint):
-    """
-    A Box API endpoint for interacting with a Box object.
-    """
-    _item_type = None
+class BaseObject(BaseEndpoint, BaseAPIJSONObject):
+    """A Box API endpoint for interacting with a Box object."""
 
     def __init__(self, session, object_id, response_object=None):
         """
@@ -42,29 +22,16 @@ def __init__(self, session, object_id, response_object=None):
         :type object_id:
             `unicode`
         :param response_object:
-            The Box API response representing the object.
+            A JSON object representing the object returned from a Box API request.
         :type response_object:
-            :class:`BoxResponse`
+            `dict`
         """
-        super(BaseObject, self).__init__(session)
+        super(BaseObject, self).__init__(session=session, response_object=response_object)
         self._object_id = object_id
-        self._response_object = response_object or {}
-        self.__dict__.update(self._response_object)
-
-    def __getitem__(self, item):
-        """Base class override. Try to get the attribute from the API response object."""
-        return self._response_object[item]
-
-    def __repr__(self):
-        """Base class override. Return a human-readable representation using the Box ID or name of the object."""
-        description = '<Box {0} - {1}>'.format(self.__class__.__name__, self._description)
-        if six.PY2:
-            return description.encode('utf-8')
-        else:
-            return description
 
     @property
     def _description(self):
+        """Base class override.  Return a description for the object."""
         if 'name' in self._response_object:
             return '{0} ({1})'.format(self._object_id, self.name)  # pylint:disable=no-member
         else:
@@ -185,7 +152,7 @@ def delete(self, params=None, headers=None):
         return box_response.ok
 
     def __eq__(self, other):
-        """Base class override. Equality is determined by object id."""
+        """Equality as determined by object id"""
         return self._object_id == other.object_id
 
     def _paging_wrapper(self, url, starting_index, limit, factory=None):

boxsdk/object/event.py

@@ -0,0 +1,11 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+
+from .api_json_object import APIJSONObject
+
+
+class Event(APIJSONObject):
+    """Represents a single Box event."""
+
+    _item_type = 'event'

boxsdk/object/events.py

@@ -1,14 +1,14 @@
 # coding: utf-8
 
-from __future__ import unicode_literals
-
+from __future__ import unicode_literals, absolute_import
 from requests.exceptions import Timeout
 from six import with_metaclass
 
-from boxsdk.object.base_endpoint import BaseEndpoint
-from boxsdk.util.enum import ExtendableEnumMeta
-from boxsdk.util.lru_cache import LRUCache
-from boxsdk.util.text_enum import TextEnum
+from .base_endpoint import BaseEndpoint
+from ..util.enum import ExtendableEnumMeta
+from ..util.lru_cache import LRUCache
+from ..util.text_enum import TextEnum
+from ..util.translator import Translator
 
 
 # pylint:disable=too-many-ancestors
@@ -79,8 +79,7 @@ def get_events(self, limit=100, stream_position=0, stream_type=UserEventsStreamT
         :type stream_type:
             :enum:`EventsStreamType`
         :returns:
-            JSON response from the Box /events endpoint. Contains the next stream position to use for the next call,
-            along with some number of events.
+            Dictionary containing the next stream position along with a list of some number of events.
         :rtype:
             `dict`
         """
@@ -91,7 +90,10 @@ def get_events(self, limit=100, stream_position=0, stream_type=UserEventsStreamT
             'stream_type': stream_type,
         }
         box_response = self._session.get(url, params=params)
-        return box_response.json()
+        response = box_response.json().copy()
+        if 'entries' in response:
+            response['entries'] = [Translator().translate(item['type'])(item) for item in response['entries']]
+        return response
 
     def get_latest_stream_position(self, stream_type=UserEventsStreamType.ALL):
         """

boxsdk/object/folder.py

@@ -4,6 +4,7 @@
 import json
 import os
 from six import text_type
+
 from boxsdk.config import API
 from boxsdk.object.collaboration import Collaboration
 from boxsdk.object.file import File

boxsdk/object/item.py

@@ -1,7 +1,6 @@
 # coding: utf-8
 
-from __future__ import unicode_literals
-
+from __future__ import unicode_literals, absolute_import
 import json
 
 from .base_object import BaseObject
@@ -111,6 +110,10 @@ def rename(self, name):
     def get(self, fields=None, etag=None):
         """Base class override.
 
+        :param fields:
+            List of fields to request.
+        :type fields:
+            `Iterable` of `unicode`
         :param etag:
             If specified, instruct the Box API to get the info only if the current version's etag doesn't match.
         :type etag:

boxsdk/object/metadata.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 
-from __future__ import unicode_literals
+from __future__ import unicode_literals, absolute_import
 import json
 from boxsdk.object.base_endpoint import BaseEndpoint