openstack/openstacksdk
Code Issues Proposed changes

Document the synchronized parameter.

Browse Source 
It is apparently confusing that the `synchronized` parameter exists in
the class signature of each resource subclass, but it's not documented
anywhere. This change moves the parameter to _synchronized and pushes
documentation of the parameter down to the new/existing methods, as it's
not directly useful to end-users in the initializer, but is necessary in
those classmethods.

Change-Id: I42a01f24d44383889cccce2a2e89442eea1943d7
Closes-Bug: 1645007
This commit is contained in:
Brian Curtin 2016-11-28 13:33:07 -05:00
parent 69d79c97e8
commit 2be9e9b6ba
8 changed files with 68 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/users/index.rst
View File

@ -122,5 +122,6 @@ can be customized.
session
resource
resource2
service_filter
utils

4
doc/source/users/resource.rst
View File

@ -1,3 +1,7 @@
**NOTE: This module is being phased out in favor of**
:mod:`openstack.resource2`. **Once all services have been moved over to use
resource2, that module will take this `resource` name.**
Resource
========
.. automodule:: openstack.resource

26
doc/source/users/resource2.rst Normal file
View File

@ -0,0 +1,26 @@
**Note: This class is in the process of being applied as the new base class
for resources around the OpenStack SDK. Once that has been completed,
this module will be drop the 2 suffix and be the only resource module.**
Resource
========
.. automodule:: openstack.resource2
Components
----------
.. autoclass:: openstack.resource2.Body
:members:
.. autoclass:: openstack.resource2.Header
:members:
.. autoclass:: openstack.resource2.URI
:members:
The Resource class
------------------
.. autoclass:: openstack.resource2.Resource
:members:
:member-order: bysource

12
openstack/compute/v2/_proxy.py
View File

@ -231,7 +231,7 @@ class Proxy(proxy2.BaseProxy):
:class:`~openstack.compute.v2.image.Image` or
:class:`~openstack.compute.v2.image.ImageDetail`
instance.
:param list keys: The keys to delete.
:param keys: The keys to delete.
:rtype: ``None``
"""
@ -465,10 +465,10 @@ class Proxy(proxy2.BaseProxy):
*Default: None*
:param dict metadata: A dictionary of metadata to rebuild with.
*Default: None*
:param list personality: A list of dictionaries, each including a
**path** and **contents** key, to be injected
into the rebuilt server at launch.
*Default: None*
:param personality: A list of dictionaries, each including a
**path** and **contents** key, to be injected
into the rebuilt server at launch.
*Default: None*
:returns: The rebuilt :class:`~openstack.compute.v2.server.Server`
instance.
@ -723,7 +723,7 @@ class Proxy(proxy2.BaseProxy):
:class:`~openstack.compute.v2.server.Server` or
:class:`~openstack.compute.v2.server.ServerDetail`
instance.
:param list keys: The keys to delete
:param keys: The keys to delete
:rtype: ``None``
"""

6
openstack/object_store/v1/_proxy.py
View File

