Python SDK

The LabTrace Python SDK provides a comprehensive interface for integrating blockchain-powered file management into Python applications, data science workflows, and backend services.

Installation

Install the SDK using pip:

# For local development (navigate to the sdk-py directory first)
cd sdk-py
pip install -e .

Quick Start

Authentication

from labtrace.client import Client

# Initialize client with username and password
client = Client(username="your-email@example.com", password="your-password")

# Or use environment variables
import os
client = Client(
    username=os.getenv("LABTRACE_USERNAME"),
    password=os.getenv("LABTRACE_PASSWORD")
)

Basic File Operations

# Upload a public file
result = client.upload_public_file(
    project_id="proj_12pip install requests PyJWT3456",
    content=open("path/to/research_data.pdf", "rb").read(),
    file_type="primary",
    name="research_data.pdf",
    label="research,data,2024"
)

print(f"Upload successful: {result}")

# Upload a private file
result = client.upload_private_file(
    project_id="proj_123456",
    content=open("path/to/sensitive_data.pdf", "rb").read(),
    file_type="primary",
    name="sensitive_data.pdf",
    label="sensitive,confidential"
)

# Get project files
files = client.get_public_project_files(project_id="proj_123456")
for file in files['records']:
    print(f"{file['name']} - {file['uploaded']}")

# Download a file
client.get_public_file(
    project_id="proj_123456",
    file_id="file_789012",
    save_path="./downloads/"
)

Client Configuration

# Set custom API base URL (optional)
import os
os.environ['LABTRACE_URL'] = 'https://api.labtrace.io'

client = Client(
    username="your-email@example.com",
    password="your-password"
)

# Get current user ID
user_id = client.get_user_id()
print(f"Current user: {user_id}")

File Management

Upload Files

# Upload a public file
result = client.upload_public_file(
    project_id="proj_123456",
    content=file_content,
    file_type="primary",
    name="document.pdf",
    label="research,important"
)

# Upload a private file
result = client.upload_private_file(
    project_id="proj_123456",
    content=file_content,
    file_type="primary",
    name="confidential.pdf",
    label="sensitive,private"
)

# Upload a secondary file with links
result = client.upload_public_file(
    project_id="proj_123456",
    content=file_content,
    file_type="secondary",
    name="analysis.pdf",
    label="analysis,results",
    primary_data="file_id_1,file_id_2",
    link_to_procedure="procedure_file_id",
    procedure_description="Statistical analysis of primary data"
)

# Upload from file path
with open("data.xlsx", "rb") as f:
    content = f.read()

result = client.upload_public_file(
    project_id="proj_123456",
    content=content,
    file_type="primary",
    name="data.xlsx",
    label="spreadsheet,data"
)

Download Files

# Download a public file
client.get_public_file(
    project_id="proj_123456",
    file_id="file_789012",
    save_path="./downloads/"
)

# Download file certificate
client.get_public_file_certificate(
    project_id="proj_123456",
    file_id="file_789012",
    save_path="./certificates/"
)

# Download private file certificate
client.get_private_file_certificate(
    project_id="proj_123456",
    file_id="file_789012",
    save_path="./certificates/"
)

List Files

# Get all public files in a project
files = client.get_public_project_files("proj_123456")

for file in files['records']:
    print(f"File: {file['name']}")
    print(f"Owner: {file['ownerName']} {file['ownerLastName']}")
    print(f"Type: {file['type']}")
    print(f"Status: {file['status']}")
    print(f"Uploaded: {file['uploaded']}")
    print("---")

# Get all private files in a project
files = client.get_private_project_files("proj_123456")

for file in files['records']:
    print(f"File: {file['name']}")
    print(f"Owner: {file['ownerName']} {file['ownerLastName']}")
    print(f"Status: {file['status']}")
    print("---")

Delete Files

# Delete a public file
result = client.delete_public_file(
    project_id="proj_123456",
    file_id="file_789012",
    user_id="user_123",
    reason="File no longer needed"
)

# Delete a private file
result = client.delete_private_file(
    project_id="proj_123456",
    file_id="file_789012",
    user_id="user_123",
    reason="Data has been processed"
)

Project Management

Get Projects

# Get all projects
projects = client.get_projects()

for project in projects['records']:
    print(f"Project: {project['name']}")
    print(f"Leader: {project['leaderFirstName']} {project['leaderLastName']}")
    print(f"Organisation: {project['organisation']}")
    print(f"Location: {project['location']}")
    print("---")

# Get specific project details
project = client.get_project("proj_123456")

print(f"Project Name: {project['name']}")
print(f"Area: {project['area']}")
print(f"Members: {project['members']['totalRecords']}")
print(f"Start Date: {project['startDate']}")
print(f"End Date: {project['endDate']}")

# Filter projects by criteria
projects = client.get_projects(
    project_name="Research",
    organisation="University",
    location="New York"
)

File Verification

Verify File Content

# Verify if file already exists
with open("document.pdf", "rb") as f:
    content = f.read()

verification = client.verify_file_content(
    content=content,
    name="document.pdf"
)

if verification['exists']:
    print(f"File already exists: {verification['fileName']}")
    print(f"In project: {verification['project']}")
else:
    print("File is unique, safe to upload")

Error Handling

Exception Handling

from labtrace import Client, ResponseException

try:
    client = Client(username="user@example.com", password="wrong-password")
