v16.0.0

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.

Table of Contents

• 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

        • get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[BaseTagType]

        • remove(slug_or_uuid_or_id, tag_key) ⇒ None

        • set(slug_or_uuid_or_id, tag_key, value) ⇒ None

      • .config_var

        • get(slug_or_uuid_or_id, env_var_name) ⇒ Optional[str]

        • get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

        • remove(slug_or_uuid_or_id, key) ⇒ None

        • set(slug_or_uuid_or_id, env_var_name, value) ⇒ None

      • .env_var

        • get(slug_or_uuid_or_id, env_var_name) ⇒ Optional[str]

        • get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

        • remove(slug_or_uuid_or_id, key) ⇒ None

        • set(slug_or_uuid_or_id, env_var_name, value) ⇒ None

      • .build_var

        • get(slug_or_uuid_or_id, env_var_name) ⇒ Optional[str]

        • get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

        • remove(slug_or_uuid_or_id, key) ⇒ None

        • set(slug_or_uuid_or_id, env_var_name, value) ⇒ None

      • .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

      • .invite

        • accept(invite_token) ⇒ None

        • create(slug_or_uuid_or_id, options) ⇒ ApplicationInviteType

        • get_all(options) ⇒ List[ApplicationInviteType]

        • get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[ApplicationInviteType]

        • revoke(invite_id) ⇒ None

    • .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

        • get(uuid_or_id, tag_key) ⇒ Optional[str]

        • get_all(options) ⇒ List[BaseTagType]

        • get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[BaseTagType]

        • get_all_by_device(uuid_or_id, options) ⇒ List[BaseTagType]

        • remove(uuid_or_id, tag_key) ⇒ None

        • set(uuid_or_id, tag_key, value) ⇒ None

      • .config_var

        • get(uuid_or_id, env_var_name) ⇒ 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, key) ⇒ None

        • set(uuid_or_id, env_var_name, value) ⇒ None

      • .env_var

        • get(uuid_or_id, env_var_name) ⇒ 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, key) ⇒ None

        • set(uuid_or_id, env_var_name, value) ⇒ None

      • .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

      • .history

        • get_all_by_application(slug_or_uuid_or_id, from_date, to_date, options) ⇒ List[DeviceHistoryType]

        • get_all_by_device(uuid_or_id, from_date, to_date, options) ⇒ List[DeviceHistoryType]

    • .device_type

      • get(id_or_slug, options) ⇒ DeviceTypeType

      • get_all(options) ⇒ List[DeviceTypeType]

      • get_all_supported(options) ⇒ None

      • get_by_slug_or_name(slug_or_name, options) ⇒ DeviceTypeType

      • get_name(slug) ⇒ str

      • get_slug_by_name(name) ⇒ str

    • .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

    • .key

      • create(title, key) ⇒ SSHKeyType

      • get(id) ⇒ SSHKeyType

      • get_all(options) ⇒ List[SSHKeyType]

      • remove(id) ⇒ None

    • .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

      • .invite

        • accept(invite_token) ⇒ None

        • create(handle_or_id, invitee, role_name, message) ⇒ OrganizationInviteType

        • get_all(options) ⇒ List[OrganizationInviteType]

        • get_all_by_organization(handle_or_id, options) ⇒ List[OrganizationInviteType]

        • revoke(invite_id) ⇒ None

    • .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

    • .config

      • get_all() ⇒ ConfigType

    • .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

    • .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

    • .image

      • get(id, options) ⇒ ImageType

      • get_logs(id) ⇒ str

  • .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

  • .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

  • .settings

  • .types

Models

This module implements all models for balena python SDK.

Application

This class implements application model for balena python SDK.

Function: create(name, device_type, organization, application_class) ⇒ TypeApplication

Create an application.

Args:

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.

Returns:

TypeApplication: application info.

Examples:

>>> balena.models.application.create('foo', 'raspberry-pi', 12345)
>>> balena.models.application.create('foo', 'raspberry-pi', 12345, 'block')

Function: disable_device_urls(slug_or_uuid_or_id) ⇒ None

Disable device urls for all devices that belong to an application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).

Examples:

>>> balena.models.application.disable_device_urls(5685)

Function: enable_device_urls(slug_or_uuid_or_id) ⇒ None

Enable device urls for all devices that belong to an application

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).

Examples:

>>> balena.models.application.enable_device_urls(5685)

Function: generate_provisioning_key(slug_or_uuid_or_id, key_name, description, expiry_date) ⇒ str

Generate a device provisioning key for a specific application.

Args:

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`.

Returns:

str: device provisioning key.

Examples:

>>> balena.models.application.generate_provisioning_key(5685)

Function: get(slug_or_uuid_or_id, options, context) ⇒ TypeApplication

Get a single application.

Args:

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'

Returns:

TypeApplication: application info.

Examples:

>>> balena.models.application.get("myorganization/myapp")
>>> balena.models.application.get(123)

Function: get_all(options, context) ⇒ List[TypeApplication]

Get all applications

Args:

options (AnyObject): extra pine options to use
context (Optional[str]): extra access filters, None or 'directly_accessible'

Returns:

List[TypeApplication]: application info.

Examples:

>>> balena.models.application.get_all()

Function: get_all_by_organization(org_handle_or_id, options) ⇒ List[TypeApplication]

Get all applications of an organization.

Args:

org_handle_or_id (Union[str, int]): handle or id of the organization.
options (AnyObject): extra pine options to use.

Returns:

List[TypeApplication]: application info.

Examples:

>>> balena.models.application.get_all_by_organization('myorg')

Function: get_all_directly_accessible(options) ⇒ List[TypeApplication]

Get all applications directly accessible by the user

Args:

options (AnyObject): extra pine options to use

Returns:

List[APIKeyType]: user API key

Examples:

>>> balena.models.application.get_all_directly_accessible()

Function: get_by_name(app_name, options, context) ⇒ TypeApplication

Get a single application using the appname.

Args:

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'

Returns:

TypeApplication: application info.

Examples:

>>> balena.models.application.get("myapp")

Function: get_dashboard_url(app_id) ⇒ str

Get Dashboard URL for a specific application.

Args:

app_id (int): application id.

Returns:

str: Dashboard URL for the specific application.

Examples:

>>> 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

Args:

slug_or_uuid_or_id (str): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

TypeApplication: application info.

Examples:

>>> balena.models.application.get_directly_accessible("myorganization/myapp")
>>> balena.models.application.get_directly_accessible(123)

Function: get_id(slug_or_uuid_or_id) ⇒ int

Given an application slug or uuid or id, returns it numeric id.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)

Returns:

int: The id.

Examples:

>>> balena.models.application.get_dashboard_url(1476418)

Function: get_target_release_hash(slug_or_uuid_or_id) ⇒ Optional[str]

Get the hash of the current release for a specific application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)

Returns:

Optional[str]: The release hash of the current release or None.

Examples:

>>> 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.

Args:

slug_or_uuid_or_id (str): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

TypeApplication: application info.

Examples:

>>> balena.models.application.get_with_device_service_details('my_org_handle/my_app_name')

Function: grant_support_access(slug_or_uuid_or_id, expiry_timestamp) ⇒ None

Grant support access to an application until a specified time.

Args:

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.

Examples:

>>> balena.models.application.grant_support_access(5685, 1511974999000)

Function: has(slug_or_uuid_or_id) ⇒ bool

Check if an application exists.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)

Returns:

bool: True if application exists, False otherwise.

Examples:

>>> balena.models.application.has('my_org/foo')

Function: has_any() ⇒ bool

Check if the user has any applications.

Returns:

bool: True if user has any applications, False otherwise.

Examples:

>>> balena.models.application.has_any()

Function: is_tracking_latest_release(slug_or_uuid_or_id) ⇒ bool

Get whether the application is up to date and is tracking the latest finalized release for updates

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).

Returns:

bool: is tracking the latest release.

Examples:

>>> balena.models.application.is_tracking_latest_release(5685)

Function: pin_to_release(slug_or_uuid_or_id, full_release_hash) ⇒ None

Configures the application to run a particular release and not get updated when the latest release changes.

Args:

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)

Examples:

>>> balena.models.application.set_to_release(5685, '7dba4e0c461215374edad74a5b78f470b894b5b7')

Function: purge(app_id) ⇒ None

Purge devices by application id

Args:

app_id (int): application id (number)

Examples:

>>> balena.models.application.purge(5685)

Function: reboot(app_id, options) ⇒ None

Reboots devices by application id

Args:

app_id (int): application id (number)
options (ShutdownOptions): override update lock

Examples:

>>> balena.models.application.reboot(5685)
>>> balena.models.application.reboot(5685, {"force": True})

Function: remove(slug_or_uuid_or_id) ⇒ None

Remove application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).

Examples:

>>> balena.models.application.remove('my_org/my_app')
>>> balena.models.application.remove('c184556293854781aea71b0bdae10e45')
>>> balena.models.application.remove(123)

Function: rename(slug_or_uuid_or_id, new_name) ⇒ None

Rename application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
new_name (str): new application name.

Examples:

>>> balena.models.application.rename(1681618, 'py-test-app')

Function: restart(slug_or_uuid_or_id) ⇒ None

Restart application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).

Examples:

>>> balena.models.application.restart('myorg/RPI1')

Function: revoke_support_access(slug_or_uuid_or_id) ⇒ None

Revoke support access to an application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).

Examples:

>>> balena.models.application.revoke_support_access(5685)

Function: shutdown(app_id, options) ⇒ None

Shutdown devices by application id

Args:

app_id (int): application id (number)
options (ShutdownOptions): override update lock

Examples:

>>> balena.models.application.shutdown(5685)
>>> balena.models.application.shutdown(5685, {"force": True})

Function: track_latest_release(slug_or_uuid_or_id) ⇒ None

Configure a specific application to track the latest available release.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)

Examples:

>>> balena.models.application.track_latest_release(5685)

Function: will_track_new_releases(slug_or_uuid_or_id) ⇒ bool

Get whether the application is configured to receive updates whenever a new release is available.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).

Returns:

bool: is tracking the latest release.

Examples:

>>> balena.models.application.will_track_new_releases(5685)

ApplicationTag

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.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[BaseTagType]: tags list.

Examples:

>>> balena.models.application.tags.get_all_by_application(1005160)

Function: remove(slug_or_uuid_or_id, tag_key) ⇒ None

Remove an application tag.

Args:

slug_or_uuid_or_id (int): application slug (string), uuid (string) or id (number)
tag_key (str): tag key.

Examples:

>>> balena.models.application.tags.remove(1005767, 'tag1')

Function: set(slug_or_uuid_or_id, tag_key, value) ⇒ None

Set an application tag (update tag value if it exists).

Args:

slug_or_uuid_or_id (int): application slug (string), uuid (string) or id (number)
tag_key (str): tag key.
value (str): tag value.

Returns:

List[BaseTagType]: tags list.

Examples:

>>> balena.models.application.tags.set(1005767, 'tag1', 'Python SDK')

ApplicationConfigVariable

This class implements application config variable model for balena python SDK.

Function: get(slug_or_uuid_or_id, env_var_name) ⇒ Optional[str]

Get application config variable.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
env_var_name (str): environment variable name.

Examples:

>>> balena.models.application.config_var.get('8deb12a7d7592c2b7f9e44735c2b0a41','test_env4')

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

Get all application config variables by application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: application config variables.

Examples:

>>> balena.models.application.config_var.get_all_by_application(9020)

Function: remove(slug_or_uuid_or_id, key) ⇒ None

Remove an application config variable.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
key (str): environment variable name.

Examples:

>>> balena.models.application.config_var.remove(2184, 'test_env')

Function: set(slug_or_uuid_or_id, env_var_name, value) ⇒ None

Set the value of a specific application config variable.

Args:

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.

Examples:

>>> balena.models.application.config_var.set('8deb12a7d7592c2b7f9e44735c2b0a41','test_env', 'testing1')

ApplicationEnvVariable

This class implements application environment variable model for balena python SDK.

Function: get(slug_or_uuid_or_id, env_var_name) ⇒ Optional[str]

Get application environment variable.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
env_var_name (str): environment variable name.

Examples:

>>> balena.models.application.env_var.get('8deb12a7d7592c2b7f9e44735c2b0a41','test_env4')

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

Get all application environment variables by application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: application environment variables.

Examples:

>>> balena.models.application.env_var.get_all_by_application(9020)
>>> balena.models.application.env_var.get_all_by_application("myorg/myslug")

Function: remove(slug_or_uuid_or_id, key) ⇒ None

Remove an application environment variable.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
key (str): environment variable name.

Examples:

>>> balena.models.application.env_var.remove(2184,'test_env4')

Function: set(slug_or_uuid_or_id, env_var_name, value) ⇒ None

Set the value of a specific application environment variable.

Args:

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.

Examples:

>>> balena.models.application.env_var.set('8deb12a7d7592c2b7f9e44735c2b0a41','test_env4', 'testing1')

BuildEnvVariable

This class implements build environment variable model for balena python SDK.

Function: get(slug_or_uuid_or_id, env_var_name) ⇒ Optional[str]

Get build environment variable.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
env_var_name (str): environment variable name.

Examples:

>>> balena.models.application.build_var.get('8deb12a7d7592c2b7f9e44735c2b0a41','test_env4')

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

Get all build environment variables by application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: build environment variables.

Examples:

>>> balena.models.application.build_var.get_all_by_application(9020)
>>> balena.models.application.build_var.get_all_by_application("myorg/myslug")

Function: remove(slug_or_uuid_or_id, key) ⇒ None

Remove an build environment variable.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
key (str): environment variable name.

Examples:

>>> balena.models.application.build_var.remove(2184, 'test_env4')

Function: set(slug_or_uuid_or_id, env_var_name, value) ⇒ None

Set the value of a specific build environment variable.

Args:

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.

Examples:

>>> balena.models.application.build_var.set('8deb12a7d7592c2b7f9e44735c2b0a41','test_env4', 'testing1')

ApplicationMembership

This class implements application membership model for balena python SDK.

Function: change_role(membership_id, role_name) ⇒ None

Changes the role of an application member.

Args:

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.

Examples:

>>> 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.

Args:

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.

Returns:

ApplicationMembershipType: application membership.

Examples:

>>> balena.models.application.membership.create(1681618, 'testuser')

Function: get(membership_id, options) ⇒ ApplicationMembershipType

Get a single application membership.

Args:

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

Returns:

ApplicationMembershipType: application membership.

Examples:

>>> 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.

Args:

options (AnyObject): extra pine options to use

Returns:

List[ApplicationMembershipType]: list contains info of application memberships.

Examples:

>>> balena.models.application.membership.get_all()

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[ApplicationMembershipType]

Get all memberships by application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
options (AnyObject): extra pine options to use

Returns:

list: list contains info of application memberships.

Examples:

>>> balena.models.application.membership.get_all_by_application(1681618)

Function: remove(membership_id) ⇒ None

Remove a membership.

Args:

membership_id (ResourceKey): the id or an object with the unique `user` & `is_member_of__application`

ApplicationInvite

This class implements application invite model for balena python SDK.

Function: accept(invite_token) ⇒ None

Accepts an invite.

Args:

invite_token (str): invitationToken - invite token.

Examples:

>>> balena.models.application.invite.accept("qwerty-invitation-token")

Function: create(slug_or_uuid_or_id, options) ⇒ ApplicationInviteType

Creates a new invite for an application.

Args:

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.

Returns:

dict: application invite.

Examples:

>>> balena.models.application.invite.create(1681618, '[email protected]', 'developer', 'Test invite')

Function: get_all(options) ⇒ List[ApplicationInviteType]

Get all invites.

Args:

options (AnyObject): extra pine options to use

Returns:

List[ApplicationInviteType]: list contains info of invites.

Examples:

>>> balena.models.application.invite.get_all()

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[ApplicationInviteType]

Get all invites by application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
options (AnyObject): extra pine options to use

Returns:

List[ApplicationInviteType]: list contains info of invites.

Examples:

>>> balena.models.application.invite.get_all_by_application(1681618)

Function: revoke(invite_id) ⇒ None

Revoke an invite.

Args:

invite_id (int): application invite id.

Examples:

>>> balena.models.application.invite.revoke(5860)

Device

This class implements device model for balena python SDK.

Function: deactivate(uuid_or_id_or_ids) ⇒ None

Deactivates a device.

Args:

uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])

Examples:

>>> balena.models.device.deactivate('44cc9d1861b9f992808c506276e5d31c')
>>> balena.models.device.deactivate([123, 234])

Function: disable_device_url(uuid_or_id_or_ids) ⇒ None

Disable device url for a device.

Args:

uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int]).

Examples:

>>> balena.models.device.disable_device_url('8deb12a7d7592c2b7f9e44735c2b0a41')
>>> balena.models.device.disable_device_url([123, 345])

Function: disable_local_mode(uuid_or_id) ⇒ None

Disable local mode.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

None.

Examples:

>>> balena.models.device.disable_local_mode('b6070f4fea5a4f11b4d05c1f1c3b4e72')

Function: disable_lock_override(uuid_or_id) ⇒ None

Disable lock override.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Function: enable_device_url(uuid_or_id_or_ids) ⇒ None

Enable device url for a device.

Args:

uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int]).

Examples:

>>> balena.models.device.enable_device_url('8deb12a7d7592c2b7f9e44735c2b0a41')
>>> balena.models.device.enable_device_url([123, 345])

Function: enable_local_mode(uuid_or_id) ⇒ None

Enable local mode.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Examples:

>>> balena.models.device.enable_local_mode('b6070f4fea5a4f11b4d05c1f1c3b4e72')

Function: enable_lock_override(uuid_or_id) ⇒ None

Enable lock override.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Function: generate_device_key(uuid_or_id, name, description, expiry_date) ⇒ str

Generate a device key.

Args:

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`.

