API documentation¶

Client¶

class pylxd.client.Client(endpoint=None, version='1.0', cert=None, verify=True, timeout=None)¶

Client class for LXD REST API.

This client wraps all the functionality required to interact with LXD, and is meant to be the sole entry point.

containers¶: Instance of Client.Containers:

images¶: Instance of Client.Images.

operations¶: Instance of Client.Operations.

profiles¶: Instance of Client.Profiles.

api¶

This attribute provides tree traversal syntax to LXD’s REST API for lower-level interaction.

Use the name of the url part as attribute or item of an api object to create another api object appended with the new url part name, ie:

>>> api = Client().api
# /
>>> response = api.get()
# Check status code and response
>>> print response.status_code, response.json()
# /containers/test/
>>> print api.containers['test'].get().json()

events(websocket_client=None)¶

Get a websocket client for getting events.

/events is a websocket url, and so must be handled differently than most other LXD API endpoints. This method returns a client that can be interacted with like any regular python socket.

An optional websocket_client parameter can be specified for implementation-specific handling of events as they occur.

Exceptions¶

class pylxd.exceptions.LXDAPIException(response)¶

A generic exception for representing unexpected LXD API responses.

LXD API responses are clearly documented, and are either a standard return value, and background operation, or an error. This exception is raised on an error case, or when the response status code is not expected for the response.

This exception should only be raised in cases where the LXD REST API has returned something unexpected.

class pylxd.exceptions.NotFound(response)¶: An exception raised when an object is not found.

class pylxd.exceptions.ClientConnectionFailed¶: An exception raised when the Client connection fails.

Certificate¶

class pylxd.models.Certificate(client, **kwargs)¶

A LXD certificate.

classmethod all(client)¶: Get all certificates.

classmethod create(client, password, cert_data)¶: Create a new certificate.

classmethod get(client, fingerprint)¶: Get a certificate by fingerprint.

Container¶

class pylxd.models.Container(*args, **kwargs)¶

An LXD Container.

This class is not intended to be used directly, but rather to be used via Client.containers.create.

class FilesManager(client, container)¶

A pseudo-manager for namespacing file operations.

delete_available()¶: File deletion is an extension API and may not be available. https://github.com/lxc/lxd/blob/master/doc/api-extensions.md#file_delete

put(filepath, data, mode=None, uid=None, gid=None)¶

Push a file to the container.

This pushes a single file to the containers file system named by the filepath.

Parameters:

filepath (str) – The path in the container to to store the data in.
data (bytes or str) – The data to store in the file.
mode (Union[oct, int, str]) – The unit mode to store the file with. The default of None stores the file with the current mask of 0700, which is the lxd default.
uid (int) – The uid to use inside the container. Default of None results in 0 (root).
gid (int) – The gid to use inside the container. Default of None results in 0 (root).

Raises:

LXDAPIException if something goes wrong

recursive_put(src, dst, mode=None, uid=None, gid=None)¶

Recursively push directory to the container.

Recursively pushes directory to the containers named by the dst

Parameters:	src (str) – The source path of directory to copy. dst (str) – The destination path in the container of directory to copy mode (Union[oct, int, str]) – The unit mode to store the file with. The default of None stores the file with the current mask of 0700, which is the lxd default. uid (int) – The uid to use inside the container. Default of None results in 0 (root). gid (int) – The gid to use inside the container. Default of None results in 0 (root).
Raises:	NotADirectoryError if src is not a directory
Raises:	LXDAPIException if an error occurs

classmethod all(client)¶

Get all containers.

Containers returned from this method will only have the name set, as that is the only property returned from LXD. If more information is needed, Container.sync is the method call that should be used.

classmethod create(client, config, wait=False)¶: Create a new container config.

execute(commands, environment={}, encoding=None, decode=True)¶

Execute a command on the container.

In pylxd 2.2, this method will be renamed execute and the existing execute method removed.

Parameters:	commands ([str]) – The command and arguments as a list of strings environment ({str: str}) – The environment variables to pass with the command encoding (str) – The encoding to use for stdout/stderr if the param decode is True. If encoding is None, then no override is performed and whatever the existing encoding from LXD is used. decode (bool) – Whether to decode the stdout/stderr or just return the raw buffers.
Raises:	ValueError – if the ws4py library is not installed.
Returns:	The return value, stdout and stdin
Return type:	_ContainerExecuteResult() namedtuple

classmethod exists(client, name)¶: Determine whether a container exists.

freeze(timeout=30, force=True, wait=False)¶: Freeze the container.

generate_migration_data()¶

Generate the migration data.

This method can be used to handle migrations where the client connection uses the local unix socket. For more information on migration, see Container.migrate.

classmethod get(client, name)¶: Get a container by name.

migrate(new_client, wait=False)¶

Migrate a container.

Destination host information is contained in the client connection passed in.

If the container is running, it either must be shut down first or criu must be installed on the source and destination machines.

publish(public=False, wait=False)¶

Publish a container as an image.

