[lxc-devel] [pylxd/master] Add more documentation for pylxd
rockstar on Github
lxc-bot at linuxcontainers.org
Sun May 29 23:35:42 UTC 2016
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 447 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20160529/1e28eaf6/attachment.bin>
-------------- next part --------------
From ced78ebba6bb8f4c6a736bc061cde3e431602070 Mon Sep 17 00:00:00 2001
From: Paul Hummer <paul at eventuallyanyway.com>
Date: Sun, 29 May 2016 14:22:39 -0600
Subject: [PATCH 1/8] Update README.rst
---
README.rst | 13 ++-----------
1 file changed, 2 insertions(+), 11 deletions(-)
diff --git a/README.rst b/README.rst
index b991ba2..a93be32 100644
--- a/README.rst
+++ b/README.rst
@@ -7,6 +7,8 @@ pylxd
:target: https://travis-ci.org/lxc/pylxd
.. image:: https://codecov.io/github/lxc/pylxd/coverage.svg?branch=master
:target: https://codecov.io/github/lxc/pylxd
+.. image:: https://readthedocs.org/projects/docs/badge/?version=latest
+ :target: https://pylxd.readthedocs.io/en/latest/?badge=latest
A Python library for interacting with the LXD REST API.
@@ -14,17 +16,6 @@ Installation
=============
``pip install pylxd``
-Documentation
-=============
-
-Documentation is maintained in the doc directory. It can be built with the
-``python setup.py build_sphinx`` command.
-
-Tests
-=====
-
-Tests can be run with tox: ``tox -e integration``.
-
Bug reports
===========
From b6a1d0aecd879a43b53dbcf3cf58ee539cfec7aa Mon Sep 17 00:00:00 2001
From: Paul Hummer <paul at eventuallyanyway.com>
Date: Sun, 29 May 2016 15:05:09 -0600
Subject: [PATCH 2/8] Update contributing document
---
CONTRIBUTING.rst | 3 ---
doc/source/contributing.rst | 35 ++++++++++++++++++++++++++++++++++-
2 files changed, 34 insertions(+), 4 deletions(-)
delete mode 100644 CONTRIBUTING.rst
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
deleted file mode 100644
index 49a394a..0000000
--- a/CONTRIBUTING.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-Bugs and pull requests should be submitted on Github:
-
- https://github.com/lxc/pylxd
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index ed77c12..097f81f 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -1,4 +1,37 @@
============
Contributing
============
-.. include:: ../../CONTRIBUTING.rst
\ No newline at end of file
+
+pyLXD development is done `on Github <https://github.com/lxc/pylxd>`_. Pull
+Requests and Issues should be filed there. We try and respond to PRs and
+Issues within a few days.
+
+If you would like to contribute large features or have big ideas, it's best
+to post on to `the lxc-users list
+<https://lists.linuxcontainers.org/listinfo/lxc-users>`_
+to discuss your ideas before submitting PRs.
+
+Code standards
+--------------
+
+pyLXD follows `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ as closely
+as practical. To check your compliance, use the `pep8` tox target::
+
+ tox -epep8
+
+Testing
+-------
+
+pyLXD tries to follow best practices when it comes to testing. PRs are gated
+by `Travis CI <https://travis-ci.org/lxc/pylxd>`_ and
+`CodeCov <https://codecov.io/gh/lxc/pylxd>`_. It's best to submit tests
+with new changes, as your patch is unlikely to be accepted without them.
+
+To run the tests, you can use nose::
+
+ nosetests pylxd
+
+...or, alternatively, you can use `tox` (with the added bonus that it will
+test python 2.7, python 3, and pypy, as well as run pep8). This is the way
+that Travis will test, so it's recommended that you run this at least once
+before submitting a Pull Request.
From 4b3dad5e9ac4e3dcfef54dea6be3491bc053a664 Mon Sep 17 00:00:00 2001
From: Paul Hummer <paul at eventuallyanyway.com>
Date: Sun, 29 May 2016 15:10:33 -0600
Subject: [PATCH 3/8] Update skeleton copyright (not OpenStack Foundation)
---
doc/source/conf.py | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 1f32bef..7aa2a72 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -37,7 +37,7 @@
# General information about the project.
project = u'pylxd'
-copyright = u'2013, OpenStack Foundation'
+copyright = u'2016, Canonical Ltd'
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True
@@ -67,8 +67,8 @@
('index',
'%s.tex' % project,
u'%s Documentation' % project,
- u'OpenStack Foundation', 'manual'),
+ u'Canonical Ltd', 'manual'),
]
# Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
\ No newline at end of file
+#intersphinx_mapping = {'http://docs.python.org/': None}
From 182abc25c9b49828d876030e08ae93c21ee3cda8 Mon Sep 17 00:00:00 2001
From: Paul Hummer <paul at eventuallyanyway.com>
Date: Sun, 29 May 2016 15:13:46 -0600
Subject: [PATCH 4/8] Update installation doc
---
doc/source/installation.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index bdf21a7..c75a08b 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -2,7 +2,7 @@
Installation
============
-If you're running on Ubuntu Wily or greater::
+If you're running on Ubuntu Xenial or greater::
sudo apt-get install python-pylxd lxd
From 8776c53aeaac0f85312ce764b782bd79bdd7e4bb Mon Sep 17 00:00:00 2001
From: Paul Hummer <paul at eventuallyanyway.com>
Date: Sun, 29 May 2016 15:43:44 -0600
Subject: [PATCH 5/8] Update usage docs for containers.
---
doc/source/usage.rst | 40 +++++++++++++++++++++++++++-------------
examples/api_test.py | 32 --------------------------------
2 files changed, 27 insertions(+), 45 deletions(-)
delete mode 100755 examples/api_test.py
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index f12d1e8..a243357 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -5,7 +5,7 @@ Usage
.. currentmodule:: pylxd
Once you have :doc:`installed <installation>`, you're ready to
-instanciate an API client to start interacting with the LXD daemon on
+instantiate an API client to start interacting with the LXD daemon on
localhost:
.. code-block:: python
@@ -37,26 +37,40 @@ This :class:`~client.Client` object exposes managers for:
Containers
==========
-Example creating a :class:`~container.Container` with
-:class:`client.containers <client.Client.Containers>`'s ``create(config,
-wait=False)``
-attribute, the partial of :meth:`Container.create
-<container.Container.create>`:
+In order to create a new container, a container config dictionary is needed,
+containing a name and the source. A create operation is asynchronous, so
+the operation will take some time. If you'd like to wait for the container
+to be created before the command returns, you'll pass `wait=True` as well.
.. code-block:: python
- >>> container = client.containers.create(dict(name='testcont'))
- [<container.Container at 0x7f95d8af72b0>,]
+ >>> config = {'name': 'my-container', 'source': {'type': 'none'}}
+ >>> container = client.containers.create(config, wait=False)
+ >>> container
+ <container.Container at 0x7f95d8af72b0>
+
+
+If you were to use an actual image source, you would be able to operate
+on the container, starting, stopping, snapshotting, and deleting the
+container.
+
+ >>> container.start()
+ >>> container.freeze()
+ >>> container.delete()
-Example getting a list of :class:`~container.Container` with
-:meth:`Client.containers.all() <client.Client.Containers.all>`:
+
+If you're looking to operate on all containers of a LXD instance, you can
+get a list of all LXD containers with `all`.
.. code-block:: python
>>> client.containers.all()
[<container.Container at 0x7f95d8af72b0>,]
-Examples
-========
-See more examples in the ``examples/`` directory of the repository.
+...or if you'd only like to fetch a single container by its name...
+
+.. code-block:: python
+
+ >>> client.containers.get('my-container')
+ <container.Container at 0x7f95d8af72b0>
diff --git a/examples/api_test.py b/examples/api_test.py
deleted file mode 100755
index 9ec7495..0000000
--- a/examples/api_test.py
+++ /dev/null
@@ -1,32 +0,0 @@
-#!/usr/bin/python
-
-# Copyright (c) 2015 Canonical Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License"); you may
-# not use this file except in compliance with the License. You may obtain
-# a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-# License for the specific language governing permissions and limitations
-# under the License.
-
-import uuid
-
-from pylxd.client import Client
-
-# Let's pick a random name, avoiding clashes
-CONTAINER_NAME = str(uuid.uuid1()).split('-')[0]
-
-lxd = Client()
-
-container_config = {
- 'name': CONTAINER_NAME,
- 'source': {'type': 'none'},
-}
-container = lxd.containers.create(container_config, wait=True)
-
-container.delete(wait=True)
From 7dba0d305f245b0de4a61da18c215590f7672b39 Mon Sep 17 00:00:00 2001
From: Paul Hummer <paul at eventuallyanyway.com>
Date: Sun, 29 May 2016 17:26:30 -0600
Subject: [PATCH 6/8] Add documentation for the other objects.
---
doc/source/usage.rst | 120 +++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 103 insertions(+), 17 deletions(-)
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index a243357..c7abc6f 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -26,21 +26,60 @@ of (cert, key) as the `cert` argument.
Note: in the case where the certificate is self signed (LXD default),
you may need to pass `verify=False`.
-This :class:`~client.Client` object exposes managers for:
-
-- :class:`~container.Container`,
-- :class:`~profile.Profile`,
-- :class:`~operation.Operation`,
-- :class:`~image.Image`,
+:class:`~client.Client` exposes an object manager protocol for
+:class:`~container.Container`, :class:`~image.Image`, and
+:class:`~profile.Profile`. These managers are `containers`, `images`,
+and `profiles` attributes on the Client itself, and contain three
+special methods.
+
+- `create` creates new object. The arguments required differ based
+ on the object that is being created.
+- `get` will get a single object by its key. Each object is keyed by its
+ own property.
+- `all` returns a list of all the objects. The caveat here is that
+ the object is "incomplete", i.e. it doesn't have all its properties
+ populated yet. Each object will require a call to `fetch` before
+ it can be modified/saved.
Containers
==========
-In order to create a new container, a container config dictionary is needed,
-containing a name and the source. A create operation is asynchronous, so
-the operation will take some time. If you'd like to wait for the container
-to be created before the command returns, you'll pass `wait=True` as well.
+If you'd only like to fetch a single container by its name...
+
+.. code-block:: python
+
+ >>> client.containers.get('my-container')
+ <container.Container at 0x7f95d8af72b0>
+
+
+If you're looking to operate on all containers of a LXD instance, you can
+get a list of all LXD containers with `all`.
+
+.. code-block:: python
+
+ >>> client.containers.all()
+ [<container.Container at 0x7f95d8af72b0>,]
+
+
+See the above caveat about `all`. For example:
+The caveat with `all` is that you won't have fully fetched objects. You'll
+have an impartial object, so you must call `fetch` on the Container before
+operating on it.
+
+ >>> container = client.containers.all()[0]
+ >>> container.architecture
+ AttributeError: ...
+ >>> container.fetch()
+ >>> container.architecture
+ 'x86_64'
+
+
+In order to create a new :class:`~container.Container`, a container
+config dictionary is needed, containing a name and the source. A create
+operation is asynchronous, so the operation will take some time. If you'd
+like to wait for the container to be created before the command returns,
+you'll pass `wait=True` as well.
.. code-block:: python
@@ -59,18 +98,65 @@ container.
>>> container.delete()
-If you're looking to operate on all containers of a LXD instance, you can
-get a list of all LXD containers with `all`.
+Images
+------
+
+:class:`~image.Image` operations follow the same protocol from the client`s
+`images` manager (i.e. `get`, `all`, and `create`). Images are keyed on
+a sha-1 fingerprint of the image itself. To get an image...
.. code-block:: python
- >>> client.containers.all()
- [<container.Container at 0x7f95d8af72b0>,]
+ >>> image = client.images.get(
+ ... 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855')
+ >>> image
+ <image.Image at 0x7f95d8af72b0>
-...or if you'd only like to fetch a single container by its name...
+Once you have an image, you can operate on it as before:
.. code-block:: python
- >>> client.containers.get('my-container')
- <container.Container at 0x7f95d8af72b0>
+ >>> image.public
+ False
+ >>> image.public = True
+ >>> image.update()
+
+
+To create a new Image, you'll open an image file, and pass that to `create`.
+If the image is to be public, `public=True`. As this is an asynchonous operation,
+you may also want to `wait=True`.
+
+.. code-block:: python
+
+ >>> image_data = open('an_image.tar.gz').read()
+ >>> image = client.images.create(image_data, public=True, wait=True)
+ >>> image.fingerprint
+ 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+
+
+Profiles
+--------
+
+:class:`~profile.Profile` operations follow the same manager-style as
+Containers and Images. Profiles are keyed on a unique name.
+
+.. code-block:: python
+
+ >>> profile = client.profiles.get('my-profile')
+ >>> profile
+ <profile.Profile at 0x7f95d8af72b0>
+
+
+The profile can then be modified and saved.
+
+ >>> profile.config = profile.config.update({'security.nesting': 'true'})
+ >>> profile.update()
+
+
+To create a new profile, use `create` with a name, and optional `config`
+and `devices` config dictionaries.
+
+ >>> profile = client.profiles.create(
+ ... 'an-profile', config={'security.nesting': 'true'},
+ ... devices={'root': {'path': '/', 'size': '10GB', 'type': 'disk'}})
From c4ef418d996178270f2061688e93a8ce1365518c Mon Sep 17 00:00:00 2001
From: Paul Hummer <paul at eventuallyanyway.com>
Date: Sun, 29 May 2016 17:33:56 -0600
Subject: [PATCH 7/8] Add more changes based on a local build of the docs
---
doc/source/usage.rst | 10 ++++++++--
1 file changed, 8 insertions(+), 2 deletions(-)
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index c7abc6f..c6fc14a 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -4,6 +4,9 @@ Usage
.. currentmodule:: pylxd
+Client
+======
+
Once you have :doc:`installed <installation>`, you're ready to
instantiate an API client to start interacting with the LXD daemon on
localhost:
@@ -26,6 +29,9 @@ of (cert, key) as the `cert` argument.
Note: in the case where the certificate is self signed (LXD default),
you may need to pass `verify=False`.
+Client Managers
+---------------
+
:class:`~client.Client` exposes an object manager protocol for
:class:`~container.Container`, :class:`~image.Image`, and
:class:`~profile.Profile`. These managers are `containers`, `images`,
@@ -99,7 +105,7 @@ container.
Images
-------
+======
:class:`~image.Image` operations follow the same protocol from the client`s
`images` manager (i.e. `get`, `all`, and `create`). Images are keyed on
@@ -136,7 +142,7 @@ you may also want to `wait=True`.
Profiles
---------
+========
:class:`~profile.Profile` operations follow the same manager-style as
Containers and Images. Profiles are keyed on a unique name.
From 280f43d397ecc9f474db38b9588c1e67958b41cd Mon Sep 17 00:00:00 2001
From: Paul Hummer <paul at eventuallyanyway.com>
Date: Sun, 29 May 2016 17:35:45 -0600
Subject: [PATCH 8/8] Remove HACKING (it's unneeded)
---
HACKING.rst | 4 ----
1 file changed, 4 deletions(-)
delete mode 100644 HACKING.rst
diff --git a/HACKING.rst b/HACKING.rst
deleted file mode 100644
index 4f5848e..0000000
--- a/HACKING.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-pylxd Style Commandments
-===============================================
-
-Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/
\ No newline at end of file
More information about the lxc-devel
mailing list