Examples:

>>> balena.models.device.generate_device_key('df0926d8a5cf4293a1b3742c98a500a1')

Function: generate_uuid() ⇒ str

Generate a random device UUID.

Returns:

str: a generated UUID.

Examples:

>>> balena.models.device.generate_uuid()

Function: get(uuid_or_id, options) ⇒ TypeDevice

This method returns a single device by id or uuid.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
options (AnyObject): extra pine options to use

Returns:

TypeDevice: device info.

Examples:

>>> balena.models.device.get('8deb12a58e3b6d3920db1c2b6303d1ff32f23d5ab99781ce1dde6876e8d143')
>>> balena.models.device.get('8deb12a7d7592c2b7f9e44735c2b0a41')
>>> 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

Args:

options (AnyObject): extra pine options to use

Returns:

List[TypeDevice]: list contains info of devices.

Examples:

>>> 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.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[TypeDevice]: list contains info of devices.

Examples:

>>> 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.

Args:

handle_or_id (Union[str, int]): organization handle (string) or id (number).
options (AnyObject): extra pine options to use

Returns:

List[TypeDevice]: list contains info of devices.

Examples:

>>> balena.models.device.get_all_by_organization('my_org')
>>> balena.models.device.get_all_by_organization(123)

Function: get_application_info(uuid_or_id) ⇒ Any

Deprecated Return information about the application running on the device. This function requires supervisor v1.8 or higher.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int).

Returns:

dict: dictionary contains application information.

Examples:

>>> balena.models.device.get_application_info('7f66ec3c5da146c3b6a84aaed1c07581')

Function: get_application_name(uuid_or_id) ⇒ str

Get application name by device uuid.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

str: application name.

Function: get_by_name(name, options) ⇒ List[TypeDevice]

Get devices by device name.

Args:

name (str): device name.

Returns:

List[TypeDevice]: list contains info of devices.

Examples:

>>> balena.models.device.get_by_name('floral-mountain')

Function: get_dashboard_url(uuid) ⇒ None

Get balena Dashboard URL for a specific device.

Args:

uuid (str): device uuid.

Examples:

>>> balena.models.device.get_dashboard_url('19619a6317072b65a240b451f45f855d')

Function: get_device_url(uuid_or_id) ⇒ str

Get a device url for a device.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Examples:

>>> balena.models.device.get_device_url('8deb12a7d7592c2b7f9e44735c2b0a41')

Function: get_local_ip_address(uuid_or_id) ⇒ List[str]

Get the local IP addresses of a device.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

List[str]: IP addresses of a device.

Function: get_local_mode_support(uuid_or_id) ⇒ LocalModeResponse

Returns whether local mode is supported and a message describing the reason why local mode is not supported.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

dict: local mode support information ({'supported': True/False, 'message': '...'}).

Examples:

>>> balena.models.device.get_local_mode_support('b6070f4fea5a4f11b4d05c1f1c3b4e72')

Function: get_mac_address(uuid_or_id) ⇒ List[str]

Get the MAC addresses of a device.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

List[str]: MAC addresses of a device.

Function: get_metrics(uuid_or_id) ⇒ DeviceMetricsType

Gets the metrics related information for a device.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

dict: metrics of the device.

Function: get_name(uuid_or_id) ⇒ str

Get device name by device uuid.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

str: device name.

Function: get_os_update_status(uuid_or_id) ⇒ HUPStatusResponse

Deprecated Get the OS update status of a device.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int).

Returns:

HUPStatusResponse: action response.

Examples:

>>> balena.models.device.get_os_update_status('b6070f4fea5a4f11b4d05c1f1c3b4e72')

Function: get_status(uuid_or_id) ⇒ str

Get the status of a device.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

str: status of a device.

Examples:

>>> balena.models.device.get_status('8deb12a7d7592c2b7f9e44735c2b0a41')

Function: get_supervisor_state(uuid_or_id) ⇒ SupervisorStateType

Get the supervisor state on a device

Args:

uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.

Returns:

dict: supervisor state.

Examples:

>>> balena.models.device.get_supervisor_state('b6070f4fea5a4f11b4d05c1f1c3b4e72')

Function: get_supervisor_target_state(uuid_or_id) ⇒ Any

Get the supervisor target state on a device

Args:

uuid_or_id (Union[str, int]): device uuid (str) or id (int).

Returns:

DeviceStateType: supervisor target state.

Examples:

>>> balena.models.device.get_supervisor_target_state('b6070f4fea5edf808b576123157fe5ec')

Function: get_supervisor_target_state_for_app(slug_or_uuid_or_id, release) ⇒ Any

Get the supervisor target state on a device

Args:

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)

Returns:

DeviceStateType: supervisor target state.

Examples:

>>> 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.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
options (AnyObject): extra pine options to use

Returns:

dict: device info with associated services details.

Examples:

>>> balena.models.device.get_with_service_details('0fcd753af396247e035de53b4e43eec3')

Function: grant_support_access(uuid_or_id_or_ids, expiry_timestamp) ⇒ None

Grant support access to a device until a specified time.

