valuesresourceset object

Author: maxtepkeev

CHANGELOG.rst

@@ -21,6 +21,9 @@ Changelog
   * Tracker - issues relation
   * IssueStatus - issues relation
 
+- Added: Introduced a ``values()`` method in a ResourceSet which returns ValuesResourceSet — a
+  ResourceSet subclass that returns dictionaries when used as an iterable, rather than resource-instance
+  objects (see `docs <http://python-redmine.readthedocs.org/operations.html#filter>`__ for details)
 - Added: Introduced ``update()`` and ``delete()`` methods in a ResourceSet object which allow to
   bulk update or bulk delete all resources in a ResourceSet object (see `docs <http://python-redmine.
   readthedocs.org/operations.html#filter>`__ for details)

docs/operations.rst

@@ -139,8 +139,8 @@ Returns a ResourceSet object that contains Resource objects filtered by some con
 
 .. hint::
 
-    ResourceSet object provides 4 helper methods ``get()``, ``filter()``, ``update()`` and
-    ``delete()``:
+    ResourceSet object provides 5 helper methods ``get()``, ``filter()``, ``update()``, ``delete()``
+    and ``values()``:
 
     * **get**. Returns a single resource from the ResourceSet by resource id:
 
@@ -177,6 +177,34 @@ Returns a ResourceSet object that contains Resource objects filtered by some con
 
             redmine.project.get('vacation').issues.delete()
 
+    * **values**. Returns a ValuesResourceSet — a ResourceSet subclass that returns dictionaries when
+      used as an iterable, rather than resource-instance objects. Each of those dictionaries represents
+      a resource, with the keys corresponding to the attribute names of resource objects. This example
+      compares the dictionaries of values() with the normal resource objects:
+
+      .. versionadded:: 1.0.0
+
+      |
+
+      .. code-block:: python
+
+         >>> list(redmine.issue_status.all(limit=1))
+         [<redmine.resources.IssueStatus #1 "New">]
+         >>> list(redmine.issue_status.all(limit=1).values())
+         [{'id': 1, 'is_default': True, 'name': 'New'}]
+
+      The values() method takes optional positional arguments, \*fields, which specify field names to
+      which resource fields should be limited. If you specify the fields, each dictionary will contain
+      only the field keys/values for the fields you specify. If you don’t specify the fields, each
+      dictionary will contain a key and value for every field in the resource:
+
+      .. code-block:: python
+
+         >>> list(redmine.issue_status.all(limit=1).values())
+         [{'id': 1, 'is_default': True, 'name': 'New'}]
+         >>> list(redmine.issue_status.all(limit=1).values('id', 'name'))
+         [{'id': 1, 'name': 'New'}]
+
     ResourceSet object also provides some attributes:
 
     * **limit**. What limit value was used to retrieve this ResourceSet:

redmine/resultsets.py

@@ -58,6 +58,10 @@ def delete(self):
 
         return True
 
+    def values(self, *fields):
+        """Returns ValuesResourceSet object which represents Resource as a dictionary"""
+        return ValuesResourceSet(self.manager, resources=self.resources, fields=fields)
+
     @property
     def total_count(self):
         """Returns total count of available resources, this is known only after ResourceSet evaluation"""
@@ -109,3 +113,70 @@ def __repr__(self):
             self.__class__.__name__,
             self.manager.resource_class.__name__
         )
