openstack/openstacksdk
Code Issues Proposed changes

Adjust some proxy method names in cluster

Browse Source 
In auditing our proxy method names heading into the 1.0 release,
where we'll need to be more careful about backwards compatibility,
some names in the cluster proxy use structures that are different than
we're using both around the other services and also within cluster
itself. We've converged on several naming formats for add/remove,
attach/detach, and several other grammar styles when naming operations
that are done on a certain resource.

This change introduces a deprecation decorator using the `deprecation`
library, which was recently added to global-requirements. This is also
the first change of several in the auditing process, just going
alphabetical order through the services.

The plan with these is that they're marked for deprecation in the
next release (0.9.14), both here in the code and in the documentation
via the deprecation library's ability to modify the docstring, which
then shows up in our built documentation. In the meantime, we should
help any users we know of—in this case we have cluster developers on
this project—in updating calling code to use the newer format before
1.0 happens.

The following deprecations were made:
* cluster_add_nodes -> add_nodes_to_cluster
* cluster_del_nodes -> remove_nodes_from_cluster
* cluster_replace_nodes -> replace_nodes_in_cluster
* cluster_scale_out -> scale_out_cluster
* cluster_scale_in -> scale_in_cluster
* cluster_attach_policy -> attach_policy_to_cluster
* cluster_detach_policy -> detach_policy_from_cluster
* cluster_update_policy -> update_cluster_policy
* cluster_operation -> perform_operation_on_cluster
* node_operation -> perform_operation_on_node

Partial-Bug: 1657498

Change-Id: I3df0494f9ec0097aee7d47e05fb42094439bc4a4
This commit is contained in:
Brian Curtin 2017-02-01 15:00:34 -05:00
parent 93894627ec
commit e97a755046
4 changed files with 198 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

150
openstack/cluster/v1/_proxy.py
View File

