Restore the default semantics of refresh()

It's fair to expect refresh() to actually refresh the resource, and that's
how it works in the previous release. This change flips the default
value of the newly introduced "force" argument to keep this behavior.

Change-Id: Ib50d7e52b76899bb6eb1ef1c5096bcb6f7a477a6

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)

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.

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

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)

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