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.
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 managementclient.groups- Group managementclient.projects- Project managementclient.assets- Asset managementclient.jobs- Job managementclient.streams- Workflow stream managementclient.metadata- Metadata managementclient.preferences- System preferencesclient.cronjobs- Scheduled tasksclient.languages- Language settingsclient.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.
- Fork the repository
- Create your feature branch
(
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.