Args:

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.

Examples:

>>> balena.models.device.grant_support_access('49b2a76e8a8d4a2b918c08a23b423580', 1511974999000)

Function: has(uuid_or_id) ⇒ bool

Check if a device exists.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

bool: True if device exists, False otherwise.

Function: has_device_url(uuid_or_id) ⇒ bool

Check if a device is web accessible with device urls

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Examples:

>>> balena.models.device.has_device_url('8deb12a7d7592c2b7f9e44735c2b0a41')

Function: has_lock_override(uuid_or_id) ⇒ bool

Check if a device has the lock override enabled.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

bool: lock override status.

Function: identify(uuid_or_id) ⇒ None

Identify device.

Args:

uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.

Examples:

>>> balena.models.device.identify('8deb12a7d7592c2b7f9e44735c2b0a41')

Function: is_in_local_mode(uuid_or_id) ⇒ bool

Check if local mode is enabled on the device.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

bool: True if local mode enabled, otherwise False.

Examples:

>>> balena.models.device.is_in_local_mode('b6070f4fea5a4f11b4d05c1f1c3b4e72')

Function: is_online(uuid_or_id) ⇒ bool

Check if a device is online.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

bool: True if the device is online, False otherwise.

Function: is_tracking_application_release(uuid_or_id) ⇒ bool

Get whether the device is configured to track the current application release.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Returns:

bool: is tracking the current application release.

Function: move(uuid_or_id, app_slug_or_uuid_or_id) ⇒ None

Move a device to another application.

Args:

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).

Examples:

>>> balena.models.device.move(123, 'RPI1Test')

Function: pin_to_release(uuid_or_id, full_release_hash_or_id) ⇒ None

Configures the device to run a particular release and not get updated when the current application release changes.

Args:

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)

Examples:

>>> balena.models.device.set_to_release('49b2a', '45c90004de73557ded7274d4896a6db90ea61e36')

Function: ping(uuid_or_id) ⇒ None

Ping a device. This is useful to signal that the supervisor is alive and responding.

Args:

uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.

Examples:

>>> balena.models.device.ping('8f66ec7335dd4a97b7661faa131b1502')
>>> balena.models.device.ping(1234)

Function: purge(uuid_or_id) ⇒ None

Purge device. This function clears the user application's /data directory.

Args:

uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.

Examples:

>>> balena.models.device.purge('8f66ec7335dd4a97b7661faa131b1502')

Function: reboot(uuid_or_id, force) ⇒ None

Reboot the device.

Args:

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.

Examples:

>>> balena.models.device.reboot('8f66ec7335dd4a97b7661faa131b1502')

Function: register(application_slug_or_uuid_or_id, uuid, device_type_slug) ⇒ RegisterResponse

Register a new device with a balena application.

Args:

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.

Returns:

dict: dictionary contains device info.

Examples:

>>> device_uuid = balena.models.device.generate_uuid()
>>> balena.models.device.register('RPI1',device_uuid)

Function: remove(uuid_or_id_or_ids) ⇒ None

Remove device(s).

Args:

uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])

Function: rename(uuid_or_id, new_name) ⇒ None

Renames a device.

Args:

uuid_or_id (Union[str, int]): device uuid (str) or id (int)
new_name (str): device new name.

Examples:

>>> balena.models.device.rename(123, 'python-sdk-test-device')

Function: restart_application(uuid_or_id) ⇒ None

This function restarts the Docker container running the application on the device, but doesn't reboot the device itself.

Args:

uuid_or_id (Optional[Union[str, int]]): device uuid (str) or id (int) or None for SDK running on device.

Examples:

>>> balena.models.device.restart_application('8deb12a7d7592c2b7f9e44735c2b0a41')
>>> balena.models.device.restart_application(1234)

Function: restart_service(uuid_or_id, image_id) ⇒ None

Restart a service on device.

Args:

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

Examples:

>>> balena.models.device.restart_service('f3887b1de5b54c6a9e6e5e3a2e57b642', 392229)
>>> balena.models.device.restart_service(None, 392229)  # if running on the device

Function: revoke_support_access(uuid_or_id_or_ids) ⇒ None

Revoke support access to a device.

Args:

uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])

Examples:

>>> balena.models.device.revoke_support_access('49b2a76e8a8d4a2b918c08a23b423580')

Function: set_custom_location(uuid_or_id_or_ids, location) ⇒ None

Set a custom location for a device.

Args:

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]}.

Examples:

>>> balena.models.device.set_custom_location(123, {'latitude': '21.032777','longitude': '105.831586'})

Function: set_note(uuid_or_id_or_ids, note) ⇒ None

Note a device.

Args:

uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])
note (str): device note.

Examples:

>>> balena.models.device.note(123, 'test note')

Function: set_supervisor_release(uuid_or_id, supervisor_version_or_id) ⇒ None

Set a specific device to run a particular supervisor release.

Args:

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)

Examples:

>>> balena.models.device.set_supervisor_release('f55dcdd9ada04b11b4d05c1f1c3b4e72', 'v13.0.0')

Function: shutdown(uuid_or_id, force) ⇒ None

Shutdown the device.

Args:

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.

Examples:

>>> balena.models.device.shutdown('8f66ec7335dd4a97b7661faa131b1502')

Function: start_application(uuid_or_id) ⇒ None

Deprecated Starts a user application container, usually after it has been stopped with stop_application(). This function requires supervisor v1.8 or higher.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int).

Returns:

dict: dictionary contains started application container id.

Examples:

>>> balena.models.device.start_application('8f66ec7335dd4a97b7661faa131b1502')

Function: start_os_update(uuid_or_id, target_os_version) ⇒ HUPStatusResponse

Start an OS update on a device.

If using run_detached option, monitor progress with device.get() -- status, provisioning_state and provisioning_progress entries.

Args:

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.

Returns:

HUPStatusResponse: action response.

Examples:

>>> balena.models.device.start_os_update('b6070f4fea5a4f11b4d05c1f1c3b4e72', '2.29.2+rev1.prod')
>>> balena.models.device.start_os_update('b6070f4fea5a4f11b4d05c1f1c3b4e72', '2.89.0+rev1')
>>> balena.models.device.start_os_update('b6070f4fea5a4f11b4d05c1f1c3b4e72', '2.89.0+rev1', run_detached=True)

Function: start_service(uuid_or_id, image_id) ⇒ None

Start a service on device.

Args:

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

Examples:

>>> balena.models.device.start_service('f3887b1de5b54c6a9e6e5e3a2e57b642', 1234)
>>> balena.models.device.start_service(None, 1234)  # if running on the device

Function: stop_application(uuid_or_id) ⇒ None

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.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int).

Returns:

dict: dictionary contains stopped application container id.

Examples:

>>> balena.models.device.stop_application('8f66ec7335dd4a97b7661faa131b1502')

Function: stop_service(uuid_or_id, image_id) ⇒ None

Stop a service on device.

Args:

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

Examples:

>>> balena.models.device.stop_service('f3887b1de5b54c6a9e6e5e3a2e57b642', 392229)
>>> balena.models.device.stop_service(None, 392229)  # if running on the device

Function: track_application_release(uuid_or_id_or_ids) ⇒ None

Configure a specific device to track the current application release.

Args:

uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])

Function: unset_custom_location(uuid_or_id_or_ids) ⇒ None

Clear the custom location of a device.

Args:

uuid_or_id_or_ids (Union[str, int, List[int]]): device uuid (str) or id (int) or ids (List[int])

Examples:

>>> balena.models.device.unset_custom_location(123)

Function: update(uuid_or_id, force) ⇒ None

update the device.

Args:

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.

Examples:

>>> balena.models.device.update('8f66ec7335dd4a97b7661faa131b1502')

