API reference

pyxs.client

This module implements XenStore client, which uses multiple connection options for communication: UnixSocketConnection and XenBusConnection. Note however, that the latter one can be a bit buggy, when dealing with WATCH_EVENT packets, so using UnixSocketConnection is preferable.

copyright:
  1. 2011 by Selectel, see AUTHORS for more details.
class pyxs.client.Client(unix_socket_path=None, socket_timeout=None, xen_bus_path=None, connection=None, transaction=None)[source]

XenStore client – <useful comment>.

Parameters:
  • xen_bus_path (str) – path to XenBus device, implies that connectionXenBusConnection is used as a backend.
  • unix_socket_path (str) – path to XenStore Unix domain socket, usually something like /var/run/xenstored/socket – implies that UnixSocketConnection is used as a backend.
  • socket_timeout (float) – see socket.settimeout() for details.
  • transaction (bool) – if True transaction_start() will be issued right after connection is established.

Note

UnixSocketConnection is used as a fallback value, if backend cannot be determined from arguments given.

Here’s a quick example:

>>> with Client() as c:
...     c.write("/foo/bar", "baz")
...     c.read("/foo/bar")
'OK'
'baz'
read(path)[source]

Reads data from a given path.

Parameters:path (str) – a path to read from.
write(path, value)[source]

Writes data to a given path.

Parameters:
  • value – data to write (can be of any type, but will be coerced to bytes() eventually).
  • path (str) – a path to write to.
mkdir(path)[source]

Ensures that a given path exists, by creating it and any missing parents with empty values. If path or any parent already exist, its value is left unchanged.

Parameters:path (str) – path to directory to create.
rm(path)[source]

Ensures that a given does not exist, by deleting it and all of its children. It is not an error if path doesn’t exist, but it is an error if path‘s immediate parent does not exist either.

Parameters:path (str) – path to directory to remove.
ls(path)[source]

Returns a list of names of the immediate children of path.

Parameters:path (str) – path to list.
get_permissions(path)[source]

Returns a list of permissions for a given path, see InvalidPermission for details on permission format.

Parameters:path (str) – path to get permissions for.
set_permissions(path, perms)[source]

Sets a access permissions for a given path, see InvalidPermission for details on permission format.

Parameters:
  • path (str) – path to set permissions for.
  • perms (list) – a list of permissions to set.
walk(top, topdown=True)[source]

Walk XenStore, yielding 3-tuples (path, value, children) for each node in the tree, rooted at node top.

Parameters:
  • top (str) – node to start from.
  • topdown (bool) – see os.walk() for details.
get_domain_path(domid)[source]

Returns the domain’s base path, as is used for relative transactions: ex: "/local/domain/<domid>". If a given domid doesn’t exists the answer is undefined.

Parameters:domid (int) – domain to get base path for.
is_domain_introduced(domid)[source]

Returns True if xenstored is in communication with the domain; that is when INTRODUCE for the domain has not yet been followed by domain destruction or explicit RELEASE; and False otherwise.

Parameters:domid (int) – domain to check status for.
introduce_domain(domid, mfn, eventchn)[source]

Tells xenstored to communicate with this domain.

Parameters:
  • domid (int) – a real domain id, (0 is forbidden).
  • mfn (long) – address of xenstore page in domid.
  • eventchn (int) – an unbound event chanel in domid.
release_domain(domid)[source]

Manually requests xenstored to disconnect from the domain.

Parameters:domid (int) – domain to disconnect.

Note

xenstored will in any case detect domain destruction and disconnect by itself.

resume_domain(domid)[source]

Tells xenstored to clear its shutdown flag for a domain. This ensures that a subsequent shutdown will fire the appropriate watches.

Parameters:domid (int) – domain to resume.
set_target(domid, target)[source]

Tells xenstored that a domain is targetting another one, so it should let it tinker with it. This grants domain domid full access to paths owned by target. Domain domid also inherits all permissions granted to target on all other paths.

Parameters:
  • domid (int) – domain to set target for.
  • target (int) – target domain (yours truly, Captain).
transaction_start()[source]

Starts a new transaction and returns transaction handle, which is simply an int.

Warning

Currently xenstored has a bug that after 2^32 transactions it will allocate id 0 for an actual transaction.

transaction_end(commit=True)[source]

End a transaction currently in progress; if no transaction is running no command is sent to XenStore.

monitor()[source]

Returns a new Monitor instance, which is currently the only way of doing PUBSUB.

transaction()[source]

Returns a new Client instance, operating within a new transaction; can only be used only when no transaction is running. Here’s an example:

>>> with Client().transaction() as t:
...     t.do_something()
...     t.transaction_end(commit=True)

However, the last line is completely optional, since the default behaviour is to commit everything on context manager exit.

Raises pyxs.exceptions.PyXSError:
 if this client is linked to and active transaction.
class pyxs.client.Monitor(connection)[source]

XenStore monitor – allows minimal PUBSUB-like functionality on top of XenStore.

>>> m = Client().monitor()
>>> m.watch("foo/bar")
>>> m.wait()
Event(...)
watch(wpath, token)[source]

Adds a watch.

