diff options
author | Josh Durgin <josh.durgin@dreamhost.com> | 2011-09-30 11:30:28 -0700 |
---|---|---|
committer | Josh Durgin <josh.durgin@dreamhost.com> | 2011-09-30 11:37:15 -0700 |
commit | c00e06f697c55dcac2acc53c842f2aaffce35310 (patch) | |
tree | 4f18976575f386491abeb38368fab03dd8e2bc62 | |
parent | 683f4dca796313ac6cbf5d47c47775b097f86a7a (diff) | |
download | ceph-c00e06f697c55dcac2acc53c842f2aaffce35310.tar.gz |
doc: add documentation for librbd python bindings
Signed-off-by: Josh Durgin <josh.durgin@dreamhost.com>
-rwxr-xr-x | admin/build-doc | 2 | ||||
-rw-r--r-- | doc/api/librbdpy.rst | 81 | ||||
-rw-r--r-- | doc/conf.py | 1 |
3 files changed, 83 insertions, 1 deletions
diff --git a/admin/build-doc b/admin/build-doc index 622d7c84031..2b3beedc074 100755 --- a/admin/build-doc +++ b/admin/build-doc @@ -36,5 +36,5 @@ cd .. install -d -m0755 \ output/html \ output/man -./virtualenv/bin/sphinx-build -a -b dirhtml -d doctrees ../doc output/html +PYTHONPATH=`pwd`/../src/pybind ./virtualenv/bin/sphinx-build -a -b dirhtml -d doctrees ../doc output/html ./virtualenv/bin/sphinx-build -a -b man -d doctrees ../doc output/man diff --git a/doc/api/librbdpy.rst b/doc/api/librbdpy.rst new file mode 100644 index 00000000000..6298a6e41e1 --- /dev/null +++ b/doc/api/librbdpy.rst @@ -0,0 +1,81 @@ +================ + Librbd (Python) +================ + +.. highlight:: python + +The `rbd` python module provides file-like access to RBD images. + + +Example: Creating and writing to an image +========================================= + +To use `rbd`, you must first connect to RADOS and open an IO +context:: + + cluster = rados.Rados(conffile='my_ceph.conf') + cluster.connect() + ioctx = cluster.open_ioctx('mypool') + +Then you instantiate an :class:rbd.RBD object, which you use to create the +image:: + + rbd_inst = rbd.RBD() + size = 4 * 1024 * 1024 # 4 GiB + rbd_inst.create('myimage', 4) + +To perform I/O on the image, you instantiate an :class:rbd.Image object:: + + image = rbd.Image('myimage') + data = 'foo' * 200 + image.write(data, 0) + +This writes 'foo' to the first 600 bytes of the image. Note that data +cannot be :type:unicode - `Librbd` does not know how to deal with +characters wider than a :c:type:char. + +In the end, you'll want to close the image, the IO context and the connection to RADOS:: + + image.close() + ioctx.close() + cluster.shutdown() + +To be safe, each of these calls would need to be in a separate :finally +block:: + + cluster = rados.Rados(conffile='my_ceph_conf') + try: + ioctx = cluster.open_ioctx('my_pool') + try: + rbd_inst = rbd.RBD() + size = 4 * 1024 * 1024 # 4 GiB + rbd_inst.create('myimage', 4) + image = rbd.Image('myimage') + try: + data = 'foo' * 200 + image.write(data, 0) + finally: + image.close() + finally: + ioctx.close() + finally: + cluster.shutdown() + +This can be cumbersome, so the :class:Rados, :class:Ioctx, and :class:Image +classes can be used as context managers that close/shutdown automatically (see +:pep:`343`). Using them as context managers, the above example becomes:: + + with rados.Rados(conffile='my_ceph.conf') as cluster: + with cluster.open_ioctx('mypool') as ioctx: + rbd_inst = rbd.RBD() + size = 4 * 1024 * 1024 # 4 GiB + rbd_inst.create('myimage', 4) + with rbd.Image('myimage') is image: + data = 'foo' * 200 + image.write(data, 0) + +API Reference +============= + +.. automodule:: rbd + :members: RBD, Image, SnapIterator diff --git a/doc/conf.py b/doc/conf.py index afac33f816a..4dab00c1604 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -22,6 +22,7 @@ html_sidebars = { # ugly kludge until breathe is distutils-friendly import sys; sys.path.append('../build-doc/breathe') extensions = [ + 'sphinx.ext.autodoc', 'sphinx.ext.graphviz', 'sphinx.ext.todo', 'breathe', |