The container must be stopped in order publish it as an image. This method does not enforce that constraint, so a LXDAPIException may be raised if this method is called on a running container.

If wait=True, an Image is returned.

rename(name, wait=False)¶: Rename a container.

restart(timeout=30, force=True, wait=False)¶: Restart the container.

start(timeout=30, force=True, wait=False)¶: Start the container.

stop(timeout=30, force=True, wait=False)¶: Stop the container.

unfreeze(timeout=30, force=True, wait=False)¶: Unfreeze the container.

class pylxd.models.Snapshot(client, **kwargs)¶

A container snapshot.

publish(public=False, wait=False)¶

Publish a snapshot as an image.

If wait=True, an Image is returned.

This functionality is currently broken in LXD. Please see https://github.com/lxc/lxd/issues/2201 - The implementation here is mostly a guess. Once that bug is fixed, we can verify that this works, or file a bug to fix it appropriately.

rename(new_name, wait=False)¶: Rename a snapshot.

Image¶

class pylxd.models.Image(client, **kwargs)¶

A LXD Image.

add_alias(name, description)¶: Add an alias to the image.

classmethod all(client)¶: Get all images.

copy(new_client, public=None, auto_update=None, wait=False)¶

Copy an image to a another LXD.

Destination host information is contained in the client connection passed in.

classmethod create(client, image_data, metadata=None, public=False, wait=True)¶

Create an image.

If metadata is provided, a multipart form data request is formed to push metadata and image together in a single request. The metadata must be a tar achive.

wait parameter is now ignored, as the image fingerprint cannot be reliably determined consistently until after the image is indexed.

classmethod create_from_simplestreams(client, server, alias, public=False, auto_update=False)¶: Copy an image from simplestreams.

classmethod create_from_url(client, url, public=False, auto_update=False)¶: Copy an image from an url.

delete_alias(name)¶: Delete an alias from the image.

classmethod exists(client, fingerprint, alias=False)¶

Determine whether an image exists.

If alias is True, look up the image by its alias, rather than its fingerprint.

export()¶

Export the image.

Because the image itself may be quite large, we stream the download in 1kb chunks, and write it to a temporary file on disk. Once that file is closed, it is deleted from the disk.

classmethod get(client, fingerprint)¶: Get an image.

classmethod get_by_alias(client, alias)¶: Get an image by its alias.

Network¶

class pylxd.models.Network(client, **kwargs)¶

Model representing a LXD network.

classmethod all(client)¶

Get all networks.

Parameters:	client (`Client`) – client instance
Return type:	list[`Network`]

classmethod create(client, name, description=None, type=None, config=None)¶

Create a network.

Parameters:	client (`Client`) – client instance name (str) – name of the network description (str) – description of the network type (str) – type of the network config (dict) – additional configuration

classmethod exists(client, name)¶

Determine whether network with provided name exists.

Parameters:	client (`Client`) – client instance name (str) – name of the network
Returns:	True if network exists, False otherwise
Return type:	bool

classmethod get(client, name)¶

Get a network by name.

Parameters:	client (`Client`) – client instance name (str) – name of the network
Returns:	network instance (if exists)
Return type:	`Network`
Raises:	`NotFound` if network does not exist

static network_extension_available(client)¶

Network operations is an extension API and may not be available.

https://github.com/lxc/lxd/blob/master/doc/api-extensions.md#network

Parameters:	client (`Client`) – client instance
Returns:	True if network API extension is available, False otherwise.
Return type:	bool

rename(new_name)¶

Rename a network.

Parameters:	new_name (str) – new name of the network
Returns:	Renamed network instance
Return type:	`Network`

save(*args, **kwargs)¶

Save data to the server.

This method should write the new data to the server via marshalling. It should be a no-op when the object is not dirty, to prevent needless I/O.

Operation¶

class pylxd.models.Operation(**kwargs)¶

A LXD operation.

classmethod get(client, operation_id)¶: Get an operation.

wait()¶: Wait for the operation to complete and return.

classmethod wait_for_operation(client, operation_id)¶: Get an operation and wait for it to complete.

Profile¶

class pylxd.models.Profile(client, **kwargs)¶

A LXD profile.

classmethod all(client)¶: Get all profiles.

classmethod create(client, name, config=None, devices=None)¶: Create a profile.

classmethod exists(client, name)¶: Determine whether a profile exists.

classmethod get(client, name)¶: Get a profile.

rename(new_name)¶: Rename the profile.

Storage Pool¶

class pylxd.models.StoragePool(client, **kwargs)¶

A LXD storage_pool.

This corresponds to the LXD endpoint at /1.0/storage-pools

classmethod all(client)¶: Get all storage_pools.

classmethod create(client, config)¶: Create a storage_pool from config.

delete()¶: Delete is not available for storage_pools.

classmethod exists(client, name)¶: Determine whether a storage pool exists.

classmethod get(client, name)¶: Get a storage_pool by name.

save(wait=False)¶: Save is not available for storage_pools.