@ -24,6 +24,7 @@ from openstack.cluster.v1 import profile_type as _profile_type
from openstack.cluster.v1 import receiver as _receiver
from openstack import proxy2
from openstack import resource2
from openstack import utils
class Proxy(proxy2.BaseProxy):
@ -275,9 +276,21 @@ class Proxy(proxy2.BaseProxy):
"""
return self._update(_cluster.Cluster, cluster, **attrs)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use add_nodes_to_cluster instead")
def cluster_add_nodes(self, cluster, nodes):
"""Add nodes to a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param nodes: List of nodes to be added to the cluster.
:returns: A dict containing the action initiated by this operation.
"""
return self.add_nodes_to_cluster(cluster, nodes)
def add_nodes_to_cluster(self, cluster, nodes):
"""Add nodes to a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param nodes: List of nodes to be added to the cluster.
@ -289,9 +302,25 @@ class Proxy(proxy2.BaseProxy):
obj = self._find(_cluster.Cluster, cluster, ignore_missing=False)
return obj.add_nodes(self.session, nodes)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use remove_nodes_from_cluster instead")
def cluster_del_nodes(self, cluster, nodes, **params):
"""Remove nodes from a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param nodes: List of nodes to be removed from the cluster.
:param kwargs \*\*params: Optional query parameters to be sent to
restrict the nodes to be returned. Available parameters include:
* destroy_after_deletion: A boolean value indicating whether the
deleted nodes to be destroyed right away.
:returns: A dict containing the action initiated by this operation.
"""
return self.remove_nodes_from_cluster(cluster, nodes, **params)
def remove_nodes_from_cluster(self, cluster, nodes, **params):
"""Remove nodes from a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param nodes: List of nodes to be removed from the cluster.
@ -307,9 +336,21 @@ class Proxy(proxy2.BaseProxy):
obj = self._find(_cluster.Cluster, cluster, ignore_missing=False)
return obj.del_nodes(self.session, nodes, **params)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use replace_nodes_in_cluster instead")
def cluster_replace_nodes(self, cluster, nodes):
"""Replace the nodes in a cluster with specified nodes.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param nodes: List of nodes to be deleted/added to the cluster.
:returns: A dict containing the action initiated by this operation.
"""
return self.replace_nodes_in_cluster(cluster, nodes)
def replace_nodes_in_cluster(self, cluster, nodes):
"""Replace the nodes in a cluster with specified nodes.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param nodes: List of nodes to be deleted/added to the cluster.
@ -321,9 +362,22 @@ class Proxy(proxy2.BaseProxy):
obj = self._find(_cluster.Cluster, cluster, ignore_missing=False)
return obj.replace_nodes(self.session, nodes)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use scale_out_cluster instead")
def cluster_scale_out(self, cluster, count=None):
"""Inflate the size of a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param count: Optional parameter specifying the number of nodes to
be added.
:returns: A dict containing the action initiated by this operation.
"""
return self.scale_out_cluster(cluster, count)
def scale_out_cluster(self, cluster, count=None):
"""Inflate the size of a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param count: Optional parameter specifying the number of nodes to
@ -336,9 +390,22 @@ class Proxy(proxy2.BaseProxy):
obj = self._find(_cluster.Cluster, cluster, ignore_missing=False)
return obj.scale_out(self.session, count)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use scale_in_cluster instead")
def cluster_scale_in(self, cluster, count=None):
"""Shrink the size of a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param count: Optional parameter specifying the number of nodes to
be removed.
:returns: A dict containing the action initiated by this operation.
"""
return self.scale_in_cluster(cluster, count)
def scale_in_cluster(self, cluster, count=None):
"""Shrink the size of a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param count: Optional parameter specifying the number of nodes to
@ -351,9 +418,22 @@ class Proxy(proxy2.BaseProxy):
obj = self._find(_cluster.Cluster, cluster, ignore_missing=False)
return obj.scale_in(self.session, count)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use resize_cluster instead")
def cluster_resize(self, cluster, **params):
"""Resize of cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param dict \*\*params: A dictionary providing the parameters for the
resize action.
:returns: A dict containing the action initiated by this operation.
"""
return self.resize_cluster(cluster, **params)
def resize_cluster(self, cluster, **params):
"""Resize of cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param dict \*\*params: A dictionary providing the parameters for the
@ -366,9 +446,23 @@ class Proxy(proxy2.BaseProxy):
obj = self._find(_cluster.Cluster, cluster, ignore_missing=False)
return obj.resize(self.session, **params)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use attach_policy_to_cluster instead")
def cluster_attach_policy(self, cluster, policy, **params):
"""Attach a policy to a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param policy: Either the name or the ID of a policy.
:param dict \*\*params: A dictionary containing the properties for the
policy to be attached.
:returns: A dict containing the action initiated by this operation.
"""
return self.attach_policy_to_cluster(cluster, policy, **params)
def attach_policy_to_cluster(self, cluster, policy, **params):
"""Attach a policy to a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param policy: Either the name or the ID of a policy.
@ -382,9 +476,21 @@ class Proxy(proxy2.BaseProxy):
obj = self._find(_cluster.Cluster, cluster, ignore_missing=False)
return obj.policy_attach(self.session, policy, **params)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use detach_policy_from_cluster instead")
def cluster_detach_policy(self, cluster, policy):
"""Attach a policy to a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param policy: Either the name or the ID of a policy.
:returns: A dict containing the action initiated by this operation.
"""
return self.detach_policy_from_cluster(cluster, policy)
def detach_policy_from_cluster(self, cluster, policy):
"""Detach a policy from a cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param policy: Either the name or the ID of a policy.
@ -396,9 +502,23 @@ class Proxy(proxy2.BaseProxy):
obj = self._find(_cluster.Cluster, cluster, ignore_missing=False)
return obj.policy_detach(self.session, policy)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use update_cluster_policy instead")
def cluster_update_policy(self, cluster, policy, **params):
"""Change properties of a policy which is bound to the cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param policy: Either the name or the ID of a policy.
:param dict \*\*params: A dictionary containing the new properties for
the policy.
:returns: A dict containing the action initiated by this operation.
"""
return self.update_cluster_policy(cluster, policy, **params)
def update_cluster_policy(self, cluster, policy, **params):
"""Change properties of a policy which is bound to the cluster.
:param cluster: Either the name or the ID of the cluster, or an
instance of :class:`~openstack.cluster.v1.cluster.Cluster`.
:param policy: Either the name or the ID of a policy.
@ -450,9 +570,24 @@ class Proxy(proxy2.BaseProxy):
obj = self._get_resource(_cluster.Cluster, cluster)
return obj.recover(self.session, **params)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use perform_operation_on_cluster instead")
def cluster_operation(self, cluster, operation, **params):
"""Perform an operation on the specified cluster.
:param cluster: The value can be either the ID of a cluster or a
:class:`~openstack.cluster.v1.cluster.Cluster` instance.
:param operation: A string specifying the operation to be performed.
:param dict params: A dictionary providing the parameters for the
operation.
:returns: A dictionary containing the action ID.
"""
return self.perform_operation_on_cluster(cluster, operation, **params)
def perform_operation_on_cluster(self, cluster, operation, **params):
"""Perform an operation on the specified cluster.
:param cluster: The value can be either the ID of a cluster or a
:class:`~openstack.cluster.v1.cluster.Cluster` instance.
:param operation: A string specifying the operation to be performed.
@ -584,9 +719,24 @@ class Proxy(proxy2.BaseProxy):
obj = self._get_resource(_node.Node, node)
return obj.recover(self.session, **params)
@utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
details="Use perform_operation_on_node instead")
def node_operation(self, node, operation, **params):
"""Perform an operation on the specified node.
:param cluster: The value can be either the ID of a node or a
:class:`~openstack.cluster.v1.node.Node` instance.
:param operation: A string specifying the operation to be performed.
:param dict params: A dictionary providing the parameters for the
operation.
:returns: A dictionary containing the action ID.
"""
return self.perform_operation_on_node(node, operation, **params)
def perform_operation_on_node(self, node, operation, **params):
"""Perform an operation on the specified node.
:param cluster: The value can be either the ID of a node or a
:class:`~openstack.cluster.v1.node.Node` instance.
:param operation: A string specifying the operation to be performed.

