openstack/shade
Code Issues Proposed changes

Clarify Munch object usage in documentation

Browse Source 
We have pretty much settled on sticking with Munch objects for the
1.x series of shade releases. Change the documentation to note this.

Change-Id: I8b2838c3a5a40b0c74e31081bfb1ed4b0d39280f
This commit is contained in:
David Shrewsbury 2016-02-05 14:11:09 -05:00
parent df379be704
commit ab8a196907
1 changed files with 12 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/source/usage.rst
View File

@ -6,12 +6,18 @@ To use shade in a project::
import shade
.. warning::
Several of the API methods return a ``dict`` that describe a resource.
It is possible to access keys of the dict as an attribute (e.g.,
``server.id`` instead of ``server['id']``) to maintain some backward
compatibility, but attribute access is deprecated. New code should
assume a normal dictionary and access values via key.
.. note::
API methods that return a description of an OpenStack resource (e.g.,
server instance, image, volume, etc.) do so using a dictionary of values
(e.g., ``server['id']``, ``image['name']``). This is the standard, and
**recommended**, way to access these resource values.
For backward compatibility, resource values can be accessed using object
attribute access (e.g., ``server.id``, ``image.name``). Shade uses the
`Munch library <https://github.com/Infinidat/munch>`_ to provide this
behavior. This is **NOT** the recommended way to access resource values.
We keep this behavior for developer convenience in the 1.x series of shade
releases. This will likely not be the case in future, major releases of shade.
.. autoclass:: shade.OpenStackCloud
:members: