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

doc/source/users/index.rst

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

doc/source/users/resource.rst

@@ -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

doc/source/users/resource2.rst

@@ -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

openstack/compute/v2/_proxy.py

@@ -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,7 +465,7 @@ 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
+        :param personality: A list of dictionaries, each including a
                             **path** and **contents** key, to be injected
                             into the rebuilt server at launch.
                             *Default: None*
@@ -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``
         """

openstack/object_store/v1/_proxy.py

@@ -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,

openstack/profile.py

@@ -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.

openstack/resource2.py

@@ -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
+        When creating the instance set the ``_synchronized`` parameter
-        server.
+        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

openstack/tests/unit/test_resource2.py

@@ -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)