Updates readme and examples with VitreaAuth Fixes #12

Author: sjoerdk

README.md

@@ -24,13 +24,12 @@ pip install dicomtrolley
 ### Basic example
 
 ```python
-# Create a logged-in http session
-session = VitreaConnection(
-    "https://server/login").log_in(user,password,realm)
+# Create a http session
+session = create_session("https://server/login",user,password,realm)
 
 # Use this session to create a trolley using MINT and WADO
 trolley = Trolley(searcher=Mint(session, "https://server/mint"),
-                  wado=Wado(session, "https://server/wado"]))
+                  wado=Wado(session, "https://server/wado"))
 
 # find some studies (using MINT)
 studies = trolley.find_studies(Query(PatientName='B*'))  
@@ -60,11 +59,11 @@ studies = trolley.find_studies(
 To include series and instance level information as well, use the `queryLevel` parameter
 
 ```python
-studies = trolley.find_studies(  # find studies series and instances
+studies = trolley.find_studies(      # find studies series and instances
     Query(studyInstanceID='B*', 
-          query_level=QueryLevels.INSTANCE)
+          query_level=QueryLevels.INSTANCE))
 
-a_series = studies.series[0]  # studies now contain series    
+a_series = studies.series[0]         # studies now contain series    
 an_instance = a_series.instances[0]  # and series contain instances
 ```
 

dicomtrolley/auth.py

@@ -1,14 +1,41 @@
 """Authentication mechanisms for DICOM servers"""
-
+import requests
 from requests.auth import AuthBase
 from requests.models import Request
 
 from dicomtrolley.exceptions import DICOMTrolleyError
 
 
+def create_session(login_url, user, password, realm="DefaultSystemRealm"):
+    """Returns a requests Session that logs in to Vitrea automatically as needed.
+
+    Facilitates single-line session creation. For readable code
+
+    Parameters
+    ----------
+    login_url: str
+        Call this url to log in
+    user: str
+        username
+    password: str
+        password
+    realm: str, optional
+        Vitrea realm to pass when logging in. Defaults to 'DefaultSystemRealm'
+    """
+    session = requests.Session()
+    session.auth = VitreaAuth(
+        login_url=login_url, user=user, password=password, realm=realm
+    )
+    return session
+
+
 class VitreaAuth(AuthBase):
     """Can log in to a server running Vitrea Connection 8.2.0.1
 
+    Usage
+    -----
+
+
     Raises
     ------
     DICOMTrolleyAuthError

dicomtrolley/servers.py

@@ -20,6 +20,10 @@ def __init__(self, login_url):
         login_url: str
             Full url of login method, including https://
         """
+        DeprecationWarning(
+            "VitreaConnection will be removed in future versions. "
+            "Use dicomtrolley.auth.VitreaAuth instead"
+        )
         self.login_url = login_url
 
     def log_in(self, user, password, realm):

examples/go_shopping.py

@@ -13,16 +13,18 @@
 """
 from os import environ
 
+from dicomtrolley.auth import create_session
 from dicomtrolley.core import Query
 from dicomtrolley.mint import Mint, QueryLevels
-from dicomtrolley.servers import VitreaConnection
 from dicomtrolley.trolley import Trolley
 from dicomtrolley.wado import Wado
 
-print("logging in")
-
-session = VitreaConnection(environ["LOGIN_URL"]).log_in(
-    environ["USER"], environ["PASSWORD"], environ["REALM"]
+print("Creating session")
+session = create_session(
+    environ["LOGIN_URL"],
+    environ["USER"],
+    environ["PASSWORD"],
+    environ["REALM"],
 )
 
 trolley = Trolley(

examples/go_shopping_rad69.py

@@ -13,15 +13,17 @@
 """
 from os import environ
 
+from dicomtrolley.auth import create_session
 from dicomtrolley.mint import Mint, MintQuery
 from dicomtrolley.rad69 import Rad69
-from dicomtrolley.servers import VitreaConnection
 from dicomtrolley.trolley import Trolley
 
-print("logging in")
-
-session = VitreaConnection(environ["LOGIN_URL"]).log_in(
-    environ["USER"], environ["PASSWORD"], environ["REALM"]
+print("Creating session")
+session = create_session(
+    environ["LOGIN_URL"],
+    environ["USER"],
+    environ["PASSWORD"],
+    environ["REALM"],
 )
 
 trolley = Trolley(

examples/search_for_studies_mint.py

@@ -13,18 +13,20 @@
 from datetime import datetime
 from os import environ
 
+from dicomtrolley.auth import create_session
 from dicomtrolley.mint import Mint, MintQuery, QueryLevels
-from dicomtrolley.servers import VitreaConnection
 
-# Log in to get an authenticated session
-session = VitreaConnection(environ["LOGIN_URL"]).log_in(
-    environ["USER"], environ["PASSWORD"], environ["REALM"]
+# Create auto-login session
+session = create_session(
+    environ["LOGIN_URL"],
+    environ["USER"],
+    environ["PASSWORD"],
+    environ["REALM"],
 )
 
 # Using mint for search
 mint = Mint(session, environ["MINT_URL"])
 
-
 print("Quick search for some studies")
 studies = mint.find_studies(
     MintQuery(PatientName="B*", include_fields=["PatientBirthDate"])

examples/use_wado_only.py

@@ -11,14 +11,16 @@
 """
 from os import environ
 
+from dicomtrolley.auth import create_session
 from dicomtrolley.core import InstanceReference
-from dicomtrolley.servers import VitreaConnection
 from dicomtrolley.wado import Wado
 
-
-# log in
-session = VitreaConnection(environ["LOGIN_URL"]).log_in(
-    environ["USER"], environ["PASSWORD"], environ["REALM"]
+# Create auto-login session
+session = create_session(
+    environ["LOGIN_URL"],
+    environ["USER"],
+    environ["PASSWORD"],
+    environ["REALM"],
 )
 
 wado = Wado(session, environ["WADO_URL"])

tests/test_storage.py

@@ -11,13 +11,13 @@
     [
         (
             quick_dataset(
-                StudyInstanceUID="A", SeriesInstanceUID="B", SOPInstanceUID="C"
+                StudyInstanceUID="1", SeriesInstanceUID="2", SOPInstanceUID="3"
             ),
-            "A/B/C",
+            "1/2/3",
         ),
         (
-            quick_dataset(StudyInstanceUID="A", SeriesInstanceUID="B"),
-            "A/B/unknown",
+            quick_dataset(StudyInstanceUID="1", SeriesInstanceUID="2"),
+            "1/2/unknown",
         ),
         (quick_dataset(), "unknown/unknown/unknown"),
     ],