+
+
+class ValuesResourceSet(ResourceSet):
+    """Represents a set of Redmine resources as dictionaries"""
+    def __init__(self, manager, resources=None, fields=()):
+        """Accepts optional fields iterable which sets field names each resource will contain"""
+        super(ValuesResourceSet, self).__init__(manager, resources)
+        self.fields = fields
+        self.resource_internal_id = 'title' if self.manager.resource_class.__name__ == 'WikiPage' else 'id'
+
+    def get(self, resource_id, default=None):
+        """Returns a single item from a ValuesResourceSet by resource id"""
+        for resource in self:
+            if int(resource_id) == resource[self.resource_internal_id]:
+                return resource
+
+        return default
+
+    def filter(self, resource_ids):
+        """Returns a ValuesResourceSet with requested resource ids"""
+        if not isinstance(resource_ids, (tuple, list)):
+            raise ResourceSetFilterParamError
+
+        resources = []
+
+        for resource in self:
+            if resource[self.resource_internal_id] in resource_ids:
+                resources.append(resource)
+
+        return ValuesResourceSet(self.manager, resources=resources, fields=self.fields)
+
+    def update(self, **fields):
+        """Updates fields of all resources in a ValuesResourceSet with the given values"""
+        resources = []
+
+        for resource in self:
+            for field in fields:
+                resource[field] = fields[field]
+
+            self.manager.update(resource[self.resource_internal_id], **fields)
+            resources.append(resource)
+
+        return ValuesResourceSet(self.manager, resources=resources, fields=self.fields)
+
+    def delete(self):
+        """Deletes all resources in a ValuesResourceSet"""
+        for resource in self:
+            self.manager.delete(resource[self.resource_internal_id])
+
+        return True
+
+    def __iter__(self):
+        """Returns requested resources in a lazy fashion"""
+        if self.resources is None:
+            self._evaluate()
+
+        for resource in self.resources:
+            if not self.fields:
+                yield resource
+            else:
+                fields = {}
+
+                for field in resource:
+                    if field in self.fields:
+                        fields.update({field: resource[field]})
+
+                yield fields

tests/test_resultsets.py

@@ -117,6 +117,52 @@ def test_update_method(self):
     def test_delete_method(self):
         self.assertEqual(self.redmine.project.all().delete(), True)
 
+    def test_values_method(self):
+        from redmine.resultsets import ValuesResourceSet
+        self.assertIsInstance(self.redmine.project.all().values(), ValuesResourceSet)
+
+    def test_values_resourceset_supports_iteration(self):
+        projects = list(self.redmine.project.all().values())
+        self.assertEqual(projects[0]['name'], 'Foo')
+        self.assertEqual(projects[0]['identifier'], 'foo')
+        self.assertEqual(projects[0]['id'], 1)
+        self.assertEqual(projects[1]['name'], 'Bar')
+        self.assertEqual(projects[1]['identifier'], 'bar')
+        self.assertEqual(projects[1]['id'], 2)
+
+    def test_values_resourceset_supports_field_limits(self):
+        projects = list(self.redmine.project.all().values('id'))
+        self.assertEqual(projects[0]['id'], 1)
+        self.assertRaises(KeyError, lambda: projects[0]['name'])
+        self.assertEqual(projects[1]['id'], 2)
+        self.assertRaises(KeyError, lambda: projects[1]['name'])
+
+    def test_values_resourceset_get_method_resource_found(self):
+        projects = self.redmine.project.all().values().get(2)
+        self.assertEqual(projects['id'], 2)
+
+    def test_values_resourceset_get_method_resource_not_found(self):
+        projects = self.redmine.project.all().values().get(6)
+        self.assertEqual(projects, None)
+
+    def test_values_resourceset_filter_method(self):
+        projects = self.redmine.project.all().values().filter((1, 3))
+        self.assertEqual(projects[0]['id'], 1)
+        self.assertEqual(projects[1]['id'], 3)
+
+    def test_values_resourceset_update_method(self):
+        projects = self.redmine.project.all().values().update(name='FooBar')
+        self.assertEqual(projects[0]['name'], 'FooBar')
+        self.assertEqual(projects[1]['name'], 'FooBar')
+        self.assertEqual(projects[2]['name'], 'FooBar')
+
+    def test_values_resourceset_delete_method(self):
+        self.assertEqual(self.redmine.project.all().values().delete(), True)
+
+    def test_values_resourceset_filter_param_exception(self):
+        from redmine.exceptions import ResourceSetFilterParamError
+        self.assertRaises(ResourceSetFilterParamError, lambda: self.redmine.project.all().values().filter(1))
+
     def test_filter_param_exception(self):
         from redmine.exceptions import ResourceSetFilterParamError
         self.assertRaises(ResourceSetFilterParamError, lambda: self.redmine.project.all().filter(1))