[lxc-devel] [pylxd/master] [WIP] Doc update
jpic on Github
lxc-bot at linuxcontainers.org
Sun May 22 02:21:08 UTC 2016
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 431 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20160522/3ddc4b11/attachment.bin>
-------------- next part --------------
From 13a70cea504d6ff8cd67e5053fee964f17438fcf Mon Sep 17 00:00:00 2001
From: jpic <jamespic at gmail.com>
Date: Sun, 22 May 2016 04:17:28 +0200
Subject: [PATCH 1/2] Remove module that breaks autodoc
---
doc/source/conf.py | 1 -
1 file changed, 1 deletion(-)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 1ede579..1f32bef 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -23,7 +23,6 @@
extensions = [
'sphinx.ext.autodoc',
#'sphinx.ext.intersphinx',
- 'oslosphinx'
]
# autodoc generation is a bit aggressive and a nuisance when doing heavy
From 213e225bc90603c58729a8bbe4ef438aa0a9dd0d Mon Sep 17 00:00:00 2001
From: jpic <jamespic at gmail.com>
Date: Sun, 22 May 2016 04:17:39 +0200
Subject: [PATCH 2/2] Wip on docs
---
doc/source/usage.rst | 48 ++++++++++++++++++++++---
pylxd/client.py | 99 ++++++++++++++++++++++++++++++++++++++++++++--------
2 files changed, 128 insertions(+), 19 deletions(-)
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index bd0155a..f52c27e 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -2,18 +2,56 @@
Usage
=====
-Once you have pylxd installed, you're ready to start interacting with LXD:
+Once you have :doc:`pylxd installed <installation>`, you're ready to
+instanciate an API client to start interacting with the LXD daemon on
+localhost:
.. code-block:: python
- import uuid
- from pylxd import api
+ >>> from pylxd.client import Client
+ >>> client = Client()
- # Let's pick a random name, avoiding clashes
- CONTAINER_NAME = str(uuid.uuid1())
+This :class:`~pylxd.client.Client` object exposes managers for:
+
+- :class:`~pylxd.container.Container`,
+- :class:`~pylxd.profile.Profile`,
+- :class:`~pylxd.operation.Operation`,
+- :class:`~pylxd.image.Image`,
+
+Also, it exposes the HTTP API with the :attr:`~pylxd.client.Client.api`
+attribute.
+
+Containers
+==========
+
+Example creating a :class:`~pylxd.container.Container` with
+:class:`client.containers <pylxd.client.Client.Containers>`'s ``create(config,
+wait=False)``
+attribute, the partial of :meth:`Container.create
+<pylxd.container.Container.create>`:
+
+.. code-block:: python
+
+ >>> container = client.container.create({})
+ [<pylxd.container.Container at 0x7f95d8af72b0>,]
+
+Example getting a list of :class:`~pylxd.container.Container` with
+:meth:`Client.containers.all() <pylxd.client.Client.Containers.all>`:
+
+.. code-block:: python
+
+ >>> client.container.all()
+ [<pylxd.container.Container at 0x7f95d8af72b0>,]
+
+ >>
+
+::
lxd = api.API()
+ # Let's pick a random name, avoiding clashes
+ CONTAINER_NAME = str(uuid.uuid1())
+
try:
lxd.container_defined(CONTAINER_NAME)
except Exception as e:
diff --git a/pylxd/client.py b/pylxd/client.py
index 43db745..5cdbc5c 100644
--- a/pylxd/client.py
+++ b/pylxd/client.py
@@ -32,15 +32,6 @@
class _APINode(object):
"""An api node object.
-
- This class allows us to dynamically create request urls by expressing them
- in python. For example:
-
- >>> node = _APINode('http://example.com/api')
- >>> node.users[1].comments.get()
-
- ...would make an HTTP GET request on
- http://example.com/api/users/1/comments
"""
def __init__(self, api_endpoint):
@@ -77,33 +68,113 @@ def delete(self, *args, **kwargs):
class Client(object):
- """A LXD client.
+ """
+ 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.
+
+ .. attribute:: containers
+
+ Instance of :class:`Client.Containers <pylxd.client.Client.Containers>`:
+
+ .. attribute:: images
+
+ Instance of :class:`Client.Images <pylxd.client.Client.Images>`.
+
+ .. attribute:: operations
+
+ Instance of :class:`Client.Operations <pylxd.client.Client.Operations>`.
+
+ .. attribute:: profiles
+
+ Instance of :class:`Client.Profiles <pylxd.client.Client.Profiles>`.
+
+ .. attribute:: 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()
+ >>> print response.status_code, response.json()
+ >>> print api.containers['test'].get().json()
"""
class Containers(object):
- """A convenience wrapper for :py:class:`~pylxd.container.Container`."""
+ """
+ Manager for :py:class:`~pylxd.container.Container` of a :class:`Client`.
+
+ .. attribute:: all
+
+ Partial of :meth:`Container.all <pylxd.container.Container.all>`,
+ calling it without argument returns the same as calling that method
+ with just the client argument.
+
+ .. attribute:: get
+
+ Partial of of :meth:`Container.get <pylxd.container.Container.get>`.
+
+ .. attribute:: create
+
+ Partial of of :meth:`Container.create <pylxd.container.Container.create>`.
+ """
def __init__(self, client):
self.get = functools.partial(Container.get, client)
self.all = functools.partial(Container.all, client)
self.create = functools.partial(Container.create, client)
class Images(object):
- """A convenience wrapper for :py:class:`~pylxd.image.Image`."""
+ """
+ Manager for :py:class:`~pylxd.image.Image` of a :class:`Client`.
+
+ .. attribute:: all
+
+ Partial of :meth:`Image.all <pylxd.image.Image.all>`,
+
+ .. attribute:: get
+
+ Partial of of :meth:`Image.get <pylxd.image.Image.get>`.
+
+ .. attribute:: create
+
+ Partial of of :meth:`Image.create <pylxd.image.Image.create>`.
+ """
def __init__(self, client):
self.get = functools.partial(Image.get, client)
self.all = functools.partial(Image.all, client)
self.create = functools.partial(Image.create, client)
class Operations(object):
- """A convenience wrapper for :py:class:`~pylxd.operation.Operation`."""
+ """
+ Manager for :py:class:`~pylxd.operation.Operation` of a :class:`Client`.
+
+ .. attribute:: get
+
+ Partial of of :meth:`Operation.get <pylxd.operation.Operation.get>`.
+ """
def __init__(self, client):
self.get = functools.partial(Operation.get, client)
class Profiles(object):
- """A convenience wrapper for :py:class:`~pylxd.profile.Profile`."""
+ """
+ Manager for :py:class:`~pylxd.profile.Profile` of a :class:`Client`.
+
+ .. attribute:: all
+
+ Partial of :meth:`Profile.all <pylxd.profile.Profile.all>`,
+
+ .. attribute:: get
+
+ Partial of of :meth:`Profile.get <pylxd.profile.Profile.get>`.
+
+ .. attribute:: create
+
+ Partial of of :meth:`Profile.create <pylxd.profile.Profile.create>`.
+ """
def __init__(self, client):
self.get = functools.partial(Profile.get, client)
self.all = functools.partial(Profile.all, client)
More information about the lxc-devel
mailing list