When a path is modified (including path creation, removal, contents change or permissions change) this generates an event on the changed path. Changes made in transactions cause an event only if and when committed.

Parameters:
  • wpath (str) – path to watch.
  • token (str) – watch token, returned in watch notification.
unwatch(wpath, token)[source]

Removes a previously added watch.

Parameters:
  • wpath (str) – path to unwatch.
  • token (str) – watch token, passed to watch().
wait(sleep=None)[source]

Waits for any of the watched paths to generate an event, which is a (path, token) pair, where the first element is event path, i.e. the actual path that was modified and second element is a token, passed to the watch().

Parameters:sleep (float) – number of seconds to sleep between event checks.

pyxs.connection

This module implements two connection backends for Client.

copyright:
  1. 2011 by Selectel, see AUTHORS for more details.
class pyxs.connection.UnixSocketConnection(path=None, socket_timeout=None)[source]

XenStore connection through Unix domain socket.

Parameters:
  • path (str) – path to XenStore unix domain socket, if not provided explicitly is restored from process environment – similar to what libxs does.
  • socket_timeout (float) – see socket.settimeout() for details.
class pyxs.connection.XenBusConnection(path=None)[source]

XenStore connection through XenBus.

Parameters:path (str) – path to XenBus block device; a predefined OS-specific constant is used, if a value isn’t provided explicitly.

pyxs.helpers

Implements various helpers.

copyright:
  1. 2011 by Selectel, see AUTHORS for more details.
pyxs.helpers.error(smth)[source]

Returns a PyXSError matching a given errno or error name.

>>> error(22)
pyxs.exceptions.PyXSError: (22, 'Invalid argument')
>>> error("EINVAL")
pyxs.exceptions.PyXSError: (22, 'Invalid argument')
pyxs.helpers.validate_path(path)[source]

Checks if a given path is valid, see InvalidPath for details.

Parameters:path (str) – path to check.
Raises pyxs.exceptions.InvalidPath:
 when path fails to validate.
pyxs.helpers.validate_watch_path(wpath)[source]

Checks if a given watch path is valid – it should either be a valid path or a special, starting with @ character.

Parameters:wpath (str) – watch path to check.
Raises pyxs.exceptions.InvalidPath:
 when path fails to validate.
pyxs.helpers.validate_perms(perms)[source]

Checks if a given list of permision follows the format described in get_permissions().

Parameters:perms (list) – permissions to check.
Raises pyxs.exceptions.InvalidPermissions:
 when any of the permissions fail to validate.

pyxs.exceptions

This module implements a number of Python exceptions used by pyxs classes.

copyright:
  1. 2011 by Selectel, see AUTHORS for more details.
exception pyxs.exceptions.InvalidOperation[source]

Exception raised when Packet is passed an operation, which isn’t listed in Op.

Parameters:operation (int) – invalid operation value.
exception pyxs.exceptions.InvalidPayload[source]

Exception raised when Packet is initialized with payload, which exceeds 4096 bytes restriction or contains a trailing NULL.

Parameters:operation (bytes) – invalid payload value.
exception pyxs.exceptions.InvalidPath[source]

Exception raised when a path proccessed by a comand doesn’t match the following constraints:

  • its length should not exceed 3072 or 2048 for absolute and relative path respectively.
  • it should only consist of ASCII alphanumerics and the four punctuation characters -/_@hyphen, slash, underscore and atsign.
  • it shouldn’t have a trailing /, except for the root path.
Parameters:path (bytes) – invalid path value.
exception pyxs.exceptions.InvalidPermission[source]

Exception raised for permission which don’t match the following format:

w<domid>        write only
r<domid>        read only
b<domid>        both read and write
n<domid>        no access
Parameters:perm (bytes) – invalid permission value.
exception pyxs.exceptions.ConnectionError[source]

Exception raised for failures during socket operations.

exception pyxs.exceptions.UnexpectedPacket[source]

Exception raised when recieved packet header doesn’t match the header of the packet sent, for example if outgoing packet has op = Op.READ the incoming packet is expected to have op = Op.READ as well.

pyxs._internal

A place for secret stuff, not available in the public API.

copyright:
  1. 2011 by Selectel, see AUTHORS for more details.
pyxs._internal.Op = Operations(DEBUG=0, DIRECTORY=1, READ=2, GET_PERMS=3, WATCH=4, UNWATCH=5, TRANSACTION_START=6, TRANSACTION_END=7, INTRODUCE=8, RELEASE=9, GET_DOMAIN_PATH=10, WRITE=11, MKDIR=12, RM=13, SET_PERMS=14, WATCH_EVENT=15, ERROR=16, IS_DOMAIN_INTRODUCED=17, RESUME=18, SET_TARGET=19, RESTRICT=128)

Operations supported by XenStore.

class pyxs._internal.Packet[source]

A single message to or from XenStore.

Parameters:
  • op (int) – an item from Op, representing operation, performed by this packet.
  • payload (bytes) – packet payload, should be a valid ASCII-string with characters between [0x20;0x7f].
  • rq_id (int) – request id – hopefuly a unique identifier for this packet, XenStore simply echoes this value back in reponse.
  • tx_id (int) – transaction id, defaults to 0 – which means no transaction is running.