helmut4-client 2026.1b3

A Python client library for interacting with the Helmut4 API.

Helmut4 Python Client

A Python client library for interacting with the Helmut4 API.

Overview

This library provides a convenient way to interact with the Helmut4 API from Python. It covers all major components of the Helmut4 system:

• Users and Groups Management
• Projects Management
• Asset Management
• Job Management
• Workflow (Streams) Management
• Metadata Management
• Preferences Management
• Cronjobs
• Languages
• Licensing

Installation

pip install helmut4-client

For development:

pip install -e ".[dev]"

Basic Usage

from helmut4.client import Helmut4Client, Helmut4Error

# Initialize the client with credentials
client = Helmut4Client(
    base_url="https://helmut.example.com",
    username="admin",
    password="your-password"
)

# Or with an existing token
client = Helmut4Client(
    base_url="https://helmut.example.com",
    token="your-jwt-token"
)

# Get all users
users = client.users.get_all()

# Create a project
new_project = client.projects.create({
    "name": "My Project",
    "group": "Documentary",
    "category": "Production",
    "template": "Default",
    # Other required fields...
})

# Search for assets in a project
assets = client.assets.search(
    search_filter={"name": "Interview"},
    project_id=new_project["id"]
)

Module Overview

The client is organized into modules corresponding to the different components of Helmut4:

• client.users - User management
• client.groups - Group management
• client.projects - Project management
• client.assets - Asset management
• client.jobs - Job management
• client.streams - Workflow stream management
• client.metadata - Metadata management
• client.preferences - System preferences
• client.cronjobs - Scheduled tasks
• client.languages - Language settings
• client.licenses - License management

Each module provides methods for interacting with the corresponding API endpoints.

Authentication

The client supports both username/password authentication and token-based authentication:

# With username/password (automatically handles token acquisition)
client = Helmut4Client(
    base_url="https://helmut.example.com",
    username="admin",
    password="your-password"
)

# With token (if you already have a valid JWT token)
client = Helmut4Client(
    base_url="https://helmut.example.com",
    token="your-jwt-token"
)

When using username/password, the client automatically handles token acquisition and sets it in the session headers.

Error Handling

All API errors are raised as Helmut4Error exceptions, which include the status code and response data when available:

from helmut4.client import Helmut4Error

try:
    client.users.get_by_id("non-existent-id")
except Helmut4Error as e:
    print(f"Error {e.status_code}: {e.message}")
    print(f"Response data: {e.response}")

Example Use Cases

Managing Users

# List all users
all_users = client.users.get_all()

# Get a specific user
user = client.users.get_by_name("johndoe")

# Create a new user
new_user = client.users.create({
    "username": "janedoe",
    "password": "[SECURE_PASSWORD]",
    "displayname": "Jane Doe",
    "role": "User"
})

# Add user to a group
client.users.add_to_group(new_user["id"], "group-id")

# Change password
client.users.change_password(
    new_user["id"], "[OLD_PASSWORD]", "[NEW_PASSWORD]"
)

Managing Projects

# Search for projects
projects = client.projects.search({"name": "Documentary"})

# Create a new project
new_project = client.projects.create({
    "name": "Summer Campaign",
    "group": "Marketing",
    "category": "Advertising",
    "template": "Commercial"
})

# Lock a project
client.projects.set_status(new_project["id"], "LOCKED")

# Download project file
project_file = client.projects.download(new_project["id"])

Managing Assets

# Get assets from a project
assets = client.assets.get_by_project_id("project-id")

# Create a new asset
new_asset = client.assets.create({
    "name": "Interview Footage",
    "projectId": "project-id",
    "type": "VIDEO",
    "path": "/path/to/footage.mp4"
})

# Add metadata to an asset
client.assets.set_metadata(new_asset["id"], [
    {
        "key": "location",
        "value": "New York"
    },
    {
        "key": "interviewer",
        "value": "John Smith"
    }
])

Executing Workflows (Streams)

# Execute a stream
result = client.streams.execute(
    stream_event="CREATE_PROJECT",
    endpoint="FX",
    content_package={
        "projectId": "project-id",
        "customData": {"key": "value"}
    }
)

# Execute a custom stream
result = client.streams.execute_custom("stream-id", "project-id")

Development

Setting up the Development Environment

# Clone the repository
git clone https://bitbucket.org/chesa/helmut4-client/
cd helmut4-client

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

Running Tests

Unit Tests (no server required):

pytest -v tests/

Integration Tests (requires a running Helmut4 server):

Integration tests are skipped by default. Configure the Helmut4 server connection by setting environment variables, then run with RUN_INTEGRATION_TESTS=1.

Option 1: Use HELMUT4_BASE_URL (recommended):

export HELMUT4_BASE_URL="https://demo.acorncloud.io"
export HELMUT4_USERNAME="your-username"
export HELMUT4_PASSWORD="your-password"
RUN_INTEGRATION_TESTS=1 pytest -v -m integration tests/

Option 2: Use HELMUT4_HOST and HELMUT4_PORT:

The schema (http/https) is auto-detected based on port (443 = https):

export HELMUT4_HOST="demo.acorncloud.io"
export HELMUT4_PORT="443"
export HELMUT4_USERNAME="your-username"
export HELMUT4_PASSWORD="your-password"
RUN_INTEGRATION_TESTS=1 pytest -v -m integration tests/

Using .env file (recommended for development):

Create a .env file in the project root:

# Either approach works
export HELMUT4_BASE_URL="https://demo.acorncloud.io"
# OR
export HELMUT4_HOST="demo.acorncloud.io"
export HELMUT4_PORT="443"

export HELMUT4_USERNAME="your-username"
export HELMUT4_PASSWORD="your-password"
export RUN_INTEGRATION_TESTS="1"

Then source and run tests:

source .env
pytest -v tests/

The .env file is in .gitignore and will not be committed.

Environment Variables Reference:

Variable	Purpose	Default	Notes
HELMUT4_BASE_URL	Full server URL (takes precedence)	(none)	If set, HOST & PORT ignored
HELMUT4_HOST	Server hostname (used if BASE_URL not set)	192.168.0.211	Only used if BASE_URL unset
HELMUT4_PORT	Server port (used if BASE_URL not set)	80	Only used if BASE_URL unset
HELMUT4_USERNAME	Authentication username	admin	Required for auth
HELMUT4_PASSWORD	Authentication password	admin	Required for auth
RUN_INTEGRATION_TESTS	Enable integration tests (must be "1")	(unset/skipped)	Set to "1" to run tests

Code Formatting and Linting

# Optionally, remove unused import statements with pycln and/or alphabetically
# sort imports within logical sections using isort
pycln [--config pyproject.toml] src/
isort src/

# Format with black or yapf
black [--config pyproject.toml] src/
yapf --in-place --recursive [--print-modified] src/

# Lint with ruff and pylint
ruff [--config pyproject.toml] check [--fix] src/
pylint [--rcfile pyproject.toml] --recursive yes src/

Markdown Formatting

Prettier is disabled in pre-commit due to npm SSL certificate issues. Format markdown and YAML files manually before committing:

# Format markdown files (prose-wrapped at 72 chars)
prettier --parser markdown --prose-wrap always --print-width 72 \
  --tab-width 4 --write "**/*.md"

# Format YAML files
prettier --parser yaml --write "**/*.{yaml,yml}"

The pre-commit hooks will still run all Python linting/formatting checks automatically.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request