DeviceTag

This class implements device tag model for balena python SDK.

Function: get(uuid_or_id, tag_key) ⇒ Optional[str]

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.

Args:

uuid_or_id (Union[str, int]): device uuid or device id.
tag_key (str): tag key.

Returns:

Optional[str]: tag value

Examples:

>>> balena.models.device.tags.get('f5213eac0d63ac4', 'testtag')

Function: get_all(options) ⇒ List[BaseTagType]

Get all device tags.

Args:

options (AnyObject): extra pine options to use

Returns:

List[BaseTagType]: tags list.

Examples:

>>> 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.

Args:

slug_or_uuid_or_id (int): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[BaseTagType]: tags list.

Examples:

>>> 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.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[BaseTagType]: tags list.

Examples:

>>> balena.models.device.tags.get_all_by_device('a03ab646ca5a4f11b4d05c1f1c3b4e72')

Function: remove(uuid_or_id, tag_key) ⇒ None

Remove a device tag.

Args:

uuid_or_id (Union[str, int]): device uuid or device id.
tag_key (str): tag key.

Examples:

>>> balena.models.device.tags.remove('f5213eac0d63ac477', 'testtag')

Function: set(uuid_or_id, tag_key, value) ⇒ None

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.

Args:

uuid_or_id (Union[str, int]): device uuid or device id.
tag_key (str): tag key.
value (str): tag value.

Examples:

>>> balena.models.device.tags.set('f5213eac0d63ac4', 'testtag', 'test1')
>>> balena.models.device.tags.set('f5213eac0d63ac4', 'testtag', 'test2')

DeviceConfigVariable

This class implements device config variable model for balena python SDK.

Function: get(uuid_or_id, env_var_name) ⇒ Optional[str]

Get a device config variable.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
env_var_name (str): environment variable name.

Examples:

>>> balena.models.device.config_var.device.get('8deb12a7d7592c2b7f9e44735c2b0a41','test_env4')

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

Get all device config variables for an application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: list of device environment variables.

Examples:

>>> 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.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: device config variables.

Examples:

>>> balena.models.device.config_var.get_all_by_device('f5213eac574a4fba8b9e32ab3a9cba12')

Function: remove(uuid_or_id, key) ⇒ None

Remove a device environment variable.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
key (str): environment variable name.

Examples:

>>> balena.models.device.config_var.device.remove(2184, 'test_env4')

Function: set(uuid_or_id, env_var_name, value) ⇒ None

Set the value of a device config variable. Note that config variables must start with BALENA_ and RESIN_ prefixes.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
env_var_name (str): environment variable name.
value (str): environment variable value.

Examples:

>>> balena.models.device.config_var.set('8deb12a7d7592c2b7f9e44735c2b0a41','BALENA_test_env4', 'testing1')

DeviceEnvVariable

This class implements device environment variable model for balena python SDK.

Function: get(uuid_or_id, env_var_name) ⇒ Optional[str]

Get device environment variable.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
env_var_name (str): environment variable name.

Examples:

>>> balena.models.device.env_var.get('8deb12a7d7592c2b7f9e44735c2b0a41', 'test_env4')

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

Get all device environment variables for an application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: list of device environment variables.

Examples:

>>> 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.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: device environment variables.

Examples:

>>> balena.models.device.env_var.get_all_by_device('8deb12a7d7592c2b7f9e44735c2b0a41')

Function: remove(uuid_or_id, key) ⇒ None

Remove a device environment variable.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
key (str): environment variable name.

Examples:

>>> balena.models.device.env_var.remove(2184, 'test_env4')

Function: set(uuid_or_id, env_var_name, value) ⇒ None

Set the value of a specific environment variable.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
env_var_name (str): environment variable name.
value (str): environment variable value.

Examples:

>>> balena.models.device.env_var.set('8deb12a7d7592c2b7f9e44735c2b0a41', 'test_env4', 'testing1')

DeviceServiceEnvVariable

This class implements device service variable model for balena python SDK.

Function: get(uuid_or_id, service_name_or_id, key) ⇒ Optional[str]

Get the overriden value of a service variable on a device

Args:

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

Returns:

Optional[str]: device service environment variables.

Examples:

>>> balena.models.device.service_var.get('8deb12a7d7592c2b7f9e44735c2b0a41', 'myservice', 'VAR')
>>> balena.models.device.service_var.get('8deb12a7d7592c2b7f9e44735c2b0a41', 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.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: device service environment variables.

Examples:

>>> 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.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: device service environment variables.

Examples:

>>> balena.models.device.service_var.get_all_by_device(8deb12a)

Function: remove(uuid_or_id, service_name_or_id, key) ⇒ None

Remove a device service environment variable.

Args:

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

Examples:

>>> balena.models.device.service_var.set('7cf02a6a016a4b3c9e3b7a8d5f46e127', 'myservice', 'VAR')
>>> balena.models.device.service_var.remove('7cf02a6a016a4b3c9e3b7a8d5f46e127', 28970, 'VAR')

Function: set(uuid_or_id, service_name_or_id, key, value) ⇒ None

Set the overriden value of a service variable on a device.

Args:

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

Examples:

>>> balena.models.device.service_var.set('7cf02a6a016a4b3c9e3b7a8d5f46e127', 'myservice', 'VAR', 'override')
>>> balena.models.device.service_var.set('7cf02a6a016a4b3c9e3b7a8d5f46e127', 123, 'VAR', 'override')

DeviceHistory

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.

Args:

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

Returns:

List[DeviceHistoryType]: device history entries.

Examples:

>>> 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.

Args:

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

Returns:

List[DeviceHistoryType]: device history entries.

Examples:

>>> 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))
... )

DeviceType

This class implements user API key model for balena python SDK.

Function: get(id_or_slug, options) ⇒ DeviceTypeType

Get a single device type.

Args:

id_or_slug (Union[str, int]): device type slug or alias (string) or id (int).
options (AnyObject): extra pine options to use.

Returns:

DeviceTypeType: Returns the device type

Function: get_all(options) ⇒ List[DeviceTypeType]

Get all device types.

Args:

options (AnyObject): extra pine options to use.

Returns:

List[DeviceTypeType]: list contains info of device types.

Function: get_all_supported(options) ⇒ None

Get all supported device types.

Args:

options (AnyObject): extra pine options to use.

Returns:

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.

Args:

slug_or_name (str): device type slug or name.
options (AnyObject): extra pine options to use.

Returns:

DeviceTypeType: Returns the device type

Function: get_name(slug) ⇒ str

Get display name for a device.

Args:

slug (str): device type slug.

Function: get_slug_by_name(name) ⇒ str

Get device slug.

Args:

name (str): device type name.

ApiKey

This class implements user API key model for balena python SDK.

Function: create(name, description, expiry_date) ⇒ str

This method registers a new api key for the current user with the name given.

Args:

name (str): the API key name
description (Optional[str]): the API key description
expiry_date (Optional[str]): the API key expiring date

Returns:

str: API key

Examples:

>>> 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.

Args:

options (AnyObject): extra pine options to use

Returns:

List[APIKeyType]: user API key

Examples:

>>> 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.

Args:

options (AnyObject): extra pine options to use

Examples:

>>> 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.

Args:

device_uuid (Union[str, int]): device, uuid (string) or id (int)
options (AnyObject): extra pine options to use

Examples:

>>> 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.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Examples:

>>> balena.models.api_key.get_provisioning_api_keys_by_application(1296047)
>>> balena.models.api_key.get_provisioning_api_keys_by_application("myorg/myapp")

Function: revoke(id) ⇒ None

This function revokes an API key.

Args:

id (int): API key id.

Examples:

>>> balena.models.api_key.revoke(1296047)

