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: |
|
---|
-
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 thatUnixSocketConnection
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'
-
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.
- value – data to write (can be of any type, but will be
coerced 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:
-
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:
-
wait
()[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 thewatch()
.
-
walk
(top, topdown=True)[source]¶ Walk XenStore, yielding 3-tuples
(path, value, children)
for each node in the tree, rooted at node top.Parameters:
-
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
ifxenstored
is in communication with the domain; that is when INTRODUCE for the domain has not yet been followed by domain destruction or explicit RELEASE; andFalse
otherwise.Parameters: domid (int) – domain to check status for.
-
introduce_domain
(domid, mfn, eventchn)[source]¶ Tells
xenstored
to communicate with this domain.Parameters:
-
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:
-
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.
-
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.
- xen_bus_path (str) – path to XenBus device, implies that
pyxs.connection¶
This module implements two connection backends for
Client
.
copyright: |
|
---|
pyxs.helpers¶
Implements various helpers.
copyright: |
|
---|
-
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: |
|
---|
-
exception
pyxs.exceptions.
InvalidOperation
[source]¶ Exception raised when
Packet
is passed an operation, which isn’t listed inOp
.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 trailingNULL
.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.
pyxs._internal¶
A place for secret stuff, not available in the public API.
copyright: |
|
---|
-
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.
- op (int) – an item from