19
openstack/tests/unit/cluster/v1/test_proxy.py
View File

@ -10,6 +10,7 @@
# License for the specific language governing permissions and limitations
# under the License.
import deprecation
import mock
from openstack.cluster.v1 import _proxy
@ -107,6 +108,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
def test_cluster_update(self):
self.verify_update(self.proxy.update_cluster, cluster.Cluster)
@deprecation.fail_if_not_removed
@mock.patch.object(proxy_base.BaseProxy, '_find')
def test_cluster_add_nodes(self, mock_find):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
@ -118,6 +120,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
mock_find.assert_called_once_with(cluster.Cluster, "FAKE_CLUSTER",
ignore_missing=False)
@deprecation.fail_if_not_removed
def test_cluster_add_nodes_with_obj(self):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
self._verify("openstack.cluster.v1.cluster.Cluster.add_nodes",
@ -125,6 +128,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
method_args=[mock_cluster, ["node1"]],
expected_args=[["node1"]])
@deprecation.fail_if_not_removed
@mock.patch.object(proxy_base.BaseProxy, '_find')
def test_cluster_del_nodes(self, mock_find):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
@ -136,6 +140,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
mock_find.assert_called_once_with(cluster.Cluster, "FAKE_CLUSTER",
ignore_missing=False)
@deprecation.fail_if_not_removed
def test_cluster_del_nodes_with_obj(self):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
self._verify("openstack.cluster.v1.cluster.Cluster.del_nodes",
@ -145,6 +150,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
expected_args=[["node1"]],
expected_kwargs={"key": "value"})
@deprecation.fail_if_not_removed
@mock.patch.object(proxy_base.BaseProxy, '_find')
def test_cluster_replace_nodes(self, mock_find):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
@ -156,6 +162,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
mock_find.assert_called_once_with(cluster.Cluster, "FAKE_CLUSTER",
ignore_missing=False)
@deprecation.fail_if_not_removed
def test_cluster_replace_nodes_with_obj(self):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
self._verify("openstack.cluster.v1.cluster.Cluster.replace_nodes",
@ -163,6 +170,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
method_args=[mock_cluster, {"node1": "node2"}],
expected_args=[{"node1": "node2"}])
@deprecation.fail_if_not_removed
@mock.patch.object(proxy_base.BaseProxy, '_find')
def test_cluster_scale_out(self, mock_find):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
@ -174,6 +182,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
mock_find.assert_called_once_with(cluster.Cluster, "FAKE_CLUSTER",
ignore_missing=False)
@deprecation.fail_if_not_removed
def test_cluster_scale_out_with_obj(self):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
self._verify("openstack.cluster.v1.cluster.Cluster.scale_out",
@ -181,6 +190,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
method_args=[mock_cluster, 5],
expected_args=[5])
@deprecation.fail_if_not_removed
@mock.patch.object(proxy_base.BaseProxy, '_find')
def test_cluster_scale_in(self, mock_find):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
@ -192,6 +202,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
mock_find.assert_called_once_with(cluster.Cluster, "FAKE_CLUSTER",
ignore_missing=False)
@deprecation.fail_if_not_removed
def test_cluster_scale_in_with_obj(self):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
self._verify("openstack.cluster.v1.cluster.Cluster.scale_in",
@ -219,6 +230,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
method_kwargs={'k1': 'v1', 'k2': 'v2'},
expected_kwargs={'k1': 'v1', 'k2': 'v2'})
@deprecation.fail_if_not_removed
@mock.patch.object(proxy_base.BaseProxy, '_find')
def test_cluster_attach_policy(self, mock_find):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
@ -232,6 +244,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
mock_find.assert_called_once_with(cluster.Cluster, "FAKE_CLUSTER",
ignore_missing=False)
@deprecation.fail_if_not_removed
def test_cluster_attach_policy_with_obj(self):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
self._verify("openstack.cluster.v1.cluster.Cluster.policy_attach",
@ -241,6 +254,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
expected_args=["FAKE_POLICY"],
expected_kwargs={"k1": "v1", 'k2': "v2"})
@deprecation.fail_if_not_removed
@mock.patch.object(proxy_base.BaseProxy, '_find')
def test_cluster_detach_policy(self, mock_find):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
@ -252,6 +266,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
mock_find.assert_called_once_with(cluster.Cluster, "FAKE_CLUSTER",
ignore_missing=False)
@deprecation.fail_if_not_removed
def test_cluster_detach_policy_with_obj(self):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
self._verify("openstack.cluster.v1.cluster.Cluster.policy_detach",
@ -259,6 +274,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
method_args=[mock_cluster, "FAKE_POLICY"],
expected_args=["FAKE_POLICY"])
@deprecation.fail_if_not_removed
@mock.patch.object(proxy_base.BaseProxy, '_find')
def test_cluster_update_policy(self, mock_find):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
@ -272,6 +288,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
mock_find.assert_called_once_with(cluster.Cluster, "FAKE_CLUSTER",
ignore_missing=False)
@deprecation.fail_if_not_removed
def test_cluster_update_policy_with_obj(self):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
self._verify("openstack.cluster.v1.cluster.Cluster.policy_update",
@ -306,6 +323,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
method_args=["FAKE_CLUSTER"])
mock_get.assert_called_once_with(cluster.Cluster, "FAKE_CLUSTER")
@deprecation.fail_if_not_removed
@mock.patch.object(proxy_base.BaseProxy, '_get_resource')
def test_cluster_operation(self, mock_get):
mock_cluster = cluster.Cluster.new(id='FAKE_CLUSTER')
@ -367,6 +385,7 @@ class TestClusterProxy(test_proxy_base2.TestProxyBase):
method_args=["FAKE_NODE"])
mock_get.assert_called_once_with(node.Node, "FAKE_NODE")
@deprecation.fail_if_not_removed
@mock.patch.object(proxy_base.BaseProxy, '_get_resource')
def test_node_operation(self, mock_get):
mock_node = node.Node.new(id='FAKE_CLUSTER')