Function: update(id, api_key_info) ⇒ None

This function updates details of an API key.

Args:

id (str): API key id.
api_key_info (APIKeyInfoType): new API key info.

Examples:

>>> balena.models.api_key.update(1296047, {"name":"new name"})

Key

This class implements ssh key model for balena python SDK.

Function: create(title, key) ⇒ SSHKeyType

Create a ssh key.

Args:

title (str): key title.
key (str): the public ssh key.

Returns:

SSHKeyType: new ssh key id.

Function: get(id) ⇒ SSHKeyType

Get a single ssh key.

Args:

id (int): key id.

Returns:

SSHKeyType: ssh key info.

Function: get_all(options) ⇒ List[SSHKeyType]

Get all ssh keys.

Args:

options (AnyObject): extra pine options to use

Returns:

List[SSHKeyType]: list of ssh keys.

Function: remove(id) ⇒ None

Remove a ssh key.

Args:

id (int): key id.

Organization

This class implements organization model for balena python SDK.

Function: create(name, handle, logo_image) ⇒ OrganizationType

Creates a new organization.

Args:

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.

Returns:

dict: organization info.

Examples:

>>> 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.

Args:

handle_or_id (str): organization handle (string) or id (number).
options (AnyObject): extra pine options to use

Returns:

dict: organization info.

Raises:

OrganizationNotFound: if organization couldn't be found.

Examples:

>>> balena.models.organization.get(26474)
>>> balena.models.organization.get('myorg')

Function: get_all(options) ⇒ List[OrganizationType]

Get all organizations.

Args:

options (AnyObject): extra pine options to use

Returns:

List[OrganizationType]: list contains information of organizations.

Examples:

>>> balena.models.organization.get_all()

Function: remove(handle_or_id) ⇒ None

Remove an organization.

Args:

handle_or_id (str): organization handle (string) or id (number).

Examples:

>>> balena.models.organization.remove(148003)

OrganizationMembership

This class implements organization membership model for balena python SDK.

Function: get(membership_id, options) ⇒ OrganizationMembershipType

Get a single organization membership.

Args:

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

Returns:

Organization membership.

Examples:

>>> balena.models.organization.memberships.get(17608)

Function: get_all(options) ⇒ List[OrganizationMembershipType]

Get all organization memberships.

Args:

options (AnyObject): extra pine options to use

Returns:

List[OrganizationMembershipType]: organization memberships.

Examples:

>>> balena.models.organization.memberships.tags.get_all()

Function: get_all_by_organization(handle_or_id, options) ⇒ List[OrganizationMembershipType]

Get all memberships by organization.

Args:

handle_or_id (Union[str, int]): organization handle (string) or id (number).
options (AnyObject): extra pine options to use

Returns:

List[OrganizationMembershipType]: organization memberships.

Examples:

>>> balena.models.organization.memberships.get_all_by_organization(3014)

OrganizationMembershipTag

This class implements organization membership tag model for balena python SDK.

Function: get(membership_id, tag_key) ⇒ Optional[str]

Get an organization membership tag.

Args:

membership_id: organization membership id.
tag_key (str): tag key.

Examples:

>>> balena.models.organization.memberships.tags.get(17608, 'mTag1')

Function: get_all(options) ⇒ List[OrganizationMembershipTagType]

Get all organization membership tags.

Args:

options (AnyObject): extra pine options to use

Examples:

>>> 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.

Args:

handle_or_id (Union[str, int]): organization handle (string) or id (number).
options (AnyObject): extra pine options to use

Returns:

List[OrganizationMembershipTagType]: organization membership tags.

Examples:

>>> 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.

Args:

membership_id (int): organization membership id.
options (AnyObject): extra pine options to use

Returns:

list: organization membership tags.

Examples:

>>> balena.models.organization.memberships.tags.get_all_by_organization_membership(17608)

Function: remove(membership_id, tag_key) ⇒ None

Remove an organization membership tag.

Args:

membership_id: organization membership id.
tag_key (str): tag key.

Examples:

>>> balena.models.organization.memberships.tags.remove(17608, 'mTag1')

Function: set(membership_id, tag_key, value) ⇒ None

Set an organization membership tag.

Args:

membership_id: organization membership id.
tag_key (str): tag key.
value (str): tag value.

Examples:

>>> balena.models.organization.memberships.tags.set(17608, 'mTag1', 'Python SDK')

OrganizationInvite

This class implements organization invite model for balena python SDK.

Function: accept(invite_token) ⇒ None

Accepts an invite.

Args:

invite_token (str): invitation Token - invite token.

Function: create(handle_or_id, invitee, role_name, message) ⇒ OrganizationInviteType

Creates a new invite for an organization.

Args:

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.

Returns:

OrganizationInviteType: organization invite.

Examples:

>>> balena.models.organization.invite.create(26474, '[email protected]', 'member', 'Test invite')

Function: get_all(options) ⇒ List[OrganizationInviteType]

Get all invites.

Args:

options (AnyObject): extra pine options to use

Returns:

List[OrganizationInviteType]: list contains info of invites.

Examples:

>>> balena.models.organization.invite.get_all()

Function: get_all_by_organization(handle_or_id, options) ⇒ List[OrganizationInviteType]

Get all invites by organization.

Args:

handle_or_id (Union[str, int]): organization handle (string), or id (number).
options (AnyObject): extra pine options to use.

Returns:

List[OrganizationInviteType]: list contains info of invites.

Examples:

>>> balena.models.organization.invite.get_all_by_organization(26474)

Function: revoke(invite_id) ⇒ None

Revoke an invite.

Args:

invite_id (int): organization invite id.

Examples:

>>> balena.models.organization.invite.revoke(2862)

DeviceOs

This class implements device os model for balena python SDK.

Function: download(device_type, version, options) ⇒ None

Get OS download size estimate. Currently only the raw (uncompressed) size is reported.

Args:

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.

Returns:

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)

Function: get_all_os_versions(device_type, options) ⇒ None

Get all OS versions for the provided device type(s), inlcuding invalidated ones

Args:

device_type (Union[str, List[str]]): device type slug.
options (AnyObject): extra pine options to use

Returns:

list: balenaOS versions.

Function: get_available_os_versions(device_type) ⇒ None

Get the supported OS versions for the provided device type(s)

Args:

device_type (Union[str, List[str]]): device type slug.

Returns:

list: balenaOS versions.

Function: get_config(slug_or_uuid_or_id, options) ⇒ None

Download application config.json.

Args:

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.

Returns:

dict: application config.json content.

Raises:

ApplicationNotFound: if application couldn't be found.

Function: get_download_size(device_type, version) ⇒ float

Get OS download size estimate. Currently only the raw (uncompressed) size is reported.

Args:

device_type (str): device type slug.
version (str): semver-compatible version or 'latest', defaults to 'latest'.
* The version **must** be the exact version number.

Returns:

float: OS image download size, in bytes.

Function: get_max_satisfying_version(device_type, version_or_range, os_type) ⇒ Optional[str]

Get OS download size estimate. Currently only the raw (uncompressed) size is reported.

Args:

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.

Returns:

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

Args:

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.

Returns:

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' } }, );

Function: get_supported_os_update_versions(device_type, current_version) ⇒ None

Get OS supported versions.

Args:

device_type (str): device type slug.
current_version (str): device type slug.

Function: is_architecture_compatible_with(os_architecture, application_architecture) ⇒ None

Returns whether the specified OS architecture is compatible with the target architecture.

Args:

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.

Returns:

bool: Whether the specified OS architecture is capable of
      running applications build for the target architecture.

Function: is_supported_os_update(device_type, current_version, target_version) ⇒ bool

Returns the supported OS update targets for the provided device type.

