v10.2.0 (DEPRECATED)
Welcome to the balena python SDK documentation. This document aims to describe all the functions supported by the SDK, as well as showing examples of their expected usage.
Install the Balena SDK:
From Pip:
pip install balena-sdkFrom Source (In case, you want to test a development branch):
https://github.com/balena-io/balena-sdk-pythonGetting started:
>>> from balena import Balena
>>> balena = Balena()
>>> credentials = {'username':<your email>, 'password':<your password>}
>>> balena.auth.login(**credentials)
...If you feel something is missing, not clear or could be improved, please don't hesitate to open an issue in GitHub, we'll be happy to help.
Table of Contents
Models
This module implements all models for balena python SDK.
Application
This class implements application model for balena python SDK.
The returned objects properties are __metadata, actor, app_name, application_type, commit, depends_on__application, device_type, id, is_accessible_by_support_until__date, should_track_latest_release, slug, user.
Function: create(name, device_type, organization, app_type)
Create an application. This function only works if you log in using credentials or Auth Token.
Args:
Returns:
Raises:
Examples:
Function: disable_device_urls(app_id)
Disable device urls for all devices that belong to an application.
Args:
Returns:
Examples:
Function: disable_rolling_updates(app_id)
Disable Rolling update on application.
Args:
Returns:
Raises:
Examples:
Function: enable_device_urls(app_id)
Enable device urls for all devices that belong to an application
Args:
Returns:
Examples:
Function: enable_rolling_updates(app_id)
Enable Rolling update on application.
Args:
Returns:
Raises:
Examples:
Function: generate_provisioning_key(app_id)
Generate a device provisioning key for a specific application.
Args:
Returns:
Examples:
Function: get(name)
Get a single application.
Args:
Returns:
Raises:
Examples:
Function: get_all()
Get all applications (including collaborator applications).
Returns:
Examples:
Function: get_all_with_device_service_details(expand_release)
Get all applications (including collaborator applications) along with associated services' essential details.
Args:
Returns:
Function: get_by_id(app_id)
Get a single application by application id.
Args:
Returns:
Raises:
Examples:
Function: get_by_owner(name, owner)
Get a single application using the appname and the handle of the owning organization.
Args:
Returns:
Raises:
Examples:
Function: get_config(app_id, version)
Download application config.json.
Args:
Returns:
Raises:
Function: get_dashboard_url(app_id)
Get Dashboard URL for a specific application.
Args:
Raises:
Returns:
Examples:
Function: get_target_release_hash(app_id)
Get the hash of the current release for a specific application.
Args:
Returns:
Examples:
Function: get_with_device_service_details(name, expand_release)
Get a single application along with its associated services' essential details.
Args:
Returns:
Raises:
Examples:
Function: grant_support_access(app_id, expiry_timestamp)
Grant support access to an application until a specified time.
Args:
Returns:
Examples:
Function: has(name)
Check if an application exists.
Args:
Returns:
Examples:
Function: has_any()
Check if the user has any applications.
Returns:
Examples:
Function: is_tracking_latest_release(app_id)
Get whether the application is up to date and is tracking the latest release for updates.
Args:
Returns:
Examples:
Function: remove(name)
Remove application. This function only works if you log in using credentials or Auth Token.
Args:
Examples:
Function: restart(name)
Restart application. This function only works if you log in using credentials or Auth Token.
Args:
Raises:
Examples:
Function: revoke_support_access(app_id)
Revoke support access to an application.
Args:
Returns:
Examples:
Function: set_to_release(app_id, full_release_hash)
Set an application to a specific commit.
Args:
Returns:
Examples:
Function: track_latest_release(app_id)
Configure a specific application to track the latest available release.
Args:
Examples:
Function: will_track_new_releases(app_id)
Get whether the application is configured to receive updates whenever a new release is available.
Args:
Returns:
Examples:
ApiKey
This class implements user API key model for balena python SDK.
Function: create_api_key(name, description)
This function registers a new api key for the current user with the name given.
Args:
Returns:
Examples:
Function: get_all()
This function gets all API keys.
Returns:
Examples:
Function: revoke(id)
This function revokes an API key.
Args:
Examples:
Function: update(id, api_key_info)
This function updates details of an API key.
Args:
Examples:
Config
This class implements configuration model for balena python SDK.
Attributes:
Function: get_all()
Get all configuration.
Returns:
Examples:
Function: get_device_types()
Get device types configuration.
Returns:
Examples:
ConfigVariable
This class is a wrapper for config variable models.
ApplicationConfigVariable
This class implements application config variable model for balena python SDK.
Function: create(app_id, config_var_name, value)
Create an application config variable.
Args:
Returns:
Examples:
Function: get_all(app_id)
Get all application config variables belong to an application.
Args:
Returns:
Examples:
Function: remove(var_id)
Remove a application config environment variable.
Args:
Examples:
Function: update(var_id, value)
Update an application config variable.
Args:
Examples:
DeviceConfigVariable
This class implements device config variable model for balena python SDK.
Function: create(uuid, config_var_name, value)
Create a device config variable.
Args:
Returns:
Examples:
Function: get_all(uuid)
Get all device config variables belong to a device.
Args:
Returns:
Examples:
Function: get_all_by_application(app_id)
Get all device config variables by application.
Args:
Returns:
Examples:
Function: remove(var_id)
Remove a device config environment variable.
Args:
Examples:
Function: update(var_id, value)
Update a device config variable.
Args:
Examples:
Device
This class implements device model for balena python SDK.
Due to API changes, the returned Device object schema has changed. Here are the formats of the old and new returned objects.
The old returned object's properties: __metadata, actor, application, build, commit, created_at, custom_latitude, custom_longitude, device, device_type, download_progress, id, ip_address, is_connected_to_vpn, is_online, is_web_accessible, last_connectivity_event, last_vpn_event, latitude, local_id, location, lock_expiry_date, logs_channel, longitude, name, note, os_variant, os_version, provisioning_progress, provisioning_state, public_address, service_instance, status, supervisor_release, supervisor_version, support_expiry_date, user, uuid, vpn_address.
The new returned object's properties (since python SDK v2.0.0): __metadata, actor, belongs_to__application, belongs_to__user, created_at, custom_latitude, custom_longitude, device_type, download_progress, id, ip_address, is_accessible_by_support_until__date, is_connected_to_vpn, is_locked_until__date, is_managed_by__device, is_managed_by__service_instance, is_on__commit, is_online, is_web_accessible, last_connectivity_event, last_vpn_event, latitude, local_id, location, logs_channel, longitude, name, note, os_variant, os_version, provisioning_progress, provisioning_state, public_address, should_be_managed_by__supervisor_release, should_be_running__build, status, supervisor_version, uuid, vpn_address.
Function: disable_device_url(uuid)
Disable device url for a device.
Args:
Raises:
Examples:
Function: disable_local_mode(uuid)
Disable local mode.
Args:
Returns:
Examples:
Function: disable_lock_override(uuid)
Disable lock override.
Args:
Raises:
Function: enable_device_url(uuid)
Enable device url for a device.
Args:
Raises:
Examples:
Function: enable_local_mode(uuid)
Enable local mode.
Args:
Returns:
Examples:
Raises:
Function: enable_lock_override(uuid)
Enable lock override.
Args:
Raises:
Function: generate_device_key(uuid)
Generate a device key.
Args:
Raises:
Examples:
Function: generate_uuid()
Generate a random device UUID.
Returns:
Examples:
Function: get(uuid)
Get a single device by device uuid.
Args:
Returns:
Raises:
Examples:
Function: get_all()
Get all devices.
Returns:
Examples:
Function: get_all_by_application(name)
Get devices by application name.
Args:
Returns:
Examples:
Function: get_all_by_application_id(appid)
Get devices by application name.
Args:
Returns:
Examples:
Function: get_application_name(uuid)
Get application name by device uuid.
Args:
Returns:
Raises:
Function: get_by_name(name)
Get devices by device name.
Args:
Returns:
Examples:
Function: get_dashboard_url(uuid)
Get balena Dashboard URL for a specific device.
Args:
Examples:
Function: get_device_slug(device_type_name)
Get device slug.
Args:
Returns:
Raises:
Examples:
Function: get_device_url(uuid)
Get a device url for a device.
Args:
Raises:
Examples:
Function: get_display_name(device_type_slug)
Get display name for a device.
Args:
Returns:
Raises:
Examples:
Function: get_local_ip_address(uuid)
Get the local IP addresses of a device.
Args:
Returns:
Raises:
Function: get_local_mode_support(uuid)
Returns whether local mode is supported along with a message describing the reason why local mode is not supported.
Args:
Returns:
Examples:
Function: get_mac_address(uuid)
Get the MAC addresses of a device.
Args:
Returns:
Raises:
Function: get_manifest_by_application(app_name)
Get a device manifest by application name.
Args:
Returns:
Function: get_manifest_by_slug(slug)
Get a device manifest by slug.
Args:
Returns:
Raises:
Function: get_metrics(uuid)
Get the metrics related information for a device.
Args:
Returns:
Raises:
Function: get_name(uuid)
Get device name by device uuid.
Args:
Returns:
Raises:
Function: get_os_update_status(uuid)
Args:
Returns:
Examples:
Function: get_status(uuid)
Get the status of a device.
Args:
Raises:
Returns:
Examples:
Function: get_supervisor_state(uuid)
Get the supervisor state on a device
Args:
Returns:
Examples:
Function: get_supervisor_target_state(uuid)
Get the supervisor target state on a device
Args:
Returns:
Examples:
Function: get_supported_device_types()
Get device slug.
Returns:
Function: get_with_service_details(uuid, expand_release)
Get a single device along with its associated services' essential details.
Args:
Returns:
Raises:
Examples:
Function: grant_support_access(uuid, expiry_timestamp)
Grant support access to a device until a specified time.
Args:
Returns:
Examples:
Function: has(uuid)
Check if a device exists.
Args:
Returns:
Function: has_device_url(uuid)
Check if a device is web accessible with device urls
Args:
Raises:
Examples:
Function: has_lock_override(uuid)
Check if a device has the lock override enabled.
Args:
Returns:
Raises:
Function: identify(uuid)
Identify device. This function only works if you log in using credentials or Auth Token.
Args:
Examples:
Function: is_in_local_mode(uuid)
Check if local mode is enabled on the device.
Args:
Returns:
Examples:
Function: is_online(uuid)
Check if a device is online.
Args:
Returns:
Raises:
Function: is_tracking_application_release(uuid)
Get whether the device is configured to track the current application release.
Args:
Returns:
Raises:
Function: move(uuid, app_name)
Move a device to another application.
Args:
Raises:
Examples:
Function: note(uuid, note)
Note a device.
Args:
Raises:
Examples:
Function: register(app_id, uuid)
Register a new device with a balena application. This function only works if you log in using credentials or Auth Token.
Args:
Returns:
Examples:
Function: remove(uuid)
Remove a device. This function only works if you log in using credentials or Auth Token.
Args:
Function: rename(uuid, new_name)
Rename a device.
Args:
Raises:
Examples:
Function: restart(uuid)
Restart a user application container on device. This function only works if you log in using credentials or Auth Token.
Args:
Raises:
Examples:
Function: revoke_support_access(uuid)
Revoke support access to a device.
Args:
Returns:
Examples:
Function: set_custom_location(uuid, location)
Set a custom location for a device.
Args:
Raises:
Examples:
Function: set_to_release(uuid, commit_id)
Set device to a specific release. Set an empty commit_id will restore rolling releases to the device.
Args:
Returns:
Examples:
Function: set_to_release_by_id(uuid, release_id)
Set device to a specific release by release id (please notice that release id is not the commit hash on balena dashboard). Remove release_id will restore rolling releases to the device.
Args:
Returns:
Examples:
Function: start_os_update(uuid, target_os_version)
Start an OS update on a device.
Args:
Returns:
Raises:
Examples:
Function: track_application_release(uuid)
Configure a specific device to track the current application release.
Args:
Raises:
Function: unset_custom_location(uuid)
clear custom location for a device.
Args:
Raises:
Examples:
DeviceOs
This class implements device os model for balena python SDK.
Function: download(raw)
Download an OS image. This function only works if you log in using credentials or Auth Token.
Args:
Returns:
Notes:
Examples:
Function: download_unconfigured_image(device_type, version, raw)
Download an unconfigured OS image.
Args:
Returns:
Notes:
Examples:
Function: get_config(app_id, options)
Get an application config.json.
Args:
Returns:
Function: get_device_os_semver_with_variant(os_version, os_variant)
Get current device os semver with variant.
Args:
Examples:
Function: get_supported_versions(device_type)
Get OS supported versions.
Args:
Returns:
Function: is_architecture_compatible_with(os_architecture, application_architecture)
Returns whether the specified OS architecture is compatible with the target architecture.
Args:
Returns:
Function: parse_params()
Validate parameters for downloading device OS image.
Args:
Returns:
Raises:
EnvironmentVariable
This class is a wrapper for environment variable models.
ApplicationEnvVariable
This class implements application environment variable model for balena python SDK.
Attributes:
Function: create(app_id, env_var_name, value)
Create an environment variable for application.
Args:
Returns:
Examples:
Function: get_all(app_id)
Get all environment variables by application.
Args:
Returns:
Examples:
Function: is_system_variable(variable)
Check if a variable is system specific.
Args:
Returns:
Examples:
Function: remove(var_id)
Remove application environment variable.
Args:
Examples:
Function: update(var_id, value)
Update an environment variable value for application.
Args:
Examples:
ServiceEnvVariable
This class implements service environment variable model for balena python SDK.
Function: create(app_id, service_name, env_var_name, value)
Create a service environment variable for application.
Args:
Returns:
Examples:
Function: get_all_by_application(app_id)
Get all service environment variables by application.
Args:
Returns:
Examples:
Function: remove(var_id)
Remove service environment variable.
Args:
Examples:
Function: update(var_id, value)
Update a service environment variable value for application.
Args:
Examples:
DeviceEnvVariable
This class implements device environment variable model for balena python SDK.
Function: create(uuid, env_var_name, value)
Create a device environment variable.
Args:
Returns:
Examples:
Function: get_all(uuid)
Get all device environment variables.
Args:
Returns:
Examples:
Function: get_all_by_application(app_id)
Get all device environment variables for an application.
Args:
Returns:
Examples:
Function: remove(var_id)
Remove a device environment variable.
Args:
Examples:
Function: update(var_id, value)
Update a device environment variable.
Args:
Examples:
DeviceServiceEnvVariable
This class implements device service variable model for balena python SDK.
Function: create(uuid, service_name, env_var_name, value)
Create a device service environment variable.
Args:
Returns:
Examples:
Function: get_all(uuid)
Get all device service environment variables belong to a device.
Args:
Returns:
Examples:
Function: get_all_by_application(app_id)
Get all device service environment variables belong to an application.
Args:
Returns:
Examples:
Function: remove(var_id)
Remove a device service environment variable.
Args:
Examples:
Function: update(var_id, value)
Update a device service environment variable.
Args:
Examples:
Image
This class implements image model for balena python SDK.
Function: get(id)
Get a specific image.
Args:
Returns:
Raises:
Function: get_log(id)
Get the build log from an image.
Args:
Returns:
Raises:
Organization
This class implements organization model for balena python SDK.
Function: create(name, handle)
Creates a new organization.
Args:
Returns:
Examples:
Function: get(org_id)
Get a single organization by id.
Args:
Returns:
Raises:
Examples:
Function: get_all()
Get all organizations.
Returns:
Examples:
Function: get_by_handle(handle)
Get a single organization by handle.
Args:
Returns:
Raises:
Examples:
Function: remove(org_id)
Remove an organization.
Args:
Returns:
Examples:
Release
This class implements release model for balena python SDK.
Function: create_from_url(app_id, url, flatten_tarball)
Create a new release built from the source in the provided url.
Args:
Returns:
Raises:
Function: get(commit_or_id)
Get a specific release.
Args:
Returns:
Raises:
Function: get_all_by_application(app_id)
Get all releases from an application.
Args:
Returns:
Function: get_latest_by_application(app_id)
Get the latest successful release for an application.
Args:
Returns:
Function: get_with_image_details(commit_or_id)
Get a specific release with the details of the images built.
Args:
Returns:
Raises:
Service
This class implements service model for balena python SDK.
Function: get_all_by_application(app_id)
Get all services from an application.
Args:
Returns:
Tag
This class is a wrapper for Tag models.
DeviceTag
This class implements device tag model for balena python SDK.
Function: get_all()
Get all device tags.
Returns:
Examples:
Function: get_all_by_application(app_id)
Get all device tags for an application.
Args:
Returns:
Examples:
Function: get_all_by_device(uuid)
Get all device tags for a device.
Args:
Returns:
Raises:
Examples:
Function: remove(uuid, tag_key)
Remove a device tag.
Args:
Raises:
Examples:
Function: set(uuid, tag_key, value)
Set a device tag (update tag value if it exists).
Args:
Returns:
Raises:
Examples:
ApplicationTag
This class implements application tag model for balena python SDK.
Function: get_all()
Get all application tags.
Returns:
Examples:
Function: get_all_by_application(app_id)
Get all application tags for an application.
Args:
Returns:
Examples:
Function: remove(app_id, tag_key)
Remove an application tag.
Args:
Examples:
Function: set(app_id, tag_key, value)
Set an application tag (update tag value if it exists).
Args:
Returns:
Examples:
ReleaseTag
This class implements release tag model for balena python SDK.
Function: get_all()
Get all release tags.
Returns:
Examples:
Function: get_all_by_application(app_id)
Get all release tags for an application.
Args:
Returns:
Examples:
Function: get_all_by_release(commit_or_id)
Get all release tags for a release.
Args:
Returns:
Examples:
Function: remove(commit_or_id, tag_key)
Remove a release tag.
Args:
Examples:
Function: set(commit_or_id, tag_key, value)
Set a release tag (update tag value if it exists).
Args:
Returns: