orcatech-client 0.1.21

A Python API client for ORCATECH

ORCATECH Python API Client

A Python-based API client for interacting with the ORCATECH server API.

Overview

This library provides a programmatic interface to make HTTP requests to the ORCATECH API using specific endpoints and request methods. It includes support for authentication, data retrieval, and AWS integration capabilities.

Installation

pip install orcatech_client

Or install from source:

git clone <repository-url>
cd python
pip install -e .

Features

• API Client: Full-featured HTTP client for ORCATECH API endpoints
• Authentication: Bearer token authentication support
• Type Safety: Comprehensive schema types for observations, records, and data structures
• AWS Integration: Certificate management for AWS services
• Configuration: Environment-based configuration using .env files

Examples

Example 1: Get Study Homes (Helper Function)

The get_study_homes helper function retrieves all homes for a study with their sensors and hubs in a denormalized format:

from orcatech_client import APIClient, get_study_homes
from orcatech_client.http_client import HTTPClient

# Create client
client = APIClient(base_url="https://api.example.com")
client.headers["Authorization"] = "Bearer your-token"

# For self-signed certificates (testing only)
HTTPClient.verify_ssl = False

# Get all homes with their sensors and hubs
homes = get_study_homes(client, "https://api.example.com", study_id=6)

# Iterate through results
for home in homes:
    print(f"Home: {home.name} (ID: {home.id})")
    print(f"  Hubs: {len(home.hubs)}")
    print(f"  Sensors: {len(home.sensors)}")

    for hub in home.hubs:
        print(f"    Hub: {hub.name}")
        print(f"      Model: {hub.model.name} (Vendor: {hub.model.vendor.name})")
        print(f"      Serial: {hub.serial_number}")
        print(f"      MAC: {hub.mac_address}")

    for sensor in home.sensors:
        print(f"    Sensor: {sensor.name}")
        print(f"      Model: {sensor.model.name}")
        if sensor.area and sensor.area.name:
            print(f"      Area: {sensor.area.name}")

Example 2: AWS Certificate Management

from orcatech_client.aws.aws_cert_manager import AWSCredentialManager

# Configuration
HOST = "https://test.c4.orcatech.org:8080/api/public"
SCOPE = "study"
SCOPE_ID = "1"
ITEM_ID = 1
SCHEMA = "com.orcatech.inventory.item"
AUTH_TOKEN = "your-auth-token"

# Read certificate and key files
with open("aws_cert.pem", "r") as cert_file:
    cert_pem = cert_file.read()

with open("aws_key.pem", "r") as key_file:
    key_pem = key_file.read()

# Combine certificate and key
combined_pem = cert_pem.strip() + "\n" + key_pem.strip()

# Initialize manager
manager = AWSCredentialManager(
    host=HOST,
    scope=SCOPE,
    scope_id=SCOPE_ID,
    auth_token=AUTH_TOKEN,
    schema=SCHEMA,
    demo_mode=False,
    insecure_ssl=True  # Set to False in production
)

# Create new AWS credentials
manager.create_aws_credentials(item_id=ITEM_ID, combined_pem=combined_pem)

# Or update existing credentials
manager.update_aws_credentials(item_id=ITEM_ID, combined_pem=combined_pem)

Configuration

Create a .env file in your project root:

HOST_URL=https://your-api-host.com
AUTH_TOKEN=your-bearer-token

Certificate File Format

AWS certificates should be in PEM format:

• aws_cert.pem - The device certificate
• aws_key.pem - The private key

Important: Never commit .pem files to version control. They are automatically ignored by .gitignore.

Available Methods

• get_observation() - Retrieve specific observations
• get() - Generic GET requests
• post() - Generic POST requests
• authenticate() - Handle authentication

Requirements

• Python >= 3.6
• requests
• python-dotenv

Author

Kezman Saboi

License

MIT License