diff --git a/doc/source/users/index.rst b/doc/source/users/index.rst index 5063549f..b03cb4c9 100644 --- a/doc/source/users/index.rst +++ b/doc/source/users/index.rst @@ -122,5 +122,6 @@ can be customized. session resource + resource2 service_filter utils diff --git a/doc/source/users/resource.rst b/doc/source/users/resource.rst index d2b905c8..f40188e1 100644 --- a/doc/source/users/resource.rst +++ b/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 diff --git a/doc/source/users/resource2.rst b/doc/source/users/resource2.rst new file mode 100644 index 00000000..bc664213 --- /dev/null +++ b/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 diff --git a/openstack/compute/v2/_proxy.py b/openstack/compute/v2/_proxy.py index c44362db..66692500 100644 --- a/openstack/compute/v2/_proxy.py +++ b/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`` """ @@ -478,10 +478,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. @@ -736,7 +736,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`` """ diff --git a/openstack/object_store/v1/_proxy.py b/openstack/object_store/v1/_proxy.py index c242500c..a38171fc 100644 --- a/openstack/object_store/v1/_proxy.py +++ b/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, diff --git a/openstack/profile.py b/openstack/profile.py index 2c3db0cd..16057cee 100644 --- a/openstack/profile.py +++ b/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. diff --git a/openstack/resource2.py b/openstack/resource2.py index cffd4e50..057fc27a 100644 --- a/openstack/resource2.py +++ b/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 - 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 diff --git a/openstack/tests/unit/test_resource2.py b/openstack/tests/unit/test_resource2.py index 147ad4ff..c4055f53 100644 --- a/openstack/tests/unit/test_resource2.py +++ b/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)