The following pull request was submitted through Github.
It can be accessed and reviewed at: https://github.com/lxc/pylxd/pull/84
This e-mail was sent by the LXC bot, direct replies will not reach the author
unless they happen to be subscribed to this list.
=== Description (from pull-request) ===
Posted before it's over to get early feedback.
It looks so beautiful now, it's going to be so helpful when it's hosted online !
From 13a70cea504d6ff8cd67e5053fee964f17438fcf Mon Sep 17 00:00:00 2001
From: jpic <james...@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 <james...@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)
_______________________________________________
lxc-devel mailing list
lxc-devel@lists.linuxcontainers.org
http://lists.linuxcontainers.org/listinfo/lxc-devel
