diff --git a/doc/source/reference/usage.rst b/doc/source/reference/usage.rst index e59376bb..66ac5524 100644 --- a/doc/source/reference/usage.rst +++ b/doc/source/reference/usage.rst @@ -95,13 +95,7 @@ Creating and using a sushy system object # Refresh the system collection object # - # In order to reload a resource post its initialization it has to be marked - # as stale (i.e. invoking 'invalidate()') first and then 'refresh()' has to - # be called. This will only reload the resource w/o reloading/refreshing its - # sub-resources (lazy-refresh of sub-resources). - # Note that calling 'refresh()' only, i.e. w/o calling 'invalidate()' first, - # will be a no-op wrt resource reload in this case. - sys_col.invalidate() + # See below for more options on how to refresh resources. sys_col.refresh() @@ -115,14 +109,16 @@ Creating and using a sushy system object print(sys_inst.get_allowed_reset_system_values()) # Refresh the system object (with all its sub-resources) - # - # Alternatively, this is the other way of reloading a resource object: - # The resource can be reloaded w/o the need of marking it stale - # (i.e. not invoking 'invalidate()'). It is achieved when the "force" - # argument of 'refresh()' method is set to True. Do note that the - # sub-resources of the resource being reloaded will also get reloaded - # (greedy-refresh of sub-resources) when this mode is adopted. - sys_inst.refresh(force=True) + sys_inst.refresh() + + # Alternatively, you can only refresh the resource if it is stale by passing + # force=False: + sys_inst.refresh(force=False) + + # A resource can be marked stale by calling invalidate. Note that its + # subresources won't be marked as stale, and thus they won't be refreshed by + # a call to refresh(force=False) + sys_inst.invalidate() # Get the current power state print(sys_inst.power_state) diff --git a/releasenotes/notes/fix-refine-resource-refresh-86c21ce230967251.yaml b/releasenotes/notes/fix-refine-resource-refresh-86c21ce230967251.yaml index 9005ae55..f09eeac4 100644 --- a/releasenotes/notes/fix-refine-resource-refresh-86c21ce230967251.yaml +++ b/releasenotes/notes/fix-refine-resource-refresh-86c21ce230967251.yaml @@ -1,6 +1,6 @@ --- -fixes: +features: - | - The library now supports reloading of the attributes by invoking - ``refresh()`` method for nested resources in contrast to recreation. - Resources can now be marked stale by invoking ``invalidate()``. + New ``force`` argument to the ``refresh`` method on resources can be set to + ``False`` to prevent refreshing of resources that are not stale. Resources + can be marked as stale by calling a new ``invalidate`` method. diff --git a/sushy/resources/base.py b/sushy/resources/base.py index f04cf61f..43d053f8 100644 --- a/sushy/resources/base.py +++ b/sushy/resources/base.py @@ -244,7 +244,7 @@ class ResourceBase(object): # Hide the Field object behind the real value setattr(self, attr, field._load(self.json, self)) - def refresh(self, force=False): + def refresh(self, force=True): """Refresh the resource Freshly retrieves/fetches the resource attributes and invokes @@ -254,8 +254,9 @@ class ResourceBase(object): in ``_do_refresh()`` method, if needed. This method represents the template method in the paradigm of Template design pattern. - :param force: will force refresh the resource and its sub-resources, - if set to True. + :param force: if set to False, will only refresh if the resource is + marked as stale, otherwise neither it nor its subresources will + be refreshed. :raises: ResourceNotFoundError :raises: ConnectionError :raises: HTTPError diff --git a/sushy/tests/unit/resources/system/test_system.py b/sushy/tests/unit/resources/system/test_system.py index f5ed6b38..20007bf8 100644 --- a/sushy/tests/unit/resources/system/test_system.py +++ b/sushy/tests/unit/resources/system/test_system.py @@ -293,7 +293,7 @@ class SystemTestCase(base.TestCase): self.conn.get.return_value.json.return_value = json.loads(f.read()) self.sys_inst.invalidate() - self.sys_inst.refresh() + self.sys_inst.refresh(force=False) # | WHEN & THEN | self.assertIsNotNone(self.sys_inst._processors) diff --git a/sushy/tests/unit/resources/test_base.py b/sushy/tests/unit/resources/test_base.py index 9353cf7e..8f92ba7d 100644 --- a/sushy/tests/unit/resources/test_base.py +++ b/sushy/tests/unit/resources/test_base.py @@ -40,19 +40,19 @@ class ResourceBaseTestCase(base.TestCase): # refresh() is called in the constructor self.conn.reset_mock() - def test_refresh(self): - self.base_resource.refresh() + def test_refresh_no_force(self): + self.base_resource.refresh(force=False) self.conn.get.assert_not_called() def test_refresh_force(self): - self.base_resource.refresh(force=True) + self.base_resource.refresh() self.conn.get.assert_called_once_with(path='/Foo') def test_invalidate(self): self.base_resource.invalidate() self.conn.get.assert_not_called() - self.base_resource.refresh() + self.base_resource.refresh(force=False) self.conn.get.assert_called_once_with(path='/Foo') def test_invalidate_force_refresh(self):