pymenderio

Python client library for the Mender API.

Table of Contents

• pymenderio
  • Table of Contents
  • Features
  • Installation
  • Quick Start
    • Synchronous Usage
    • Asynchronous Usage
  • API Coverage
  • Major Functionality Blocks
    • Devices (client.devices)
    • Deployments (client.deployments)
    • Artifacts (client.artifacts)
    • Releases (client.releases)
    • Inventory (client.inventory)
      • Groups (client.inventory.groups)
      • Tags (client.inventory.tags)
    • Inventory Filters v2 (client.filters)
    • User Administration (client.useradm)
    • Tenant Administration (client.tenantadm)
    • Device Connect (client.deviceconnect)
    • Device Configure (client.deviceconfigure)
    • Device Monitor (client.devicemonitor)
    • IoT Manager (client.iot)
  • Authentication
    • Token File
    • mender-cli Compatible Config
    • Direct Token
    • Login
  • Examples
  • API Reference
  • Error Handling
  • Development
  • Release
  • License

Features

• Type-safe: Full type hints and Pydantic models for all API objects
• Async/Sync: Both synchronous and asynchronous clients
• Transparent pagination: All list operations return complete results
• Clean API: Pythonic interface mirroring the Mender CLI

Installation

pip install pymenderio

Or with Poetry:

poetry add pymenderio

Quick Start

Synchronous Usage

from pymenderio import MenderClient

# Using a token file (default: ~/.cache/mender/authtoken)
with MenderClient.from_token_file() as client:
    # List all accepted devices
    devices = client.devices.list(status="accepted")
    for device in devices:
        print(f"{device.id}: {device.identity}")

    # Create a deployment
    deployment_id = client.deployments.create(
        name="Production rollout",
        artifact_name="myapp-v2.0",
        devices=["device-id-1", "device-id-2"],
    )
    print(f"Created deployment: {deployment_id}")

# Using a token directly
with MenderClient(server="https://hosted.mender.io", token="...") as client:
    releases = client.releases.list()

Asynchronous Usage

import asyncio
from pymenderio import AsyncMenderClient

async def main():
    async with AsyncMenderClient.from_token_file() as client:
        # List devices
        devices = await client.devices.list(status="accepted")
        
        # Get deployment stats
        stats = await client.deployments.stats("deployment-id")
        print(f"Success: {stats.success}, Pending: {stats.pending}")

asyncio.run(main())

API Coverage

Every API method documented below is available in both variants:

• Sync: MenderClient method call
• Async: same method name on AsyncMenderClient, awaited

Example pattern:

# sync
from pymenderio import MenderClient

with MenderClient.from_mender_cli() as client:
        devices = client.devices.list(status="accepted")

# async
from pymenderio import AsyncMenderClient

async with AsyncMenderClient.from_mender_cli() as client:
        devices = await client.devices.list(status="accepted")

Function parity reference by API family:

• Devices methods (list, search, get, count, preauthorize, accept, reject, set_auth_status, get_auth_status, remove_auth_set, decommission, revoke_token, limits, license, auto_auth)
  • Sync form: client.devices.<method>(...)
  • Async form: await client.devices.<method>(...)
• Deployments methods (list, get, create, stats, stats_list, devices, log, try_log, abort, device_history, abort_device)
  • Sync form: client.deployments.<method>(...)
  • Async form: await client.deployments.<method>(...)
• Artifacts methods (list, get, upload, download, download_to_file, delete)
  • Sync form: client.artifacts.<method>(...)
  • Async form: await client.artifacts.<method>(...)
• Releases methods (list, get, delete, update, set_tags, list_tags, list_update_types, list_delta_jobs, get_delta_job)
  • Sync form: client.releases.<method>(...)
  • Async form: await client.releases.<method>(...)
• Inventory methods (list, get, count, get_device_group, set_device_group, clear_device_group)
  • Sync form: client.inventory.<method>(...)
  • Async form: await client.inventory.<method>(...)
• Inventory groups methods (list, devices, add_devices, remove_devices, delete)
  • Sync form: client.inventory.groups.<method>(...)
  • Async form: await client.inventory.groups.<method>(...)
• Inventory tags methods (list, set, delete)
  • Sync form: client.inventory.tags.<method>(...)
  • Async form: await client.inventory.tags.<method>(...)
• Inventory filters v2 methods (attributes, search, list, create, get, update, delete, execute, statistics)
  • Sync form: client.filters.<method>(...)
  • Async form: await client.filters.<method>(...)
