Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Helmut4 Python Client

A Python client library for interacting with the Helmut4 API.

PyPI Version Python Versions License

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

Metadata

Release files for helmut4-client 2026.1b6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for helmut4-client 2026.1b6
File Size Uploaded Provenance Actions
helmut4_client-2026.1b6.tar.gz 35.0 kB Without provenance Details for helmut4_client-2026.1b6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for helmut4-client 2026.1b6
File Interpreter ABI Platform Actions
helmut4_client-2026.1b6-py3-none-any.whl Python 3 none any Details for helmut4_client-2026.1b6-py3-none-any.whl

Total release size: 56.5 kB

Release files / helmut4_client-2026.1b6.tar.gz

Download URL helmut4_client-2026.1b6.tar.gz
Size 35.0 kB
Tags Source
SHA-256 checksum
How to use checksums
2f85f2b03f5fbd7ce9d752cd1c7a28072dc54a2281403ad188164abbfbf7ccd6
BLAKE2b-256 checksum
How to use checksums
f6c2acca85580444cd8e97e9a43693682948bc01411c97805accae665656b5ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.8.0 pkginfo/1.12.1.2 readme-renderer/44.0 requests/2.32.5 requests-toolbelt/1.0.0 urllib3/2.6.3 tqdm/4.67.1 importlib-metadata/8.7.1 keyring/25.7.0 rfc3986/2.0.0 colorama/0.4.6 CPython/3.11.14

Release files / helmut4_client-2026.1b6-py3-none-any.whl

Download URL helmut4_client-2026.1b6-py3-none-any.whl
Size 21.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
443bec9820d3092035d8d1a81d2b1a4bf0a7f0ed4e1038881cfc2fabb17f5de7
BLAKE2b-256 checksum
How to use checksums
5fe954de4b3cfc272b08c4aeccf5bf80384e2f5e253c40bf2e3f06f16c86770b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.8.0 pkginfo/1.12.1.2 readme-renderer/44.0 requests/2.32.5 requests-toolbelt/1.0.0 urllib3/2.6.3 tqdm/4.67.1 importlib-metadata/8.7.1 keyring/25.7.0 rfc3986/2.0.0 colorama/0.4.6 CPython/3.11.14

Security for helmut4-client 2026.1b6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page