You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@libcloud.apache.org by to...@apache.org on 2013/08/21 22:10:15 UTC
git commit: docs: Add new "Working with the object oriented APIs"
chapter.
Updated Branches:
refs/heads/trunk f62392572 -> 858de16e3
docs: Add new "Working with the object oriented APIs" chapter.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/858de16e
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/858de16e
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/858de16e
Branch: refs/heads/trunk
Commit: 858de16e38e2bf7e5fcf7db313024a6b9c938656
Parents: f623925
Author: Tomaz Muraus <to...@apache.org>
Authored: Wed Aug 21 22:09:40 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Wed Aug 21 22:09:40 2013 +0200
----------------------------------------------------------------------
docs/examples/compute/create_ec2_node.py | 20 +++++++
.../create_ec2_node_manual_instantiation.py | 18 ++++++
docs/examples/dns/list_zone_records.py | 11 ++++
.../list_zone_records_manual_instantiation.py | 13 +++++
docs/other/working-with-oo-apis.rst | 61 ++++++++++++++++++++
5 files changed, 123 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/858de16e/docs/examples/compute/create_ec2_node.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/create_ec2_node.py b/docs/examples/compute/create_ec2_node.py
new file mode 100644
index 0000000..8889410
--- /dev/null
+++ b/docs/examples/compute/create_ec2_node.py
@@ -0,0 +1,20 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+ACCESS_ID = 'your access id'
+SECRET_KEY = 'your secret key'
+
+IMAGE_ID = 'ami-c8052d8d'
+SIZE_ID = 't1.micro'
+
+cls = get_driver(Provider.EC2_US_WEST)
+driver = cls(ACCESS_ID, SECRET_KEY)
+
+# Here we select size and image
+sizes = driver.list_sizes()
+images = driver.list_images()
+
+size = [s for s in sizes if s.id == SIZE_ID][0]
+image = [i for i in images if i.id == IMAGE_ID][0]
+
+node = driver.create_node(name='test-node', image=image, size=size)
http://git-wip-us.apache.org/repos/asf/libcloud/blob/858de16e/docs/examples/compute/create_ec2_node_manual_instantiation.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/create_ec2_node_manual_instantiation.py b/docs/examples/compute/create_ec2_node_manual_instantiation.py
new file mode 100644
index 0000000..db43c4c
--- /dev/null
+++ b/docs/examples/compute/create_ec2_node_manual_instantiation.py
@@ -0,0 +1,18 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+from libcloud.compute.base import NodeSize, NodeImage
+
+ACCESS_ID = 'your access id'
+SECRET_KEY = 'your secret key'
+
+IMAGE_ID = 'ami-c8052d8d'
+SIZE_ID = 't1.micro'
+
+cls = get_driver(Provider.EC2_US_WEST)
+driver = cls(ACCESS_ID, SECRET_KEY)
+
+size = NodeSize(id=SIZE_ID, name=None, ram=None, disk=None, bandwidth=None,
+ price=None, driver=driver)
+image = NodeImage(id=IMAGE_ID, name=None, driver=driver)
+
+node = driver.create_node(name='test-node', image=image, size=size)
http://git-wip-us.apache.org/repos/asf/libcloud/blob/858de16e/docs/examples/dns/list_zone_records.py
----------------------------------------------------------------------
diff --git a/docs/examples/dns/list_zone_records.py b/docs/examples/dns/list_zone_records.py
new file mode 100644
index 0000000..86e4987
--- /dev/null
+++ b/docs/examples/dns/list_zone_records.py
@@ -0,0 +1,11 @@
+from libcloud.dns.providers import get_driver
+from libcloud.dns.types import Provider
+
+CREDENTIALS_ZERIGO = ('email', 'api key')
+ZONE_ID = 'example.myzone.com'
+
+Cls = get_driver(Provider.ZERIGO)
+driver = Cls(*CREDENTIALS_ZERIGO)
+
+zone = driver.get_zone(zone_id=ZONE_ID)
+records = driver.list_records(zone=zone)
http://git-wip-us.apache.org/repos/asf/libcloud/blob/858de16e/docs/examples/dns/list_zone_records_manual_instantiation.py
----------------------------------------------------------------------
diff --git a/docs/examples/dns/list_zone_records_manual_instantiation.py b/docs/examples/dns/list_zone_records_manual_instantiation.py
new file mode 100644
index 0000000..e6d77f2
--- /dev/null
+++ b/docs/examples/dns/list_zone_records_manual_instantiation.py
@@ -0,0 +1,13 @@
+from libcloud.dns.base import Zone
+from libcloud.dns.providers import get_driver
+from libcloud.dns.types import Provider
+
+CREDENTIALS_ZERIGO = ('email', 'api key')
+ZONE_ID = 'example.myzone.com'
+
+Cls = get_driver(Provider.ZERIGO)
+driver = Cls(*CREDENTIALS_ZERIGO)
+
+zone = Zone(ZONE_ID, domain=None, type=None, ttl=None,
+ driver=driver)
+records = driver.list_records(zone=zone)
http://git-wip-us.apache.org/repos/asf/libcloud/blob/858de16e/docs/other/working-with-oo-apis.rst
----------------------------------------------------------------------
diff --git a/docs/other/working-with-oo-apis.rst b/docs/other/working-with-oo-apis.rst
new file mode 100644
index 0000000..45fb45a
--- /dev/null
+++ b/docs/other/working-with-oo-apis.rst
@@ -0,0 +1,61 @@
+Working with the object oriented APIs
+=====================================
+
+To make it easier for the end user, Libcloud components expose a fully
+object-oriented API.
+
+This means that besides the driver object you also work with ``NodeImage``,
+and ``NodeSize`` object in the compute API, ``Container`` and ``Object``
+object in the Storage API, ``Zone`` and ``Record`` object in the DNS API
+and so on.
+
+Methods which operate on those resources usually require you to pass in an
+instance of the resource you want to manipulate or work with and not just an
+id.
+
+To obtain a reference to this resource, Libcloud providers corresponding get
+and / or list methods.
+
+A couple of examples are shown bellow.
+
+Example 1 - listing records for a zone with a known id
+------------------------------------------------------
+
+.. literalinclude:: /examples/dns/list_zone_records.py
+ :language: python
+
+In this example, :func:`driver.get_zone` method call results in an HTTP call.
+
+Example 2 - creating an EC2 instance with a known ``NodeSize`` and ``NodeImage`` id
+-----------------------------------------------------------------------------------
+
+.. literalinclude:: /examples/compute/create_ec2_node.py
+ :language: python
+
+In this example, both :func:`driver.list_sizes` an :func:`driver.list_images`
+method calls result in an HTTP call.
+
+As you can see above, most of those getter methods retrieve extra information
+about the resource from the provider API and result in an HTTP request.
+
+There are some cases when you might not want this:
+
+* You don't care if a resource doesn't exist
+* You don't care about the extra attributes
+* You want to avoid an extra HTTP request
+* You want to avoid holding a reference to the resource object
+
+If that is true for you, you can directly instantiate a resource with a known
+id. You can see how to do this in the examples bellow.
+
+Example 1 - listing records for a zone with a known id
+------------------------------------------------------
+
+.. literalinclude:: /examples/dns/list_zone_records_manual_instantiation.py
+ :language: python
+
+Example 2 - creating an EC2 instance with a known ``NodeSize`` and ``NodeImage`` id
+-----------------------------------------------------------------------------------
+
+.. literalinclude:: /examples/compute/create_ec2_node_manual_instantiation.py
+ :language: python