Improve the connection reuse example in the documentation

The example made a single request, which is exactly the case where reusing
a connection makes no difference. Make one request per history returned, and
quote strings with `"` as in the rest of the documentation.

Writing the example also showed that `__enter__()` was annotated as returning
`GalaxyClient`, so the subclass was lost and accessing e.g. `gi.histories` on
the result did not type check. Return `Self` instead, as done elsewhere in the
package.

Author: mvdbeek

bioblend/_tests/TestGalaxyRateLimit.py

@@ -17,6 +17,7 @@
 from typing import Any
 
 import pytest
+from typing_extensions import Self
 
 from bioblend import ConnectionError
 from bioblend.galaxy import GalaxyInstance
@@ -72,7 +73,7 @@ def log_message(self, format: str, *args: Any) -> None:
     def request_count(self) -> int:
         return len(self.requests)
 
-    def __enter__(self) -> "MockServer":
+    def __enter__(self) -> Self:
         self._thread = threading.Thread(target=self._httpd.serve_forever, daemon=True)
         self._thread.start()
         return self
@@ -237,7 +238,10 @@ def test_context_manager_enables_and_closes_the_session(self):
             with gi as entered:
                 assert entered is gi
                 used_inside = gi.use_session
-                assert gi.make_get_request(f"{gi.url}/libraries").status_code == 200
+                # Accessing a GalaxyInstance-only attribute also checks that
+                # entering the context manager preserves the subclass.
+                assert entered.libraries.gi is entered
+                assert entered.make_get_request(f"{gi.url}/libraries").status_code == 200
             assert used_inside is True
             assert gi.use_session is False
 

bioblend/galaxyclient.py

@@ -24,6 +24,7 @@
 from requests_toolbelt import MultipartEncoder
 from tusclient.storage.filestorage import FileStorage
 from tusclient.uploader.uploader import Uploader
+from typing_extensions import Self
 from urllib3 import BaseHTTPResponse
 from urllib3.connectionpool import ConnectionPool
 from urllib3.util.retry import Retry
@@ -295,11 +296,11 @@ def close(self) -> None:
             self._session.close()
             self._session = None
 
-    def __enter__(self) -> "GalaxyClient":
+    def __enter__(self) -> Self:
         self.use_session = True
         return self
 
-    def __exit__(self, *args: Any) -> None:
+    def __exit__(self, *args: object) -> None:
         self.close()
 
     @property

docs/index.rst

@@ -61,7 +61,7 @@ ToolShed) instance object::
 
     from bioblend.galaxy import GalaxyInstance
 
-    gi = GalaxyInstance(url='https://usegalaxy.org', key='your_api_key')
+    gi = GalaxyInstance(url="https://usegalaxy.org", key="your_api_key")
     # Give up after a total of 5 minutes of waiting.
     gi.max_total_retry_delay = 300.0
     # Never wait more than 1 minute before a single retry.
@@ -79,11 +79,13 @@ Reusing connections
 
 By default, each request opens a new connection. Scripts making many requests
 can reuse a single session instead, which avoids re-establishing a connection
-every time::
+every time. In the following example, one connection is used for the initial
+request and for the one made for each history returned by it::
 
-    with GalaxyInstance(url='https://usegalaxy.org', key='your_api_key') as gi:
+    with GalaxyInstance(url="https://usegalaxy.org", key="your_api_key") as gi:
         for history in gi.histories.get_histories():
-            print(history['name'])
+            datasets = gi.histories.show_history(history["id"], contents=True)
+            print(history["name"], len(datasets))
 
 Equivalently, ``gi.use_session = True`` enables it and ``gi.close()`` releases
 the connections. An instance with a session enabled should not be shared between