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 the type of the instance instead.

Author: mvdbeek

bioblend/_tests/TestGalaxyRateLimit.py

@@ -237,7 +237,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

@@ -15,6 +15,7 @@
 from types import TracebackType
 from typing import (
     Any,
+    TypeVar,
 )
 
 import requests
@@ -50,6 +51,9 @@
 # Number of connections kept in the pool when ``use_session`` is enabled.
 SESSION_POOL_MAXSIZE = 20
 
+# Used to preserve the subclass when a client is used as a context manager.
+GalaxyClientT = TypeVar("GalaxyClientT", bound="GalaxyClient")
+
 
 class _RateLimitRetry(Retry):
     """
@@ -295,7 +299,7 @@ def close(self) -> None:
             self._session.close()
             self._session = None
 
-    def __enter__(self) -> "GalaxyClient":
+    def __enter__(self: GalaxyClientT) -> GalaxyClientT:
         self.use_session = True
         return self
 

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