@ -40,7 +40,7 @@ class Proxy(proxy.BaseProxy):
def delete_account_metadata(self, keys):
"""Delete metadata for this account.
:param list keys: The keys of metadata to be deleted.
:param keys: The keys of metadata to be deleted.
"""
account = self._get_resource(_account.Account, None)
account.delete_metadata(self.session, keys)
@ -129,7 +129,7 @@ class Proxy(proxy.BaseProxy):
:param container: The value can be the ID of a container or a
:class:`~openstack.object_store.v1.container.Container`
instance.
:param list keys: The keys of metadata to be deleted.
:param keys: The keys of metadata to be deleted.
"""
res = self._get_resource(_container.Container, container)
res.delete_metadata(self.session, keys)
@ -310,7 +310,7 @@ class Proxy(proxy.BaseProxy):
:param container: The value can be the ID of a container or a
:class:`~openstack.object_store.v1.container.Container`
instance.
:param list keys: The keys of metadata to be deleted.
:param keys: The keys of metadata to be deleted.
"""
container_name = self._get_container_name(obj, container)
res = self._get_resource(_obj.Object, obj,

2
openstack/profile.py
View File

@ -82,7 +82,7 @@ class Profile(object):
def __init__(self, plugins=None):
"""User preference for each service.
:param list plugins: List of entry point namespaces to load.
:param plugins: List of entry point namespaces to load.
Create a new :class:`~openstack.profile.Profile`
object with no preferences defined, but knowledge of the services.

33
openstack/resource2.py
View File

@ -251,7 +251,14 @@ class Resource(object):
#: Use PUT for create operations on this resource.
put_create = False
def __init__(self, synchronized=False, **attrs):
def __init__(self, _synchronized=False, **attrs):
"""The base resource
:param bool _synchronized: This is not intended to be used directly.
See :meth:`~openstack.resource2.Resource.new` and
:meth:`~openstack.resource2.Resource.existing`.
"""
# NOTE: _collect_attrs modifies **attrs in place, removing
# items as they match up with any of the body, header,
# or uri mappings.
@ -261,11 +268,11 @@ class Resource(object):
# How strict should we be here? Should strict be an option?
self._body = _ComponentManager(attributes=body,
synchronized=synchronized)
synchronized=_synchronized)
self._header = _ComponentManager(attributes=header,
synchronized=synchronized)
synchronized=_synchronized)
self._uri = _ComponentManager(attributes=uri,
synchronized=synchronized)
synchronized=_synchronized)
def __repr__(self):
pairs = ["%s=%s" % (k, v) for k, v in dict(itertools.chain(
@ -418,24 +425,32 @@ class Resource(object):
def new(cls, **kwargs):
"""Create a new instance of this resource.
Internally set flags such that it is marked as not present on the
server.
When creating the instance set the ``_synchronized`` parameter
of :class:`Resource` to ``False`` to indicate that the resource does
not yet exist on the server side. This marks all attributes passed
in ``**kwargs`` as "dirty" on the resource, and thusly tracked
as necessary in subsequent calls such as :meth:`update`.
:param dict kwargs: Each of the named arguments will be set as
attributes on the resulting Resource object.
"""
return cls(synchronized=False, **kwargs)
return cls(_synchronized=False, **kwargs)
@classmethod
def existing(cls, **kwargs):
"""Create an instance of an existing remote resource.
It is marked as an exact replication of a resource present on a server.
When creating the instance set the ``_synchronized`` parameter
of :class:`Resource` to ``True`` to indicate that it represents the
state of an existing server-side resource. As such, all attributes
passed in ``**kwargs`` are considered "clean", such that an immediate
:meth:`update` call would not generate a body of attributes to be
modified on the server.
:param dict kwargs: Each of the named arguments will be set as
attributes on the resulting Resource object.
"""
return cls(synchronized=True, **kwargs)
return cls(_synchronized=True, **kwargs)
def to_dict(self, body=True, headers=True, ignore_none=False):
"""Return a dictionary of this resource's contents

6
openstack/tests/unit/test_resource2.py
View File

@ -395,7 +395,7 @@ class TestResource(base.TestCase):
with mock.patch.object(resource2.Resource,
"_collect_attrs", mock_collect):
sot = resource2.Resource(synchronized=False, **everything)
sot = resource2.Resource(_synchronized=False, **everything)
mock_collect.assert_called_once_with(everything)
self.assertEqual("somewhere", sot.location)
@ -787,7 +787,7 @@ class TestResource(base.TestCase):
body_value = "body"
header_value = "header"
sot = Test(id=the_id, body_attr=body_value, header_attr=header_value,
synchronized=False)
_synchronized=False)
result = sot._prepare_request(requires_id=True)
@ -813,7 +813,7 @@ class TestResource(base.TestCase):
body_value = "body"
header_value = "header"
sot = Test(body_attr=body_value, header_attr=header_value,
synchronized=False)
_synchronized=False)
result = sot._prepare_request(requires_id=False, prepend_key=True)