shaarpec 2.0.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. Roadmap
5. License
6. Contact

About The Project

This project is a Python client for convenient access to the SHAARPEC Analytics API, including automated authentication handling via device or code flow.

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 protected by the SHAARPEC Identity Server.

(back to top)

Built With

• 
• 

(back to top)

Getting Started

Prerequisites

The shaarpec client is used as a regular Python library. As always, it is a good idea to install a Python library in an isolated 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_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(...) and Client.with_code(...) class create clients that authenticate with the SHAARPEC IdentityServer with either device (not tied to an individual user, recommended) or code flow (tied to an individual user, for debugging and development).

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 class.

from shaarpec import Client

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

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

# Using a client with device flow.
client = Client.with_device(
        host="https://api.shaarpec.com/",
        auth={"host": "https://idp.shaarpec.com"}
    )

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 their documentation and 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 or post.

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.get("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},
 ...
]

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 for jupyter which can be disabled via client.run("path/to/task", progress_bar=False).

(back to top)

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)