helmut4-client 2026.1b2

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="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="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

pytest -v tests/

To run integration tests against a test Helmut4 server, create a .env file in the project root with test server credentials:

export HELMUT4_BASE_URL="https://test-server"
export HELMUT4_USERNAME="username"
export HELMUT4_PASSWORD="password"

Then run integration tests:

source .env
pytest -v -m integration tests/

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

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