Pull request #14: Feature/BAC-9434 token auth documentation

Merge in BAC/icometrix-sdk from feature/BAC-9434-token-auth-documentation to master

Squashed commit of the following:

commit 67846136496529042d4544e4ddacdd733bdd4040
Merge: f4e1c78 309752f
Author: Jeroen Pinxten <jeroen.pinxten@icometrix.com>
Date:   Tue Jul 23 16:23:51 2024 +0200

    Merge branch 'BAC-9434-token-auth-docs' into feature/BAC-9434-token-auth-documentation

    # Conflicts:
    #	docs/quickstart.rst

commit 309752f56e3622178d8c023caacbc41a7e0e2fd1
Author: Jeroen Pinxten <jeroen.pinxten@icometrix.com>
Date:   Tue Jul 23 16:16:52 2024 +0200

    BAC-9434: Improve TOKEN auth documentation for SDK

commit c4d4672f2447098accb78cfec0507e7bac1b2ca0
Author: Jeroen Pinxten <jeroen.pinxten@icometrix.com>
Date:   Mon Jul 1 08:45:02 2024 +0200

    BAC-9397: typo

commit a3986ce495da648283daad8513103ea4807afaaf
Author: Jeroen Pinxten <jeroen.pinxten@icometrix.com>
Date:   Fri Jun 28 16:12:44 2024 +0200

    BAC-9397: create processing abstraction functions + docs

docs/quickstart.rst

@@ -13,8 +13,8 @@ icometrix_sdk can be installed with `pip <https://pip.pypa.io>`_
   $ python -m pip install icometrix_sdk
 
 
-Authentication
----------------
+First steps
+-----------
 
 First things first, import the IcometrixApi:
 
@@ -23,23 +23,35 @@ First things first, import the IcometrixApi:
     from icometrix_sdk import IcometrixApi
 
 
-Next thing is to set the correct server region (icobrain-eu.icometrix.com, icobrain-us.icometrix.com...):
+Next thing is to set the correct server region (see regions below), you can do this by setting the `REGION` environment
+variable or, for illustrative purposes, using python code:
 
 .. code-block:: python
 
     from icometrix_sdk import IcometrixApi
 
-    SERVER = "https://icobrain-{region}.icometrix.com"
+    os.environ["REGION"] = "<region>"
+
+Authentication
+--------------
+
+By default the icometrix_sdk will try to auto detect the authentication method. The preferred way is using an API TOKEN.
+You can use this my setting the `TOKEN` environment variable or, for illustrative purposes, using python code:
+
+.. code-block:: python
+
+    from icometrix_sdk import IcometrixApi
+
+    os.environ["TOKEN"] = "<token>"
 
-By default the icometrix_sdk will try to auto detect the authentication method. But we can
-also force a method e.g. password authentication. To do this import the PasswordAuthentication
+We can also force a method e.g. password authentication. To do this import the PasswordAuthentication
 method and pass it as a parameter to the IcometrixApi.
 
 .. code-block:: python
 
     from icometrix_sdk import IcometrixApi
 
-    SERVER = "https://icobrain-{region}.icometrix.com"
+    os.environ["REGION"] = "<region>"
 
     auth = PasswordAuthentication("example@company.com", os.environ["PASSWORD"])
     client = RequestsApiClient(SERVER, auth)
@@ -65,6 +77,43 @@ You can use :meth:`~icometrix_sdk.resources.profile.Profile.who_am_i` function t
     print(me.email)
     # "example@company.com"
 
+Regions
+-------
+Icometrix hosts servers across various geographic regions including the European Union (EU),
+the United States (US), Australia (AU), and Canada (CA).
+
+You have the flexibility to select the region where your data will reside by specifying the desired region as
+the `REGION` environment variable. This ensures that your data is processed and stored in compliance with local
+data residency requirements.
+
+Projects
+--------
+
+A project serves as a top-level isolation entity within our system, typically representing a single hospital or
+medical facility. Each project is designed to prevent patient data collisions and ensure the segregation of
+configurations, billing, and other operational aspects.
+
+Projects are region-specific and are not replicated across different regions. This means you can have access to
+projects in one or multiple regions, depending on your needs, but each project will remain isolated within its designated region.
+
+To retrieve all your projects within the EU region, you can use the following example:
+
+.. code-block:: python
+
+    import os
+    from icometrix_sdk import IcometrixApi
+    from icometrix_sdk.utils.paginator import get_paginator
+
+    os.environ["REGION"] = "EU"
+
+    ico_api = IcometrixApi()
+
+    for projects in get_paginator(ico_api.projects.get_all, page_size=5):
+        for project in projects:
+            print(project.name)
+
+Processing data
+---------------
 
 This quickstart guide will help you get up and running with the `process_dicom_directory` function, which provides a
 high-level interface for processing DICOM files from a specified directory.
@@ -74,7 +123,7 @@ In this example:
 - Replace `"<project_uuid>"` with your project ID.
 - Replace `"<input_dir_path>"` with the path to your input directory containing DICOM files.
 - Replace `"<output_dir_path>"` with the path to your desired output directory.
-- Replace `"<report_type>"` with the appropriate report type for your use case.
+- Replace `"<report_type>"` with the appropriate report type for your use case. (e.g. icobrain_ms, icobrain_dm...)
 
 .. code-block:: python
 
@@ -93,7 +142,7 @@ In this example:
     logging.basicConfig(level=logging.INFO)
 
     if __name__ == '__main__':
-        os.environ["API_HOST"] = Region.<REGION>.value
+        os.environ["REGION"] = <REGION>
 
         # Initialize the icometrix API
         ico_api = IcometrixApi()

examples/get_all_projects.py

@@ -10,7 +10,8 @@
 
     os.environ["API_HOST"] = Region.EU.value
 
-    with IcometrixApi() as ico_api:
-        for projects in get_paginator(ico_api.projects.get_all, page_size=5):
-            for project in projects:
-                print(project.name)
+    ico_api = IcometrixApi()
+
+    for projects in get_paginator(ico_api.projects.get_all, page_size=5):
+        for project in projects:
+            print(project.name)