test-1604

pending completion

Build # test-1604

Build Type

push

github

Committed by

andy-maier

Commit Message

Added support for auto-updated resource managers

Details:

* Added support for auto-updated resource managers. An auto-updated resource
  manager has its list of resources automatically updated as resources are
  created and deleted on the HMC, based on HMC notifications. (issue #1055)

  Added an example script examples/show_auto_updated_partition_manager.py
  to demonstrate an auto-updating enabled partition manager.

  Renamed the existing example script show_auto_update.py to
  show_auto_updated_partition.py, for clarity, and improved it by
  controlling the logging by a global flag.

* Renamed the Session.resource_updater property to auto_updater and the
  zhmcclient.ResourceUpdater class to AutoUpdater to take into account that
  the class and property now represent auto-updated manager objects in addition
  to auto-updated resource objects. Note that the property and class are
  still experimental in this version.

* Docs: In the description of the list() methods of the resource manager
  classes, described the optimized lookup behavior for auto-updated managers
  and optimized access via the name-to-URI cache.

* Added optimized lookup by name in list() methods of the following resource
  classes: `LdapServerDefinition`, `PasswordRule`, `Task`, `User`,
  `UserPattern`, `UserRole`,

Internal Details:

* Reworked the unit testcases for AutoUpdater to be more explicit
  in the testcase specification, and to add support for specifying
  inventory change notifications. Added testcases.

* Renamed the end2end testcase module test_resource_auto_update.py
  to test_auto_update.py and added a test function test_autoupdate_list()
  which tests the behavior of list() with and without auto-update.

Signed-off-by: Andreas Maier <maiera@de.ibm.com>

Run Details

554 of 714 new or added lines in 29 files covered. (77.59%)

7526 of 9470 relevant lines covered (79.47%)

8.44 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

89.23

/zhmcclient/_virtual_function.py

# Copyright 2016-2021 IBM Corp. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""
A :term:`Virtual Function` is a logical entity that provides a
:term:`Partition` with access to
:term:`Accelerator Adapters <Accelerator Adapter>`.

Virtual Function resources are contained in Partition resources.

Virtual Functions only exist in :term:`CPCs <CPC>` that are in DPM mode.
"""

from __future__ import absolute_import

import copy

from ._manager import BaseManager
from ._resource import BaseResource
from ._logging import logged_api_call
from ._utils import matches_filters, RC_VIRTUAL_FUNCTION

__all__ = ['VirtualFunctionManager', 'VirtualFunction']


class VirtualFunctionManager(BaseManager):
    """
    Manager providing access to the
    :term:`Virtual Functions <Virtual Function>` in a particular
    :term:`Partition`.

    Derived from :class:`~zhmcclient.BaseManager`; see there for common methods
    and attributes.

    Objects of this class are not directly created by the user; they are
    accessible via the following instance variable of a
    :class:`~zhmcclient.Partition` object (in DPM mode):

    * :attr:`~zhmcclient.Partition.virtual_functions`
    """

    def __init__(self, partition):
        # This function should not go into the docs.
        # Parameters:
        #   partition (:class:`~zhmcclient.Partition`):
        #     Partition defining the scope for this manager.
        super(VirtualFunctionManager, self).__init__(
            resource_class=VirtualFunction,
            class_name=RC_VIRTUAL_FUNCTION,
            session=partition.manager.session,
            parent=partition,
            base_uri='{}/virtual-functions'.format(partition.uri),
            oid_prop='element-id',
            uri_prop='element-uri',
            name_prop='name',
            query_props=[],
            list_has_name=False)

    @property
    def partition(self):
        """
        :class:`~zhmcclient.Partition`: :term:`Partition` defining the scope
        for this manager.
        """
        return self._parent

    @logged_api_call
    def list(self, full_properties=False, filter_args=None):
        """
        List the Virtual Functions of this Partition.

        Any resource property may be specified in a filter argument. For
        details about filter arguments, see :ref:`Filtering`.

        The listing of resources is handled in an optimized way:

        * If this manager is enabled for :ref:`auto-updating`, a locally
          maintained resource list is used (which is automatically updated via
          inventory notifications from the HMC) and the provided filter
          arguments are applied.

        * Otherwise, if the filter arguments specify the resource name as a
          single filter argument with a straight match string (i.e. without
          regular expressions), an optimized lookup is performed based on a
          locally maintained name-URI cache.

        * Otherwise, the corresponding array property for this resource in the
          parent object is used to list the resources, and the provided filter
          arguments are applied.

        Authorization requirements:

        * Object-access permission to this Partition.

        Parameters:

          full_properties (bool):
            Controls whether the full set of resource properties should be
            retrieved, vs. only the short set as returned by the list
            operation.

          filter_args (dict):
            Filter arguments that narrow the list of returned resources to
            those that match the specified filter arguments. For details, see
            :ref:`Filtering`.

            `None` causes no filtering to happen, i.e. all resources are
            returned.

        Returns:

          : A list of :class:`~zhmcclient.VirtualFunction` objects.

        Raises:

          :exc:`~zhmcclient.HTTPError`
          :exc:`~zhmcclient.ParseError`
          :exc:`~zhmcclient.AuthError`
          :exc:`~zhmcclient.ConnectionError`
        """
        resource_obj_list = []
        if self.auto_update_enabled() and not self.auto_update_needs_pull():
            for resource_obj in self.list_resources_local():
                if matches_filters(resource_obj, filter_args):
                    resource_obj_list.append(resource_obj)
        else:
            uris = self.partition.get_property('virtual-function-uris')
            if uris:
                for uri in uris:

                    resource_obj = self.resource_class(
                        manager=self,
                        uri=uri,
                        name=None,
                        properties=None)

                    if matches_filters(resource_obj, filter_args):
                        resource_obj_list.append(resource_obj)
                        if full_properties:
                            resource_obj.pull_full_properties()

            self.add_resources_local(resource_obj_list)

        self._name_uri_cache.update_from(resource_obj_list)
        return resource_obj_list

    @logged_api_call
    def create(self, properties):
        """
        Create a Virtual Function in this Partition.

        Authorization requirements:

        * Object-access permission to this Partition.
        * Object-access permission to the backing accelerator Adapter.
        * Task permission for the "Partition Details" task.

        Parameters:

          properties (dict): Initial property values.
            Allowable properties are defined in section 'Request body contents'
            in section 'Create Virtual Function' in the :term:`HMC API` book.

        Returns:

          VirtualFunction:
            The resource object for the new Virtual Function.
            The object will have its 'element-uri' property set as returned by
            the HMC, and will also have the input properties set.

        Raises:

          :exc:`~zhmcclient.HTTPError`
          :exc:`~zhmcclient.ParseError`
          :exc:`~zhmcclient.AuthError`
          :exc:`~zhmcclient.ConnectionError`
        """
        result = self.session.post(self.partition.uri + '/virtual-functions',
                                   body=properties)
        # There should not be overlaps, but just in case there are, the
        # returned props should overwrite the input props:
        props = copy.deepcopy(properties)
        props.update(result)
        name = props.get(self._name_prop, None)
        uri = props[self._uri_prop]
        vf = VirtualFunction(self, uri, name, props)
        self._name_uri_cache.update(name, uri)
        return vf


class VirtualFunction(BaseResource):
    """
    Representation of a :term:`Virtual Function`.

    Derived from :class:`~zhmcclient.BaseResource`; see there for common
    methods and attributes.

    For the properties of a Virtual Function, see section
    'Data model - Virtual Function Element Object' in section
    'Partition object' in the :term:`HMC API` book.

    Objects of this class are not directly created by the user; they are
    returned from creation or list functions on their manager object
    (in this case, :class:`~zhmcclient.VirtualFunctionManager`).
    """

    def __init__(self, manager, uri, name=None, properties=None):
        # This function should not go into the docs.
        #   manager (:class:`~zhmcclient.VirtualFunctionManager`):
        #     Manager object for this resource object.
        #   uri (string):
        #     Canonical URI path of the resource.
        #   name (string):
        #     Name of the resource.
        #   properties (dict):
        #     Properties to be set for this resource object. May be `None` or
        #     empty.
        assert isinstance(manager, VirtualFunctionManager), \
            "VirtualFunction init: Expected manager type %s, got %s" % \
            (VirtualFunctionManager, type(manager))
        super(VirtualFunction, self).__init__(manager, uri, name, properties)

    @logged_api_call
    def delete(self):
        """
        Delete this Virtual Function.

        Authorization requirements:

        * Object-access permission to the Partition of this Virtual Function.
        * Task permission for the "Partition Details" task.

        Raises:

          :exc:`~zhmcclient.HTTPError`
          :exc:`~zhmcclient.ParseError`
          :exc:`~zhmcclient.AuthError`
          :exc:`~zhmcclient.ConnectionError`
        """
        # pylint: disable=protected-access
        self.manager.session.delete(self._uri)
        self.manager._name_uri_cache.delete(
            self.get_properties_local(self.manager._name_prop, None))

        parent_vf_uris = self.manager.parent.get_properties_local(
            'virtual-function-uris')
        if parent_vf_uris:
            try:
                parent_vf_uris.remove(self._uri)
            except ValueError:
                pass

    @logged_api_call
    def update_properties(self, properties):
        """
        Update writeable properties of this Virtual Function.

        This method serializes with other methods that access or change
        properties on the same Python object.

        Authorization requirements:

        * Object-access permission to the Partition of this Virtual Function.
        * When updating the "adapter-uri" property, object-access permission to
          the Adapter identified in that URI.
        * Task permission for the "Partition Details" task.

        Parameters:

          properties (dict): New values for the properties to be updated.
            Properties not to be updated are omitted.
            Allowable properties are the properties with qualifier (w) in
            section 'Data model - Virtual Function element object' in the
            :term:`HMC API` book.

        Raises:

          :exc:`~zhmcclient.HTTPError`
          :exc:`~zhmcclient.ParseError`
          :exc:`~zhmcclient.AuthError`
          :exc:`~zhmcclient.ConnectionError`
        """
        # pylint: disable=protected-access
        self.manager.session.post(self.uri, body=properties)
        is_rename = self.manager._name_prop in properties
        if is_rename:
            # Delete the old name from the cache
            self.manager._name_uri_cache.delete(self.name)
        self.update_properties_local(copy.deepcopy(properties))
        if is_rename:
            # Add the new name to the cache
            self.manager._name_uri_cache.update(self.name, self.uri)

1	# Copyright 2016-2021 IBM Corp. All Rights Reserved.
2	#
3	# Licensed under the Apache License, Version 2.0 (the "License");
4	# you may not use this file except in compliance with the License.
5	# You may obtain a copy of the License at
6	#
7	# http://www.apache.org/licenses/LICENSE-2.0
8	#
9	# Unless required by applicable law or agreed to in writing, software
10	# distributed under the License is distributed on an "AS IS" BASIS,
11	# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12	# See the License for the specific language governing permissions and
13	# limitations under the License.
14
15	"""	11✔
16	A :term:`Virtual Function` is a logical entity that provides a
17	:term:`Partition` with access to
18	:term:`Accelerator Adapters <Accelerator Adapter>`.
19
20	Virtual Function resources are contained in Partition resources.
21
22	Virtual Functions only exist in :term:`CPCs <CPC>` that are in DPM mode.
23	"""
24
25	from __future__ import absolute_import	11✔
26
27	import copy	11✔
28
29	from ._manager import BaseManager	11✔
30	from ._resource import BaseResource	11✔
31	from ._logging import logged_api_call	11✔
32	from ._utils import matches_filters, RC_VIRTUAL_FUNCTION	11✔
33
34	__all__ = ['VirtualFunctionManager', 'VirtualFunction']	11✔
35
36
37	class VirtualFunctionManager(BaseManager):	11✔
38	"""
39	Manager providing access to the
40	:term:`Virtual Functions <Virtual Function>` in a particular
41	:term:`Partition`.
42
43	Derived from :class:`~zhmcclient.BaseManager`; see there for common methods
44	and attributes.
45
46	Objects of this class are not directly created by the user; they are
47	accessible via the following instance variable of a
48	:class:`~zhmcclient.Partition` object (in DPM mode):
49
50	* :attr:`~zhmcclient.Partition.virtual_functions`
51	"""
52
53	def __init__(self, partition):	11✔
54	# This function should not go into the docs.
55	# Parameters:
56	# partition (:class:`~zhmcclient.Partition`):
57	# Partition defining the scope for this manager.
58	super(VirtualFunctionManager, self).__init__(	11✔
59	resource_class=VirtualFunction,
60	class_name=RC_VIRTUAL_FUNCTION,
61	session=partition.manager.session,
62	parent=partition,
63	base_uri='{}/virtual-functions'.format(partition.uri),
64	oid_prop='element-id',
65	uri_prop='element-uri',
66	name_prop='name',
67	query_props=[],
68	list_has_name=False)
69
70	@property	11✔
71	def partition(self):	5✔
72	"""
73	:class:`~zhmcclient.Partition`: :term:`Partition` defining the scope
74	for this manager.
75	"""
76	return self._parent	11✔
77
78	@logged_api_call	11✔
79	def list(self, full_properties=False, filter_args=None):	11✔
80	"""
81	List the Virtual Functions of this Partition.
82
83	Any resource property may be specified in a filter argument. For
84	details about filter arguments, see :ref:`Filtering`.
85
86	The listing of resources is handled in an optimized way:
87
88	* If this manager is enabled for :ref:`auto-updating`, a locally
89	maintained resource list is used (which is automatically updated via
90	inventory notifications from the HMC) and the provided filter
91	arguments are applied.
92
93	* Otherwise, if the filter arguments specify the resource name as a
94	single filter argument with a straight match string (i.e. without
95	regular expressions), an optimized lookup is performed based on a
96	locally maintained name-URI cache.
97
98	* Otherwise, the corresponding array property for this resource in the
99	parent object is used to list the resources, and the provided filter
100	arguments are applied.
101
102	Authorization requirements:
103
104	* Object-access permission to this Partition.
105
106	Parameters:
107
108	full_properties (bool):
109	Controls whether the full set of resource properties should be
110	retrieved, vs. only the short set as returned by the list
111	operation.
112
113	filter_args (dict):
114	Filter arguments that narrow the list of returned resources to
115	those that match the specified filter arguments. For details, see
116	:ref:`Filtering`.
117
118	`None` causes no filtering to happen, i.e. all resources are
119	returned.
120
121	Returns:
122
123	: A list of :class:`~zhmcclient.VirtualFunction` objects.
124
125	Raises:
126
127	:exc:`~zhmcclient.HTTPError`
128	:exc:`~zhmcclient.ParseError`
129	:exc:`~zhmcclient.AuthError`
130	:exc:`~zhmcclient.ConnectionError`
131	"""
132	resource_obj_list = []	11✔
133	if self.auto_update_enabled() and not self.auto_update_needs_pull():	11✔
NEW 134	for resource_obj in self.list_resources_local():	×
135	if matches_filters(resource_obj, filter_args):	×
136	resource_obj_list.append(resource_obj)	×
137	else:
138	uris = self.partition.get_property('virtual-function-uris')	11✔
139	if uris:	11✔
140	for uri in uris:	11✔
141
142	resource_obj = self.resource_class(	11✔
143	manager=self,
144	uri=uri,
145	name=None,
146	properties=None)
147
148	if matches_filters(resource_obj, filter_args):	11✔
149	resource_obj_list.append(resource_obj)	11✔
150	if full_properties:	11✔
151	resource_obj.pull_full_properties()	11✔
152
153	self.add_resources_local(resource_obj_list)	11✔
154
155	self._name_uri_cache.update_from(resource_obj_list)	11✔
156	return resource_obj_list	11✔
157
158	@logged_api_call	11✔
159	def create(self, properties):	5✔
160	"""
161	Create a Virtual Function in this Partition.
162
163	Authorization requirements:
164
165	* Object-access permission to this Partition.
166	* Object-access permission to the backing accelerator Adapter.
167	* Task permission for the "Partition Details" task.
168
169	Parameters:
170
171	properties (dict): Initial property values.
172	Allowable properties are defined in section 'Request body contents'
173	in section 'Create Virtual Function' in the :term:`HMC API` book.
174
175	Returns:
176
177	VirtualFunction:
178	The resource object for the new Virtual Function.
179	The object will have its 'element-uri' property set as returned by
180	the HMC, and will also have the input properties set.
181
182	Raises:
183
184	:exc:`~zhmcclient.HTTPError`
185	:exc:`~zhmcclient.ParseError`
186	:exc:`~zhmcclient.AuthError`
187	:exc:`~zhmcclient.ConnectionError`
188	"""
189	result = self.session.post(self.partition.uri + '/virtual-functions',	11✔
190	body=properties)
191	# There should not be overlaps, but just in case there are, the
192	# returned props should overwrite the input props:
193	props = copy.deepcopy(properties)	11✔
194	props.update(result)	11✔
195	name = props.get(self._name_prop, None)	11✔
196	uri = props[self._uri_prop]	11✔
197	vf = VirtualFunction(self, uri, name, props)	11✔
198	self._name_uri_cache.update(name, uri)	11✔
199	return vf	11✔
200
201
202	class VirtualFunction(BaseResource):	11✔
203	"""
204	Representation of a :term:`Virtual Function`.
205
206	Derived from :class:`~zhmcclient.BaseResource`; see there for common
207	methods and attributes.
208
209	For the properties of a Virtual Function, see section
210	'Data model - Virtual Function Element Object' in section
211	'Partition object' in the :term:`HMC API` book.
212
213	Objects of this class are not directly created by the user; they are
214	returned from creation or list functions on their manager object
215	(in this case, :class:`~zhmcclient.VirtualFunctionManager`).
216	"""
217
218	def __init__(self, manager, uri, name=None, properties=None):	11✔
219	# This function should not go into the docs.
220	# manager (:class:`~zhmcclient.VirtualFunctionManager`):
221	# Manager object for this resource object.
222	# uri (string):
223	# Canonical URI path of the resource.
224	# name (string):
225	# Name of the resource.
226	# properties (dict):
227	# Properties to be set for this resource object. May be `None` or
228	# empty.
229	assert isinstance(manager, VirtualFunctionManager), \	11✔
230	"VirtualFunction init: Expected manager type %s, got %s" % \
231	(VirtualFunctionManager, type(manager))
232	super(VirtualFunction, self).__init__(manager, uri, name, properties)	11✔
233
234	@logged_api_call	11✔
235	def delete(self):	5✔
236	"""
237	Delete this Virtual Function.
238
239	Authorization requirements:
240
241	* Object-access permission to the Partition of this Virtual Function.
242	* Task permission for the "Partition Details" task.
243
244	Raises:
245
246	:exc:`~zhmcclient.HTTPError`
247	:exc:`~zhmcclient.ParseError`
248	:exc:`~zhmcclient.AuthError`
249	:exc:`~zhmcclient.ConnectionError`
250	"""
251	# pylint: disable=protected-access
252	self.manager.session.delete(self._uri)	11✔
253	self.manager._name_uri_cache.delete(	11✔
254	self.get_properties_local(self.manager._name_prop, None))
255
256	parent_vf_uris = self.manager.parent.get_properties_local(	11✔
257	'virtual-function-uris')
258	if parent_vf_uris:	11✔
259	try:	11✔
260	parent_vf_uris.remove(self._uri)	11✔
261	except ValueError:	×
262	pass	×
263
264	@logged_api_call	11✔
265	def update_properties(self, properties):	5✔
266	"""
267	Update writeable properties of this Virtual Function.
268
269	This method serializes with other methods that access or change
270	properties on the same Python object.
271
272	Authorization requirements:
273
274	* Object-access permission to the Partition of this Virtual Function.
275	* When updating the "adapter-uri" property, object-access permission to
276	the Adapter identified in that URI.
277	* Task permission for the "Partition Details" task.
278
279	Parameters:
280
281	properties (dict): New values for the properties to be updated.
282	Properties not to be updated are omitted.
283	Allowable properties are the properties with qualifier (w) in
284	section 'Data model - Virtual Function element object' in the
285	:term:`HMC API` book.
286
287	Raises:
288
289	:exc:`~zhmcclient.HTTPError`
290	:exc:`~zhmcclient.ParseError`
291	:exc:`~zhmcclient.AuthError`
292	:exc:`~zhmcclient.ConnectionError`
293	"""
294	# pylint: disable=protected-access
295	self.manager.session.post(self.uri, body=properties)	11✔
296	is_rename = self.manager._name_prop in properties	11✔
297	if is_rename:	11✔
298	# Delete the old name from the cache
299	self.manager._name_uri_cache.delete(self.name)	×
300	self.update_properties_local(copy.deepcopy(properties))	11✔
301	if is_rename:	11✔
302	# Add the new name to the cache
303	self.manager._name_uri_cache.update(self.name, self.uri)	×

zhmcclient / python-zhmcclient / test-1604

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous