create new session if refresh is True (#939)

---------

Co-authored-by: Martin Durant <martin.durant@alumni.utoronto.ca>

Author: hutch3232

s3fs/core.py

@@ -480,9 +480,30 @@ def _prepare_config_kwargs(self):
 
     async def set_session(self, refresh=False, kwargs={}):
         """Establish S3 connection object.
+
+        This async method is called by any operation on an ``S3FileSystem`` instance.
+        The ``refresh=True`` argument is useful if new credentials have been created
+        and the instance needs to be reestablished. ``connect`` is a blocking
+        version of ``set_session``.
+
+        Parameters
+        ----------
+        refresh : bool (False)
+            If True, create a new session even if one already exists.
+        kwargs : dict
+            Currently unused.
+
         Returns
         -------
         Session to be closed later with await .close()
+
+        Examples
+        --------
+        >>> s3 = S3FileSystem(profile="<profile name>")  # doctest: +SKIP
+        # use in an async coroutine to assign the client object to a local variable
+        >>> await s3.set_session()  # doctest: +SKIP
+        # blocking version of set_session
+        >>> s3.connect(refresh=True)  # doctest: +SKIP
         """
         if self._s3 is not None and not refresh:
             return self._s3
@@ -522,7 +543,7 @@ async def set_session(self, refresh=False, kwargs={}):
             config_kwargs["signature_version"] = UNSIGNED
 
         conf = AioConfig(**config_kwargs)
-        if self.session is None:
+        if self.session is None or refresh:
             self.session = aiobotocore.session.AioSession(**self.kwargs)
 
         for parameters in (config_kwargs, self.kwargs, init_kwargs, client_kwargs):

s3fs/tests/test_s3fs.py

@@ -247,8 +247,11 @@ def test_user_session_is_preserved():
 
 
 def test_idempotent_connect(s3):
-    first = s3.s3
-    assert s3.connect(refresh=True) is not first
+    stale_s3 = s3.s3
+    stale_session = s3.session
+    s3.connect(refresh=True)
+    assert stale_s3 is not s3.s3
+    assert stale_session is not s3.session
 
 
 def test_multiple_objects(s3):