except ResponseException as e:
    print(f"Authentication failed: {e.status_code} - {e.msg}")

try:
    files = client.get_public_project_files("invalid-project-id")
except ResponseException as e:
    if e.status_code == 404:
        print("Project not found")
    elif e.status_code == 403:
        print("Access denied")
    else:
        print(f"Error: {e.status_code} - {e.msg}")

Automatic Token Refresh

The SDK automatically handles JWT token expiration and refreshes tokens when needed:

client = Client(username="user@example.com", password="password")

# Token is automatically refreshed if expired
files = client.get_public_project_files("proj_123456")  # Works even if token expired

Advanced Features

Custom Request Headers

# The SDK handles authentication automatically
# Custom headers can be added by modifying the client internals
client = Client(username="user@example.com", password="password")

# All requests will include the proper Authorization header
response = client.get_projects()

Bulk Operations

# Upload multiple files
files_to_upload = [
    {"path": "file1.pdf", "label": "document1"},
    {"path": "file2.pdf", "label": "document2"},
    {"path": "file3.pdf", "label": "document3"}
]

for file_info in files_to_upload:
    with open(file_info["path"], "rb") as f:
        content = f.read()
    
    result = client.upload_public_file(
        project_id="proj_123456",
        content=content,
        file_type="primary",
        name=file_info["path"],
        label=file_info["label"]
    )
    print(f"Uploaded {file_info['path']}: {result}")

API Reference

Client Methods

Authentication

Client(username, password) - Initialize client with credentials
get_user_id() - Get current user ID from JWT token

Project Operations

get_projects(**filters) - Get all projects with optional filters
get_project(project_id) - Get specific project details

Public File Operations

upload_public_file(project_id, content, file_type, name, label, **kwargs) - Upload public file
get_public_project_files(project_id) - Get all public files in project
get_public_file(project_id, file_id, save_path) - Download public file
get_public_file_certificate(project_id, file_id, save_path, raw=False) - Download certificate
delete_public_file(project_id, file_id, user_id, reason) - Delete public file

Private File Operations

upload_private_file(project_id, content, file_type, name, label, **kwargs) - Upload private file
get_private_project_files(project_id) - Get all private files in project
get_private_file_certificate(project_id, file_id, save_path, raw=False) - Download certificate
delete_private_file(project_id, file_id, user_id, reason) - Delete private file

File Verification

verify_file_content(content, name) - Check if file already exists

Response Formats

All methods return Python dictionaries with the response data. The SDK automatically handles JSON parsing and error responses.

Environment Variables

The SDK supports the following environment variables:

LABTRACE_URL - API base URL (default: https://api.labtrace.io)
LABTRACE_USERNAME - Default username for authentication
LABTRACE_PASSWORD - Default password for authentication

Best Practices

Security

Store credentials securely (use environment variables or secure vaults)
Use different accounts for different environments (dev/staging/prod)
Regularly rotate passwords and update credentials

Performance

Reuse client instances when possible
Handle large files in chunks for better memory usage
Use appropriate file types (primary vs secondary) for organization

Error Handling

Always wrap SDK calls in try-catch blocks
Check response status codes for specific error handling
Implement retry logic for transient network errors

Examples

Complete Workflow Example

from labtrace import Client
import os

# Initialize client
client = Client(
    username=os.getenv("LABTRACE_USERNAME"),
    password=os.getenv("LABTRACE_PASSWORD")
)

# Get user's projects
projects = client.get_projects()
if not projects['records']:
    print("No projects found")
    exit()

project_id = projects['records'][0]['id']
print(f"Using project: {projects['records'][0]['name']}")

# Upload a file
with open("research_data.pdf", "rb") as f:
    content = f.read()

upload_result = client.upload_public_file(
    project_id=project_id,
    content=content,
    file_type="primary",
    name="research_data.pdf",
    label="research,data,analysis"
)

print(f"File uploaded successfully: {upload_result}")

# List all files
files = client.get_public_project_files(project_id)
print(f"Project has {files['totalRecords']} files")

# Download the first file
if files['records']:
    first_file = files['records'][0]
    client.get_public_file(
        project_id=project_id,
        file_id=first_file['id'],
        save_path="./downloads/"
    )
    print(f"Downloaded: {first_file['name']}")

​Python SDK

​Installation

​Quick Start

​Authentication

​Basic File Operations

​Client Configuration

​File Management

​Upload Files

​Download Files

​List Files

​Delete Files

​Project Management

​Get Projects

​File Verification

​Verify File Content

​Error Handling

​Exception Handling

​Automatic Token Refresh

​Advanced Features

​Custom Request Headers

​Bulk Operations

​API Reference

​Client Methods

​Authentication

​Project Operations

​Public File Operations

​Private File Operations

​File Verification

​Response Formats

​Environment Variables

​Best Practices

​Security

​Performance

​Error Handling

​Examples

​Complete Workflow Example

Python SDK

Installation

Quick Start

Authentication

Basic File Operations

Client Configuration

File Management

Upload Files

Download Files

List Files

Delete Files

Project Management

Get Projects

File Verification

Verify File Content

Error Handling

Exception Handling

Automatic Token Refresh

Advanced Features

Custom Request Headers

Bulk Operations

API Reference

Client Methods

Authentication

Project Operations

Public File Operations

Private File Operations

File Verification

Response Formats

Environment Variables

Best Practices

Security

Performance

Error Handling

Examples

Complete Workflow Example