iaso-client 1.1.0__tar.gz

iaso_client-1.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+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.

iaso_client-1.1.0/README.md

@@ -0,0 +1,196 @@
+# 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.

iaso_client-1.1.0/pyproject.toml

@@ -0,0 +1,91 @@
+[project]
+name = "iaso-client"
+version = "1.1.0"
+description = "Python client library for interacting with IASO APIs"
+readme = "README.md"
+authors = [
+    { name = "abdelrahman meroual", email = "g62496@etu.he2b.be" }
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "requests>=2.32.0",
+
+]
+keywords = ["iaso", "api", "client", "sdk", "python"]
+
+[build-system]
+requires = ["uv_build>=0.10.12,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "requests-mock>=1.12.1",
+    "python-dotenv>=1.2.2",
+    "ruff>=0.15.8",
+    "pre-commit>=4.5.1",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["ALL"]
+
+ignore = [
+    # Official recommendation from Ruff to avoid conflicts
+    "W191",    # tab-indentation
+    "E111",    # indentation-with-invalid-multiple
+    "E114",    # indentation-with-invalid-multiple-comment
+    "E117",    # over-indented
+    "D206",    # docstring-tab-indentation
+    "D300",    # triple-single-quotes
+    "Q000",    # bad-quotes-inline-string
+    "Q001",    # bad-quotes-multiline-string
+    "Q002",    # bad-quotes-docstring
+    "Q003",    # avoidable-escaped-quote
+    "Q004",    # unnecessary-escaped-quote
+    "COM812",  # missing-trailing-comma
+    "COM819",  # prohibited-trailing-comma
+    "ISC001",  # single-line-implicit-string-concatenation
+    "ISC002",  # multi-line-implicit-string-concatenation
+
+    "D203", # incorrect-blank-line-before-class conflict with D211
+    "D213", # multi-line-summary-first-line conflict with D212
+
+
+    # We don't need documentation every time
+    "D103", # undocumented-public-function
+    "D100", # undocumented-public-module
+    "D101", # undocumented-public-class
+    "D102", # undocumented-public-method
+    "D104", # undocumented-public-package
+    "D107", # undocumented-public-init
+
+    "ANN401", # any-type
+
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = [
+    "S101",    # assert
+    "S105",    # hardcoded-password-string
+    "SLF001",  # private-member-access
+    "PLR2004", # magic-value-comparison
+]
+"examples/main.py" =[
+    "T201"  # print
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

iaso_client-1.1.0/src/iaso_client/__init__.py

@@ -0,0 +1,5 @@
+from .client import IasoClient
+
+__all__ = [
+    "IasoClient",
+]

iaso_client-1.1.0/src/iaso_client/base_resource.py

@@ -0,0 +1,95 @@
+from .exceptions import IasoValidationError
+from .pagination import Pagination
+from .params import QueryParams
+from .transport import IasoTransportClient
+
+
+class BaseResource:
+    def __init__(self, transport: IasoTransportClient, base_path: str) -> None:
+        self.transport = transport
+        self.base_path = base_path
+
+    def _build_params(
+        self,
+        *,
+        pagination: Pagination | None = None,
+        filters: QueryParams | None = None,
+    ) -> dict[str, object] | None:
+        params: dict[str, object] = {}
+
+        if pagination is not None:
+            params.update(pagination.to_params())
+
+        if filters is not None:
+            params.update(filters.to_params())
+
+        return params or None
+
+    def _get(
+        self,
+        path: str = "",
+        *,
+        pagination: Pagination | None = None,
+        filters: QueryParams | None = None,
+    ) -> object:
+        params = self._build_params(pagination=pagination, filters=filters)
+
+        try:
+            return self.transport.get(f"{self.base_path}{path}", params=params)
+
+        except IasoValidationError as exc:
+            if (
+                params
+                and "fields" in params
+                and exc.payload
+                and "fields" in exc.payload
+            ):
+                fields_value = params["fields"]
+                if isinstance(fields_value, list):
+                    fields_value = ", ".join(str(field) for field in fields_value)
+                msg = (
+                    f"Check value for 'fields': {fields_value}. "
+                    "Please check the available list values and in Swagger UI: "
+                    f"{self.transport.base_url}/swagger-ui/"
+                )
+                raise IasoValidationError(
+                    msg,
+                    status_code=exc.status_code,
+                    payload=exc.payload,
+                ) from exc
+            raise
+
+    def _fetch_all_pages(
+        self,
+        path: str = "",
+        *,
+        filters: QueryParams | None = None,
+        limit: int = 10,
+    ) -> list[dict[str, object]]:
+        """Fetch all paginated responses and return them as a list."""
+        if limit < 1:
+            msg = "'limit' must be greater than 0."
+            raise ValueError(msg)
+
+        page = 1
+        all_pages = []
+
+        while True:
+            response = self._get(
+                path,
+                pagination=Pagination(page=page, limit=limit),
+                filters=filters,
+            )
+
+            if not isinstance(response, dict):
+                msg = "Expected a paginated dict response."
+                raise TypeError(msg)
+
+            all_pages.append(response)
+
+            if not response.get("has_next"):
+                break
+
+            page += 1
+
+        return all_pages