• User administration methods (list_users, create_user, user_exists, get_user, update_user, delete_user, me, update_me, enable_2fa, disable_2fa, settings, set_settings, my_settings, set_my_settings, list_personal_access_tokens, create_personal_access_token, revoke_personal_access_token, list_roles, create_role, get_role, update_role, delete_role, list_permission_sets, create_permission_set, get_permission_set, update_permission_set, delete_permission_set)
  • Sync form: client.useradm.<method>(...)
  • Async form: await client.useradm.<method>(...)
• Tenant administration methods (list_tenants, create_tenant, me, delete_inactive_tenant, cancel_tenant, update_child_tenant, update_plan, init_tenant_removal, set_tenant_status, billing_products, billing_info, init_card_update, confirm_card_update, register_billing_profile, billing_profile, update_billing_profile, change_subscription, subscription, preview_invoice, stripe_secret, contact_support)
  • Sync form: client.tenantadm.<method>(...)
  • Async form: await client.tenantadm.<method>(...)
• Device connect methods (get_device, connect, check_update, send_inventory, playback, download, upload)
  • Sync form: client.deviceconnect.<method>(...)
  • Async form: await client.deviceconnect.<method>(...)
• Device configure methods (get, set, deploy)
  • Sync form: client.deviceconfigure.<method>(...)
  • Async form: await client.deviceconfigure.<method>(...)
• Device monitor methods (alerts, latest_alerts, config, set_alert_channel_status)
  • Sync form: client.devicemonitor.<method>(...)
  • Async form: await client.devicemonitor.<method>(...)
• IoT manager methods (list_integrations, register_integration, remove_integration, set_integration_credentials, unregister_device_integrations, device_states, device_state, set_device_state, events)
  • Sync form: client.iot.<method>(...)
  • Async form: await client.iot.<method>(...)

Authentication helper parity:

• Sync: login(...), login_and_save_session(...)
• Async: await async_login(...), await async_login_and_save_session(...)

Major Functionality Blocks

• Device Identity and Lifecycle Management:
  • Device listing/search, auth-set lifecycle, preauthorization, token revocation, auto-auth, decommission, and limits/license helpers.
• OTA and Release Operations:
  • Deployments lifecycle, stats and logs, release metadata/tag management, artifact operations, and server-side delta generation visibility.
• Inventory and Fleet Querying:
  • Inventory list/get/count, groups/tags management, and inventory v2 filters/search/statistics with saved filter workflows.
• Administrative and Tenant Operations:
  • User administration (users, PATs, settings, RBAC) and tenant administration (tenant lifecycle, billing/profile/subscription, support).
• Device Service Operations:
  • Device Connect, Device Configure, Device Monitor, and IoT Manager families for operational actions beyond OTA.
• Typed Ergonomics and Compatibility:
  • Pydantic models for typed payloads/queries, sync+async parity, and compatibility fallbacks for evolving backend query parameters.

Devices (client.devices)

Deployments (client.deployments)

Artifacts (client.artifacts)

Releases (client.releases)

Inventory (client.inventory)

Groups (client.inventory.groups)

Tags (client.inventory.tags)

Inventory Filters v2 (client.filters)

User Administration (client.useradm)

Tenant Administration (client.tenantadm)

Device Connect (client.deviceconnect)

Typed helper support:

• upload(..., request=UploadFileRequest(...)) for structured upload metadata and optional inline bytes content.

Device Configure (client.deviceconfigure)

Device Monitor (client.devicemonitor)

Typed helper support:

• alerts(..., query=AlertsQuery(...))
• latest_alerts(..., query=LatestAlertsQuery(...))

IoT Manager (client.iot)

Typed helper support:

• events(..., query=EventsQuery(...)) for typed integration_id, page, and per_page
• list_integrations(query=IntegrationsQuery(...)) for typed page and per_page

IntegrationsQuery(...) also supports additive client-side filters:

• provider
• scope
• description_contains

Compatibility fallback strategy for future backend query params:

• Use future_params={...} to pass through potential future server query params.
• If backend rejects unknown params with HTTP 400/422, pymenderio retries with stable params when allow_unsupported_params_fallback=True (default), then applies client-side typed filters.

Credential variants for client.iot.register_integration(...) and client.iot.set_integration_credentials(...):

• HTTP webhook credentials (type="http")
• Azure IoT Hub shared access secret (type="sas")
• AWS credentials (type="aws")

Typed helper support for integration registration:

• register_integration(IntegrationCreateRequest(provider=..., credentials=..., scopes=...))

IoT event payload parsing for client.iot.events(...):

• device-provisioned, device-decommissioned, device-status-changed map event.data to DeviceAuthEvent
• device-inventory-changed maps event.data to DeviceInventoryEvent

