90 lines
3.2 KiB
ReStructuredText
90 lines
3.2 KiB
ReStructuredText
********************************
|
|
Shade Developer Coding Standards
|
|
********************************
|
|
|
|
In the beginning, there were no guidelines. And it was good. But that
|
|
didn't last long. As more and more people added more and more code,
|
|
we realized that we needed a set of coding standards to make sure that
|
|
the shade API at least *attempted* to display some form of consistency.
|
|
|
|
Thus, these coding standards/guidelines were developed. Note that not
|
|
all of shade adheres to these standards just yet. Some older code has
|
|
not been updated because we need to maintain backward compatibility.
|
|
Some of it just hasn't been changed yet. But be clear, all new code
|
|
*must* adhere to these guidelines.
|
|
|
|
Below are the patterns that we expect Shade developers to follow.
|
|
|
|
API Methods
|
|
===========
|
|
|
|
- When an API call acts on a resource that has both a unique ID and a
|
|
name, that API call should accept either identifier with a name_or_id
|
|
parameter.
|
|
|
|
- All resources should adhere to the get/list/search interface that
|
|
control retrieval of those resources. E.g., `get_image()`, `list_images()`,
|
|
`search_images()`.
|
|
|
|
- Resources should have `create_RESOURCE()`, `delete_RESOURCE()`,
|
|
`update_RESOURCE()` API methods (as it makes sense).
|
|
|
|
- For those methods that should behave differently for omitted or None-valued
|
|
parameters, use the `_utils.valid_kwargs` decorator. Notably: all Neutron
|
|
`update_*` functions.
|
|
|
|
- Deleting a resource should return True if the delete succeeded, or False
|
|
if the resource was not found.
|
|
|
|
Exceptions
|
|
==========
|
|
|
|
All underlying client exceptions must be captured and converted to an
|
|
`OpenStackCloudException` or one of its derivatives.
|
|
|
|
Client Calls
|
|
============
|
|
|
|
All underlying client calls (novaclient, swiftclient, etc.) must be
|
|
wrapped by a Task object.
|
|
|
|
Returned Resources
|
|
==================
|
|
|
|
Complex objects returned to the caller must be a dict type. The
|
|
methods `obj_to_dict()` or `obj_list_to_dict()` should be used for this.
|
|
|
|
As of this writing, those two methods are returning Bunch objects, which help
|
|
to maintain backward compatibility with a time when shade returned raw
|
|
objects. Bunch allows the returned resource to act as *both* an object
|
|
and a dict. Use of Bunch objects will eventually be deprecated in favor
|
|
of just pure dicts, so do not depend on the Bunch object functionality.
|
|
Expect a pure dict type.
|
|
|
|
Nova vs. Neutron
|
|
================
|
|
|
|
- Recognize that not all cloud providers support Neutron, so never
|
|
assume it will be present. If a task can be handled by either
|
|
Neutron or Nova, code it to be handled by either.
|
|
|
|
- For methods that accept either a Nova pool or Neutron network, the
|
|
parameter should just refer to the network, but documentation of it
|
|
should explain about the pool. See: `create_floating_ip()` and
|
|
`available_floating_ip()` methods.
|
|
|
|
Tests
|
|
=====
|
|
|
|
- New API methods *must* have unit tests!
|
|
|
|
- Functional tests should be added, when possible.
|
|
|
|
- In functional tests, always use unique names (for resources that have this
|
|
attribute) and use it for clean up (see next point).
|
|
|
|
- In functional tests, always define cleanup functions to delete data added
|
|
by your test, should something go wrong. Data removal should be wrapped in
|
|
a try except block and try to delete as many entries added by the test as
|
|
possible.
|