Add support for Role resource in Identity v3

This change adds the Role resource to Identity v3 and exposes the CRUD
methods in the proxy. It also adds a small example to the documentation.

Change-Id: I064c27fcd1d15bfd064c63b8c50bc2461b8c1156

examples/identity/list.py

@@ -71,3 +71,10 @@ def list_regions(conn):
 
     for region in conn.identity.regions():
         print(region)
+
+
+def list_roles(conn):
+    print("List Roles:")
+
+    for role in conn.identity.roles():
+        print(role)

openstack/identity/v3/_proxy.py

@@ -17,6 +17,7 @@ from openstack.identity.v3 import group as _group
 from openstack.identity.v3 import policy as _policy
 from openstack.identity.v3 import project as _project
 from openstack.identity.v3 import region as _region
+from openstack.identity.v3 import role as _role
 from openstack.identity.v3 import service as _service
 from openstack.identity.v3 import trust as _trust
 from openstack.identity.v3 import user as _user
@@ -797,3 +798,80 @@ class Proxy(proxy.BaseProxy):
         :rtype: :class:`~openstack.identity.v3.region.Region`
         """
         return self._update(_region.Region, region, **attrs)
+
+    def create_role(self, **attrs):
+        """Create a new role from attributes
+
+        :param dict attrs: Keyword arguments which will be used to create
+                           a :class:`~openstack.identity.v3.role.Role`,
+                           comprised of the properties on the Role class.
+
+        :returns: The results of role creation.
+        :rtype: :class:`~openstack.identity.v3.role.Role`
+        """
+        return self._create(_role.Role, **attrs)
+
+    def delete_role(self, role, ignore_missing=True):
+        """Delete a role
+
+        :param role: The value can be either the ID of a role or a
+               :class:`~openstack.identity.v3.role.Role` instance.
+        :param bool ignore_missing: When set to ``False``
+                    :class:`~openstack.exceptions.ResourceNotFound` will be
+                    raised when the role does not exist.
+                    When set to ``True``, no exception will be thrown when
+                    attempting to delete a nonexistent role.
+
+        :returns: ``None``
+        """
+        self._delete(_role.Role, role, ignore_missing=ignore_missing)
+
+    def find_role(self, name_or_id, ignore_missing=True):
+        """Find a single role
+
+        :param name_or_id: The name or ID of a role.
+        :param bool ignore_missing: When set to ``False``
+                    :class:`~openstack.exceptions.ResourceNotFound` will be
+                    raised when the role does not exist.
+                    When set to ``True``, None will be returned when
+                    attempting to find a nonexistent role.
+        :returns: One :class:`~openstack.identity.v3.role.Role` or None
+        """
+        return self._find(_role.Role, name_or_id,
+                          ignore_missing=ignore_missing)
+
+    def get_role(self, role):
+        """Get a single role
+
+        :param role: The value can be the ID of a role or a
+                       :class:`~openstack.identity.v3.role.Role` instance.
+
+        :returns: One :class:`~openstack.identity.v3.role.Role`
+        :raises: :class:`~openstack.exceptions.ResourceNotFound`
+                 when no matching role can be found.
+        """
+        return self._get(_role.Role, role)
+
+    def roles(self, **query):
+        """Retrieve a generator of roles
+
+        :param kwargs \*\*query: Optional query parameters to be sent to limit
+                                 the resources being returned. The options
+                                 are: domain_id, name.
+        :return: A generator of role instances.
+        :rtype: :class:`~openstack.identity.v3.role.Role`
+        """
+        return self._list(_role.Role, paginated=False, **query)
+
+    def update_role(self, role, **attrs):
+        """Update a role
+
+        :param role: Either the ID of a role or a
+                      :class:`~openstack.identity.v3.role.Role` instance.
+        :param dict kwargs: The attributes to update on the role represented
+                       by ``value``. Only name can be updated
+
+        :returns: The updated role.
+        :rtype: :class:`~openstack.identity.v3.role.Role`
+        """
+        return self._update(_role.Role, role, **attrs)

openstack/identity/v3/role.py

@@ -0,0 +1,43 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from openstack.identity import identity_service
+from openstack import resource2 as resource
+
+
+class Role(resource.Resource):
+    resource_key = 'role'
+    resources_key = 'roles'
+    base_path = '/roles'
+    service = identity_service.IdentityService()
+
+    # capabilities
+    allow_create = True
+    allow_get = True
+    allow_update = True
+    allow_delete = True
+    allow_list = True
+    put_create = True
+
+    _query_mapping = resource.QueryParameters(
+        'name', 'domain_id')
+
+    # Properties
+    #: References the domain ID which owns the role; if a domain ID is not
+    #: specified by the client, the Identity service implementation will
+    #: default it to the domain ID to which the client's token is scoped.
+    #: *Type: string*
+    domain_id = resource.Body('domain_id')
+    #: Unique role name, within the owning domain. *Type: string*
+    name = resource.Body('name')
+    #: The links for the service resource.
+    links = resource.Body('links')

openstack/tests/unit/identity/v3/test_proxy.py

@@ -18,6 +18,7 @@ from openstack.identity.v3 import group
 from openstack.identity.v3 import policy
 from openstack.identity.v3 import project
 from openstack.identity.v3 import region
+from openstack.identity.v3 import role
 from openstack.identity.v3 import service
 from openstack.identity.v3 import trust
 from openstack.identity.v3 import user
@@ -242,3 +243,24 @@ class TestIdentityProxy(test_proxy_base2.TestProxyBase):
 
     def test_region_update(self):
         self.verify_update(self.proxy.update_region, region.Region)
+
+    def test_role_create_attrs(self):
+        self.verify_create(self.proxy.create_role, role.Role)
+
+    def test_role_delete(self):
+        self.verify_delete(self.proxy.delete_role, role.Role, False)
+
+    def test_role_delete_ignore(self):
+        self.verify_delete(self.proxy.delete_role, role.Role, True)
+
+    def test_role_find(self):
+        self.verify_find(self.proxy.find_role, role.Role)
+
+    def test_role_get(self):
+        self.verify_get(self.proxy.get_role, role.Role)
+
+    def test_roles(self):
+        self.verify_list(self.proxy.roles, role.Role, paginated=False)
+
+    def test_role_update(self):
+        self.verify_update(self.proxy.update_role, role.Role)

openstack/tests/unit/identity/v3/test_role.py

@@ -0,0 +1,46 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+import testtools
+
+from openstack.identity.v3 import role
+
+IDENTIFIER = 'IDENTIFIER'
+EXAMPLE = {
+    'domain_id': '1',
+    'id': IDENTIFIER,
+    'links': {'self': 'http://example.com/user1'},
+    'name': '2',
+}
+
+
+class TestRole(testtools.TestCase):
+
+    def test_basic(self):
+        sot = role.Role()
+        self.assertEqual('role', sot.resource_key)
+        self.assertEqual('roles', sot.resources_key)
+        self.assertEqual('/roles', sot.base_path)
+        self.assertEqual('identity', sot.service.service_type)
+        self.assertTrue(sot.allow_create)
+        self.assertTrue(sot.allow_get)
+        self.assertTrue(sot.allow_update)
+        self.assertTrue(sot.allow_delete)
+        self.assertTrue(sot.allow_list)
+        self.assertTrue(sot.put_create)
+
+    def test_make_it(self):
+        sot = role.Role(**EXAMPLE)
+        self.assertEqual(EXAMPLE['domain_id'], sot.domain_id)
+        self.assertEqual(EXAMPLE['id'], sot.id)
+        self.assertEqual(EXAMPLE['links'], sot.links)
+        self.assertEqual(EXAMPLE['name'], sot.name)