Connection handler

src/README.md

@@ -142,7 +142,7 @@ query_result = hiro_client.query('ogit\\/_type:"ogit/MARS/Machine"')
 print(query_result)
 ```
 
-## Handler sharing
+## Token Handler sharing
 
 When you need to access multiple APIs of HIRO, share the TokenApiHandler between the API objects to avoid unnecessary
 requests for token- and version-information against HIRO. The TokenApiHandler will share a `requests.Session`, token-
@@ -168,6 +168,55 @@ hiro_app_client: HiroApp = HiroApp(
 )
 ```
 
+## Connection sharing
+
+You can also let TokenApiHandlers share a common connection session instead of letting each of them create their own.
+This might prove useful in a multithreading environment where tokens have to be set externally or change often (i.e.
+one token per user per thread). This also ensures, that version-requests happen only once when the connection is
+initialized.
+
+Use the parameters `pool_maxsize` and `pool_block` to further tune the connection parameters for parallel access to 
+the backend. See [requests Session Objects](https://docs.python-requests.org/en/latest/user/advanced/#session-objects)
+and Python documentation of `requests.adapters.HTTPAdapter` for more information.
+
+```python
+from hiro_graph_client import HiroGraph, HiroApp, FixedTokenApiHandler, GraphConnectionHandler
+
+connection_handler = GraphConnectionHandler(
+    root_url="https://core.arago.co",
+    pool_maxsize=200,                     # Optional: Max pool of cached connections for this connection session
+    pool_block=True,                      # Optional: Do not allow more parallel connections than pool_maxsize
+    client_name="Your Graph Client 0.0.1" # Optional: Will be used in the header 'User-Agent'
+)
+
+# Work with token of user 1
+
+user1_client: HiroGraph = HiroGraph(
+    api_handler=FixedTokenApiHandler(
+        connection_handler=connection_handler,
+        token='token user 1'
+    )
+)
+
+# Work with token of user 2 (Shared Token Handler)
+
+user2_api_handler = FixedTokenApiHandler(
+    connection_handler=connection_handler,
+    token='token user 2'
+)
+
+user2_client: HiroGraph = HiroGraph(
+    api_handler=user2_api_handler
+)
+
+hiro_app_client: HiroApp = HiroApp(
+    api_handler=user2_api_handler
+)
+
+```
+
+Everything written in [Token Handler Sharing](#token-handler-sharing) still applies.
+
 ## SSL Configuration
 
 SSL parameters are configured using the class `SSLConfig`. This class translates the parameters given to the required

src/hiro_graph_client/VERSION

@@ -1 +1 @@
-5.1.0
+5.2.0

src/hiro_graph_client/__init__.py

@@ -8,9 +8,9 @@
 from hiro_graph_client.authclient import HiroAuth
 from hiro_graph_client.authzclient import HiroAuthz
 from hiro_graph_client.client import HiroGraph
-from hiro_graph_client.clientlib import AbstractTokenApiHandler, AuthenticationTokenError, FixedTokenError, \
-    TokenUnauthorizedError, PasswordAuthTokenApiHandler, FixedTokenApiHandler, EnvironmentTokenApiHandler, \
-    SSLConfig
+from hiro_graph_client.clientlib import AbstractTokenApiHandler, GraphConnectionHandler, AuthenticationTokenError, \
+    FixedTokenError, TokenUnauthorizedError, PasswordAuthTokenApiHandler, FixedTokenApiHandler, \
+    EnvironmentTokenApiHandler, SSLConfig
 from hiro_graph_client.iamclient import HiroIam
 from hiro_graph_client.kiclient import HiroKi
 from hiro_graph_client.variablesclient import HiroVariables
@@ -19,7 +19,7 @@
 this_directory = path.abspath(path.dirname(__file__))
 
 __all__ = [
-    'HiroGraph', 'HiroAuth', 'HiroApp', 'HiroIam', 'HiroKi', 'HiroAuthz', 'HiroVariables',
+    'HiroGraph', 'HiroAuth', 'HiroApp', 'HiroIam', 'HiroKi', 'HiroAuthz', 'HiroVariables', 'GraphConnectionHandler',
     'AbstractTokenApiHandler', 'PasswordAuthTokenApiHandler', 'FixedTokenApiHandler', 'EnvironmentTokenApiHandler',
     'AuthenticationTokenError', 'FixedTokenError', 'TokenUnauthorizedError', '__version__',
     'SSLConfig'