Args:

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

Config

This class implements configuration model for balena python SDK.

Function: get_all() ⇒ ConfigType

Get all configuration.

Returns:

ConfigType: configuration information.

Examples:

>>> balena.models.config.get_all()

Release

This class implements release model for balena python SDK.

Function: create_from_url(slug_or_uuid_or_id, url, flatten_tarball) ⇒ int

Create a new release built from the source in the provided url.

Args:

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.

Returns:

int: release Id.

Function: finalize(commit_or_id_or_raw_version) ⇒ None

Finalizes a draft release.

Args:

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.

Args:

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

Returns:

ReleaseType: release info.

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[ReleaseType]

Get all releases from an application.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
options (AnyObject): extra pine options to use

Returns:

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.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number).
options (AnyObject): extra pine options to use

Returns:

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.

Args:

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

Returns:

dict: release info.

Raises:

ReleaseNotFound: if release couldn't be found.

Function: set_is_invalidated(commit_or_id_or_raw_version, is_invalidated) ⇒ None

Set the is_invalidated property of a release to True or False.

Args:

commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string)
is_invalidated (bool): True for invalidated, False for validated.

Function: set_known_issue_list(commit_or_id_or_raw_version, known_issue_list) ⇒ None

Set a known issue list for a release.

Args:

commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string)
known_issue_list (Optional[str]): the known issue list.

Function: set_note(commit_or_id_or_raw_version, note) ⇒ None

Set a note for a release.

Args:

commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string)
note (Optional[str]): the note.

Function: set_release_version(commit_or_id, semver) ⇒ None

Set a direct semver for a given release.

Args:

commit_or_id(Union[str, int]): release commit (string) or id (int)
semver (str): the version to be released, must be a valid semver

ReleaseTag

This class implements release tag model for balena python SDK.

Function: get(commit_or_id_or_raw_version, tag_key) ⇒ Optional[str]

Get a single release tag.

Args:

commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string) or
tag_key (str): tag key.

Examples:

>>> balena.models.release.tags.get(465307, 'releaseTag1')

Function: get_all(options) ⇒ List[BaseTagType]

Get all release tags.

Args:

options (AnyObject): extra pine options to use

Returns:

List[BaseTagType]: tags list.

Examples:

>>> 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.

Args:

slug_or_uuid_or_id (int): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[BaseTagType]: tags list.

Examples:

>>> 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.

Args:

commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string) or
options (AnyObject): extra pine options to use

Returns:

List[BaseTagType]: tags list.

Examples:

>>> balena.models.release.tags.get_all_by_release(135)

Function: remove(commit_or_id_or_raw_version, tag_key) ⇒ None

Remove a release tag.

Args:

commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string) or
tag_key (str): tag key.

Examples:

>>> balena.models.release.tags.remove(135, 'releaseTag1')

Function: set(commit_or_id_or_raw_version, tag_key, value) ⇒ None

Set a release tag (update tag value if it exists).

Args:

commit_or_id_or_raw_version(Union[str, int, ReleaseRawVersionApplicationPair]): release commit (string) or
tag_key (str): tag key.
value (str): tag value.

Examples:

>>> balena.models.release.tags.set(465307, 'releaseTag1', 'Python SDK')

Service

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.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[ServiceType]: service info.

ServiceEnvVariable

This class implements Service environment variable model for balena python SDK.

Function: get(service_id_or_natural_key, key) ⇒ Optional[str]

Get the value of a specific service variable

Args:

service_id_or_natural_key (Union[int, ServiceNaturalKey]): service id (number) or appliation-service_name
key (str): variable name

Examples:

>>> 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.

Args:

slug_or_uuid_or_id (Union[str, int]): application slug (string), uuid (string) or id (number)
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: application environment variables.

Examples:

>>> 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.

Args:

service_id_or_natural_key (Union[int, ServiceNaturalKey]): service id (number) or appliation-service_name
options (AnyObject): extra pine options to use

Returns:

List[EnvironmentVariableBase]: service environment variables.

Examples:

>>> balena.models.service.var.get_all_by_service(1234)
>>> balena.models.service.var.get_all_by_service({'application': 'myorg/myapp', 'service_name': 'service'})

Function: remove(service_id_or_natural_key, key) ⇒ None

Clear the value of a specific service variable

Args:

service_id_or_natural_key (Union[int, ServiceNaturalKey]): service id (number) or appliation-service_name
key (str): variable name

Examples:

>>> balena.models.service.var.remove({'application': 'myorg/myapp', 'service_name': 'service'}, 'VAR')
>>> balena.models.service.var.remove(1234,'test_env4')

Function: set(service_id_or_natural_key, key, value) ⇒ None

Set the value of a specific application environment variable.

Args:

service_id_or_natural_key (Union[int, ServiceNaturalKey]): service id (number) or appliation-service_name
key (str): variable name
value (str): environment variable value.

Examples:

>>> balena.models.service.var.set({'application': 'myorg/myapp', 'service_name': 'service'}, 'VAR', 'value')
>>> balena.models.service.var.set(1234,'test_env4', 'value')

Image

This class implements image model for balena python SDK.

Function: get(id, options) ⇒ ImageType

Get a specific image.

Args:

id (int): image id.
options (AnyObject): extra pine options to use.

Returns:

ImageType: image info.

Function: get_logs(id) ⇒ str

Get the build log from an image.

Args:

id (str): image id.

Returns:

str: build log.

Auth

This class implements all authentication functions for balena python SDK.

Function: authenticate() ⇒ str

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.

Args:

**credentials: credentials keyword arguments.
    username (str): Balena username.
    password (str): Password.

Returns:

str: Auth Token,

Examples:

>>> balena.auth.authenticate(username='<your email>', password='<your password>')

Function: get_actor_id() ⇒ int

Get current logged in actor id.

Returns:

int: actor id

Examples:

# If you are logged in.
>>> balena.auth.get_actor_id()

Function: get_token() ⇒ Optional[str]

This function retrieves Auth Token.

Returns:

str: Auth Token.

Examples:

>>> balena.auth.get_token()

Function: get_user_info() ⇒ UserInfo

Get current logged in user's info

Returns:

UserInfo: user info.

Examples:

# If you are logged in as a user.
>>> balena.auth.get_user_info()

Function: is_logged_in() ⇒ bool

This function checks if you're logged in

Returns:

bool: True if logged in, False otherwise.

Examples:

# Check if user logged in.
>>> if balena.auth.is_logged_in():
...     print('You are logged in!')
... else:
...     print('You are not logged in!')

Function: login() ⇒ None

This function is used for logging into balena using email and password.

Args:

**credentials: credentials keyword arguments.
    username (str): Balena email.
    password (str): Password.

Examples:

>>> 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>')

Function: login_with_token(token) ⇒ None

This function is used for logging into balena using Auth Token. Auth Token can be found in Preferences section on balena Dashboard.

Args:

token (str): Auth Token.

Returns:

This functions saves Auth Token to Settings and returns nothing.

Examples:

>>> from balena import Balena
>>> balena = Balena()
>>> auth_token = <your token>
>>> balena.auth.login_with_token(auth_token)

Function: logout() ⇒ None

This function is used for logging out from balena.

Examples:

# If you are logged in.
>>> balena.auth.logout()

Function: register() ⇒ str

This function is used for registering to balena.

Args:

**credentials: credentials keyword arguments.
    email (str): email to register.
    password (str): Password.

Returns:

str: Auth Token for new account.

Examples:

>>> credentials = {'email': '<your email>', 'password': '<your password>'}
>>> balena.auth.register(**credentials)

Function: whoami() ⇒ Union[UserKeyWhoAmIResponse, ApplicationKeyWhoAmIResponse, DeviceKeyWhoAmIResponse, None]

