iaso-client 1.2.0

Python client library for interacting with IASO APIs

iaso-client

iaso-client is a Python client library for interacting with IASO APIs.

Installation

From the project root:

uv sync

Configuration

1. Copy .env.sample to .env at the project root, then fill in your credentials:

The IASO_BASE_URL can't be provided with a trailing slash at the end.

IASO_BASE_URL=https://your.iaso-server.com
IASO_LOGIN=your_login
IASO_PASSWORD=your_password

2. Create a symlink so Bruno can read the root .env file:
   • Windows (Run Command Prompt as Administrator):

     cd bruno
     mklink .env ..\.env
     

   • Mac / Linux:

     cd bruno
     ln -s ../.env .env
     

Quickstart

import os

from iaso_client import IasoClient

IASO_BASE_URL = os.getenv("IASO_BASE_URL")
IASO_LOGIN = os.getenv("IASO_LOGIN")
IASO_PASSWORD = os.getenv("IASO_PASSWORD")

client = IasoClient(base_url=IASO_BASE_URL)
client.login(IASO_LOGIN, IASO_PASSWORD)
page = client.org_unit_types_list_page(page=1, limit=10, project=975)
items = client.org_unit_types_list(search="District/Zone de sante - DIST")

print(page)
print(items)

Authentication

Use login() to authenticate and automatically store the bearer token for subsequent requests.

client.login("your_login", "your_password")

Current typed resources

The current typed client API supports:

Resource	Endpoint
Org unit types	/api/v2/orgunittypes/
Forms	/api/forms/
Form versions	/api/formversions/
Instances	/api/instances/
Instance files	/api/instances/attachments/, /api/instances/attachments_count/

Org unit types:

client.org_unit_types_list(...)
client.org_unit_types_list_page(...)
client.org_unit_types_retrieve(...)
client.org_unit_types_hierarchy(...)

Forms:

client.forms_list(...)
client.forms_list_page(...)
client.forms_retrieve(...)

Form versions:

client.form_versions_list(...)
client.form_versions_list_page(...)
client.form_versions_retrieve(...)

Instances:

client.instances_list(...)
client.instances_list_page(...)
client.instances_retrieve(...)

Instance files:

client.instance_files_list(...)
client.instance_files_list_page(...)
client.instance_files_count(...)

Instances:

client.instances_list(...)
client.instances_list_page(...)
client.instances_retrieve(...)

Pagination behavior

list() fetches and aggregates results across all pages.
list_page() returns a single paginated response.

HTTP request logging

You can enable request logging when creating the client:

import logging
from iaso_client import IasoClient

logging.basicConfig(level=logging.INFO)

client = IasoClient(
    base_url="https://your.iaso-server.com",
    enable_logging=True,
)

Example log output:

GET https://iaso-staging.bluesquare.org/api/v2/orgunittypes/ -> 200 [143.21 ms]

Development

Run tests

uv run pytest

Run the main script

uv run .\examples\main.py

Setup Pre-commit hooks

1. To ensure your code is properly formatted and linted before every commit, install the pre-commit hook:

uv run pre-commit install

2. Linting & Formatting (Ruff) Format the code (auto-fix styling issues):

uv run ruff format .

3. Check for logic errors and bad practices:

uv run ruff check .

Bruno

This repository also contains a Bruno collection for manually testing IASO API requests.

Configure the environment

Copy .env.sample to .env in the bruno folder, then fill in your credentials:

IASO_BASE_URL=https://your.iaso-server.com
IASO_LOGIN=your_login
IASO_PASSWORD=your_password

Run Bruno requests

1. Open Bruno.
2. In the top-left corner, open the collection and select the bruno directory from this repository.
3. In the top-right corner, select the iaso_client environment for the current collection.
4. Before running any protected request, run the login request first to authenticate.
5. Then select the request you want to run and click -> to execute it.