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 <[email protected]> Authored: Wed Aug 21 22:09:40 2013 +0200 Committer: Tomaz Muraus <[email protected]> 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