28
openstack/utils.py
View File

@ -10,8 +10,36 @@
# License for the specific language governing permissions and limitations
# under the License.
import functools
import logging
import deprecation
from openstack import version
def deprecated(deprecated_in=None, removed_in=None,
details=""):
"""Mark a method as deprecated
:param deprecated_in: The version string where this method is deprecated.
Generally this is the next version to be released.
:param removed_in: The version where this method will be removed
from the code base. Generally this is the next
major version. This argument is helpful for the
tests when using ``deprecation.fail_if_not_removed``.
:param str details: Helpful details to callers and the documentation.
This will usually be a recommendation for alternate
code to use.
"""
# As all deprecations within this library have the same current_version,
# return a partial function with the library version always set.
partial = functools.partial(deprecation.deprecated,
current_version=version.__version__)
return partial(deprecated_in=deprecated_in, removed_in=removed_in,
details=details)
def enable_logging(debug=False, path=None, stream=None):
"""Enable logging to a file at path and/or a console stream.

1
requirements.txt
View File

@ -6,3 +6,4 @@ six>=1.9.0 # MIT
stevedore>=1.17.1 # Apache-2.0
os-client-config>=1.22.0 # Apache-2.0
keystoneauth1>=2.18.0 # Apache-2.0
deprecation>=1.0 # Apache-2.0