openstack/shade
Code Issues Proposed changes

Update coding document to mention direct REST calls

Browse Source 
Now that we've got glance and swift done and have started on neutron,
let's update the doc to tell people that it's the way forward.

Change-Id: I16f7ae58f5ae280bc4b1533f62bf3e3a09dbaeb0
This commit is contained in:
Monty Taylor 2017-01-21 16:35:21 +01:00
parent efe7b8d469
commit e71e79c397
No known key found for this signature in database
GPG Key ID: 7BAE94BC7141A594
1 changed files with 23 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
doc/source/coding.rst
View File

@ -56,22 +56,32 @@ Exceptions
All underlying client exceptions must be captured and converted to an All underlying client exceptions must be captured and converted to an
`OpenStackCloudException` or one of its derivatives. `OpenStackCloudException` or one of its derivatives.
Client Calls REST Calls
============ ============
All underlying client calls (novaclient, swiftclient, etc.) must be All interactions with the cloud should be done with direct REST using
wrapped by a Task object. the appropriate `keystoneauth1.adapter.Adapter`. See Glance and Swift
calls for examples.
Returned Resources Returned Resources
================== ==================
Complex objects returned to the caller must be a dict type. The Complex objects returned to the caller must be a `munch.Munch` type. The
methods `obj_to_dict()` or `obj_list_to_dict()` should be used for this. `shade._adapter.Adapter` class makes resources into `munch.Munch`.
As of this writing, those two methods are returning Munch objects, which help All objects should be normalized. It is shade's purpose in life to make
to maintain backward compatibility with a time when shade returned raw OpenStack consistent for end users, and this means not trusting the clouds
objects. Munch allows the returned resource to act as *both* an object to return consistent objects. There should be a normalize function in
and a dict. `shade/_normalize.py` that is applied to objects before returning them to
the user. See :doc:`model` for further details on object model requirements.
Fields should not be in the normalization contract if we cannot commit to
providing them to all users.
Fields should be renamed in normalization to be consistent with
the rest of shade. For instance, nothing in shade exposes the legacy OpenStack
concept of "tenant" to a user, but instead uses "project" even if the
cloud uses tenant.
Nova vs. Neutron Nova vs. Neutron
================ ================
@ -90,6 +100,10 @@ Tests
- New API methods *must* have unit tests! - New API methods *must* have unit tests!
- New unit tests should only mock at the REST layer using `requests_mock`.
Any mocking of shade itself or of legacy client libraries should be
considered legacy and to be avoided.
- Functional tests should be added, when possible. - Functional tests should be added, when possible.
- In functional tests, always use unique names (for resources that have this - In functional tests, always use unique names (for resources that have this