Provided by: python-pyxs-doc_0.4.2~git20190115.97f14313-5_all 
NAME
pyxs - pyxs Documentation
.---. .-..-..-.,-. .--.
: .; `: :; :`. .'`._-.'
: ._.'`._. ;:_,._;`.__.'
: : .-. :
:_; `._.' 0.4.2-dev
-- XenStore access the Python way!
It's a pure Python XenStore client implementation, which covers all of the libxs features and adds some
nice Pythonic sugar on top. Here's a shortlist:
• pyxs supports both Python 2 and 3,
• works over a Unix socket or XenBus,
• has a clean and well-documented API,
• is written in easy to understand Python,
• can be used with gevent or eventlet.
If you have pip you can do the usual:
pip install --user pyxs
Otherwise, download the source from GitHub and run:
python setup.py install
Fedora users can install the package from the system repository:
dnf install python2-pyxs
dnf install python3-pyxs
RHEL/CentOS users can install the package from the EPEL repository:
yum install python2-pyxs
yum install python34-pyxs
Head over to our brief tutorial or, if you're feeling brave, dive right into the api; pyxs also has a
couple of examples in the examples directory.
TUTORIAL
Basics
Using pyxs is easy! The only class you need to import is Client. It provides a simple straightforward API
to XenStore content with a bit of Python's syntactic sugar here and there.
Generally, if you just need to fetch or update some XenStore items you can do:
>>> from pyxs import Client
>>> with Client() as c:
... c[b"/local/domain/0/name"] = b"Ziggy"
... c[b"/local/domain/0/name"]
b'Ziggy'
Using Client without the with statement is possible, albeit, not recommended:
>>> c = Client()
>>> c.connect()
>>> c[b"/local/domain/0/name"] = b"It works!"
>>> c.close()
The reason for preferring a context manager is simple: you don't have to DIY. The context manager will
make sure that a started transaction was either rolled back or committed and close the underlying
XenStore connection afterwards.
Connections
pyxs supports two ways of communicating with XenStore:
• over a Unix socket with UnixSocketConnection;
• over XenBus with XenBusConnection.
Connection type is determined from the arguments passed to Client constructor. For example, the following
code creates a Client instance, operating over a Unix socket:
>>> Client(unix_socket_path="/var/run/xenstored/socket_ro")
Client(UnixSocketConnection('/var/run/xenstored/socket_ro'))
>>> Client()
Client(UnixSocketConnection('/var/run/xenstored/socket'))
Use xen_bus_path argument to initialize a Client with XenBusConnection:
>>> Client(xen_bus_path="/dev/xen/xenbus")
Client(XenBusConnection('/dev/xen/xenbus'))
Transactions
Transactions allow you to operate on an isolated copy of XenStore tree and merge your changes back
atomically on commit. Keep in mind, however, that changes made within a transaction become available to
other XenStore clients only if and when committed. Here's an example:
>>> with Client() as c:
... c.transaction()
... c[b"/foo/bar"] = b"baz"
... c.commit() # !
... print(c[b"/foo/bar"])
b'baz'
The line with an exclamation mark is a bit careless, because it ignores the fact that committing a
transaction might fail. A more robust way to commit a transaction is by using a loop:
>>> with Client() as c:
... success = False
... while not success:
... c.transaction()
... c[b"/foo/bar"] = b"baz"
... success = c.commit()
You can also abort the current transaction by calling rollback().
Events
When a new path is created or an existing path is modified, XenStore fires an event, notifying all
watching clients that a change has been made. pyxs implements watching via the Monitor class. To watch a
path create a monitor monitor() and call watch() with a path you want to watch and a unique token. Right
after that the monitor will start to accumulate incoming events. You can iterate over them via wait():
>>> with Client() as c:
... m = c.monitor()
... m.watch(b"/foo/bar", b"a unique token")
... next(m.wait())
Event(b"/foo/bar", b"a unique token")
XenStore has a notion of special paths, which start with @ and are reserved for special occasions:
────────────────────────────────────────────────────────────
Path Description
────────────────────────────────────────────────────────────
@introduceDomain Fired when a new domain is introduced
to XenStore -- you can also introduce
domains yourself with a
introduce_domain() call, but in most
of the cases, xenstored will do that
for you.
────────────────────────────────────────────────────────────
@releaseDomain Fired when XenStore is no longer
communicating with a domain, see
release_domain().
┌──────────────────┬───────────────────────────────────────┐
│ │ │
--
API REFERENCE │ │ │
Client and Monitor │ │ │
--
CONTRIBUTING
Submitting a bug report
In case you experience issues using pyxs, do not hesitate to report it to the Bug Tracker on GitHub.
Setting up development environment
Writing a XenStore client library without having access to a running XenStore instance can be
troublesome. Luckily, there is a way to setup a development using VirtualBox.
1. Create a VM running Ubuntu 14.04 or later.
2. Install Xen hypervisor: sudo apt-get install xen-hypervisor-4.4-amd64.
3. Configure VM for SSH access.
4. Done! You can now rsync your changes to the VM and run the tests.
Running the tests
Only root is allowed to access XenStore, so the tests require sudo:
$ sudo python setup.py test
pyxs strives to work across a range of Python versions. Use tox to run the tests on all supported
versions:
$ cat tox.ini
[tox]
envlist = py26,py27,py34,py35,pypy
[testenv]
commands = python setup.py test
$ sudo tox
Style guide
pyxs follows Pocoo style guide. Please read it before you start implementing your changes.
PYXS CHANGELOG
Here you can see the full list of changes between each pyxs release.
Version 0.4.2-dev
• Allowed values to be empty b"". Thanks to Stephen Czetty. See PR #13 on GitHub.
Version 0.4.1
Bugfix release, released on May 11th, 2016
• Fixed a bug in XenBusConnection.create_transport which failed on attribute lookup. See PR #7 on GitHub.
Version 0.4.0
Released on March 6th, 2016
• Fixed a bug in Client.set_permissions which coerced permission lists (e.g. ["b0"]) to repr-strings
prior to validation.
• The API is now based around bytes, which means that all methods which used to accept str (or text) now
require bytes. XenStore paths and values are specified to be 7-bit ASCII, thus it makes little sense to
allow any Unicode string as input and then validate if it matches the spec.
• Removed transaction argument from Client constructor. The user is advised to use the corresponding
methods explicitly.
• Removed connection argument from Client constructor. The user should now wrap it in a Router.
• Renamed some of the Client methods to more human-readable names:
───────────────────────────────────────────
Old name New name
───────────────────────────────────────────
ls list
───────────────────────────────────────────
rm delete
───────────────────────────────────────────
get_permissions get_perms
───────────────────────────────────────────
set_permissions set_perms
───────────────────────────────────────────
transaction_start transaction
───────────────────────────────────────────
transaction_end commit and rollback
┌───────────────────┬─────────────────────┐
│ │ │
--
AUTHOR
Sergei Lebedev, Fedor Gogolev
COPYRIGHT
2011-2022, Selectel
0.4.2 Jan 31, 2022 PYXS(3)