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-sdk
From Source (In case, you want to test a development branch):
https://github.com/balena-io/balena-sdk-python
Getting started:
>>> from balena import Balena
>>> balena = Balena()
>>> credentials = {'username':<your email>, 'password':<your password>}
>>> balena.auth.login(**credentials)
...
The Balena object can be configured with a dict of type Settings
balena = Balena({
"balena_host": "balena-cloud.com",
"api_version": "v7",
"device_actions_endpoint_version": "v1",
"data_directory": "/home/example/.balena",
"image_cache_time": str(1 * 1000 * 60 * 60 * 24 * 7), # 1 week
"token_refresh_interval": str(1 * 1000 * 60 * 60), # 1 hour
"timeout": str(30 * 1000), # request timeout, 30s
"request_limit": str(300), # the number of requests per request_limit_interval that the SDK should respect, defaults to unlimited.
"request_limit_interval": str(60), # the timespan that the request_limit should apply to in seconds, defaults to 60s (1 minute).
"retry_rate_limited_request": False, # awaits and retry once a request is rate limited (429)
})
Notice that if you want to change for the staging environment, you could simply do: balena = Balena({"balena_host": "balena-staging.com"})
However, this will overwrite your balena-cloud settings (stored api keys etc). So we recommend using a different data_directory for each balena-sdk instance, e.g:
balena_prod = Balena()
balena_staging = Balena({
"balena_host": "balena-staging.com",
"data_directory": "/home/balena-staging-sdk/.balena",
})
In adition, you can also run balena-python-sdk completely in memory, without writing anything to the file system like:
balena_prod = Balena({"data_directory": False})
balena_staging = Balena({
"balena_host": "balena-staging.com",
"data_directory": False
})
By default the SDK will throw once a request is Rate limited by the API (with a 429 status code). A 429 request will contain a header called "retry-after" which informs how long the client should wait before trying a new request. If you would like the SDK to use this header and wait and automatically retry the request, just do:
balena = Balena({"retry_rate_limited_request": True})
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.
- balena
- .models
- .application
- create(name, device_type, organization, application_class) ⇒
TypeApplication
- disable_device_urls(slug_or_uuid_or_id) ⇒
None
- enable_device_urls(slug_or_uuid_or_id) ⇒
None
- generate_provisioning_key(slug_or_uuid_or_id, key_name, description, expiry_date) ⇒
str
- get(slug_or_uuid_or_id, options, context) ⇒
TypeApplication
- get_all(options, context) ⇒
List[TypeApplication]
- get_all_by_organization(org_handle_or_id, options) ⇒
List[TypeApplication]
- get_all_directly_accessible(options) ⇒
List[TypeApplication]
- get_by_name(app_name, options, context) ⇒
TypeApplication
- get_dashboard_url(app_id) ⇒
str
- get_directly_accessible(slug_or_uuid_or_id, options) ⇒
TypeApplication
- get_id(slug_or_uuid_or_id) ⇒
int
- get_target_release_hash(slug_or_uuid_or_id) ⇒
Optional[str]
- get_with_device_service_details(slug_or_uuid_or_id, options) ⇒
TypeApplicationWithDeviceServiceDetails
- grant_support_access(slug_or_uuid_or_id, expiry_timestamp) ⇒
None
- has(slug_or_uuid_or_id) ⇒
bool
- has_any() ⇒
bool
- is_tracking_latest_release(slug_or_uuid_or_id) ⇒
bool
- pin_to_release(slug_or_uuid_or_id, full_release_hash) ⇒
None
- purge(app_id) ⇒
None
- reboot(app_id, options) ⇒
None
- remove(slug_or_uuid_or_id) ⇒
None
- rename(slug_or_uuid_or_id, new_name) ⇒
None
- restart(slug_or_uuid_or_id) ⇒
None
- revoke_support_access(slug_or_uuid_or_id) ⇒
None
- shutdown(app_id, options) ⇒
None
- track_latest_release(slug_or_uuid_or_id) ⇒
None
- will_track_new_releases(slug_or_uuid_or_id) ⇒
bool
- .tags
- .config_var
- .env_var
- .build_var
- .membership
- change_role(membership_id, role_name) ⇒
None
- create(slug_or_uuid_or_id, username, role_name) ⇒
ApplicationMembershipType
- get(membership_id, options) ⇒
ApplicationMembershipType
- get_all(options) ⇒
List[ApplicationMembershipType]
- get_all_by_application(slug_or_uuid_or_id, options) ⇒
List[ApplicationMembershipType]
- remove(membership_id) ⇒
None
- change_role(membership_id, role_name) ⇒
- .invite
- create(name, device_type, organization, application_class) ⇒
- .device
- deactivate(uuid_or_id_or_ids) ⇒
None
- disable_device_url(uuid_or_id_or_ids) ⇒
None
- disable_local_mode(uuid_or_id) ⇒
None
- disable_lock_override(uuid_or_id) ⇒
None
- enable_device_url(uuid_or_id_or_ids) ⇒
None
- enable_local_mode(uuid_or_id) ⇒
None
- enable_lock_override(uuid_or_id) ⇒
None
- generate_device_key(uuid_or_id, name, description, expiry_date) ⇒
str
- generate_uuid() ⇒
str
- get(uuid_or_id, options) ⇒
TypeDevice
- get_all(options) ⇒
List[TypeDevice]
- get_all_by_application(slug_or_uuid_or_id, options) ⇒
List[TypeDevice]
- get_all_by_organization(handle_or_id, options) ⇒
List[TypeDevice]
- get_application_info(uuid_or_id) ⇒
Any
- get_application_name(uuid_or_id) ⇒
str
- get_by_name(name, options) ⇒
List[TypeDevice]
- get_dashboard_url(uuid) ⇒
None
- get_device_url(uuid_or_id) ⇒
str
- get_local_ip_address(uuid_or_id) ⇒
List[str]
- get_local_mode_support(uuid_or_id) ⇒
LocalModeResponse
- get_mac_address(uuid_or_id) ⇒
List[str]
- get_metrics(uuid_or_id) ⇒
DeviceMetricsType
- get_name(uuid_or_id) ⇒
str
- get_os_update_status(uuid_or_id) ⇒
HUPStatusResponse
- get_status(uuid_or_id) ⇒
str
- get_supervisor_state(uuid_or_id) ⇒
SupervisorStateType
- get_supervisor_target_state(uuid_or_id) ⇒
Any
- get_supervisor_target_state_for_app(slug_or_uuid_or_id, release) ⇒
Any
- get_with_service_details(uuid_or_id, options) ⇒
TypeDeviceWithServices
- grant_support_access(uuid_or_id_or_ids, expiry_timestamp) ⇒
None
- has(uuid_or_id) ⇒
bool
- has_device_url(uuid_or_id) ⇒
bool
- has_lock_override(uuid_or_id) ⇒
bool
- identify(uuid_or_id) ⇒
None
- is_in_local_mode(uuid_or_id) ⇒
bool
- is_online(uuid_or_id) ⇒
bool
- is_tracking_application_release(uuid_or_id) ⇒
bool
- move(uuid_or_id, app_slug_or_uuid_or_id) ⇒
None
- pin_to_release(uuid_or_id, full_release_hash_or_id) ⇒
None
- ping(uuid_or_id) ⇒
None
- purge(uuid_or_id) ⇒
None
- reboot(uuid_or_id, force) ⇒
None
- register(application_slug_or_uuid_or_id, uuid, device_type_slug) ⇒
RegisterResponse
- remove(uuid_or_id_or_ids) ⇒
None
- rename(uuid_or_id, new_name) ⇒
None
- restart_application(uuid_or_id) ⇒
None
- restart_service(uuid_or_id, image_id) ⇒
None
- revoke_support_access(uuid_or_id_or_ids) ⇒
None
- set_custom_location(uuid_or_id_or_ids, location) ⇒
None
- set_note(uuid_or_id_or_ids, note) ⇒
None
- set_supervisor_release(uuid_or_id, supervisor_version_or_id) ⇒
None
- shutdown(uuid_or_id, force) ⇒
None
- start_application(uuid_or_id) ⇒
None
- start_os_update(uuid_or_id, target_os_version) ⇒
HUPStatusResponse
- start_service(uuid_or_id, image_id) ⇒
None
- stop_application(uuid_or_id) ⇒
None
- stop_service(uuid_or_id, image_id) ⇒
None
- track_application_release(uuid_or_id_or_ids) ⇒
None
- unset_custom_location(uuid_or_id_or_ids) ⇒
None
- update(uuid_or_id, force) ⇒
None
- .tags
- .config_var
- .env_var
- .service_var
- get(uuid_or_id, service_name_or_id, key) ⇒
Optional[str]
- get_all_by_application(slug_or_uuid_or_id, options) ⇒
List[EnvironmentVariableBase]
- get_all_by_device(uuid_or_id, options) ⇒
List[EnvironmentVariableBase]
- remove(uuid_or_id, service_name_or_id, key) ⇒
None
- set(uuid_or_id, service_name_or_id, key, value) ⇒
None
- get(uuid_or_id, service_name_or_id, key) ⇒
- .history
- deactivate(uuid_or_id_or_ids) ⇒
- .device_type
- .api_key
- create(name, description, expiry_date) ⇒
str
- get_all(options) ⇒
List[APIKeyType]
- get_all_named_user_api_keys(options) ⇒
List[APIKeyType]
- get_device_api_keys_by_device(uuid_or_id, options) ⇒
List[APIKeyType]
- get_provisioning_api_keys_by_application(slug_or_uuid_or_id, options) ⇒
List[APIKeyType]
- revoke(id) ⇒
None
- update(id, api_key_info) ⇒
None
- create(name, description, expiry_date) ⇒
- .key
- .organization
- create(name, handle, logo_image) ⇒
OrganizationType
- get(handle_or_id, options) ⇒
OrganizationType
- get_all(options) ⇒
List[OrganizationType]
- remove(handle_or_id) ⇒
None
- .membership
- get(membership_id, options) ⇒
OrganizationMembershipType
- get_all(options) ⇒
List[OrganizationMembershipType]
- get_all_by_organization(handle_or_id, options) ⇒
List[OrganizationMembershipType]
- .tags
- get(membership_id, tag_key) ⇒
Optional[str]
- get_all(options) ⇒
List[OrganizationMembershipTagType]
- get_all_by_organization(handle_or_id, options) ⇒
List[OrganizationMembershipTagType]
- get_all_by_organization_membership(membership_id, options) ⇒
List[OrganizationMembershipTagType]
- remove(membership_id, tag_key) ⇒
None
- set(membership_id, tag_key, value) ⇒
None
- get(membership_id, tag_key) ⇒
- get(membership_id, options) ⇒
- .invite
- create(name, handle, logo_image) ⇒
- .os
- download(device_type, version, options) ⇒
None
- get_all_os_versions(device_type, options) ⇒
None
- get_available_os_versions(device_type) ⇒
None
- get_config(slug_or_uuid_or_id, options) ⇒
None
- get_download_size(device_type, version) ⇒
float
- get_max_satisfying_version(device_type, version_or_range, os_type) ⇒
Optional[str]
- get_supervisor_releases_for_cpu_architecture(cpu_architecture_slug_or_id, options) ⇒
List[ReleaseType]
- get_supported_os_update_versions(device_type, current_version) ⇒
None
- is_architecture_compatible_with(os_architecture, application_architecture) ⇒
None
- is_supported_os_update(device_type, current_version, target_version) ⇒
bool
- download(device_type, version, options) ⇒
- .config
- get_all() ⇒
ConfigType
- get_all() ⇒
- .release
- create_from_url(slug_or_uuid_or_id, url, flatten_tarball) ⇒
int
- finalize(commit_or_id_or_raw_version) ⇒
None
- get(commit_or_id_or_raw_version, options) ⇒
ReleaseType
- get_all_by_application(slug_or_uuid_or_id, options) ⇒
List[ReleaseType]
- get_latest_by_application(slug_or_uuid_or_id, options) ⇒
Optional[ReleaseType]
- get_with_image_details(commit_or_id_or_raw_version, image_options, release_options) ⇒
ReleaseWithImageDetailsType
- set_is_invalidated(commit_or_id_or_raw_version, is_invalidated) ⇒
None
- set_known_issue_list(commit_or_id_or_raw_version, known_issue_list) ⇒
None
- set_note(commit_or_id_or_raw_version, note) ⇒
None
- set_release_version(commit_or_id, semver) ⇒
None
- .tags
- get(commit_or_id_or_raw_version, tag_key) ⇒
Optional[str]
- get_all(options) ⇒
List[BaseTagType]
- get_all_by_application(slug_or_uuid_or_id, options) ⇒
List[BaseTagType]
- get_all_by_release(commit_or_id_or_raw_version, options) ⇒
List[BaseTagType]
- remove(commit_or_id_or_raw_version, tag_key) ⇒
None
- set(commit_or_id_or_raw_version, tag_key, value) ⇒
None
- get(commit_or_id_or_raw_version, tag_key) ⇒
- create_from_url(slug_or_uuid_or_id, url, flatten_tarball) ⇒
- .service
- get_all_by_application(slug_or_uuid_or_id, options) ⇒
List[ServiceType]
- .var
- get(service_id_or_natural_key, key) ⇒
Optional[str]
- get_all_by_application(slug_or_uuid_or_id, options) ⇒
List[EnvironmentVariableBase]
- get_all_by_service(service_id_or_natural_key, options) ⇒
List[EnvironmentVariableBase]
- remove(service_id_or_natural_key, key) ⇒
None
- set(service_id_or_natural_key, key, value) ⇒
None
- get(service_id_or_natural_key, key) ⇒
- get_all_by_application(slug_or_uuid_or_id, options) ⇒
- .image
- get(id, options) ⇒
ImageType
- get_logs(id) ⇒
str
- get(id, options) ⇒
- .application
- .auth
- authenticate() ⇒
str
- get_actor_id() ⇒
int
- get_token() ⇒
Optional[str]
- get_user_info() ⇒
UserInfo
- is_logged_in() ⇒
bool
- login() ⇒
None
- login_with_token(token) ⇒
None
- logout() ⇒
None
- register() ⇒
str
- whoami() ⇒
Union[UserKeyWhoAmIResponse, ApplicationKeyWhoAmIResponse, DeviceKeyWhoAmIResponse, None]
- .two_factor
- challenge(code) ⇒
None
- disable(password) ⇒
str
- enable(code) ⇒
str
- get_setup_key() ⇒
str
- is_enabled() ⇒
bool
- is_passed() ⇒
bool
- verify(code) ⇒
str
- challenge(code) ⇒
- authenticate() ⇒
- .logs
- history(uuid_or_id, count) ⇒
List[Log]
- stop() ⇒
None
- subscribe(uuid_or_id, callback, error, count) ⇒
None
- unsubscribe(uuid_or_id) ⇒
None
- unsubscribe_all() ⇒
None
- history(uuid_or_id, count) ⇒
- .settings
- .types
- .models
This module implements all models for balena python SDK.
This class implements application model for balena python SDK.
Function: create(name, device_type, organization, application_class) ⇒ TypeApplication
Create an application.
name (str): application name.
device_type (str): device type (slug).
organization (Union[str, int]): handle or id of the organization that the application will belong to.
application_class (Optional[Literal["app", "fleet", "block"]]): application class.
TypeApplication: application info.
>>> balena.models.application.create('foo', 'raspberry-pi', 12345)
>>> balena.models.application.create('foo', 'raspberry-pi', 12345, 'block')
Disable device urls for all devices that belong to an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
>>> balena.models.application.disable_device_urls(5685)
Enable device urls for all devices that belong to an application
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
>>> balena.models.application.enable_device_urls(5685)
Generate a device provisioning key for a specific application.
slug_or_uuid_or_id (str): application slug (string), uuid (string) or id (number)
key_name (Optional[str]): provisioning key name.
description (Optional[str]): description for provisioning key.
expiry_date (Optional[str]): expiry date for provisioning key, for example: `2030-01-01T00:00:00Z`.
str: device provisioning key.
>>> balena.models.application.generate_provisioning_key(5685)
Function: get(slug_or_uuid_or_id, options, context) ⇒ TypeApplication
Get a single application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
context (Optional[str]): extra access filters, None or 'directly_accessible'
TypeApplication: application info.
>>> balena.models.application.get("myorganization/myapp")
>>> balena.models.application.get(123)
Function: get_all(options, context) ⇒ List[TypeApplication]
Get all applications
options (AnyObject): extra pine options to use
context (Optional[str]): extra access filters, None or 'directly_accessible'
List[TypeApplication]: application info.
>>> balena.models.application.get_all()
Function: get_all_by_organization(org_handle_or_id, options) ⇒ List[TypeApplication]
Get all applications of an organization.
org_handle_or_id (Union[str, int]): handle or id of the organization.
options (AnyObject): extra pine options to use.
List[TypeApplication]: application info.
>>> balena.models.application.get_all_by_organization('myorg')
Function: get_all_directly_accessible(options) ⇒ List[TypeApplication]
Get all applications directly accessible by the user
options (AnyObject): extra pine options to use
List[APIKeyType]: user API key
>>> balena.models.application.get_all_directly_accessible()
Function: get_by_name(app_name, options, context) ⇒ TypeApplication
Get a single application using the appname.
slug_or_uuid_or_id (str): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
context (Optional[str]): extra access filters, None or 'directly_accessible'
TypeApplication: application info.
>>> balena.models.application.get("myapp")
Get Dashboard URL for a specific application.
app_id (int): application id.
str: Dashboard URL for the specific application.
>>> balena.models.application.get_dashboard_url(1476418)
Function: get_directly_accessible(slug_or_uuid_or_id, options) ⇒ TypeApplication
Get a single application directly accessible by the user
slug_or_uuid_or_id (str): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
TypeApplication: application info.
>>> balena.models.application.get_directly_accessible("myorganization/myapp")
>>> balena.models.application.get_directly_accessible(123)
Given an application slug or uuid or id, returns it numeric id.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
int: The id.
>>> balena.models.application.get_dashboard_url(1476418)
Get the hash of the current release for a specific application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
Optional[str]: The release hash of the current release or None.
>>> balena.models.application.get_target_release_hash(5685)
Function: get_with_device_service_details(slug_or_uuid_or_id, options) ⇒ TypeApplicationWithDeviceServiceDetails
This method does not map exactly to the underlying model: it runs a
larger prebuilt query, and reformats it into an easy to use and
understand format. If you want more control, or to see the raw model
directly, use application.get(uuidOrId, options)
instead.
slug_or_uuid_or_id (str): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
TypeApplication: application info.
>>> balena.models.application.get_with_device_service_details('my_org_handle/my_app_name')
Grant support access to an application until a specified time.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
expiry_timestamp (int): a timestamp in ms for when the support access will expire.
>>> balena.models.application.grant_support_access(5685, 1511974999000)
Check if an application exists.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
bool: True if application exists, False otherwise.
>>> balena.models.application.has('my_org/foo')
Check if the user has any applications.
bool: True if user has any applications, False otherwise.
>>> balena.models.application.has_any()
Get whether the application is up to date and is tracking the latest finalized release for updates
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
bool: is tracking the latest release.
>>> balena.models.application.is_tracking_latest_release(5685)
Configures the application to run a particular release and not get updated when the latest release changes.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
full_release_hash (str) : the hash of a successful release (string)
>>> balena.models.application.set_to_release(5685, '7dba4e0c461215374edad74a5b78f470b894b5b7')
Purge devices by application id
app_id (int): application id (number)
>>> balena.models.application.purge(5685)
Reboots devices by application id
app_id (int): application id (number)
options (ShutdownOptions): override update lock
>>> balena.models.application.reboot(5685)
>>> balena.models.application.reboot(5685, {"force": True})
Remove application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
>>> balena.models.application.remove('my_org/my_app')
>>> balena.models.application.remove('c184556293854781aea71b0bdae10e45')
>>> balena.models.application.remove(123)
Rename application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
new_name (str): new application name.
>>> balena.models.application.rename(1681618, 'py-test-app')
Restart application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
>>> balena.models.application.restart('myorg/RPI1')
Revoke support access to an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
>>> balena.models.application.revoke_support_access(5685)
Shutdown devices by application id
app_id (int): application id (number)
options (ShutdownOptions): override update lock
>>> balena.models.application.shutdown(5685)
>>> balena.models.application.shutdown(5685, {"force": True})
Configure a specific application to track the latest available release.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
>>> balena.models.application.track_latest_release(5685)
Get whether the application is configured to receive updates whenever a new release is available.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
bool: is tracking the latest release.
>>> balena.models.application.will_track_new_releases(5685)
This class implements application tag model for balena python SDK.
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[BaseTagType]
Get all application tags for an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[BaseTagType]: tags list.
>>> balena.models.application.tags.get_all_by_application(1005160)
Remove an application tag.
slug_or_uuid_or_id (int): application slug (string), uuid (string) or id (number)
tag_key (str): tag key.
>>> balena.models.application.tags.remove(1005767, 'tag1')
Set an application tag (update tag value if it exists).
slug_or_uuid_or_id (int): application slug (string), uuid (string) or id (number)
tag_key (str): tag key.
value (str): tag value.
List[BaseTagType]: tags list.
>>> balena.models.application.tags.set(1005767, 'tag1', 'Python SDK')
This class implements application config variable model for balena python SDK.
Get application config variable.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
env_var_name (str): environment variable name.
>>> balena.models.application.config_var.get('8deb12','test_env4')
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]
Get all application config variables by application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: application config variables.
>>> balena.models.application.config_var.get_all_by_application(9020)
Remove an application config variable.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
key (str): environment variable name.
>>> balena.models.application.config_var.remove(2184, 'test_env')
Set the value of a specific application config variable.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
env_var_name (str): environment variable name.
value (str): environment variable value.
>>> balena.models.application.config_var.set('8deb12','test_env', 'testing1')
This class implements application environment variable model for balena python SDK.
Get application environment variable.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
env_var_name (str): environment variable name.
>>> balena.models.application.env_var.get('8deb12','test_env4')
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]
Get all application environment variables by application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: application environment variables.
>>> balena.models.application.env_var.get_all_by_application(9020)
>>> balena.models.application.env_var.get_all_by_application("myorg/myslug")
Remove an application environment variable.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
key (str): environment variable name.
>>> balena.models.application.env_var.remove(2184,'test_env4')
Set the value of a specific application environment variable.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
env_var_name (str): environment variable name.
value (str): environment variable value.
>>> balena.models.application.env_var.set('8deb12','test_env4', 'testing1')
This class implements build environment variable model for balena python SDK.
Get build environment variable.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
env_var_name (str): environment variable name.
>>> balena.models.application.build_var.get('8deb12','test_env4')
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]
Get all build environment variables by application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: build environment variables.
>>> balena.models.application.build_var.get_all_by_application(9020)
>>> balena.models.application.build_var.get_all_by_application("myorg/myslug")
Remove an build environment variable.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
key (str): environment variable name.
>>> balena.models.application.build_var.remove(2184, 'test_env4')
Set the value of a specific build environment variable.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
env_var_name (str): environment variable name.
value (str): environment variable value.
>>> balena.models.application.build_var.set('8deb12','test_env4', 'testing1')
This class implements application membership model for balena python SDK.
Changes the role of an application member.
membership_id (ResourceKey): the id or an object with the unique `user` & `is_member_of__application`
numeric pair of the membership
role_name (str): the role name to be granted to the membership.
>>> balena.models.application.membership.change_role(55074, 'observer')
Function: create(slug_or_uuid_or_id, username, role_name) ⇒ ApplicationMembershipType
Creates a new membership for an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
username (str): the username of the balena user that will become a member.
role_name (Optional[str]): the role name to be granted to the membership.
ApplicationMembershipType: application membership.
>>> balena.models.application.membership.create(1681618, 'testuser')
Function: get(membership_id, options) ⇒ ApplicationMembershipType
Get a single application membership.
membership_id (ResourceKey): the id or an object with the unique `user` & `is_member_of__application`
numeric pair of the membership
options (AnyObject): extra pine options to use
ApplicationMembershipType: application membership.
>>> balena.models.application.membership.get(55074)
>>> balena.models.application.membership.get({"user": 123, "is_member_of__application": 125})
Function: get_all(options) ⇒ List[ApplicationMembershipType]
Get all application memberships.
options (AnyObject): extra pine options to use
List[ApplicationMembershipType]: list contains info of application memberships.
>>> balena.models.application.membership.get_all()
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[ApplicationMembershipType]
Get all memberships by application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
options (AnyObject): extra pine options to use
list: list contains info of application memberships.
>>> balena.models.application.membership.get_all_by_application(1681618)
Remove a membership.
membership_id (ResourceKey): the id or an object with the unique `user` & `is_member_of__application`
This class implements application invite model for balena python SDK.
Accepts an invite.
invite_token (str): invitationToken - invite token.
>>> balena.models.application.invite.accept("qwerty-invitation-token")
Function: create(slug_or_uuid_or_id, options) ⇒ ApplicationInviteType
Creates a new invite for an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
options (ApplicationInviteOptions): Application Invite options dict to use.
invitee (str): the email/balena_username of the invitee.
role_name (Optional[str]): the role name to be granted to the invitee.
One of "observer", "developer", "operator". Defaults to "developer"
message (Optional[str]): the message to send along with the invite.
dict: application invite.
>>> balena.models.application.invite.create(1681618, 'invitee@example.org', 'developer', 'Test invite')
Function: get_all(options) ⇒ List[ApplicationInviteType]
Get all invites.
options (AnyObject): extra pine options to use
List[ApplicationInviteType]: list contains info of invites.
>>> balena.models.application.invite.get_all()
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[ApplicationInviteType]
Get all invites by application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
options (AnyObject): extra pine options to use
List[ApplicationInviteType]: list contains info of invites.
>>> balena.models.application.invite.get_all_by_application(1681618)
Revoke an invite.
invite_id (int): application invite id.
>>> balena.models.application.invite.revoke(5860)
This class implements device model for balena python SDK.
Deactivates a device.
uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])
>>> balena.models.device.deactivate('44cc9d1861b9f992808c506276e5d31c')
>>> balena.models.device.deactivate([123, 234])
Disable device url for a device.
uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int]).
>>> balena.models.device.disable_device_url('8deb12a58')
>>> balena.models.device.disable_device_url([123, 345])
Disable local mode.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
None.
>>> balena.models.device.disable_local_mode('b6070f4f')
Disable lock override.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
Enable device url for a device.
uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int]).
>>> balena.models.device.enable_device_url('8deb12a58')
>>> balena.models.device.enable_device_url([123, 345])
Enable local mode.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
>>> balena.models.device.enable_local_mode('b6070f4f')
Enable lock override.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
Generate a device key.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
name (Optional[str]): device key name.
description (Optional[str]): description for device key.
expiry_date (Optional[str]): expiry date for device key, for example: `2030-01-01T00:00:00Z`.
>>> balena.models.device.generate_device_key('df0926')
Generate a random device UUID.
str: a generated UUID.
>>> balena.models.device.generate_uuid()
Function: get(uuid_or_id, options) ⇒ TypeDevice
This method returns a single device by id or uuid.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
options (AnyObject): extra pine options to use
TypeDevice: device info.
>>> balena.models.device.get('8deb12a58e3b6d3920db1c2b6303d1ff32f23d5ab99781ce1dde6876e8d143')
>>> balena.models.device.get('8deb12')
>>> balena.models.device.get(12345)
Function: get_all(options) ⇒ List[TypeDevice]
This method returns all devices that the current user can access.
In order to have the following computed properties in the result
you have to explicitly define them in a $select
in the extra options:
- overall_status
- overall_progress
- is_frozen
options (AnyObject): extra pine options to use
List[TypeDevice]: list contains info of devices.
>>> balena.models.device.get_all()
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[TypeDevice]
Get devices by application slug, uuid or id.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[TypeDevice]: list contains info of devices.
>>> balena.models.device.get_all_by_application('my_org/RPI1')
Function: get_all_by_organization(handle_or_id, options) ⇒ List[TypeDevice]
Get devices by organization slug, uuid or id.
handle_or_id (Union[str, int]): organization handle (string) or id (number).
options (AnyObject): extra pine options to use
List[TypeDevice]: list contains info of devices.
>>> balena.models.device.get_all_by_organization('my_org')
>>> balena.models.device.get_all_by_organization(123)
Deprecated Return information about the application running on the device. This function requires supervisor v1.8 or higher.
uuid_or_id (Union[str, int]): device uuid (string) or id (int).
dict: dictionary contains application information.
>>> balena.models.device.get_application_info('7f66ec')
Get application name by device uuid.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
str: application name.
Function: get_by_name(name, options) ⇒ List[TypeDevice]
Get devices by device name.
name (str): device name.
List[TypeDevice]: list contains info of devices.
>>> balena.models.device.get_by_name('floral-mountain')
Get balena Dashboard URL for a specific device.
uuid (str): device uuid.
>>> balena.models.device.get_dashboard_url('19619a6317072b65a240b451f45f855d')
Get a device url for a device.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
>>> balena.models.device.get_device_url('8deb12a')
Get the local IP addresses of a device.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
List[str]: IP addresses of a device.
Returns whether local mode is supported and a message describing the reason why local mode is not supported.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
dict: local mode support information ({'supported': True/False, 'message': '...'}).
>>> balena.models.device.get_local_mode_support('b6070f4')
Get the MAC addresses of a device.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
List[str]: MAC addresses of a device.
Function: get_metrics(uuid_or_id) ⇒ DeviceMetricsType
Gets the metrics related information for a device.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
dict: metrics of the device.
Get device name by device uuid.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
str: device name.
Deprecated Get the OS update status of a device.
uuid_or_id (Union[str, int]): device uuid (string) or id (int).
HUPStatusResponse: action response.
>>> balena.models.device.get_os_update_status('b6070f4f')
Get the status of a device.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
str: status of a device.
>>> balena.models.device.get_status('8deb12')
Get the supervisor state on a device
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
dict: supervisor state.
>>> balena.models.device.get_supervisor_state('b6070f4fea')
Get the supervisor target state on a device
uuid_or_id (Union[str, int]): device uuid (str) or id (int).
DeviceStateType: supervisor target state.
>>> balena.models.device.get_supervisor_target_state('b6070f4fea5edf808b576123157fe5ec')
Get the supervisor target state on a device
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
release (Optional[Union[str, int]]): (optional) release uuid (default tracked)
DeviceStateType: supervisor target state.
>>> balena.models.device.get_supervisor_target_state_for_app('myorg/myapp')
Function: get_with_service_details(uuid_or_id, options) ⇒ TypeDeviceWithServices
This method does not map exactly to the underlying model: it runs a
larger prebuilt query, and reformats it into an easy to use and
understand format. If you want more control, or to see the raw model
directly, use device.get(uuidOrId, options)
instead.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
options (AnyObject): extra pine options to use
dict: device info with associated services details.
>>> balena.models.device.get_with_service_details('0fcd753af396247e035de53b4e43eec3')
Grant support access to a device until a specified time.
uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])
expiry_timestamp (int): a timestamp in ms for when the support access will expire.
>>> balena.models.device.grant_support_access('49b2a7', 1511974999000)
Check if a device exists.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
bool: True if device exists, False otherwise.
Check if a device is web accessible with device urls
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
>>> balena.models.device.has_device_url('8deb12a')
Check if a device has the lock override enabled.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
bool: lock override status.
Identify device.
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
>>> balena.models.device.identify('8deb12a5')
Check if local mode is enabled on the device.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
bool: True if local mode enabled, otherwise False.
>>> balena.models.device.is_in_local_mode('b6070f4f')
Check if a device is online.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
bool: True if the device is online, False otherwise.
Get whether the device is configured to track the current application release.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
bool: is tracking the current application release.
Move a device to another application.
uuid_or_id (Union[str, int]): device uuid (str) or id (int).
app_slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
>>> balena.models.device.move(123, 'RPI1Test')
Configures the device to run a particular release and not get updated when the current application release changes.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
full_release_hash_or_id (Union[str, int]) : the hash of a successful release (string) or id (number)
>>> balena.models.device.set_to_release('49b2a', '45c90004de73557ded7274d4896a6db90ea61e36')
Ping a device. This is useful to signal that the supervisor is alive and responding.
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
>>> balena.models.device.ping('8f66ec7')
>>> balena.models.device.ping(1234)
Purge device.
This function clears the user application's /data
directory.
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
>>> balena.models.device.purge('8f66ec7')
Reboot the device.
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
force (Optional[bool]): If force is True, the update lock will be overridden.
>>> balena.models.device.reboot('8f66ec7')
Register a new device with a balena application.
application_slug_or_uuid_or_id (Union[int, str]): application slug (string), uuid (string) or id (number).
uuid (str): device uuid.
device_type_slug (Optional[str]): device type slug or alias.
dict: dictionary contains device info.
>>> device_uuid = balena.models.device.generate_uuid()
>>> balena.models.device.register('RPI1',device_uuid)
Remove device(s).
uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])
Renames a device.
uuid_or_id (Union[str, int]): device uuid (str) or id (int)
new_name (str): device new name.
>>> balena.models.device.rename(123, 'python-sdk-test-device')
This function restarts the Docker container running the application on the device, but doesn't reboot the device itself.
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
>>> balena.models.device.restart_application('8deb12a58')
>>> balena.models.device.restart_application(1234)
Restart a service on device.
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
image_id (int): id of the image to restart
>>> balena.models.device.restart_service('f3887b', 392229)
>>> balena.models.device.restart_service(None, 392229) # if running on the device
Revoke support access to a device.
uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])
>>> balena.models.device.revoke_support_access('49b2a7')
Set a custom location for a device.
uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])
location (dict): device custom location { 'latitude': Union[int,, str], 'longitude': Union[int, str]}.
>>> balena.models.device.set_custom_location(123, {'latitude': '21.032777','longitude': '105.831586'})
Note a device.
uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])
note (str): device note.
>>> balena.models.device.note(123, 'test note')
Set a specific device to run a particular supervisor release.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
supervisor_version_or_id (Union[str, int]): the version of a released supervisor (string) or id (number)
>>> balena.models.device.set_supervisor_release('f55dcdd9ad', 'v13.0.0')
Shutdown the device.
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
force (Optional[bool]): If force is True, the update lock will be overridden.
>>> balena.models.device.shutdown('8f66ec7')
Deprecated
Starts a user application container, usually after it has been stopped with stop_application()
.
This function requires supervisor v1.8 or higher.
uuid_or_id (Union[str, int]): device uuid (string) or id (int).
dict: dictionary contains started application container id.
>>> balena.models.device.start_application('8f66ec7')
Start an OS update on a device.
If using run_detached option, monitor progress with device.get() -- status, provisioning_state and provisioning_progress entries.
uuid_or_id (Union[str, int]): device uuid (string) or id (int).
target_os_version (str): semver-compatible version for the target device.
Unsupported (unpublished) version will result in rejection.
The version **must** be the exact version number, a "prod" variant
and greater than the one running on the device.
run_detached (Optional[bool]): run the update in detached mode.
Default behaviour is run_detached=False but is DEPRECATED and will be
removed in a future release. Use run_detached=True for more reliable updates.
HUPStatusResponse: action response.
>>> balena.models.device.start_os_update('b6070f4', '2.29.2+rev1.prod')
>>> balena.models.device.start_os_update('b6070f4', '2.89.0+rev1')
>>> balena.models.device.start_os_update('b6070f4', '2.89.0+rev1', run_detached=True)
Start a service on device.
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
image_id (int): id of the image to start
>>> balena.models.device.start_service('f3887b1', 1234)
>>> balena.models.device.start_service(None, 1234) # if running on the device
Deprecated Temporarily stops a user application container. Application container will not be removed after invoking this function and a reboot or supervisor restart will cause the container to start again. This function requires supervisor v1.8 or higher.
uuid_or_id (Union[str, int]): device uuid (string) or id (int).
dict: dictionary contains stopped application container id.
>>> balena.models.device.stop_application('8f66ec')
Stop a service on device.
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
image_id (int): id of the image to stop
>>> balena.models.device.stop_service('f3887b1', 392229)
>>> balena.models.device.stop_service(None, 392229) # if running on the device
Configure a specific device to track the current application release.
uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])
Clear the custom location of a device.
uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])
>>> balena.models.device.unset_custom_location(123)
update the device.
uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.
force (Optional[bool]): If force is True, the update lock will be overridden.
>>> balena.models.device.update('8f66ec7')
This class implements device tag model for balena python SDK.
Get a device tag (update tag value if it exists). Note: Notice that when using the device ID rather than UUID, it will avoid one extra API roundtrip.
uuid_or_id (Union[str, int]): device uuid or device id.
tag_key (str): tag key.
Optional[str]: tag value
>>> balena.models.device.tags.get('f5213eac0d63ac4', 'testtag')
Function: get_all(options) ⇒ List[BaseTagType]
Get all device tags.
options (AnyObject): extra pine options to use
List[BaseTagType]: tags list.
>>> balena.models.device.tags.get_all()
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[BaseTagType]
Get all device tags for an application.
slug_or_uuid_or_id (int): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[BaseTagType]: tags list.
>>> balena.models.device.tags.get_all_by_application(1005160)
Function: get_all_by_device(uuid_or_id, options) ⇒ List[BaseTagType]
Get all device tags for a device.
uuid_or_id (Union[str, int]): device uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[BaseTagType]: tags list.
>>> balena.models.device.tags.get_all_by_device('a03ab646c')
Remove a device tag.
uuid_or_id (Union[str, int]): device uuid or device id.
tag_key (str): tag key.
>>> balena.models.device.tags.remove('f5213eac0d63ac477', 'testtag')
Set a device tag (update tag value if it exists). Note: Notice that when using the device ID rather than UUID, it will avoid one extra API roundtrip.
uuid_or_id (Union[str, int]): device uuid or device id.
tag_key (str): tag key.
value (str): tag value.
>>> balena.models.device.tags.set('f5213eac0d63ac4', 'testtag', 'test1')
>>> balena.models.device.tags.set('f5213eac0d63ac4', 'testtag', 'test2')
This class implements device config variable model for balena python SDK.
Get a device config variable.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
env_var_name (str): environment variable name.
>>> balena.models.device.config_var.device.get('8deb12','test_env4')
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]
Get all device config variables for an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: list of device environment variables.
>>> balena.models.device.config_var.device.get_all_by_application(5780)
Function: get_all_by_device(uuid_or_id, options) ⇒ List[EnvironmentVariableBase]
Get all device config variables belong to a device.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: device config variables.
>>> balena.models.device.config_var.get_all_by_device('f5213ea')
Remove a device environment variable.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
key (str): environment variable name.
>>> balena.models.device.config_var.device.remove(2184, 'test_env4')
Set the value of a device config variable. Note that config variables must start with BALENA_ and RESIN_ prefixes.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
env_var_name (str): environment variable name.
value (str): environment variable value.
>>> balena.models.device.config_var.set('8deb12','BALENA_test_env4', 'testing1')
This class implements device environment variable model for balena python SDK.
Get device environment variable.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
env_var_name (str): environment variable name.
>>> balena.models.device.env_var.get('8deb12', 'test_env4')
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]
Get all device environment variables for an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: list of device environment variables.
>>> balena.models.device.env_var.get_all_by_application(5780)
Function: get_all_by_device(uuid_or_id, options) ⇒ List[EnvironmentVariableBase]
Get all device environment variables.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: device environment variables.
>>> balena.models.device.env_var.get_all_by_device('8deb12a')
Remove a device environment variable.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
key (str): environment variable name.
>>> balena.models.device.env_var.remove(2184, 'test_env4')
Set the value of a specific environment variable.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
env_var_name (str): environment variable name.
value (str): environment variable value.
>>> balena.models.device.env_var.set('8deb12', 'test_env4', 'testing1')
This class implements device service variable model for balena python SDK.
Get the overriden value of a service variable on a device
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
service_name_or_id (Union[str, int]): service name (string) or service id (number)
key (str): variable name
Optional[str]: device service environment variables.
>>> balena.models.device.service_var.get('8deb12a', 'myservice', 'VAR')
>>> balena.models.device.service_var.get('8deb12a', 1234', 'VAR')
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]
Get all device service environment variables belong to an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: device service environment variables.
>>> balena.models.device.service_var.get_all_by_application(1043050)
Function: get_all_by_device(uuid_or_id, options) ⇒ List[EnvironmentVariableBase]
Get all device environment variables.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: device service environment variables.
>>> balena.models.device.service_var.get_all_by_device(8deb12a)
Remove a device service environment variable.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
service_name_or_id (Union[str, int]): service name (string) or service id (number)
key (str): variable name
>>> balena.models.device.service_var.set('7cf02a6', 'myservice', 'VAR')
>>> balena.models.device.service_var.remove('7cf02a6', 28970, 'VAR')
Set the overriden value of a service variable on a device.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
service_name_or_id (Union[str, int]): service name (string) or service id (number)
key (str): variable name
value (str): variable value
>>> balena.models.device.service_var.set('7cf02a6', 'myservice', 'VAR', 'override')
>>> balena.models.device.service_var.set('7cf02a6', 123, 'VAR', 'override')
This class implements device history model for balena python SDK.
Function: get_all_by_application(slug_or_uuid_or_id, from_date, to_date, options) ⇒ List[DeviceHistoryType]
Get all device history entries for an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
from_date (datetime): history entries newer than or equal to this timestamp. Defaults to 7 days ago
to_date (datetime): history entries younger or equal to this date.
options (AnyObject): extra pine options to use
List[DeviceHistoryType]: device history entries.
>>> balena.models.device.history.get_all_by_application('myorg/myapp')
>>> balena.models.device.history.get_all_by_application(11196426)
>>> balena.models.device.history.get_all_by_application(
... 11196426, from_date=datetime.utcnow() + timedelta(days=-5)
... )
>>> balena.models.device.history.get_all_by_application(
... 11196426,
... from_date=datetime.utcnow() + timedelta(days=-10),
... to_date=from_date = datetime.utcnow() + timedelta(days=-5))
... )
Function: get_all_by_device(uuid_or_id, from_date, to_date, options) ⇒ List[DeviceHistoryType]
Get all device history entries for a device.
uuid_or_id (str): device uuid (32 / 62 digits string) or id (number) __note__: No short IDs supported
from_date (datetime): history entries newer than or equal to this timestamp. Defaults to 7 days ago
to_date (datetime): history entries younger or equal to this date.
options (AnyObject): extra pine options to use
List[DeviceHistoryType]: device history entries.
>>> balena.models.device.history.get_all_by_device('6046335305c8142883a4466d30abe211')
>>> balena.models.device.history.get_all_by_device(11196426)
>>> balena.models.device.history.get_all_by_device(
... 11196426, from_date=datetime.utcnow() + timedelta(days=-5)
... )
>>> balena.models.device.history.get_all_by_device(
... 11196426,
... from_date=datetime.utcnow() + timedelta(days=-10),
... to_date=from_date = datetime.utcnow() + timedelta(days=-5))
... )
This class implements user API key model for balena python SDK.
Function: get(id_or_slug, options) ⇒ DeviceTypeType
Get a single device type.
id_or_slug (Union[str, int]): device type slug or alias (string) or id (int).
options (AnyObject): extra pine options to use.
DeviceTypeType: Returns the device type
Function: get_all(options) ⇒ List[DeviceTypeType]
Get all device types.
options (AnyObject): extra pine options to use.
List[DeviceTypeType]: list contains info of device types.
Get all supported device types.
options (AnyObject): extra pine options to use.
List[DeviceTypeType]: list contains info of all supported device types.
Function: get_by_slug_or_name(slug_or_name, options) ⇒ DeviceTypeType
Get a single device type by slug or name.
slug_or_name (str): device type slug or name.
options (AnyObject): extra pine options to use.
DeviceTypeType: Returns the device type
Get display name for a device.
slug (str): device type slug.
Get device slug.
name (str): device type name.
This class implements user API key model for balena python SDK.
This method registers a new api key for the current user with the name given.
name (str): the API key name
description (Optional[str]): the API key description
expiry_date (Optional[str]): the API key expiring date
str: API key
>>> balena.models.api_key.create_api_key("myApiKey")
>>> balena.models.api_key.create_api_key("myApiKey", "my api key description")
>>> balena.models.api_key.create_api_key("myApiKey", "my descr", datetime.datetime.utcnow().isoformat())
Function: get_all(options) ⇒ List[APIKeyType]
This function gets all API keys.
options (AnyObject): extra pine options to use
List[APIKeyType]: user API key
>>> balena.models.api_key.get_all()
Function: get_all_named_user_api_keys(options) ⇒ List[APIKeyType]
Get all named user API keys of the current user.
options (AnyObject): extra pine options to use
>>> balena.models.api_key.get_all_named_user_api_keys()
Function: get_device_api_keys_by_device(uuid_or_id, options) ⇒ List[APIKeyType]
Get all API keys for a device.
device_uuid (Union[str, int]): device, uuid (string) or id (int)
options (AnyObject): extra pine options to use
>>> balena.models.api_key.get_device_api_keys_by_device("44cc9d186")
>>> balena.models.api_key.get_device_api_keys_by_device(1111386)
Function: get_provisioning_api_keys_by_application(slug_or_uuid_or_id, options) ⇒ List[APIKeyType]
Get all provisioning API keys for an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
>>> balena.models.api_key.get_provisioning_api_keys_by_application(1296047)
>>> balena.models.api_key.get_provisioning_api_keys_by_application("myorg/myapp")
This function revokes an API key.
id (int): API key id.
>>> balena.models.api_key.revoke(1296047)
This function updates details of an API key.
id (str): API key id.
api_key_info (APIKeyInfoType): new API key info.
>>> balena.models.api_key.update(1296047, {"name":"new name"})
This class implements ssh key model for balena python SDK.
Function: create(title, key) ⇒ SSHKeyType
Create a ssh key.
title (str): key title.
key (str): the public ssh key.
SSHKeyType: new ssh key id.
Function: get(id) ⇒ SSHKeyType
Get a single ssh key.
id (int): key id.
SSHKeyType: ssh key info.
Function: get_all(options) ⇒ List[SSHKeyType]
Get all ssh keys.
options (AnyObject): extra pine options to use
List[SSHKeyType]: list of ssh keys.
Remove a ssh key.
id (int): key id.
This class implements organization model for balena python SDK.
Function: create(name, handle, logo_image) ⇒ OrganizationType
Creates a new organization.
name (str): the name of the organization that will be created.
handle (Optional[str]): The handle of the organization that will be created.
logo_image (Optional[io.BufferedReader]): The organization logo to be used.
dict: organization info.
>>> balena.models.organization.create('My Org', 'test_org')
>>> with open('mypath/myfile.png', 'rb') as f:
>>> org = sdk.models.organization.create("my-name", None, f)
Function: get(handle_or_id, options) ⇒ OrganizationType
Get a single organization.
handle_or_id (str): organization handle (string) or id (number).
options (AnyObject): extra pine options to use
dict: organization info.
OrganizationNotFound: if organization couldn't be found.
>>> balena.models.organization.get(26474)
>>> balena.models.organization.get('myorg')
Function: get_all(options) ⇒ List[OrganizationType]
Get all organizations.
options (AnyObject): extra pine options to use
List[OrganizationType]: list contains information of organizations.
>>> balena.models.organization.get_all()
Remove an organization.
handle_or_id (str): organization handle (string) or id (number).
>>> balena.models.organization.remove(148003)
This class implements organization membership model for balena python SDK.
Function: get(membership_id, options) ⇒ OrganizationMembershipType
Get a single organization membership.
membership_id (ResourceKey): the id (int) or an object with the unique
`user` & `is_member_of__organization` numeric pair of the membership
options (AnyObject): extra pine options to use
Organization membership.
>>> balena.models.organization.memberships.get(17608)
Function: get_all(options) ⇒ List[OrganizationMembershipType]
Get all organization memberships.
options (AnyObject): extra pine options to use
List[OrganizationMembershipType]: organization memberships.
>>> balena.models.organization.memberships.tags.get_all()
Function: get_all_by_organization(handle_or_id, options) ⇒ List[OrganizationMembershipType]
Get all memberships by organization.
handle_or_id (Union[str, int]): organization handle (string) or id (number).
options (AnyObject): extra pine options to use
List[OrganizationMembershipType]: organization memberships.
>>> balena.models.organization.memberships.get_all_by_organization(3014)
This class implements organization membership tag model for balena python SDK.
Get an organization membership tag.
membership_id: organization membership id.
tag_key (str): tag key.
>>> balena.models.organization.memberships.tags.get(17608, 'mTag1')
Function: get_all(options) ⇒ List[OrganizationMembershipTagType]
Get all organization membership tags.
options (AnyObject): extra pine options to use
>>> balena.models.organization.memberships.tags.get_all()
Function: get_all_by_organization(handle_or_id, options) ⇒ List[OrganizationMembershipTagType]
Get all organization membership tags for an organization.
handle_or_id (Union[str, int]): organization handle (string) or id (number).
options (AnyObject): extra pine options to use
List[OrganizationMembershipTagType]: organization membership tags.
>>> balena.models.organization.memberships.tags.get_all_by_organization(3014)
Function: get_all_by_organization_membership(membership_id, options) ⇒ List[OrganizationMembershipTagType]
Get all organization membership tags for a memberships of an organization.
membership_id (int): organization membership id.
options (AnyObject): extra pine options to use
list: organization membership tags.
>>> balena.models.organization.memberships.tags.get_all_by_organization_membership(17608)
Remove an organization membership tag.
membership_id: organization membership id.
tag_key (str): tag key.
>>> balena.models.organization.memberships.tags.remove(17608, 'mTag1')
Set an organization membership tag.
membership_id: organization membership id.
tag_key (str): tag key.
value (str): tag value.
>>> balena.models.organization.memberships.tags.set(17608, 'mTag1', 'Python SDK')
This class implements organization invite model for balena python SDK.
Accepts an invite.
invite_token (str): invitation Token - invite token.
Function: create(handle_or_id, invitee, role_name, message) ⇒ OrganizationInviteType
Creates a new invite for an organization.
handle_or_id (Union[str, int]): organization handle (string), or id (number).
invitee (str): the email/balena_username of the invitee.
role_name (Optional[str]): the role name to be granted to the invitee.
message (Optional[str]): the message to send along with the invite.
OrganizationInviteType: organization invite.
>>> balena.models.organization.invite.create(26474, 'invitee@example.org', 'member', 'Test invite')
Function: get_all(options) ⇒ List[OrganizationInviteType]
Get all invites.
options (AnyObject): extra pine options to use
List[OrganizationInviteType]: list contains info of invites.
>>> balena.models.organization.invite.get_all()
Function: get_all_by_organization(handle_or_id, options) ⇒ List[OrganizationInviteType]
Get all invites by organization.
handle_or_id (Union[str, int]): organization handle (string), or id (number).
options (AnyObject): extra pine options to use.
List[OrganizationInviteType]: list contains info of invites.
>>> balena.models.organization.invite.get_all_by_organization(26474)
Revoke an invite.
invite_id (int): organization invite id.
>>> balena.models.organization.invite.revoke(2862)
This class implements device os model for balena python SDK.
Get OS download size estimate. Currently only the raw (uncompressed) size is reported.
device_type (str): device type slug.
version (str): semver-compatible version or 'latest', defaults to 'latest'.
* The version **must** be the exact version number.
options (DownloadConfig): OS configuration options to use.
float: OS image download size, in bytes.
Example:
>>> with b.models.device_os.download("raspberrypi3") as stream:
... stream.raise_for_status()
... with open("my-image-filename", "wb") as f:
... for chunk in stream.iter_content(chunk_size=8192):
... f.write(chunk)
Get all OS versions for the provided device type(s), inlcuding invalidated ones
device_type (Union[str, List[str]]): device type slug.
options (AnyObject): extra pine options to use
list: balenaOS versions.
Get the supported OS versions for the provided device type(s)
device_type (Union[str, List[str]]): device type slug.
list: balenaOS versions.
Download application config.json.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (ImgConfigOptions): OS configuration dict to use. The available options
are listed below:
network (Optional[Literal["ethernet", "wifi"]]): The network type that
the device will use, one of 'ethernet' or 'wifi'.
appUpdatePollInterval (Optional[int]): How often the OS checks for updates, in minutes.
provisioningKeyName (Optional[str]): Name assigned to API key
provisioningKeyExpiryDate (Optional[str]): Expiry Date assigned to API key
wifiKey (Optional[str]): The key for the wifi network the device will connect to.
wifiSsid (Optional[str]): The ssid for the wifi network the device will connect to.
ip (Optional[str]): static ip address
gateway (Optional[str]): static ip gateway.
netmask (Optional[str]): static ip netmask.
deviceType (Optional[str]): The device type.
version (str): Required: the OS version of the image.
developmentMode (Optional[bool]): If the device should be in development mode.
dict: application config.json content.
ApplicationNotFound: if application couldn't be found.
Get OS download size estimate. Currently only the raw (uncompressed) size is reported.
device_type (str): device type slug.
version (str): semver-compatible version or 'latest', defaults to 'latest'.
* The version **must** be the exact version number.
float: OS image download size, in bytes.
Get OS download size estimate. Currently only the raw (uncompressed) size is reported.
device_type (str): device type slug.
version_or_range (str): can be one of the exact version number,
in which case it is returned if the version is supported,
or `None` is returned otherwise,
* a [semver](https://www.npmjs.com/package/semver)-compatible
range specification, in which case the most recent satisfying version is returned
if it exists, or `None` is returned,
`'latest'` in which case the most recent version is returned, including pre-releases,
`'recommended'` in which case the recommended version is returned, i.e. the most
recent version excluding pre-releases, which can be `None` if only pre-release versions
are available,
`'default'` in which case the recommended version is returned if available,
or `latest` is returned otherwise.
Defaults to `'latest'`
os_type (Optional[Literal["default", "esr"]]): The used OS type.
float: OS image download size, in bytes.
Function: get_supervisor_releases_for_cpu_architecture(cpu_architecture_slug_or_id, options) ⇒ List[ReleaseType]
Returns the Releases of the supervisor for the CPU Architecture
cpu_architecture_slug_or_id (Union[str, int]): The slug (string) or id (number) for the CPU Architecture.
options (AnyObject): extra pine options to use.
ReleaseType: release info.
Example: results = balena.models.os.get_supervisor_releases_for_cpu_architecture('aarch64'); results = balena.models.os.get_supervisor_releases_for_cpu_architecture( 'aarch64', { $filter: { raw_version: '12.11.0' } }, );
Get OS supported versions.
device_type (str): device type slug.
current_version (str): device type slug.
Returns whether the specified OS architecture is compatible with the target architecture.
os_architecture (str): The OS's architecture as specified in its device type.
application_architecture (str): The application's architecture as specified in its device type.
bool: Whether the specified OS architecture is capable of
running applications build for the target architecture.
Returns the supported OS update targets for the provided device type.
device_type (str): device type slug.
current_version (str): emver-compatible version for the starting OS version
target_version (str): semver-compatible version for the target OS version
This class implements configuration model for balena python SDK.
Get all configuration.
ConfigType: configuration information.
>>> balena.models.config.get_all()
This class implements release model for balena python SDK.
Create a new release built from the source in the provided url.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
url (str): a url with a tarball of the project to build.
flatten_tarball (bool): Should be true when the tarball includes an extra root folder
with all the content.
int: release Id.
Finalizes a draft release.
commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string)
Function: get(commit_or_id_or_raw_version, options) ⇒ ReleaseType
Get a specific release.
commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string)
or id (number) or an object with the unique `application` (number or string) & `rawVersion` (string)
pair of the release options
options(AnyObject): extra pine options to use
ReleaseType: release info.
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[ReleaseType]
Get all releases from an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
options (AnyObject): extra pine options to use
List[ReleaseType]: release info.
Function: get_latest_by_application(slug_or_uuid_or_id, options) ⇒ Optional[ReleaseType]
Get the latest successful release for an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
options (AnyObject): extra pine options to use
Optional[ReleaseType]: release info.
Function: get_with_image_details(commit_or_id_or_raw_version, image_options, release_options) ⇒ ReleaseWithImageDetailsType
Get a specific release with the details of the images built.
commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string)
image_options (AnyObject): extra pine options to use on image expand
release_options (AnyObject): extra pine options to use on release expand
dict: release info.
ReleaseNotFound: if release couldn't be found.
Set the is_invalidated property of a release to True or False.
commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string)
is_invalidated (bool): True for invalidated, False for validated.
Set a known issue list for a release.
commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string)
known_issue_list (Optional[str]): the known issue list.
Set a note for a release.
commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string)
note (Optional[str]): the note.
Set a direct semver for a given release.
commit_or_id(Union[str, int]): release commit (string) or id (int)
semver (str): the version to be released, must be a valid semver
This class implements release tag model for balena python SDK.
Get a single release tag.
commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string) or
tag_key (str): tag key.
>>> balena.models.release.tags.get(465307, 'releaseTag1')
Function: get_all(options) ⇒ List[BaseTagType]
Get all release tags.
options (AnyObject): extra pine options to use
List[BaseTagType]: tags list.
>>> balena.models.release.tags.get_all()
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[BaseTagType]
Get all device tags for an application.
slug_or_uuid_or_id (int): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[BaseTagType]: tags list.
>>> balena.models.release.tags.get_all_by_application(1005160)
Function: get_all_by_release(commit_or_id_or_raw_version, options) ⇒ List[BaseTagType]
Get all release tags for a release.
commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string) or
options (AnyObject): extra pine options to use
List[BaseTagType]: tags list.
>>> balena.models.release.tags.get_all_by_release(135)
Remove a release tag.
commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string) or
tag_key (str): tag key.
>>> balena.models.release.tags.remove(135, 'releaseTag1')
Set a release tag (update tag value if it exists).
commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string) or
tag_key (str): tag key.
value (str): tag value.
>>> balena.models.release.tags.set(465307, 'releaseTag1', 'Python SDK')
This class implements service model for balena python SDK.
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[ServiceType]
Get all services from an application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[ServiceType]: service info.
This class implements Service environment variable model for balena python SDK.
Get the value of a specific service variable
service_id_or_natural_key (Union[int, ServiceNaturalKey]): service id (number) or appliation-service_name
key (str): variable name
>>> balena.models.service.var.get(1234,'test_env4')
>>> balena.models.service.var.get({'application': 'myorg/myapp', 'service_name': 'service'}, 'VAR')
Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]
Get all service variables by application.
slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: application environment variables.
>>> balena.models.service.var.get_all_by_application(9020)
>>> balena.models.service.var.get_all_by_application("myorg/myslug")
Function: get_all_by_service(service_id_or_natural_key, options) ⇒ List[EnvironmentVariableBase]
Get all variables for a service.
service_id_or_natural_key (Union[int, ServiceNaturalKey]): service id (number) or appliation-service_name
options (AnyObject): extra pine options to use
List[EnvironmentVariableBase]: service environment variables.
>>> balena.models.service.var.get_all_by_service(1234)
>>> balena.models.service.var.get_all_by_service({'application': 'myorg/myapp', 'service_name': 'service'})
Clear the value of a specific service variable
service_id_or_natural_key (Union[int, ServiceNaturalKey]): service id (number) or appliation-service_name
key (str): variable name
>>> balena.models.service.var.remove({'application': 'myorg/myapp', 'service_name': 'service'}, 'VAR')
>>> balena.models.service.var.remove(1234,'test_env4')
Set the value of a specific application environment variable.
service_id_or_natural_key (Union[int, ServiceNaturalKey]): service id (number) or appliation-service_name
key (str): variable name
value (str): environment variable value.
>>> balena.models.service.var.set({'application': 'myorg/myapp', 'service_name': 'service'}, 'VAR', 'value')
>>> balena.models.service.var.set(1234,'test_env4', 'value')
This class implements image model for balena python SDK.
Function: get(id, options) ⇒ ImageType
Get a specific image.
id (int): image id.
options (AnyObject): extra pine options to use.
ImageType: image info.
Get the build log from an image.
id (str): image id.
str: build log.
This class implements all authentication functions for balena python SDK.
This function authenticates provided credentials information. You should use Auth.login when possible, as it takes care of saving the Auth Token and username as well.
**credentials: credentials keyword arguments.
username (str): Balena username.
password (str): Password.
str: Auth Token,
>>> balena.auth.authenticate(username='<your email>', password='<your password>')
Get current logged in actor id.
int: actor id
# If you are logged in.
>>> balena.auth.get_actor_id()
This function retrieves Auth Token.
str: Auth Token.
>>> balena.auth.get_token()
Get current logged in user's info
UserInfo: user info.
# If you are logged in as a user.
>>> balena.auth.get_user_info()
This function checks if you're logged in
bool: True if logged in, False otherwise.
# Check if user logged in.
>>> if balena.auth.is_logged_in():
... print('You are logged in!')
... else:
... print('You are not logged in!')
This function is used for logging into balena using email and password.
**credentials: credentials keyword arguments.
username (str): Balena email.
password (str): Password.
>>> from balena import Balena
... balena = Balena()
... credentials = {'username': '<your email>', 'password': '<your password>'}
... balena.auth.login(**credentials)
... # or
... balena.auth.login(username='<your email>', password='<your password>')
This function is used for logging into balena using Auth Token. Auth Token can be found in Preferences section on balena Dashboard.
token (str): Auth Token.
This functions saves Auth Token to Settings and returns nothing.
>>> from balena import Balena
>>> balena = Balena()
>>> auth_token = <your token>
>>> balena.auth.login_with_token(auth_token)
This function is used for logging out from balena.
# If you are logged in.
>>> balena.auth.logout()
This function is used for registering to balena.
**credentials: credentials keyword arguments.
email (str): email to register.
password (str): Password.
str: Auth Token for new account.
>>> credentials = {'email': '<your email>', 'password': '<your password>'}
>>> balena.auth.register(**credentials)
Function: whoami() ⇒ Union[UserKeyWhoAmIResponse, ApplicationKeyWhoAmIResponse, DeviceKeyWhoAmIResponse, None]
Return current logged in username.
Optional[WhoamiResult]: current logged in information
>>> balena.auth.whoami()
This class implements basic 2FA functionalities for balena python SDK.
Challenge two-factor authentication. If your account has two-factor authentication enabled and logging in using credentials, you need to pass two-factor authentication before being allowed to use other functions.
code (str): two-factor authentication code.
# You need to enable two-factor authentication on dashboard first.
# Check if two-factor authentication is passed for current session.
>>> balena.twofactor_auth.is_passed()
False
>>> balena.twofactor_auth.challenge('123456')
# Check again if two-factor authentication is passed for current session.
>>> balena.twofactor_auth.is_passed()
True
Disable two factor authentication. Note: Disable will only work when using a token that has 2FA enabled.
password (str): password.
str: session token.
>>> balena.twofactor_auth.disable('your_password')
Enable two factor authentication.
code (str): two-factor authentication code.
str: session token.
>>> balena.twofactor_auth.enable('123456')
Retrieves a setup key for enabling two factor authentication. This value should be provided to your 2FA app in order to get a token. This function only works if you disable two-factor authentication or log in using Auth Token from dashboard.
str: setup key.
>>> balena.twofactor_auth.get_setup_key()
Check if two-factor authentication is enabled.
bool: True if enabled. Otherwise False.
>>> balena.twofactor_auth.is_enabled()
Check if two-factor authentication challenge was passed. If the user does not have 2FA enabled, this will be True.
bool: True if passed. Otherwise False.
>>> balena.twofactor_auth.is_passed()
Verifies two factor authentication. Note that this method not update the token automatically. You should use balena.twofactor_auth.challenge() when possible, as it takes care of that as well.
code (str): two-factor authentication code.
str: session token.
>>> balena.twofactor_auth.verify('123456')
This class implements functions that allow processing logs from device.
Get device logs history.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
count (Optional[Union[int, Literal["all"]]]): number of historical messages to include.
Will grecefully unsubscribe from all devices and stop the consumer thread.
Subscribe to device logs.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
callback (Callable[[Log], None]): this callback is called on receiving a message.
error (Optional[Callable[[Any], None]]): this callback is called on an error event.
count (Optional[Union[int, Literal["all"]]]): number of historical messages to include.
Unsubscribe from device logs for a specific device.
uuid_or_id (Union[str, int]): device uuid (string) or id (int)
Unsubscribe all subscribed devices.
Create a module object.
The name must be a string; the optional doc argument can have any type.
{
"name": str,
"description": Optional[str],
"expiry_date": Optional[str]
}
{
"id": int,
"created_at": str,
"name": str,
"description": Optional[str],
"expiry_date": Optional[str],
"is_of__actor": Union[List[ActorType], PineDeferred]
}
{
"id": int,
"is_of__user": Union[List[UserType], PineDeferred, None],
"is_of__application": Union[List[TypeApplication], PineDeferred, None],
"is_of__device": Union[List[TypeDevice], PineDeferred, None],
"is_of__public_device": Union[List[PublicDeviceType], PineDeferred, None],
"api_key": Union[List[APIKeyType], PineDeferred, None]
}
{
"application": Union[List[TypeApplication], PineDeferred],
"can_use__application_as_host": Union[List[TypeApplication], PineDeferred]
}
{
"id": int,
"message": str,
"created_at": str,
"invitationToken": str,
"application_membership_role": Union[List[ApplicationMembershipRoleType], PineDeferred],
"invitee": Union[List[InviteeType], PineDeferred],
"is_invited_to__application": Union[List[ApplicationType], PineDeferred]
}
{
"id": int,
"name": Literal["developer", "operator", "observer"]
}
{
"id": int,
"user": Union[List[UserType], PineDeferred],
"is_member_of__application": Union[List[TypeApplication], PineDeferred],
"application_membership_role": Union[List[ApplicationMembershipRoleType], PineDeferred]
}
{
"id": int,
"name": str,
"slug": str,
"description": Optional[str],
"supports_multicontainer": bool,
"supports_web_url": bool,
"is_legacy": bool,
"requires_payment": bool,
"needs__os_version_range": Optional[str],
"maximum_device_count": Optional[int]
}
{
"id": int,
"tag_key": str,
"value": str
}
{
"id": int,
"username": str
}
{
"id": int,
"slug": str,
"is_supported_by__device_type": Optional[List[CpuArchitectureType]]
}
{
"id": int,
"created_at": str,
"is_created_by__user": Union[List[UserType], PineDeferred, None],
"original_quantity": float,
"total_balance": float,
"total_cost": float,
"payment_status": Literal["processing", "paid", "failed", "complimentary", "cancelled", "refunded"],
"belongs_to__organization": Union[List[OrganizationType], PineDeferred],
"is_for__feature": Any,
"is_associated_with__invoice_id": Optional[str],
"error_message": Optional[str]
}
{
"created_at": str,
"modified_at": str,
"id": int,
"slug": str,
"name": str,
"is_manufactured_by__device_manufacturer": Union[List[DeviceManufacturerType], PineDeferred, None]
}
{
"created_at": str,
"id": int,
"end_timestamp": str,
"is_created_by__actor": Union[List[ActorType], PineDeferred, None],
"is_ended_by__actor": Union[List[ActorType], PineDeferred, None],
"tracks__device": Union[List[TypeDevice], PineDeferred],
"tracks__actor": Union[List[ActorType], PineDeferred, None],
"uuid": Optional[str],
"belongs_to__application": Union[List[TypeApplication], PineDeferred],
"is_active": bool,
"is_running__release": Union[List[ReleaseType], PineDeferred, None],
"should_be_running__release": Union[List[ReleaseType], PineDeferred, None],
"os_version": Optional[str],
"os_variant": Optional[str],
"supervisor_version": Optional[str],
"is_of__device_type": Union[List[DeviceTypeType], PineDeferred, None],
"should_be_managed_by__release": Union[List[ReleaseType], PineDeferred, None]
}
{
"created_at": str,
"modified_at": str,
"id": int,
"slug": str,
"name": str
}
{
"memory_usage": int,
"memory_total": int,
"storage_block_device": str,
"storage_usage": int,
"storage_total": int,
"cpu_usage": int,
"cpu_temp": int,
"cpu_id": str,
"is_undervolted": bool
}
{
"id": int,
"is_referenced_by__alias": str,
"references__device_type": Union[List[DeviceTypeType], PineDeferred]
}
{
"id": int,
"slug": str,
"name": str,
"is_private": bool,
"logo": str,
"contract": Any,
"belongs_to__device_family": Union[List[DeviceFamilyType], PineDeferred, None],
"is_default_for__application": Optional[List[TypeApplication]],
"is_of__cpu_architecture": Union[List[CpuArchitectureType], PineDeferred],
"is_accessible_privately_by__organization": Optional[List[OrganizationType]],
"describes_device": Optional[List[TypeDevice]],
"device_type_alias": Optional[List[DeviceTypeAliasType]]
}
{
"id": int,
"name": str,
"value": str
}
{
"id": int,
"service_name": str
}
{
"id": int,
"download_progress": Optional[float],
"status": str,
"install_date": str,
"installs__image": Union[List[ImageType], PineDeferred],
"device": Union[List[TypeDevice], PineDeferred],
"is_provided_by__release": Union[List[ReleaseType], PineDeferred]
}
{
"id": int,
"created_at": str,
"build_log": str,
"contract": Any,
"content_hash": str,
"project_type": str,
"status": str,
"is_stored_at__image_location": str,
"start_timestamp": str,
"end_timestamp": str,
"push_timestamp": str,
"image_size": str,
"dockerfile": str,
"error_message": str,
"is_a_build_of__service": Union[List[ServiceType], PineDeferred],
"release_image": Optional[List[ReleaseImageType]]
}
{
"id": int,
"created_at": str,
"email": str
}
{
"id": int,
"message": str,
"created_at": str,
"invitationToken": str,
"organization_membership_role": Union[List[OrganizationMembershipRoleType], PineDeferred],
"invitee": Union[List[InviteeType], PineDeferred],
"is_invited_to__organization": Union[List[OrganizationType], PineDeferred]
}
{
"id": int,
"name": Literal["administrator", "member"]
}
{
"organization_membership": Union[List[OrganizationMembershipType], PineDeferred]
}
{
"id": int,
"created_at": str,
"user": Union[List[UserType], PineDeferred],
"is_member_of__organization": Union[List[OrganizationType], PineDeferred],
"organization_membership_role": Union[List[OrganizationMembershipRoleType], PineDeferred],
"effective_seat_role": str,
"organization_membership_tag": Optional[List[OrganizationMembershipTagType]]
}
{
"id": int,
"organization": Union[List[OrganizationType], PineDeferred],
"has_private_access_to__device_type": Union[List[TypeDevice], PineDeferred]
}
{
"id": int,
"created_at": str,
"name": str,
"handle": str,
"logo_image": WebResource,
"has_past_due_invoice_since__date": str,
"application": Optional[List[TypeApplication]],
"organization_membership": Optional[List[OrganizationMembershipType]],
"owns__team": Optional[List[TeamType]],
"organization__has_private_access_to__device_type": Optional[List[OrganizationPrivateDeviceTypeAccess]]
}
{
"_PineDeferred__id": int
}
{
"latitude": str,
"longitude": str,
"belongs_to__application": Union[List[TypeApplication], PineDeferred],
"is_of__device_type": Union[List[TypeDevice], PineDeferred],
"was_recently_online": bool
}
{
"id": int,
"name": str,
"handle": str
}
{
"id": int,
"created_at": str,
"image": Union[List[ImageType], PineDeferred],
"is_part_of__release": Union[List[ReleaseType], PineDeferred]
}
{
"id": int,
"created_at": str,
"commit": str,
"composition": Any,
"contract": Any,
"status": Literal["cancelled", "error", "failed", "interrupted", "local", "running", "success", "timeout"],
"source": str,
"build_log": str,
"is_invalidated": bool,
"start_timestamp": str,
"update_timestamp": str,
"end_timestamp": str,
"phase": Literal["next", "current", "sunset", "end-of-life"],
"semver": str,
"semver_major": int,
"semver_minor": int,
"semver_patch": int,
"semver_prerelease": str,
"semver_build": str,
"variant": str,
"revision": int,
"known_issue_list": str,
"raw_version": str,
"version": ReleaseVersion,
"is_final": bool,
"is_finalized_at__date": str,
"note": str,
"invalidation_reason": str,
"is_created_by__user": Union[List[UserType], PineDeferred, None],
"belongs_to__application": Union[List[TypeApplication], PineDeferred],
"release_image": Optional[List[ReleaseImageType]],
"should_be_running_on__application": Optional[List[TypeApplication]],
"is_running_on__device": Optional[List[TypeDevice]],
"is_pinned_to__device": Optional[List[TypeDevice]],
"should_operate__device": Optional[List[TypeDevice]],
"should_manage__device": Optional[List[TypeDevice]],
"release_tag": Optional[List[BaseTagType]]
}
{
"raw": str,
"major": int,
"minor": int,
"patch": int,
"version": str,
"build": List[str],
"prerelease": List[Union[str, int]]
}
{
"id": int,
"created_at": str,
"commit": str,
"composition": Any,
"contract": Any,
"status": Literal["cancelled", "error", "failed", "interrupted", "local", "running", "success", "timeout"],
"source": str,
"build_log": str,
"is_invalidated": bool,
"start_timestamp": str,
"update_timestamp": str,
"end_timestamp": str,
"phase": Literal["next", "current", "sunset", "end-of-life"],
"semver": str,
"semver_major": int,
"semver_minor": int,
"semver_patch": int,
"semver_prerelease": str,
"semver_build": str,
"variant": str,
"revision": int,
"known_issue_list": str,
"raw_version": str,
"version": ReleaseVersion,
"is_final": bool,
"is_finalized_at__date": str,
"note": str,
"invalidation_reason": str,
"is_created_by__user": Union[List[UserType], PineDeferred, None],
"belongs_to__application": Union[List[TypeApplication], PineDeferred],
"release_image": Optional[List[ReleaseImageType]],
"should_be_running_on__application": Optional[List[TypeApplication]],
"is_running_on__device": Optional[List[TypeDevice]],
"is_pinned_to__device": Optional[List[TypeDevice]],
"should_operate__device": Optional[List[TypeDevice]],
"should_manage__device": Optional[List[TypeDevice]],
"release_tag": Optional[List[BaseTagType]],
"images": List[ImageBasicInfoType],
"user": BasicUserInfoType
}
{
"title": str,
"public_key": str,
"id": int,
"created_at": str,
"user": Union[List[UserType], PineDeferred]
}
{
"id": int,
"created_at": str,
"service_type": str,
"ip_address": str,
"last_heartbeat": str
}
{
"id": int,
"created_at": str,
"service_name": str,
"application": Union[List[TypeApplication], PineDeferred],
"is_built_by__image": Optional[List[ImageType]],
"service_environment_variable": Optional[List[EnvironmentVariableBase]],
"device_service_environment_variable": Optional[List[EnvironmentVariableBase]]
}
{
"id": int,
"team": Union[List[TeamType], PineDeferred],
"grants_access_to__application": Union[List[TypeApplication], PineDeferred],
"application_membership_role": Union[List[ApplicationMembershipRoleType], PineDeferred]
}
{
"id": int,
"created_at": str,
"user": Union[List[UserType], PineDeferred],
"is_member_of__team": Union[List[TeamType], PineDeferred]
}
{
"id": int,
"created_at": str,
"name": str,
"belongs_to__organization": Union[List[OrganizationType], PineDeferred],
"team_membership": Optional[List[TeamMembershipType]],
"team_application_access": Optional[List[TeamApplicationAccessType]]
}
{
"id": int,
"created_at": str,
"app_name": str,
"actor": Union[List[ActorType], PineDeferred],
"slug": str,
"uuid": str,
"is_accessible_by_support_until__date": str,
"is_host": bool,
"should_track_latest_release": bool,
"is_public": bool,
"is_of__class": Literal["fleet", "block", "app"],
"is_archived": bool,
"is_discoverable": bool,
"is_stored_at__repository_url": str,
"public_organization": Union[List[PublicOrganizationType], PineDeferred, None],
"application_type": Union[List[ApplicationType], PineDeferred],
"is_for__device_type": Union[List[DeviceTypeType], PineDeferred],
"depends_on__application": Union[List[ApplicationType], PineDeferred, None],
"organization": Union[List[OrganizationType], PineDeferred],
"should_be_running__release": Union[List[ReleaseType], PineDeferred, None],
"application_config_variable": Optional[List[EnvironmentVariableBase]],
"application_environment_variable": Optional[List[EnvironmentVariableBase]],
"build_environment_variable": Optional[List[EnvironmentVariableBase]],
"application_tag": Optional[List[BaseTagType]],
"owns__device": Optional[List[TypeDevice]],
"owns__public_device": Optional[List[PublicDeviceType]],
"owns__release": Optional[List[ReleaseType]],
"service": Optional[List[ServiceType]],
"is_depended_on_by__application": Optional[List[ApplicationType]],
"is_directly_accessible_by__user": Optional[List[UserType]],
"user_application_membership": Optional[List[ApplicationMembershipType]],
"team_application_access": Optional[List[TeamApplicationAccessType]],
"can_use__application_as_host": Optional[List[ApplicationHostedOnApplication]]
}
{
"id": int,
"created_at": str,
"app_name": str,
"actor": Union[List[ActorType], PineDeferred],
"slug": str,
"uuid": str,
"is_accessible_by_support_until__date": str,
"is_host": bool,
"should_track_latest_release": bool,
"is_public": bool,
"is_of__class": Literal["fleet", "block", "app"],
"is_archived": bool,
"is_discoverable": bool,
"is_stored_at__repository_url": str,
"public_organization": Union[List[PublicOrganizationType], PineDeferred, None],
"application_type": Union[List[ApplicationType], PineDeferred],
"is_for__device_type": Union[List[DeviceTypeType], PineDeferred],
"depends_on__application": Union[List[ApplicationType], PineDeferred, None],
"organization": Union[List[OrganizationType], PineDeferred],
"should_be_running__release": Union[List[ReleaseType], PineDeferred, None],
"application_config_variable": Optional[List[EnvironmentVariableBase]],
"application_environment_variable": Optional[List[EnvironmentVariableBase]],
"build_environment_variable": Optional[List[EnvironmentVariableBase]],
"application_tag": Optional[List[BaseTagType]],
"owns__device": List[TypeDeviceWithServices],
"owns__public_device": Optional[List[PublicDeviceType]],
"owns__release": Optional[List[ReleaseType]],
"service": Optional[List[ServiceType]],
"is_depended_on_by__application": Optional[List[ApplicationType]],
"is_directly_accessible_by__user": Optional[List[UserType]],
"user_application_membership": Optional[List[ApplicationMembershipType]],
"team_application_access": Optional[List[TeamApplicationAccessType]],
"can_use__application_as_host": Optional[List[ApplicationHostedOnApplication]]
}
{
"id": int,
"image_id": int,
"service_id": int,
"download_progress": int,
"status": str,
"install_date": str
}
{
"id": int,
"actor": Union[List[ActorType], PineDeferred],
"created_at": str,
"modified_at": str,
"custom_latitude": str,
"custom_longitude": str,
"device_name": str,
"download_progress": int,
"ip_address": str,
"public_address": str,
"mac_address": str,
"is_accessible_by_support_until__date": str,
"is_connected_to_vpn": bool,
"is_locked_until__date": str,
"is_web_accessible": bool,
"is_active": bool,
"is_frozen": bool,
"is_online": bool,
"last_connectivity_event": str,
"last_vpn_event": str,
"latitude": str,
"local_id": str,
"location": str,
"longitude": str,
"note": str,
"os_variant": str,
"os_version": str,
"provisioning_progress": int,
"provisioning_state": str,
"status": str,
"supervisor_version": str,
"uuid": str,
"api_heartbeat_state": Literal["online", "offline", "timeout", "unknown"],
"memory_usage": int,
"memory_total": int,
"storage_block_device": str,
"storage_usage": int,
"storage_total": int,
"cpu_usage": int,
"cpu_temp": int,
"cpu_id": str,
"is_undervolted": bool,
"overall_status": Literal["configuring", "inactive", "post-provisioning", "updating", "operational", "disconnected", "reduced-functionality"],
"overall_progress": int,
"is_of__device_type": Union[List[DeviceTypeType], PineDeferred],
"belongs_to__application": Union[List[TypeApplication], PineDeferred],
"belongs_to__user": Union[List[UserType], PineDeferred, None],
"is_running__release": Union[List[ReleaseType], PineDeferred, None],
"is_pinned_on__release": Union[List[ReleaseType], PineDeferred, None],
"is_managed_by__service_instance": Union[List[ServiceInstanceType], PineDeferred, None],
"should_be_operated_by__release": Union[List[ReleaseType], PineDeferred, None],
"should_be_managed_by__release": Union[List[ReleaseType], PineDeferred, None],
"device_config_variable": Optional[List[EnvironmentVariableBase]],
"device_environment_variable": Optional[List[EnvironmentVariableBase]],
"device_tag": Optional[List[BaseTagType]],
"service_install": Optional[List[ServiceInstanceType]],
"image_install": Optional[List[ImageInstallType]]
}
{
"id": int,
"actor": Union[List[ActorType], PineDeferred],
"created_at": str,
"modified_at": str,
"custom_latitude": str,
"custom_longitude": str,
"device_name": str,
"download_progress": int,
"ip_address": str,
"public_address": str,
"mac_address": str,
"is_accessible_by_support_until__date": str,
"is_connected_to_vpn": bool,
"is_locked_until__date": str,
"is_web_accessible": bool,
"is_active": bool,
"is_frozen": bool,
"is_online": bool,
"last_connectivity_event": str,
"last_vpn_event": str,
"latitude": str,
"local_id": str,
"location": str,
"longitude": str,
"note": str,
"os_variant": str,
"os_version": str,
"provisioning_progress": int,
"provisioning_state": str,
"status": str,
"supervisor_version": str,
"uuid": str,
"api_heartbeat_state": Literal["online", "offline", "timeout", "unknown"],
"memory_usage": int,
"memory_total": int,
"storage_block_device": str,
"storage_usage": int,
"storage_total": int,
"cpu_usage": int,
"cpu_temp": int,
"cpu_id": str,
"is_undervolted": bool,
"overall_status": Literal["configuring", "inactive", "post-provisioning", "updating", "operational", "disconnected", "reduced-functionality"],
"overall_progress": int,
"is_of__device_type": Union[List[DeviceTypeType], PineDeferred],
"belongs_to__application": Union[List[TypeApplication], PineDeferred],
"belongs_to__user": Union[List[UserType], PineDeferred, None],
"is_running__release": Union[List[ReleaseType], PineDeferred, None],
"is_pinned_on__release": Union[List[ReleaseType], PineDeferred, None],
"is_managed_by__service_instance": Union[List[ServiceInstanceType], PineDeferred, None],
"should_be_operated_by__release": Union[List[ReleaseType], PineDeferred, None],
"should_be_managed_by__release": Union[List[ReleaseType], PineDeferred, None],
"device_config_variable": Optional[List[EnvironmentVariableBase]],
"device_environment_variable": Optional[List[EnvironmentVariableBase]],
"device_tag": Optional[List[BaseTagType]],
"service_install": Optional[List[ServiceInstanceType]],
"image_install": Optional[List[ImageInstallType]],
"current_services": Dict[str, List[TypeCurrentService]]
}
{
}
{
}
{
"id": int,
"actor": Union[List[ActorType], PineDeferred],
"created_at": str,
"username": str,
"organization_membership": Optional[List[OrganizationMembershipType]],
"user_application_membership": Optional[List[ApplicationMembershipType]],
"team_membership": Optional[List[TeamMembershipType]],
"has_direct_access_to__application": Optional[List[TypeApplication]]
}
{
"filename": str,
"href": str,
"content_type": str,
"content_disposition": str,
"size": int
}