Skip to content

Commit 2be9e9b

Browse files
briancurtinbriancurtin
committed
Document the synchronized parameter.
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
1 parent 69d79c9 commit 2be9e9b

File tree

8 files changed

+68
-22
lines changed

8 files changed

+68
-22
lines changed

‎doc/source/users/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,5 +122,6 @@ can be customized.
122122

123123
session
124124
resource
125+
resource2
125126
service_filter
126127
utils

‎doc/source/users/resource.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
**NOTE: This module is being phased out in favor of**
2+
:mod:`openstack.resource2`. **Once all services have been moved over to use
3+
resource2, that module will take this `resource` name.**
4+
15
Resource
26
========
37
.. automodule:: openstack.resource

‎doc/source/users/resource2.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
**Note: This class is in the process of being applied as the new base class
2+
for resources around the OpenStack SDK. Once that has been completed,
3+
this module will be drop the 2 suffix and be the only resource module.**
4+
5+
Resource
6+
========
7+
.. automodule:: openstack.resource2
8+
9+
Components
10+
----------
11+
12+
.. autoclass:: openstack.resource2.Body
13+
:members:
14+
15+
.. autoclass:: openstack.resource2.Header
16+
:members:
17+
18+
.. autoclass:: openstack.resource2.URI
19+
:members:
20+
21+
The Resource class
22+
------------------
23+
24+
.. autoclass:: openstack.resource2.Resource
25+
:members:
26+
:member-order: bysource

‎openstack/compute/v2/_proxy.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,7 @@ def delete_image_metadata(self, image, keys):
231231
:class:`~openstack.compute.v2.image.Image` or
232232
:class:`~openstack.compute.v2.image.ImageDetail`
233233
instance.
234-
:param list keys: The keys to delete.
234+
:param keys: The keys to delete.
235235
236236
:rtype: ``None``
237237
"""
@@ -465,10 +465,10 @@ def rebuild_server(self, server, name, admin_password, **attrs):
465465
*Default: None*
466466
:param dict metadata: A dictionary of metadata to rebuild with.
467467
*Default: None*
468-
:param list personality: A list of dictionaries, each including a
469-
**path** and **contents** key, to be injected
470-
into the rebuilt server at launch.
471-
*Default: None*
468+
:param personality: A list of dictionaries, each including a
469+
**path** and **contents** key, to be injected
470+
into the rebuilt server at launch.
471+
*Default: None*
472472
473473
:returns: The rebuilt :class:`~openstack.compute.v2.server.Server`
474474
instance.
@@ -723,7 +723,7 @@ def delete_server_metadata(self, server, keys):
723723
:class:`~openstack.compute.v2.server.Server` or
724724
:class:`~openstack.compute.v2.server.ServerDetail`
725725
instance.
726-
:param list keys: The keys to delete
726+
:param keys: The keys to delete
727727
728728
:rtype: ``None``
729729
"""

‎openstack/object_store/v1/_proxy.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ def set_account_metadata(self, **metadata):
4040
def delete_account_metadata(self, keys):
4141
"""Delete metadata for this account.
4242
43-
:param list keys: The keys of metadata to be deleted.
43+
:param keys: The keys of metadata to be deleted.
4444
"""
4545
account = self._get_resource(_account.Account, None)
4646
account.delete_metadata(self.session, keys)
@@ -129,7 +129,7 @@ def delete_container_metadata(self, container, keys):
129129
:param container: The value can be the ID of a container or a
130130
:class:`~openstack.object_store.v1.container.Container`
131131
instance.
132-
:param list keys: The keys of metadata to be deleted.
132+
:param keys: The keys of metadata to be deleted.
133133
"""
134134
res = self._get_resource(_container.Container, container)
135135
res.delete_metadata(self.session, keys)
@@ -310,7 +310,7 @@ def delete_object_metadata(self, obj, container=None, keys=None):
310310
:param container: The value can be the ID of a container or a
311311
:class:`~openstack.object_store.v1.container.Container`
312312
instance.
313-
:param list keys: The keys of metadata to be deleted.
313+
:param keys: The keys of metadata to be deleted.
314314
"""
315315
container_name = self._get_container_name(obj, container)
316316
res = self._get_resource(_obj.Object, obj,

‎openstack/profile.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ class Profile(object):
8282
def __init__(self, plugins=None):
8383
"""User preference for each service.
8484
85-
:param list plugins: List of entry point namespaces to load.
85+
:param plugins: List of entry point namespaces to load.
8686
8787
Create a new :class:`~openstack.profile.Profile`
8888
object with no preferences defined, but knowledge of the services.

‎openstack/resource2.py‎

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -251,7 +251,14 @@ class Resource(object):
251251
#: Use PUT for create operations on this resource.
252252
put_create = False
253253

254-
def __init__(self, synchronized=False, **attrs):
254+
def __init__(self, _synchronized=False, **attrs):
255+
"""The base resource
256+
257+
:param bool _synchronized: This is not intended to be used directly.
258+
See :meth:`~openstack.resource2.Resource.new` and
259+
:meth:`~openstack.resource2.Resource.existing`.
260+
"""
261+
255262
# NOTE: _collect_attrs modifies **attrs in place, removing
256263
# items as they match up with any of the body, header,
257264
# or uri mappings.
@@ -261,11 +268,11 @@ def __init__(self, synchronized=False, **attrs):
261268
# How strict should we be here? Should strict be an option?
262269

263270
self._body = _ComponentManager(attributes=body,
264-
synchronized=synchronized)
271+
synchronized=_synchronized)
265272
self._header = _ComponentManager(attributes=header,
266-
synchronized=synchronized)
273+
synchronized=_synchronized)
267274
self._uri = _ComponentManager(attributes=uri,
268-
synchronized=synchronized)
275+
synchronized=_synchronized)
269276

270277
def __repr__(self):
271278
pairs = ["%s=%s" % (k, v) for k, v in dict(itertools.chain(
@@ -418,24 +425,32 @@ def _get_id(value):
418425
def new(cls, **kwargs):
419426
"""Create a new instance of this resource.
420427
421-
Internally set flags such that it is marked as not present on the
422-
server.
428+
When creating the instance set the ``_synchronized`` parameter
429+
of :class:`Resource` to ``False`` to indicate that the resource does
430+
not yet exist on the server side. This marks all attributes passed
431+
in ``**kwargs`` as "dirty" on the resource, and thusly tracked
432+
as necessary in subsequent calls such as :meth:`update`.
423433
424434
:param dict kwargs: Each of the named arguments will be set as
425435
attributes on the resulting Resource object.
426436
"""
427-
return cls(synchronized=False, **kwargs)
437+
return cls(_synchronized=False, **kwargs)
428438

429439
@classmethod
430440
def existing(cls, **kwargs):
431441
"""Create an instance of an existing remote resource.
432442
433-
It is marked as an exact replication of a resource present on a server.
443+
When creating the instance set the ``_synchronized`` parameter
444+
of :class:`Resource` to ``True`` to indicate that it represents the
445+
state of an existing server-side resource. As such, all attributes
446+
passed in ``**kwargs`` are considered "clean", such that an immediate
447+
:meth:`update` call would not generate a body of attributes to be
448+
modified on the server.
434449
435450
:param dict kwargs: Each of the named arguments will be set as
436451
attributes on the resulting Resource object.
437452
"""
438-
return cls(synchronized=True, **kwargs)
453+
return cls(_synchronized=True, **kwargs)
439454

440455
def to_dict(self, body=True, headers=True, ignore_none=False):
441456
"""Return a dictionary of this resource's contents

‎openstack/tests/unit/test_resource2.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -395,7 +395,7 @@ def test_initialize_basic(self):
395395

396396
with mock.patch.object(resource2.Resource,
397397
"_collect_attrs", mock_collect):
398-
sot = resource2.Resource(synchronized=False, **everything)
398+
sot = resource2.Resource(_synchronized=False, **everything)
399399
mock_collect.assert_called_once_with(everything)
400400
self.assertEqual("somewhere", sot.location)
401401

@@ -787,7 +787,7 @@ class Test(resource2.Resource):
787787
body_value = "body"
788788
header_value = "header"
789789
sot = Test(id=the_id, body_attr=body_value, header_attr=header_value,
790-
synchronized=False)
790+
_synchronized=False)
791791

792792
result = sot._prepare_request(requires_id=True)
793793

@@ -813,7 +813,7 @@ class Test(resource2.Resource):
813813
body_value = "body"
814814
header_value = "header"
815815
sot = Test(body_attr=body_value, header_attr=header_value,
816-
synchronized=False)
816+
_synchronized=False)
817817

818818
result = sot._prepare_request(requires_id=False, prepend_key=True)
819819

0 commit comments

Comments
 (0)