imednet 0.5.0

Unofficial Python SDK for the iMednet clinical trials API

imednet

Unofficial Python SDK for the iMednet clinical trials API.

Full documentation: https://fderuiter.github.io/imednet-python-sdk/

This package simplifies integration with the iMednet REST API for clinical trial management. It provides typed endpoint wrappers, helper workflows and a CLI so researchers and developers can automate data extraction and submission without reimplementing HTTP logic.

Features

• Simple, consistent interface for API calls
• Automatic pagination across endpoints
• Pydantic models for requests and responses
• Workflow helpers for data extraction and mapping
• Pandas and CSV utilities
• Optional in-memory caching of study metadata
• Structured JSON logging and OpenTelemetry tracing
• Async client and command line interface
• Form Designer: Pythonic API for building and validating CRFs

---

Architecture

The SDK is organized around a core HTTP client layer, endpoint wrappers that model the iMednet API, workflow helpers that combine multiple endpoint calls, and a CLI built on top of those pieces.

graph TD
    CLI[CLI] --> |invokes| Workflows
    Workflows --> |coordinate| Endpoints
    Endpoints --> |use| Client["(HTTP Client)"]
    Client --> |requests| API

---

Installation

# PyPI release
pip install imednet

Optional Dependencies

To use data export features (SQL, Parquet, Excel) or integrations (Airflow), install the relevant extras:

# Install all export dependencies
pip install "imednet[pandas,sqlalchemy,pyarrow,excel]"

# Or pick specific ones
pip install "imednet[sqlalchemy]"  # For SQL export
pip install "imednet[pyarrow]"     # For Parquet export
pip install "imednet[excel]"       # For Excel export

# For Airflow integration (must be installed manually due to version conflicts)
pip install imednet apache-airflow apache-airflow-providers-amazon

Development Version

pip install git+https://github.com/fderuiter/imednet-python-sdk.git@main

---

Quick Start

Set your credentials as environment variables before running the examples:

export IMEDNET_API_KEY="your_api_key"
export IMEDNET_SECURITY_KEY="your_security_key"

Synchronous Example

from dotenv import load_dotenv

from imednet import ImednetSDK, load_config
from imednet.utils import configure_json_logging

# Optional: Configure structured JSON logging
configure_json_logging()

# Load credentials from .env file or environment variables
load_dotenv()
cfg = load_config()

with ImednetSDK(
    api_key=cfg.api_key,
    security_key=cfg.security_key,
    base_url=cfg.base_url,
) as sdk:
    # List all studies available to the user
    studies = sdk.studies.list()
    for study in studies:
        print(f"{study.study_name} ({study.study_key})")

Asynchronous Example

import asyncio

from dotenv import load_dotenv

from imednet import AsyncImednetSDK, load_config
from imednet.utils import configure_json_logging

async def main() -> None:
    # Optional: Configure structured JSON logging
    configure_json_logging()

    # Load credentials from .env file or environment variables
    load_dotenv()
    cfg = load_config()

    async with AsyncImednetSDK(
        api_key=cfg.api_key,
        security_key=cfg.security_key,
        base_url=cfg.base_url,
    ) as sdk:
        studies = await sdk.studies.async_list()
        for study in studies:
            print(f"{study.study_name} ({study.study_key})")

asyncio.run(main())

See docs/async_quick_start.rst for more details.

---

Configuration

The SDK and CLI read credentials from environment variables such as IMEDNET_API_KEY and IMEDNET_SECURITY_KEY. You can set these in your shell or use a .env file. Copy .env.example to .env to get started.

See configuration for the complete list of options. Use imednet.config.load_config() to access these values in your code.

---

CLI Usage

The package installs an imednet command with subcommands for studies, sites, subjects, records, jobs, queries and more. Use imednet --help to explore all options.

(Note: If you are running the project from source or a local clone, make sure to first install dependencies with poetry install. Then, prefix commands with poetry run, e.g., poetry run imednet --help)

Data Export

Example of exporting a subset of variables:

imednet export sql MY_STUDY table sqlite:///data.db --vars AGE,SEX --forms 10,20

When the connection string uses SQLite, the command splits the output into one table per form to avoid the 2000 column limit (in this case, the table argument is ignored). Pass --single-table to disable this behaviour and use the specified table name. See docs/cli.rst for full examples.

---

Documentation & Resources

• API Documentation: Full documentation is available at https://fderuiter.github.io/imednet-python-sdk/.
• Official iMednet API Docs: https://portal.prod.imednetapi.com/.
• Postman Collection: Download imednet.postman_collection.json and import it into Postman to explore and test the API endpoints.

---

Development & Contributing

Tech Stack

• Python 3.10–3.12
• httpx, pydantic, typer, tenacity, python-dotenv

Prerequisites

• Poetry (for dependency management)
• Make (optional, for building docs)

Project Structure

.
├── docs/       - Sphinx documentation
├── examples/   - Usage samples
├── imednet/    - SDK package
├── scripts/    - Helper scripts
└── tests/      - Unit and integration tests

Testing & Development

./scripts/setup.sh  # once
poetry run ruff check --fix .
poetry run black --check .
poetry run isort --check --profile black .
poetry run mypy src/imednet
poetry run pytest -q

After running tests, validate documentation builds cleanly (no warnings):

make docs

See AGENTS.md for full documentation guidelines.

Smoke-test workflow

The optional smoke.yml action runs the tests/live suite. It relies on repository secrets APIKEY and SECURITYKEY and sets IMEDNET_RUN_E2E. Use the workflow to confirm real API access on demand or via its nightly schedule. INFO-level log messages stream to the terminal during these runs, making it easier to debug failures.

Building & Publishing

python -m build
python -m twine upload dist/*

Pushing a Git tag like v0.1.4 triggers the GitHub Actions workflow that builds and publishes the package to PyPI.

Versioning & Changelog

This project follows Semantic Versioning. See GitHub Releases for release history.

Contributing

Contributions are welcome! See the contributing guide and CONTRIBUTING.md for full details.

---

Troubleshooting

Missing or invalid required environment variable(s) If you see an error like Error: IMEDNET_API_KEY and IMEDNET_SECURITY_KEY environment variables must be set. (CLI) or API key and security key are required (SDK), or an "Unauthorized" or "Forbidden" (403) API error, ensure you have set valid keys in your shell or in a .env file in the directory where you run the script (avoid using "dummy" keys). See Configuration.

ModuleNotFoundError when running the CLI locally If you are running the imednet CLI from source (e.g., poetry run imednet) and see a ModuleNotFoundError (such as No module named 'imednet'), ensure you have installed the project dependencies by running poetry install in the project root.

---

License

This project is licensed under the MIT license. See LICENSE for details.

---

Acknowledgements

Built with open source libraries including requests, httpx, pydantic and typer.