mig-dx-api 0.1.4

Dataset Exchange API Client Library

DX API Client Library

Welcome to the DX API Client Library! This library provides a convenient Python interface to interact with the DX API, allowing you to manage datasets, installations, and perform various operations with ease.

Table of Contents

• Features
• Installation
• Prerequisites
• Getting Started
  • Authentication
  • Initialization
• Usage
  • Who Am I
  • Managing Installations
    • Listing Installations
    • Accessing an Installation Context
  • Managing Datasets
    • Listing Datasets
    • Creating a Dataset
    • Uploading Data to a Dataset
    • Retrieving Records from a Dataset
• Asynchronous Usage
• Examples
• Contributing
• License

Features

• Authenticate with the DX API using JWT tokens.
• Manage installations and datasets.
• Upload and download data to and from datasets.
• Synchronous and asynchronous support.
• Context managers for handling authentication scopes.

Installation

You can install the library using pip:

pip install dx-api-client

Note: Replace dx-api-client with the actual package name when it's published.

Prerequisites

• Python 3.10 or higher.
• An application ID (app_id) and a corresponding private key in PEM format.
• DX API access credentials.

Getting Started

Authentication

The library uses JWT tokens for authentication. You need to provide your app_id and the path to your private key file when initializing the client.

Initialization

from dx_api_client import DX

# Initialize the client
dx = DX(app_id='your_app_id', private_key_path='path/to/private_key.pem')

Alternatively, you can set the environment variables DX_CONFIG_APP_ID and DX_CONFIG_PRIVATE_KEY_PATH:

export DX_CONFIG_APP_ID='your_app_id'
export DX_CONFIG_PRIVATE_KEY_PATH='path/to/private_key.pem'

And initialize the client without arguments:

dx = DX()

Usage

Who Am I

Retrieve information about the authenticated user:

user_info = dx.whoami()
print(user_info)

Managing Installations

Listing Installations

installations = dx.get_installations()
for installation in installations:
    print(installation.name)

Accessing an Installation Context

Use the installation context to perform operations related to a specific installation:

# Find an installation by name or ID
installation = dx.installations.find(install_id=1)

# Use the installation context
with dx.installation(installation) as ctx:
    # Perform operations within the context
    datasets = list(ctx.datasets)
    for dataset in datasets:
        print(dataset.name)

Or enter context with a lookup by name:

with dx.installation(install_id=1) as ctx:
    # Perform operations within the context
    datasets = list(ctx.datasets)
    for dataset in datasets:
        print(dataset.name)

Managing Datasets

Listing Datasets

with dx.installation(installation) as ctx:
    for dataset in ctx.datasets:
        print(dataset.name)

Creating a Dataset

from dx_api_client import DatasetSchema, SchemaProperty

# Define the schema
schema = DatasetSchema(
    properties=[
        SchemaProperty(name='id', type='string', required=True),
        SchemaProperty(name='value', type='number', required=True),
    ],
    primary_key=['id']
)

# Create the dataset
with dx.installation(installation) as ctx:
    new_dataset = ctx.datasets.create(
        name='My Dataset',
        description='A test dataset',
        schema=schema.model_dump()  # this can also be defined as a dictionary
    )

Uploading Data to a Dataset

data = [
    {'id': '1', 'value': 10},
    {'id': '2', 'value': 20},
]

with dx.installation(installation) as ctx:
    dataset_ops = ctx.datasets.find(name='My Dataset')
    dataset_ops.load(data, validate_records=True)  # validate_records=True will validate the records against the schema using Pydantic

Retrieving Records from a Dataset

with dx.installation(installation) as ctx:
    dataset_ops = ctx.datasets.find(name='My Dataset')
    records = dataset_ops.records()
    for record in records:
        print(record)

Asynchronous Usage

The library supports asynchronous operations using async/await.

import asyncio

async def main():
    dx = DX()
    async with dx.installation(installation) as ctx:
        async for dataset in ctx.datasets:
            print(dataset.name)

        dataset = await ctx.datasets.find(name='My Dataset')

        data = [
            {'id': '1', 'value': 10},
            {'id': '2', 'value': 20},
        ]

        await dataset.load(data)

        async for record in dataset.records():
            print(record)

asyncio.run(main())

Examples

Example: Loading Data from a File

with dx.installation(installation) as ctx:
    dataset = ctx.datasets.get(id='00000000-0000-0000-0000-000000000000')
    dataset.load_from_file('data.csv')

Example: Uploading Data from a URL

with dx.installation(installation) as ctx:
    dataset = ctx.datasets.find(name='My Dataset')
    dataset.load_from_url('https://example.com/data.csv')

---

Note: This README assumes that the package name is dx-api-client and that the code is properly packaged and available for installation via pip. Adjust the instructions accordingly based on the actual package name and installation method.