Add documentation for new client constructor

Author: hackermd

docs/package.rst

@@ -44,3 +44,10 @@ dicomweb\_client.log module
     :undoc-members:
     :show-inheritance:
 
+dicomweb\_client.session_utils module
++++++++++++++++++++++++++++++++++++++
+
+.. automodule:: dicomweb_client.session_utils
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/usage.rst

@@ -16,7 +16,7 @@ To interact with a publicly accessible server, you only need to provide the ``ur
 
     from dicomweb_client.api import DICOMwebClient
 
-    client = DICOMwebClient("https://mydicomwebserver.com")
+    client = DICOMwebClient(url="https://mydicomwebserver.com")
 
 
 Some servers expose the different DICOMweb RESTful services using different path prefixes.
@@ -41,25 +41,33 @@ To interact with servers requiring authentication, ``DICOMwebClient`` accepts ar
 
     from requests.auth import HTTPBasicAuth
     from dicomweb_client.api import DICOMwebClient
+    from dicomweb_client.session_utils import create_session_from_auth
+
+    auth=HTTPBasicAuth('myusername', 'mypassword')
+    session = create_session_from_auth(auth)
 
     client = DICOMwebClient(
         url="https://mydicomwebserver.com",
-        auth=HTTPBasicAuth('myusername', 'mypassword')
+        session=session
     )
 
 To simplify usage for ``HTTPBasicAuth``, you may also directly provide a username and password using the corresponding arguments.
 
 .. code-block:: python
 
     from dicomweb_client.api import DICOMwebClient
+    from dicomweb_client.session_utils import create_session_from_user_pass
+
+    session = create_session_from_user_pass(
+        username='myusername',
+        password='mypassword'
+    )
 
     client = DICOMwebClient(
         url="https://mydicomwebserver.com",
-        username="myusername",
-        password="mypassword"
+        session=session
     )
 
-
 To interact with servers supporting token-based authorization, you can provide the access token using the ``headers`` argument (the header will be included in every client request message).
 
 .. code-block:: python
@@ -78,13 +86,38 @@ To interact with servers requiring certificate-based authentication, you can pro
 .. code-block:: python
 
     from dicomweb_client.api import DICOMwebClient
+    from dicomweb_client.session_utils import (
+        create_session,
+        add_certs_to_session
+    )
 
-    client = DICOMwebClient(
-        url="https://mydicomwebserver.com",
+    session = create_session()
+    session = add_certs_to_session(
+        session=session,
         ca_bundle="/path/to/ca.crt",
         cert="/path/to/cert.pem"
     )
 
+    client = DICOMwebClient(url="https://mydicomwebserver.com")
+
+
+To interact with a server of the Google Healthcare API requiring OpenID Connect based authentication and authorization provide a session authenticated using the Google Cloud Platform (GCP) credentials.
+See `GCP documentation <https://cloud.google.com/docs/authentication/production>`_ for details.
+
+Note that GCP authentication requires installation of the package distribution with the ``gcp`` extra requirements: ``$ pip install dicomweb-client[gcp]``.
+
+.. code-block:: python
+
+    from dicomweb_client.api import DICOMwebClient
+    from dicomweb_client.session_utils import create_session_from_gcp_credentials
+
+    session = create_session_from_gcp_credentials()
+
+    client = DICOMwebClient(
+        url="https://mydicomwebserver.com",
+        session=session
+    )
+
 
 .. _storeinstances:
 

src/dicomweb_client/session_utils.py

@@ -7,56 +7,79 @@
 logger = logging.getLogger(__name__)
 
 
+def create_session() -> requests.Session:
+    '''Creates an unauthorized session.
+
+    Returns
+    -------
+    requests.Session
+        unauthorized session
+
+    '''
+    logger.debug('initialize HTTP session')
+    return requests.Session()
+
+
 def create_session_from_auth(
-        auth: [requests.auth.AuthBase]) -> requests.Session:
-    '''Creates a session from a gicen AuthBase object
+        auth: requests.auth.AuthBase
+    ) -> requests.Session:
+    '''Creates a session from a gicen AuthBase object.
+
     Parameters
     ----------
-    auth: requests.auth.AuthBase, optional
+    auth: requests.auth.AuthBase
         an implementation of `requests.auth.AuthBase` to be used for
         authentication with services
 
     Returns
     -------
     requests.Session
-        authenticated session
+        authorized session
 
     '''
     logger.debug('initialize HTTP session')
     session = requests.Session()
+    logger.debug('authenticate HTTP session')
     session.auth = auth
     return session
 
 
-def create_session_from_user_pass(username: [str],
-                                  password: [str]) -> requests.Session:
-    '''Creates a session from a given username and password
+def create_session_from_user_pass(
+        username: str,
+        password: str
+    ) -> requests.Session:
+    '''Creates a session from a given username and password.
+
     Parameters
     ----------
-    username: str,
+    username: str
         username for authentication with services
-    password: str,
+    password: str
         password for authentication with services
 
     Returns
     -------
     requests.Session
-        authenticated session
+        authorized session
 
     '''
     logger.debug('initialize HTTP session')
     session = requests.Session()
+    logger.debug('authenticate and authorize HTTP session')
     session.auth = (username, password)
     return session
 
 
-def add_certs_to_session(session: [requests.Session],
-                         ca_bundle: Optional[str] = None,
-                         cert: Optional[str] = None) -> requests.Session:
-    '''Adds ca_bundle and certificate to an existing session
+def add_certs_to_session(
+        session: requests.Session,
+        ca_bundle: Optional[str] = None,
+        cert: Optional[str] = None
+    ) -> requests.Session:
+    '''Adds CA bundle and certificate to an existing session.
+
     Parameters
     ----------
-    session: requests.Session,
+    session: requests.Session
         input session
     ca_bundle: str, optional
         path to CA bundle file
@@ -89,15 +112,17 @@ def add_certs_to_session(session: [requests.Session],
 
 
 def create_session_from_gcp_credentials(
-        google_credentials: [Any] = None) -> requests.Session:
-    '''Creates a session for Google Cloud Platform
+        google_credentials: Optional[Any] = None
+    ) -> requests.Session:
+    '''Creates an authorized session for Google Cloud Platform.
+
     Parameters
     ----------
     google_credentials: Any
         Google cloud credentials.
         (see https://cloud.google.com/docs/authentication/production
         for more information on Google cloud authentication).
-        If not set, will be initialized to google.auth.default()
+        If not set, will be initialized to ``google.auth.default()``
 
     Returns
     -------
@@ -110,12 +135,13 @@ def create_session_from_gcp_credentials(
         if google_credentials is None:
             import google.auth
             google_credentials, _ = google.auth.default(
-                scopes=['https://www.googleapis.com/auth/cloud-platform'])
+                scopes=['https://www.googleapis.com/auth/cloud-platform']
+            )
     except ImportError:
         raise ImportError(
             'The dicomweb-client package needs to be installed with the '
             '"gcp" extra requirements to support interaction with the '
             'Google Cloud Healthcare API: pip install dicomweb-client[gcp]'
         )
-    logger.debug('initialize Google AuthorizedSession')
+    logger.debug('initialize, authenticate and authorize HTTP session')
     return google_requests.AuthorizedSession(google_credentials)