shaarpec 2.5.0

Client for SHAARPEC Analytics API.

Python client for SHAARPEC Analytics API.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Troubleshooting
5. Roadmap
6. License
7. Contact

About The Project

This is a Python client for simple access to the SHAARPEC Analytics API. Authentication is handled automatically via device flow, authorization code flow, or client credentials flow. Authentication can also be disabled if accessing a public Analytics API.

The SHAARPEC Analytics API provides calculations on the healthcare organization's resources, capacities, clinical outcomes, and much more. These results can be accessed via a standard REST API, which is usually protected by the SHAARPEC Identity Server.

(back to top)

Built With

• 
• 

(back to top)

Getting Started

Prerequisites

The shaarpec client is used as a standard Python library. It is always a good idea to install the library in a virtual environment.

Installation

1. Install the library into your virtual environment.

   pip install shaarpec
   

2. Store your credentials to the SHAARPEC IdentityServer in an .env file.

   $ cat .env
   OIDCISH_HOST="https://idp.example.com"
   OIDCISH_CLIENT_ID="my client id"
   OIDCISH_CLIENT_SECRET="my client secret"
   OIDCISH_AUDIENCE="shaarpec_api.full_access_scope"
   OIDCISH_SCOPE="openid shaarpec_api.full_access_scope offline_access"
   

(back to top)

Usage

This library provides a Client class to easily interact with the SHAARPEC Analytics API. The class methods Client.with_device(...), Client.with_code(...), and Client.with_credentials(...) create clients that authenticate with the SHAARPEC IdentityServer with either device flow (not tied to an individual user, recommended), code flow (tied to an individual user, for debugging and development), or credentials flow (non-interactive). There is also a class method Client.without_auth(...) that does not invoke the IDP server (but will only work if the Analytics API is public, otherwise give 401 Authentication invalid errors).

All API data is returned as httpx.Response objects.

Let's look at some code examples on how to get data from the Analytics API. First, import the client.

from shaarpec import Client

Next, use device flow or code flow to connect the client to the API with the Client.with_device(...), Client.with_code(...), and/or Client.with_credentials(...) class methods.

The credentials can either be stored in a .env file in the working directory (as explained in the Prerequisites section), provided as a path, or given directly as arguments to the auth dict.

# Create a client with device flow, give authentication details directly.
client = Client.with_device(
        host="https://api.shaarpec.com/",
        auth={
            "host": "https://idp.shaarpec.com",
            "client_id": ...,
            "client_secret": ...,
            "scope": ...,
            "audience": ...
        }
    )
# Create a client with device flow, read authentication details from .env file.
client = Client.with_device(host="https://api.shaarpec.com/", auth="path/to/.env")

Here host is the base URL to the Analytics API and auth is a dictionary with the login credentials. With device flow, the user needs to finish the sign-in by visiting a url provided by the IdentityServer. A message will be shown:

Visit https://idp.shaarpec.com/device?userCode=XXXXXXXXX to complete sign-in.

The user visits the website, verifies that the user code is correct and confirms the sign-in. After a few seconds, the client will confirm the sign-in:

SUCCESS: Authentication was successful. Took XX.Y seconds.

The client is now connected to the API. Visit the Analytics API Base URL to interactively test the endpoints and read the documentation about their path and query parameters. These parameters are used in the regular requests and httpx way with client.verb calls, where verb is either get, post, or run (see below).

GET and POST

The get and post verbs are supported in the standard way. For example (API responses are returned as httpx.Response objects):

client.get("terminology/allergy_type").json()

might return

{'419263009': 'Allergy to tree pollen',
 '420174000': 'Allergy to wheat',
 '425525006': 'Allergy to dairy product',
 '714035009': 'Allergy to soya',
 '419474003': 'Allergy to mould',
 '232347008': 'Dander (animal) allergy',
 '91934008': 'Allergy to nut',
 '417532002': 'Allergy to fish',
 '300913006': 'Shellfish allergy',
 '232350006': 'House dust mite allergy',
 '418689008': 'Allergy to grass pollen',
 '91935009': 'Allergy to peanuts',
 '91930004': 'Allergy to eggs',
 '300916003': 'Latex allergy',
 '424213003': 'Allergy to bee venom'}

or

client.post("population", conditions=["T78.2", "K81.0"])

might return

[{'patient_origin_id': '4c92f494-3c98-f8dd-1473-da9eb0196f6f',
    'age': '10-16',
    'is_alive': True,
    'gender': 'F',
    'deceased_year': 0},
 ...
]

You can send keyword arguments to the underlying httpx calls via the httpx_kwargs parameter, for example:

client.get("terminology/condition_type/codes", httpx_kwargs={"timeout": 120}).json()
# Sends API call with 120 second timeout)

Read about the available parameters in the httpx documentation.

Running tasks

SHAARPEC Analytics API supports long-running tasks by POST:ing to /service/path/to/endpoint, and then polling with GET to /service/tasks/{task_id}/status until the result becomes available at /service/tasks/{task_id}/results. There is a run function in the library that performs this pattern.

For example

task = client.run("population/conditions")

will return a task with the comorbidities in the entire population. A task is a Pydantic model with the following properties:

class Task(BaseModel):
    """A running task."""
    service: str
    task_id: str
    submitted_at: str
    status: str
    success: Optional[bool]
    progress: Optional[float]
    result: Optional[Any]
    error: Optional[Any]

As you can see, the success, progress, result and error are optional and updated automatically when available. The method comes with a progress bar which can be disabled via client.run("path/to/task", progress_bar=False). If you want to use the task result in a subsequent command, you can wait (blocking) for the result with the task.wait_for_result() method:

task = client.run("path/to/task")
print(f"The result is: {task.wait_for_result()}!")

(back to top)

Troubleshooting

Progress bar fails to render in (Dockerized) Jupyter Lab

Sometimes (especially in a Dockerized environment) the progress bar fails to render when running a task. This seems to be related to an issue in tqdm and its dependencies. A workaround seems to be to run:

jupyter lab build

in the environment (in a terminal inside the running Docker container) and refresh the browser. This requires a node.js installation first, e.g. per:

conda install -c conda-forge nodejs

See discussion for issue 1310 on the tqdm Github repo.

Roadmap

See the open issues for a full list of proposed features (and known issues).

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

SHAARPEC Support - [e-mail]

Project Link: https://github.com/SHAARPEC/shaarpec-python-client

(back to top)