Python library API

This page describes the methods and properties available in the PiCloud and Pi classes and are intended as a useful reference to the functionality provided.

The way to use the module is to import the PiCloud class and initialise it with your API keys. This will allow you to provision new Pi services with the create_pi() method or access existing services from the pis property.

Once you have a connected PiCloud instance and access to newly or previously created Pi instances, the following API documentation should prove useful to show what you can do with the API via the hostedpi module.

You can authenticate by passing your API ID and secret as arguments to the PiCloud constructor:

>>> from hostedpi import PiCloud
>>> cloud = PiCloud('YOUR ID', 'YOUR SECRET')

or set them in environment variables instead:

$ export HOSTEDPI_ID='YOUR ID'
$ export HOSTEDPI_SECRET='YOUR SECRET'

>>> from hostedpi import PiCloud
>>> cloud = PiCloud()

PiCloud

class hostedpi.picloud.PiCloud(api_id=None, api_secret=None, *, ssh_keys=None, ssh_key_path=None, ssh_import_github=None, ssh_import_launchpad=None)

A connection to the Mythic Beasts Pi Cloud API for creating and managing cloud Pi services.

Set up API keys at https://www.mythic-beasts.com/customer/api-users

Parameters:

• api_id (str or None) – Your Mythic Beasts API ID (alternatively, the environment variable HOSTEDPI_ID can be used)
• api_secret (str or None) – Your Mythic Beasts API secret (alternatively, the environment variable HOSTEDPI_SECRET can be used)
• ssh_keys (list or set or None) – A list/set of SSH key strings (keyword-only argument)
• ssh_key_path (str or None) – The path to your SSH public key (keyword-only argument)
• ssh_import_github (list or set or None) – A list/set of GitHub usernames to import SSH keys from (keyword-only argument)
• ssh_import_launchpad (list or set or None) – A list/set of Launchpad usernames to import SSH keys from (keyword-only argument)

Note

If any SSH keys are provided on class initialisation, they will be used when creating Pis but are overriden by any passed to the create_pi() method.

All SSH arguments provided will be used in combination.

__str__()

String of information about all the Pis in the account

create_pi(name, *, model=3, disk_size=10, os_image=None, ssh_keys=None, ssh_key_path=None, ssh_import_github=None, ssh_import_launchpad=None)

Provision a new cloud Pi with the specified name, model, disk size and SSH keys. Return a new Pi instance.

Parameters:

• name (str) – A unique identifier for the server. This will form part of the hostname for the server, and must consist only of alphanumeric characters and hyphens.
• model (int or None) – The Raspberry Pi model to provision (3 or 4) - defaults to 3 (keyword-only argument)
• disk_size (int or None) – The amount of disk space (in GB) attached to the Pi - must be a multiple of 10 - defaults to 10 (keyword-only argument)
• os_image (str) – The name of the operating system image to boot from. Defaults to None which falls back to Mythic’s default (Raspbian/PiOS stable). If given, this must be a string which appears as a key in the return value of get_operating_systems() for the relevant Pi model.
• ssh_keys (list or set or None) – A list/set of SSH key strings (keyword-only argument)
• ssh_key_path (str or None) – The path to your SSH public key (keyword-only argument)
• ssh_import_github (list or set or None) – A list/set of GitHub usernames to import SSH keys from (keyword-only argument)
• ssh_import_launchpad (list or set or None) – A list/set of Launchpad usernames to import SSH keys from (keyword-only argument)

Note

If any SSH keys are provided on class initialisation, they will be used here but are overriden by any passed to this method.

Note

When requesting a Pi 3, you will either get a model 3B or 3B+. It is not possible to request a particular model beyond 3 or 4. The Pi 4 is the 4GB RAM model.

get_operating_systems(*, model)

Return a dict of operating systems supported by the given Pi model (3 or 4). Dict keys are identifiers (e.g. “raspbian-buster”) which can be used when provisioning a new Pi with create_pi(); dict values are text labels of the OS/distro names (e.g. “Raspbian Buster”).

