Metadata-Version: 2.3
Name: iaso-client
Version: 1.1.0
Summary: Python client library for interacting with IASO APIs
Keywords: iaso,api,client,sdk,python
Author: abdelrahman meroual
Author-email: abdelrahman meroual <g62496@etu.he2b.be>
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: requests>=2.32.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# iaso-client

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

## Installation

From the project root:

```bash
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.

```bash
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):
     ```bash
     cd bruno
     mklink .env ..\.env
     ```
   - **Mac / Linux**:
     ```bash
     cd bruno
     ln -s ../.env .env
     ```
### Quickstart

```python
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.

```python
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:

```python
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:

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

### Development

Run tests

```bash
uv run pytest
```

Run the main script

```bash
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:

```bash
uv run pre-commit install
```

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

```bash
uv run ruff format .
```

3. Check for logic errors and bad practices:

```Bash
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:

```bash
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.