Typed helper support for state updates:

• set_device_state(..., DeviceStateUpdate(desired=...))

Authentication

Token File

By default, pymenderio reads the JWT token from the same cache path used by mender-cli: ~/.cache/mender/authtoken.

client = MenderClient.from_token_file()
# or specify a custom token file path
client = MenderClient.from_token_file("/path/to/authtoken")

mender-cli Compatible Config

pymenderio can also read mender-cli configuration from ~/.mender-clirc (JSON containing server and username) and combine it with the default token path:

client = MenderClient.from_mender_cli()

Direct Token

client = MenderClient(
    server="https://hosted.mender.io",
    token="your-jwt-token",
)

Login

from pymenderio.auth import login, write_token_file

token = login(
    server="https://hosted.mender.io",
    email="user@example.com",
    password="password",
    totp_code="123456",  # Optional 2FA code
)

# Optionally save for future use
write_token_file(token)

To persist server and username in mender-cli config format:

from pymenderio.auth import write_config_file

write_config_file(
    server="https://eu.hosted.mender.io",
    username="user@example.com",
)

For a single call that logs in and saves both config and token in mender-cli compatible locations:

from pymenderio.auth import login_and_save_session

token = login_and_save_session(
    server="https://eu.hosted.mender.io",
    email="user@example.com",
    password="password",
)

Examples

The repository includes runnable sync/async script pairs under examples.

Parity script pairs:

• Device list: examples/sync_list_devices.py and examples/async_list_devices.py
• Inventory list: examples/sync_list_inventory.py and examples/async_list_inventory.py
• Artifacts list: examples/sync_list_artifacts.py and examples/async_list_artifacts.py
• Releases list: examples/sync_list_releases.py and examples/async_list_releases.py
• Deployments list: examples/sync_list_deployments.py and examples/async_list_deployments.py
• Get resource by kind: examples/sync_get_resource.py and examples/async_get_resource.py
• Deployment details: examples/sync_deployment_details.py and examples/async_deployment_details.py
• Inventory filters v2: examples/sync_inventory_v2_filters.py and examples/async_inventory_v2_filters.py
• Deployment delta jobs: examples/sync_deployment_delta_jobs.py and examples/async_deployment_delta_jobs.py
• Device auth search/preauthorize: examples/sync_devauth_search_and_preauth.py and examples/async_devauth_search_and_preauth.py
• User administration basics: examples/sync_user_admin_basics.py and examples/async_user_admin_basics.py
• Tenant administration basics: examples/sync_tenant_admin_basics.py and examples/async_tenant_admin_basics.py
• Device services overview: examples/sync_device_services_overview.py and examples/async_device_services_overview.py
• Login and save session: examples/sync_login_and_save_session.py and examples/async_login_and_save_session.py
• Real API smoke (combined sync + async probe): examples/real_api_smoke.py

See EXAMPLES.md for:

• script-by-script usage
• live API validation results
• model compatibility notes

See API.md for the full public SDK reference:

• all public methods
• all public classes
• all public errors

API Reference

For a complete surface inventory, see API.md.

Error Handling

from pymenderio import MenderClient
from pymenderio.exceptions import (
    AuthenticationError,
    NotFoundError,
    ValidationError,
)

with MenderClient.from_token_file() as client:
    try:
        device = client.devices.get("nonexistent-id")
    except NotFoundError:
        print("Device not found")
    except AuthenticationError:
        print("Invalid or expired token")

Development

# Show available targets
make help

# Create local virtual environment and install dependencies
make venv

# Run tests in Docker
make test

# Lint and type-check in Docker
make lint
make typecheck

# Run all checks (lint, typecheck, test)
make check

# Remove local virtual environment
make venv-clean

If you prefer Poetry directly:

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Type checking
poetry run mypy src/

# Linting
poetry run ruff check src/

Release

GitHub Actions workflows in .github/workflows/release-testpypi.yml and .github/workflows/release-pypi.yml handle package publishing.

One-time setup:

• Configure a Trusted Publisher in TestPyPI for .github/workflows/release-testpypi.yml.
• Configure a Trusted Publisher in PyPI for .github/workflows/release-pypi.yml.

Release flow:

• Publish a prerelease to TestPyPI with a prerelease tag, for example:

git tag v0.1.1-rc1
git push origin v0.1.1-rc1

• Publish a final release to PyPI with a stable tag:

git tag v0.1.1
git push origin v0.1.1

The PyPI workflow validates that the tag version matches the package version in pyproject.toml.

License

MIT License - see LICENSE for details.