Parameters:model (int) – The Raspberry Pi model (3 or 4) to get operating systems for (keyword-only argument)

ipv4_ssh_config

A string containing the IPv4 SSH config for all Pis within the account. The contents could be added to an SSH config file for easy access to the Pis in the account.

ipv6_ssh_config

A string containing the IPv6 SSH config for all Pis within the account. The contents could be added to an SSH config file for easy access to the Pis in the account.

pis

A dictionary of Pi objects keyed by their names.

Pi

class hostedpi.pi.Pi

The Pi class represents a single Raspberry Pi service in the Mythic Beasts Pi cloud. Initialising a Pi object does not provision a new Pi, rather initialisation is for internal construction only.

There are two ways to get access to a Pi object: retrieval from the pis dictionary; and the return value of create_pi() method.

With a Pi object, you can access data about that particular Pi service, add SSH keys, reboot it, cancel it and more.

Note

The Pi class should not be initialised by the user, only internally within the module.

__str__()

A multi-line string of the information about the Pi

cancel()

Cancel the Pi service

off()

Power the Pi off and return immediately

on(*, wait=False)

Power the Pi on. If wait is False (the default), return immediately. If wait is True, wait until the power on request is completed, and return True on success, and False on failure.

reboot(*, wait=False)

Reboot the Pi. If wait is False (the default), return None immediately. If wait is True, wait until the reboot request is completed, and return True on success, and False on failure.

Note

Note that if wait is False, you can poll for the boot status while rebooting by inspecting the properties is_booting and boot_progress.

ssh_import_id(*, github=None, launchpad=None)

Import SSH keys from GitHub or Launchpad, and add them to the Pi. Return the set of keys added.

Parameters:

• ssh_import_github (list or set or None) – A list/set of GitHub usernames to import SSH keys from (keyword-only argument)
• ssh_import_launchpad (list or set or None) – A list/set of Launchpad usernames to import SSH keys from (keyword-only argument)

boot_progress

A string representing the Pi’s boot progress. Can be booted, powered off or a particular stage of the boot process if currently booting.

disk_size

The Pi’s disk size in GB

initialised_keys

A boolean representing whether or not the Pi has been initialised with SSH keys

ipv4_ssh_command

The SSH command required to connect to the Pi over IPv4

ipv4_ssh_config

A string containing the IPv4 SSH config for the Pi. The contents could be added to an SSH config file for easy access to the Pi.

ipv4_ssh_port

The SSH port to use when connecting via the IPv4 proxy

ipv6_address

The Pi’s IPv6 address as an IPv6Address object

ipv6_network

The Pi’s IPv6 network as an IPv6Network object

ipv6_ssh_command

The SSH command required to connect to the Pi over IPv6

ipv6_ssh_config

A string containing the IPv6 SSH config for the Pi. The contents could be added to an SSH config file for easy access to the Pi.

is_booting

A boolean representing whether or not the Pi is currently booting

location

The Pi’s physical location (data centre)

model

The Pi’s model (3 or 4)

model_full

The Pi’s model name (3B, 3B+ or 4B)

name

The name of the Pi service.

power

A boolean representing whether or not the Pi is currently powered on

provision_status

A string representing the provision status of the Pi. Can be “provisioning”, “initialising” or “live”.

ssh_keys

Retrieve the SSH keys on the Pi, or use assignment to update them. Property value is a set of strings. Assigned value should also be a set of strings.

url

The http version of the hostedpi.com URL of the Pi.

Note

Note that a web server must be installed on the Pi for the URL to resolve in a web browser.

url_ssl

The https version of the hostedpi.com URL of the Pi.

Note

Note that a web server must be installed on the Pi for the URL to resolve in a web browser, and an SSL certificate must be created. See https://letsencrypt.org/