Return current logged in username.

Returns:

Optional[WhoamiResult]: current logged in information

Examples:

>>> balena.auth.whoami()

TwoFactorAuth

This class implements basic 2FA functionalities for balena python SDK.

Function: challenge(code) ⇒ None

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.

Args:

code (str): two-factor authentication code.

Examples:

# 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

Function: disable(password) ⇒ str

Disable two factor authentication. Note: Disable will only work when using a token that has 2FA enabled.

Args:

password (str): password.

Returns:

str: session token.

Examples:

>>> balena.twofactor_auth.disable('your_password')

Function: enable(code) ⇒ str

Enable two factor authentication.

Args:

code (str): two-factor authentication code.

Returns:

str: session token.

Examples:

>>> balena.twofactor_auth.enable('123456')

Function: get_setup_key() ⇒ str

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.

Returns:

str: setup key.

Examples:

>>> balena.twofactor_auth.get_setup_key()

Function: is_enabled() ⇒ bool

Check if two-factor authentication is enabled.

Returns:

bool: True if enabled. Otherwise False.

Examples:

>>> balena.twofactor_auth.is_enabled()

Function: is_passed() ⇒ bool

Check if two-factor authentication challenge was passed. If the user does not have 2FA enabled, this will be True.

Returns:

bool: True if passed. Otherwise False.

Examples:

>>> balena.twofactor_auth.is_passed()

Function: verify(code) ⇒ str

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.

Args:

code (str): two-factor authentication code.

Returns:

str: session token.

Examples:

>>> balena.twofactor_auth.verify('123456')

Logs

This class implements functions that allow processing logs from device.

Function: history(uuid_or_id, count) ⇒ List[Log]

Get device logs history.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)
count (Optional[Union[int, Literal["all"]]]): number of historical messages to include.

Function: stop() ⇒ None

Will grecefully unsubscribe from all devices and stop the consumer thread.

Function: subscribe(uuid_or_id, callback, error, count) ⇒ None

Subscribe to device logs.

Args:

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.

Function: unsubscribe(uuid_or_id) ⇒ None

Unsubscribe from device logs for a specific device.

Args:

uuid_or_id (Union[str, int]): device uuid (string) or id (int)

Function: unsubscribe_all() ⇒ None

Unsubscribe all subscribed devices.

Settings

Create a module object.

The name must be a string; the optional doc argument can have any type.

Types

APIKeyInfoType

{
    "name": str,
    "description": Optional[str],
    "expiry_date": Optional[str]
}

APIKeyType

{
    "id": int,
    "created_at": str,
    "name": str,
    "description": Optional[str],
    "expiry_date": Optional[str],
    "is_of__actor": Union[List[ActorType], PineDeferred]
}

ActorType

{
    "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]
}

ApplicationHostedOnApplication

{
    "application": Union[List[TypeApplication], PineDeferred],
    "can_use__application_as_host": Union[List[TypeApplication], PineDeferred]
}

ApplicationInviteType

{
    "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]
}

ApplicationMembershipRoleType

{
    "id": int,
    "name": Literal["developer", "operator", "observer"]
}

ApplicationMembershipType

{
    "id": int,
    "user": Union[List[UserType], PineDeferred],
    "is_member_of__application": Union[List[TypeApplication], PineDeferred],
    "application_membership_role": Union[List[ApplicationMembershipRoleType], PineDeferred]
}

ApplicationType

{
    "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]
}

BaseTagType

{
    "id": int,
    "tag_key": str,
    "value": str
}

BasicUserInfoType

{
    "id": int,
    "username": str
}

CpuArchitectureType

{
    "id": int,
    "slug": str,
    "is_supported_by__device_type": Optional[List[CpuArchitectureType]]
}

CreditBundleType

{
    "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]
}

DeviceFamilyType

{
    "created_at": str,
    "modified_at": str,
    "id": int,
    "slug": str,
    "name": str,
    "is_manufactured_by__device_manufacturer": Union[List[DeviceManufacturerType], PineDeferred, None]
}

DeviceHistoryType

{
    "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]
}

DeviceManufacturerType

{
    "created_at": str,
    "modified_at": str,
    "id": int,
    "slug": str,
    "name": str
}

DeviceMetricsType

{
    "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
}

DeviceTypeAliasType

{
    "id": int,
    "is_referenced_by__alias": str,
    "references__device_type": Union[List[DeviceTypeType], PineDeferred]
}

DeviceTypeType

{
    "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]]
}

EnvironmentVariableBase

{
    "id": int,
    "name": str,
    "value": str
}

ImageBasicInfoType

{
    "id": int,
    "service_name": str
}

ImageInstallType

{
    "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]
}

ImageType

{
    "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]]
}

InviteeType

{
    "id": int,
    "created_at": str,
    "email": str
}

OrganizationInviteType

{
    "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]
}

OrganizationMembershipRoleType

{
    "id": int,
    "name": Literal["administrator", "member"]
}

OrganizationMembershipTagType

{
    "organization_membership": Union[List[OrganizationMembershipType], PineDeferred]
}

OrganizationMembershipType

{
    "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]]
}

OrganizationPrivateDeviceTypeAccess

{
    "id": int,
    "organization": Union[List[OrganizationType], PineDeferred],
    "has_private_access_to__device_type": Union[List[TypeDevice], PineDeferred]
}

OrganizationType

{
    "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

{
    "_PineDeferred__id": int
}

PublicDeviceType

{
    "latitude": str,
    "longitude": str,
    "belongs_to__application": Union[List[TypeApplication], PineDeferred],
    "is_of__device_type": Union[List[TypeDevice], PineDeferred],
    "was_recently_online": bool
}

PublicOrganizationType

{
    "id": int,
    "name": str,
    "handle": str
}

ReleaseImageType

{
    "id": int,
    "created_at": str,
    "image": Union[List[ImageType], PineDeferred],
    "is_part_of__release": Union[List[ReleaseType], PineDeferred]
}

ReleaseType

{
    "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]]
}

ReleaseVersion

{
    "raw": str,
    "major": int,
    "minor": int,
    "patch": int,
    "version": str,
    "build": List[str],
    "prerelease": List[Union[str, int]]
}

ReleaseWithImageDetailsType

{
    "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
}

SSHKeyType

{
    "title": str,
    "public_key": str,
    "id": int,
    "created_at": str,
    "user": Union[List[UserType], PineDeferred]
}

ServiceInstanceType

{
    "id": int,
    "created_at": str,
    "service_type": str,
    "ip_address": str,
    "last_heartbeat": str
}

ServiceType

{
    "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]]
}

TeamApplicationAccessType

{
    "id": int,
    "team": Union[List[TeamType], PineDeferred],
    "grants_access_to__application": Union[List[TypeApplication], PineDeferred],
    "application_membership_role": Union[List[ApplicationMembershipRoleType], PineDeferred]
}

TeamMembershipType

{
    "id": int,
    "created_at": str,
    "user": Union[List[UserType], PineDeferred],
    "is_member_of__team": Union[List[TeamType], PineDeferred]
}

TeamType

{
    "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]]
}

TypeApplication

{
    "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]]
}

TypeApplicationWithDeviceServiceDetails

{
    "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]]
}

TypeCurrentService

{
    "id": int,
    "image_id": int,
    "service_id": int,
    "download_progress": int,
    "status": str,
    "install_date": str
}

TypeDevice

{
    "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]]
}

TypeDeviceWithServices

{
    "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]]
}

TypeVar

{

}

TypedDict

{

}

UserType

{
    "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]]
}

WebResource

{
    "filename": str,
    "href": str,
    "content_type": str,
    "content_disposition": str,
    "size": int
}