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/03 18:00:37 UTC
[1/7] git commit: Port base storage api docstrings to Sphinx format,
add storage sphinx api docs.
Updated Branches:
refs/heads/trunk 937e33a27 -> 73bd38289
Port base storage api docstrings to Sphinx format, add storage sphinx api docs.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/a8627b48
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/a8627b48
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/a8627b48
Branch: refs/heads/trunk
Commit: a8627b48bf0ca9c97aea77600e81dce7dd38b0ae
Parents: 937e33a
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 17:07:07 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 17:07:07 2013 +0200
----------------------------------------------------------------------
docs/storage/api.rst | 5 +
libcloud/storage/base.py | 325 +++++++++++++++++++++---------------------
2 files changed, 167 insertions(+), 163 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8627b48/docs/storage/api.rst
----------------------------------------------------------------------
diff --git a/docs/storage/api.rst b/docs/storage/api.rst
new file mode 100644
index 0000000..f44b0b4
--- /dev/null
+++ b/docs/storage/api.rst
@@ -0,0 +1,5 @@
+Storage Base API
+================
+
+.. autoclass:: libcloud.storage.base.StorageDriver
+ :members:
http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8627b48/libcloud/storage/base.py
----------------------------------------------------------------------
diff --git a/libcloud/storage/base.py b/libcloud/storage/base.py
index f0e4e3a..4a965b8 100644
--- a/libcloud/storage/base.py
+++ b/libcloud/storage/base.py
@@ -44,26 +44,26 @@ class Object(object):
def __init__(self, name, size, hash, extra, meta_data, container,
driver):
"""
- @param name: Object name (must be unique per container).
- @type name: C{str}
+ :param name: Object name (must be unique per container).
+ :type name: ``str``
- @param size: Object size in bytes.
- @type size: C{int}
+ :param size: Object size in bytes.
+ :type size: ``int``
- @param hash Object hash.
- @type hash: C{str}
+ :param hash Object hash.
+ :type hash: ``str``
- @param container: Object container.
- @type container: L{Container}
+ :param container: Object container.
+ :type container: :class:`Container`
- @param extra: Extra attributes.
- @type extra: C{dict}
+ :param extra: Extra attributes.
+ :type extra: ``dict``
- @param meta_data: Optional object meta data.
- @type meta_data: C{dict}
+ :param meta_data: Optional object meta data.
+ :type meta_data: ``dict``
- @param driver: StorageDriver instance.
- @type driver: L{StorageDriver}
+ :param driver: StorageDriver instance.
+ :type driver: :class:`StorageDriver`
"""
self.name = name
@@ -104,14 +104,14 @@ class Container(object):
def __init__(self, name, extra, driver):
"""
- @param name: Container name (must be unique).
- @type name: C{str}
+ :param name: Container name (must be unique).
+ :type name: ``str``
- @param extra: Extra attributes.
- @type extra: C{dict}
+ :param extra: Extra attributes.
+ :type extra: ``dict``
- @param driver: StorageDriver instance.
- @type driver: L{StorageDriver}
+ :param driver: StorageDriver instance.
+ :type driver: :class:`StorageDriver`
"""
self.name = name
@@ -183,8 +183,8 @@ class StorageDriver(BaseDriver):
"""
Return a generator of containers for the given account
- @return: A generator of Container instances.
- @rtype: C{generator} of L{Container}
+ :return: A generator of Container instances.
+ :rtype: ``generator`` of :class:`Container`
"""
raise NotImplementedError(
'iterate_containers not implemented for this driver')
@@ -193,8 +193,8 @@ class StorageDriver(BaseDriver):
"""
Return a list of containers.
- @return: A list of Container instances.
- @rtype: C{list} of L{Container}
+ :return: A list of Container instances.
+ :rtype: ``list`` of :class:`Container`
"""
return list(self.iterate_containers())
@@ -202,11 +202,11 @@ class StorageDriver(BaseDriver):
"""
Return a generator of objects for the given container.
- @param container: Container instance
- @type container: L{Container}
+ :param container: Container instance
+ :type container: :class:`Container`
- @return: A generator of Object instances.
- @rtype: C{generator} of L{Object}
+ :return: A generator of Object instances.
+ :rtype: ``generator`` of :class:`Object`
"""
raise NotImplementedError(
'iterate_container_objects not implemented for this driver')
@@ -215,11 +215,11 @@ class StorageDriver(BaseDriver):
"""
Return a list of objects for the given container.
- @param container: Container instance
- @type container: L{Container}
+ :param container: Container instance.
+ :type container: :class:`Container`
- @return: A list of Object instances.
- @rtype: C{list} of L{Object}
+ :return: A list of Object instances.
+ :rtype: ``list`` of :class:`Object`
"""
return list(self.iterate_container_objects(container))
@@ -227,11 +227,11 @@ class StorageDriver(BaseDriver):
"""
Return a container instance.
- @param container_name: Container name.
- @type container_name: C{str}
+ :param container_name: Container name.
+ :type container_name: ``str``
- @return: L{Container} instance.
- @rtype: L{Container}
+ :return: :class:`Container` instance.
+ :rtype: :class:`Container`
"""
raise NotImplementedError(
'get_object not implemented for this driver')
@@ -240,11 +240,11 @@ class StorageDriver(BaseDriver):
"""
Return a container CDN URL.
- @param container: Container instance
- @type container: L{Container}
+ :param container: Container instance
+ :type container: :class:`Container`
- @return: A CDN URL for this container.
- @rtype: C{str}
+ :return: A CDN URL for this container.
+ :rtype: ``str``
"""
raise NotImplementedError(
'get_container_cdn_url not implemented for this driver')
@@ -253,14 +253,14 @@ class StorageDriver(BaseDriver):
"""
Return an object instance.
- @param container_name: Container name.
- @type container_name: C{str}
+ :param container_name: Container name.
+ :type container_name: ``str``
- @param object_name: Object name.
- @type object_name: C{str}
+ :param object_name: Object name.
+ :type object_name: ``str``
- @return: L{Object} instance.
- @rtype: L{Object}
+ :return: :class:`Object` instance.
+ :rtype: :class:`Object`
"""
raise NotImplementedError(
'get_object not implemented for this driver')
@@ -269,11 +269,11 @@ class StorageDriver(BaseDriver):
"""
Return a object CDN URL.
- @param obj: Object instance
- @type obj: L{Object}
+ :param obj: Object instance
+ :type obj: :class:`Object`
- @return: A CDN URL for this object.
- @rtype: C{str}
+ :return: A CDN URL for this object.
+ :rtype: ``str``
"""
raise NotImplementedError(
'get_object_cdn_url not implemented for this driver')
@@ -282,10 +282,10 @@ class StorageDriver(BaseDriver):
"""
Enable container CDN.
- @param container: Container instance
- @type container: L{Container}
+ :param container: Container instance
+ :type container: :class:`Container`
- @rtype: C{bool}
+ :rtype: ``bool``
"""
raise NotImplementedError(
'enable_container_cdn not implemented for this driver')
@@ -294,10 +294,10 @@ class StorageDriver(BaseDriver):
"""
Enable object CDN.
- @param obj: Object instance
- @type obj: L{Object}
+ :param obj: Object instance
+ :type obj: :class:`Object`
- @rtype: C{bool}
+ :rtype: ``bool``
"""
raise NotImplementedError(
'enable_object_cdn not implemented for this driver')
@@ -307,24 +307,25 @@ class StorageDriver(BaseDriver):
"""
Download an object to the specified destination path.
- @param obj: Object instance.
- @type obj: L{Object}
+ :param obj: Object instance.
+ :type obj: :class:`Object`
- @param destination_path: Full path to a file or a directory where the
- incoming file will be saved.
- @type destination_path: C{str}
+ :param destination_path: Full path to a file or a directory where the
+ incoming file will be saved.
+ :type destination_path: ``str``
- @param overwrite_existing: True to overwrite an existing file,
- defaults to False.
- @type overwrite_existing: C{bool}
+ :param overwrite_existing: True to overwrite an existing file,
+ defaults to False.
+ :type overwrite_existing: ``bool``
- @param delete_on_failure: True to delete a partially downloaded file if
- the download was not successful (hash mismatch / file size).
- @type delete_on_failure: C{bool}
+ :param delete_on_failure: True to delete a partially downloaded file if
+ the download was not successful (hash
+ mismatch / file size).
+ :type delete_on_failure: ``bool``
- @return: True if an object has been successfully downloaded, False
- otherwise.
- @rtype: C{bool}
+ :return: True if an object has been successfully downloaded, False
+ otherwise.
+ :rtype: ``bool``
"""
raise NotImplementedError(
'download_object not implemented for this driver')
@@ -333,13 +334,11 @@ class StorageDriver(BaseDriver):
"""
Return a generator which yields object data.
- @param obj: Object instance
- @type obj: L{Object}
+ :param obj: Object instance
+ :type obj: :class:`Object`
- @param chunk_size: Optional chunk size (in bytes).
- @type chunk_size: C{int}
-
- @rtype: C{object}
+ :param chunk_size: Optional chunk size (in bytes).
+ :type chunk_size: ``int``
"""
raise NotImplementedError(
'download_object_as_stream not implemented for this driver')
@@ -349,22 +348,22 @@ class StorageDriver(BaseDriver):
"""
Upload an object currently located on a disk.
- @param file_path: Path to the object on disk.
- @type file_path: C{str}
+ :param file_path: Path to the object on disk.
+ :type file_path: ``str``
- @param container: Destination container.
- @type container: L{Container}
+ :param container: Destination container.
+ :type container: :class:`Container`
- @param object_name: Object name.
- @type object_name: C{str}
+ :param object_name: Object name.
+ :type object_name: ``str``
- @param verify_hash: Verify hash
- @type verify_hash: C{bool}
+ :param verify_hash: Verify hash
+ :type verify_hash: ``bool``
- @param extra: (optional) Extra attributes (driver specific).
- @type extra: C{dict}
+ :param extra: Extra attributes (driver specific). (optional)
+ :type extra: ``dict``
- @rtype: C{object}
+ :rtype: :class:`Object`
"""
raise NotImplementedError(
'upload_object not implemented for this driver')
@@ -389,21 +388,21 @@ class StorageDriver(BaseDriver):
function which uses fs.stat function to determine the file size and it
doesn't need to buffer whole object in the memory.
- @type iterator: C{object}
- @param iterator: An object which implements the iterator interface.
+ :type iterator: :class:`object`
+ :param iterator: An object which implements the iterator interface.
- @type container: L{Container}
- @param container: Destination container.
+ :type container: :class:`Container`
+ :param container: Destination container.
- @type object_name: C{str}
- @param object_name: Object name.
+ :type object_name: ``str``
+ :param object_name: Object name.
- @type extra: C{dict}
- @param extra: (optional) Extra attributes (driver specific). Note:
+ :type extra: ``dict``
+ :param extra: (optional) Extra attributes (driver specific). Note:
This dictionary must contain a 'content_type' key which represents
a content type of the stored object.
- @rtype: C{object}
+ :rtype: C{object}
"""
raise NotImplementedError(
'upload_object_via_stream not implemented for this driver')
@@ -412,11 +411,11 @@ class StorageDriver(BaseDriver):
"""
Delete an object.
- @type obj: L{Object}
- @param obj: Object instance.
+ :type obj: :class:`Object`
+ :param obj: Object instance.
- @return: C{bool} True on success.
- @rtype: C{bool}
+ :return: ``bool`` True on success.
+ :rtype: ``bool``
"""
raise NotImplementedError(
'delete_object not implemented for this driver')
@@ -425,11 +424,11 @@ class StorageDriver(BaseDriver):
"""
Create a new container.
- @type container_name: C{str}
- @param container_name: Container name.
+ :type container_name: ``str``
+ :param container_name: Container name.
- @return: C{Container} instance on success.
- @rtype: L{Container}
+ :return: Container instance on success.
+ :rtype: :class:`Container`
"""
raise NotImplementedError(
'create_container not implemented for this driver')
@@ -438,11 +437,11 @@ class StorageDriver(BaseDriver):
"""
Delete a container.
- @type container: L{Container}
- @param container: Container instance
+ :type container: :class:`Container`
+ :param container: Container instance
- @return: True on success, False otherwise.
- @rtype: C{bool}
+ :return: ``True`` on success, ``False`` otherwise.
+ :rtype: ``bool``
"""
raise NotImplementedError(
'delete_container not implemented for this driver')
@@ -452,26 +451,26 @@ class StorageDriver(BaseDriver):
"""
Call passed callback and start transfer of the object'
- @type obj: C{Object}
- @param obj: Object instance.
+ :type obj: :class:`Object`
+ :param obj: Object instance.
- @type callback: C{Function}
- @param callback: Function which is called with the passed
+ :type callback: :class:`function`
+ :param callback: Function which is called with the passed
callback_kwargs
- @type callback_kwargs: C{dict}
- @param callback_kwargs: Keyword arguments which are passed to the
+ :type callback_kwargs: ``dict``
+ :param callback_kwargs: Keyword arguments which are passed to the
callback.
- @typed response: L{Response}
- @param response: Response instance.
+ :typed response: :class:`Response`
+ :param response: Response instance.
- @type success_status_code: C{int}
- @param success_status_code: Status code which represents a successful
+ :type success_status_code: ``int``
+ :param success_status_code: Status code which represents a successful
transfer (defaults to httplib.OK)
- @return: True on success, False otherwise.
- @rtype: C{bool}
+ :return: ``True`` on success, ``False`` otherwise.
+ :rtype: ``bool``
"""
success_status_code = success_status_code or httplib.OK
@@ -491,29 +490,29 @@ class StorageDriver(BaseDriver):
"""
Save object to the provided path.
- @type response: L{RawResponse}
- @param response: RawResponse instance.
+ :type response: :class:`RawResponse`
+ :param response: RawResponse instance.
- @type obj: L{Object}
- @param obj: Object instance.
+ :type obj: :class:`Object`
+ :param obj: Object instance.
- @type destination_path: C{str}
- @param destination_path: Destination directory.
+ :type destination_path: ``str``
+ :param destination_path: Destination directory.
- @type delete_on_failure: C{bool}
- @param delete_on_failure: True to delete partially downloaded object if
+ :type delete_on_failure: ``bool``
+ :param delete_on_failure: True to delete partially downloaded object if
the download fails.
- @type overwrite_existing: C{bool}
- @param overwrite_existing: True to overwrite a local path if it already
+ :type overwrite_existing: ``bool``
+ :param overwrite_existing: True to overwrite a local path if it already
exists.
- @type chunk_size: C{int}
- @param chunk_size: Optional chunk size
- (defaults to L{libcloud.storage.base.CHUNK_SIZE}, 8kb)
+ :type chunk_size: ``int``
+ :param chunk_size: Optional chunk size
+ (defaults to ``libcloud.storage.base.CHUNK_SIZE``, 8kb)
- @return: True on success, False otherwise.
- @rtype: C{bool}
+ :return: ``True`` on success, ``False`` otherwise.
+ :rtype: ``bool``
"""
chunk_size = chunk_size or CHUNK_SIZE
@@ -640,18 +639,18 @@ class StorageDriver(BaseDriver):
"""
Upload data stored in a string.
- @type response: C{RawResponse}
- @param response: RawResponse object.
+ :type response: :class:`RawResponse`
+ :param response: RawResponse object.
- @type data: C{str}
- @param data: Data to upload.
+ :type data: ``str``
+ :param data: Data to upload.
- @type calculate_hash: C{boolean}
- @param calculate_hash: True to calculate hash of the transfered data.
+ :type calculate_hash: ``bool``
+ :param calculate_hash: True to calculate hash of the transfered data.
(defauls to True).
- @rtype: C{tuple}
- @return: First item is a boolean indicator of success, second
+ :rtype: ``tuple``
+ :return: First item is a boolean indicator of success, second
one is the uploaded data MD5 hash and the third one
is the number of transferred bytes.
"""
@@ -681,26 +680,26 @@ class StorageDriver(BaseDriver):
"""
Stream a data over an http connection.
- @type response: C{RawResponse}
- @param response: RawResponse object.
+ :type response: :class:`RawResponse`
+ :param response: RawResponse object.
- @type iterator: C{}
- @param response: An object which implements an iterator interface
+ :type iterator: :class:`object`
+ :param response: An object which implements an iterator interface
or a File like object with read method.
- @type chunked: C{boolean}
- @param chunked: True if the chunked transfer encoding should be used
+ :type chunked: ``bool``
+ :param chunked: True if the chunked transfer encoding should be used
(defauls to False).
- @type calculate_hash: C{boolean}
- @param calculate_hash: True to calculate hash of the transfered data.
+ :type calculate_hash: ``bool``
+ :param calculate_hash: True to calculate hash of the transfered data.
(defauls to True).
- @type chunk_size: C{int}
- @param chunk_size: Optional chunk size (defaults to CHUNK_SIZE)
+ :type chunk_size: ``int``
+ :param chunk_size: Optional chunk size (defaults to ``CHUNK_SIZE``)
- @rtype: C{tuple}
- @return: First item is a boolean indicator of success, second
+ :rtype: ``tuple``
+ :return: First item is a boolean indicator of success, second
one is the uploaded data MD5 hash and the third one
is the number of transferred bytes.
"""
@@ -766,18 +765,18 @@ class StorageDriver(BaseDriver):
"""
Upload a file to the server.
- @type response: C{RawResponse}
- @param response: RawResponse object.
+ :type response: :class:`RawResponse`
+ :param response: RawResponse object.
- @type file_path: C{str}
- @param file_path: Path to a local file.
+ :type file_path: ``str``
+ :param file_path: Path to a local file.
- @type iterator: C{}
- @param response: An object which implements an iterator interface (File
+ :type iterator: :class:`object`
+ :param response: An object which implements an iterator interface (File
object, etc.)
- @rtype: C{tuple}
- @return: First item is a boolean indicator of success, second
+ :rtype: ``tuple``
+ :return: First item is a boolean indicator of success, second
one is the uploaded data MD5 hash and the third one
is the number of transferred bytes.
"""
[7/7] git commit: Port "SSL Certificate Validation" documentation
section.
Posted by to...@apache.org.
Port "SSL Certificate Validation" documentation section.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/73bd3828
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/73bd3828
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/73bd3828
Branch: refs/heads/trunk
Commit: 73bd382891e6b168eafcb7e5dd04d5e1f62b4b6a
Parents: 75ac8ca
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 17:59:22 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 17:59:22 2013 +0200
----------------------------------------------------------------------
docs/other/ssl-certificate-validation.rst | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/73bd3828/docs/other/ssl-certificate-validation.rst
----------------------------------------------------------------------
diff --git a/docs/other/ssl-certificate-validation.rst b/docs/other/ssl-certificate-validation.rst
new file mode 100644
index 0000000..ec02782
--- /dev/null
+++ b/docs/other/ssl-certificate-validation.rst
@@ -0,0 +1,26 @@
+SSL Certificate Validation
+==========================
+
+When establishing a secure connection to a cloud provider endpoint,
+Libcloud verifies server SSL certificate. By default, Libcloud searches
+paths listed in ``libcloud.security.CA_CERTS_PATH`` for CA certificate files.
+
+``CA_CERTS_PATH`` contains common paths to CA bundle installations on the
+following platforms:
+
+* openssl on CentOS / Fedora
+* ca-certificates on Debian / Ubuntu / Arch / Gentoo
+* ca_root_nss on FreeBSD
+* curl-ca-bundle on Mac OS X
+
+If no valid CA certificate files are found, you will see an error message
+similar to the one bellow:
+
+``No CA Certificates were found in CA_CERTS_PATH.``
+
+Acquiring CA Certificates
+-------------------------
+
+If the above packages are unavailable to you, and you don't wish to roll
+your own, the makers of cURL provides an excellent resource, generated
+from Mozilla: http://curl.haxx.se/docs/caextract.html.
[6/7] git commit: Add troubleshoting section to the docs.
Posted by to...@apache.org.
Add troubleshoting section to the docs.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/75ac8ca5
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/75ac8ca5
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/75ac8ca5
Branch: refs/heads/trunk
Commit: 75ac8ca5f4524f83750508129080ec8b1c5e7f87
Parents: b6be3e7
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 17:56:12 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 17:56:12 2013 +0200
----------------------------------------------------------------------
docs/troubleshooting.rst | 48 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 48 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/75ac8ca5/docs/troubleshooting.rst
----------------------------------------------------------------------
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
new file mode 100644
index 0000000..78cb6e0
--- /dev/null
+++ b/docs/troubleshooting.rst
@@ -0,0 +1,48 @@
+Troubleshooting
+===============
+
+This page contains various tips which can help you troubleshoot and debug
+code with interfaces with libcloud.
+
+Debugging
+---------
+
+Libcloud has a special debug mode which when enabled outputs all the outgoing
+HTTP requests and all the incoming HTTP responses. Output also includes cURL
+commands which can be used to re-produce the requests.
+
+When this mode is enabled and if ``paramiko`` library is installed (used for
+deployment), paramiko library log level is also set to ``DEBUG`` which helps
+with debugging the deployment issues.
+
+To enable it, set ``LIBCLOUD_DEBUG`` environment variable and make it point
+to a file where the output should be saved.
+
+For example if you want the output to be logged to the standard error (on
+Unix) you can set it to ``/dev/stderr``:
+
+.. sourcecode:: bash
+
+ LIBCLOUD_DEBUG=/dev/stderr python my_script.py.
+
+Example output:
+
+.. sourcecode:: bash
+
+ # -------- begin 4431824872 request ----------
+ curl -i -X GET -H 'Host: s3.amazonaws.com' -H 'X-LC-Request-ID: 4431824872' -H 'Content-Length: 0' -H 'User-Agent: libcloud/0.6.0-beta1 (Amazon S3 (standard))' 'https://s3.amazonaws.com:443/?AWSAccessKeyId=foo&Signature=bar'
+ # -------- begin 4431824872:4431825232 response ----------
+ HTTP/1.1 200 OK
+ X-Amz-Id-2: 1234
+ Server: AmazonS3
+ Transfer-Encoding: chunked
+ X-Amz-Request-Id: FFFFFFFFFF
+ Date: Tue, 01 Nov 2011 22:29:11 GMT
+ Content-Type: application/xml
+
+ 171
+ <?xml version="1.0" encoding="UTF-8"?>
+ <ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><Owner><ID>sada8932dsa8d30i</ID><DisplayName>kami</DisplayName></Owner><Buckets><Bucket><Name>test34324323</Name><CreationDate>2011-11-01T22:17:23.000Z</CreationDate></Bucket></Buckets></ListAllMyBucketsResult>
+ 0
+
+ # -------- end 4431824872:4431825232 response ----------
[4/7] git commit: Hook up example and base api links for storage,
dns and loadbalancer api.
Posted by to...@apache.org.
Hook up example and base api links for storage, dns and loadbalancer api.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/318ed78c
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/318ed78c
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/318ed78c
Branch: refs/heads/trunk
Commit: 318ed78c333deefa70bee8481087e4665630b10b
Parents: 3132bf5
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 17:14:55 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 17:14:55 2013 +0200
----------------------------------------------------------------------
docs/dns/index.rst | 11 +++++++++++
docs/loadbalancer/index.rst | 11 +++++++++++
docs/storage/index.rst | 11 +++++++++++
3 files changed, 33 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/318ed78c/docs/dns/index.rst
----------------------------------------------------------------------
diff --git a/docs/dns/index.rst b/docs/dns/index.rst
index 7e899b1..dafb455 100644
--- a/docs/dns/index.rst
+++ b/docs/dns/index.rst
@@ -4,3 +4,14 @@ DNS
.. note::
TODO: Write me!
+
+Examples
+--------
+
+We have :doc:`examples of several common patterns </dns/examples>`.
+
+API Reference
+-------------
+
+There is a reference to :doc:`all the methods on the base dns driver
+</dns/api/>`.
http://git-wip-us.apache.org/repos/asf/libcloud/blob/318ed78c/docs/loadbalancer/index.rst
----------------------------------------------------------------------
diff --git a/docs/loadbalancer/index.rst b/docs/loadbalancer/index.rst
index f9baa2d..59f17c2 100644
--- a/docs/loadbalancer/index.rst
+++ b/docs/loadbalancer/index.rst
@@ -4,3 +4,14 @@ Load Balancers
.. note::
TODO: Write me!
+
+Examples
+--------
+
+We have :doc:`examples of several common patterns </loadbalancer/examples>`.
+
+API Reference
+-------------
+
+There is a reference to :doc:`all the methods on the base loadbalancer driver
+</loadbalancer/api/>`.
http://git-wip-us.apache.org/repos/asf/libcloud/blob/318ed78c/docs/storage/index.rst
----------------------------------------------------------------------
diff --git a/docs/storage/index.rst b/docs/storage/index.rst
index 3ab1bb5..6d93f9e 100644
--- a/docs/storage/index.rst
+++ b/docs/storage/index.rst
@@ -4,3 +4,14 @@ Object Storage
.. note::
TODO: Write me!
+
+Examples
+--------
+
+We have :doc:`examples of several common patterns </storage/examples>`.
+
+API Reference
+-------------
+
+There is a reference to :doc:`all the methods on the base storage driver
+</storage/api/>`.
[3/7] git commit: loadbalancers -> loadbalancers.
Posted by to...@apache.org.
loadbalancers -> loadbalancers.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/3132bf5d
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/3132bf5d
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/3132bf5d
Branch: refs/heads/trunk
Commit: 3132bf5d4195b8cabb472bc45964e6390339fedf
Parents: 6746570
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 17:13:41 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 17:13:41 2013 +0200
----------------------------------------------------------------------
docs/index.rst | 4 ++--
docs/loadbalancer/api.rst | 5 +++++
docs/loadbalancer/examples.rst | 8 ++++++++
docs/loadbalancer/index.rst | 6 ++++++
docs/loadbalancers/api.rst | 5 -----
docs/loadbalancers/examples.rst | 8 --------
docs/loadbalancers/index.rst | 6 ------
7 files changed, 21 insertions(+), 21 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/3132bf5d/docs/index.rst
----------------------------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index f1d8faa..09cff04 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -20,7 +20,7 @@ resources:
RackSpace CloudServers
* :doc:`Cloud object storage </storage/index>` - services such as Amazon S3 and
Rackspace CloudFiles
-* :doc:`Load Balancers as a Service </loadbalancers/index>`
+* :doc:`Load Balancers as a Service </loadbalancer/index>`
* :doc:`DNS as a Service </dns/index>`
@@ -30,7 +30,7 @@ resources:
compute/*
storage/*
- loadbalancers/*
+ loadbalancer/*
dns/*
.. _`Apache 2.0 license`: https://www.apache.org/licenses/LICENSE-2.0.html
http://git-wip-us.apache.org/repos/asf/libcloud/blob/3132bf5d/docs/loadbalancer/api.rst
----------------------------------------------------------------------
diff --git a/docs/loadbalancer/api.rst b/docs/loadbalancer/api.rst
new file mode 100644
index 0000000..0be4329
--- /dev/null
+++ b/docs/loadbalancer/api.rst
@@ -0,0 +1,5 @@
+LoadBalancer Base API
+=====================
+
+.. autoclass:: libcloud.loadbalancer.base.Driver
+ :members:
http://git-wip-us.apache.org/repos/asf/libcloud/blob/3132bf5d/docs/loadbalancer/examples.rst
----------------------------------------------------------------------
diff --git a/docs/loadbalancer/examples.rst b/docs/loadbalancer/examples.rst
new file mode 100644
index 0000000..bfc2dda
--- /dev/null
+++ b/docs/loadbalancer/examples.rst
@@ -0,0 +1,8 @@
+LoadBalancer Examples
+=====================
+
+Create a Load Balancer with two members and wait for it to become ready
+-----------------------------------------------------------------------
+
+.. literalinclude:: /examples/loadbalancer/create_lb_wait_for_ready.py
+ :language: python
http://git-wip-us.apache.org/repos/asf/libcloud/blob/3132bf5d/docs/loadbalancer/index.rst
----------------------------------------------------------------------
diff --git a/docs/loadbalancer/index.rst b/docs/loadbalancer/index.rst
new file mode 100644
index 0000000..f9baa2d
--- /dev/null
+++ b/docs/loadbalancer/index.rst
@@ -0,0 +1,6 @@
+Load Balancers
+==============
+
+.. note::
+
+ TODO: Write me!
http://git-wip-us.apache.org/repos/asf/libcloud/blob/3132bf5d/docs/loadbalancers/api.rst
----------------------------------------------------------------------
diff --git a/docs/loadbalancers/api.rst b/docs/loadbalancers/api.rst
deleted file mode 100644
index 0be4329..0000000
--- a/docs/loadbalancers/api.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-LoadBalancer Base API
-=====================
-
-.. autoclass:: libcloud.loadbalancer.base.Driver
- :members:
http://git-wip-us.apache.org/repos/asf/libcloud/blob/3132bf5d/docs/loadbalancers/examples.rst
----------------------------------------------------------------------
diff --git a/docs/loadbalancers/examples.rst b/docs/loadbalancers/examples.rst
deleted file mode 100644
index bfc2dda..0000000
--- a/docs/loadbalancers/examples.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-LoadBalancer Examples
-=====================
-
-Create a Load Balancer with two members and wait for it to become ready
------------------------------------------------------------------------
-
-.. literalinclude:: /examples/loadbalancer/create_lb_wait_for_ready.py
- :language: python
http://git-wip-us.apache.org/repos/asf/libcloud/blob/3132bf5d/docs/loadbalancers/index.rst
----------------------------------------------------------------------
diff --git a/docs/loadbalancers/index.rst b/docs/loadbalancers/index.rst
deleted file mode 100644
index f9baa2d..0000000
--- a/docs/loadbalancers/index.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-Load Balancers
-==============
-
-.. note::
-
- TODO: Write me!
[5/7] git commit: Port "Using Libcloud in multi-threaded and async
environments" documentation section.
Posted by to...@apache.org.
Port "Using Libcloud in multi-threaded and async environments" documentation
section.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/b6be3e70
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/b6be3e70
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/b6be3e70
Branch: refs/heads/trunk
Commit: b6be3e70e1fe31281f537c74c9b435e52264e20c
Parents: 318ed78
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 17:52:50 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 17:52:50 2013 +0200
----------------------------------------------------------------------
docs/examples/misc/twisted_create_node.py | 34 ++++++++++
docs/index.rst | 3 +-
...-in-multithreaded-and-async-environments.rst | 69 ++++++++++++++++++++
3 files changed, 105 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/b6be3e70/docs/examples/misc/twisted_create_node.py
----------------------------------------------------------------------
diff --git a/docs/examples/misc/twisted_create_node.py b/docs/examples/misc/twisted_create_node.py
new file mode 100644
index 0000000..e0109e1
--- /dev/null
+++ b/docs/examples/misc/twisted_create_node.py
@@ -0,0 +1,34 @@
+from __future__ import absolute_import
+
+from pprint import pprint
+
+from twisted.internet import defer, threads, reactor
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+
+@defer.inlineCallbacks
+def create_node(name):
+ node = yield threads.deferToThread(_thread_create_node,
+ name=name)
+ pprint(node)
+ reactor.stop()
+
+
+def _thread_create_node(name):
+ Driver = get_driver(Provider.RACKSPACE)
+ conn = Driver('username', 'api key')
+ image = conn.list_images()[0]
+ size = conn.list_sizes()[0]
+ node = conn.create_node(name=name, image=image, size=size)
+ return node
+
+
+def stop(*args, **kwargs):
+ reactor.stop()
+
+d = create_node(name='my-lc-node')
+d.addCallback(stop)
+d.addErrback(stop)
+
+reactor.run()
http://git-wip-us.apache.org/repos/asf/libcloud/blob/b6be3e70/docs/index.rst
----------------------------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index 09cff04..be5f382 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -23,14 +23,15 @@ resources:
* :doc:`Load Balancers as a Service </loadbalancer/index>`
* :doc:`DNS as a Service </dns/index>`
-
.. toctree::
:glob:
+ :maxdepth: 2
:hidden:
compute/*
storage/*
loadbalancer/*
dns/*
+ other/*
.. _`Apache 2.0 license`: https://www.apache.org/licenses/LICENSE-2.0.html
http://git-wip-us.apache.org/repos/asf/libcloud/blob/b6be3e70/docs/other/using-libcloud-in-multithreaded-and-async-environments.rst
----------------------------------------------------------------------
diff --git a/docs/other/using-libcloud-in-multithreaded-and-async-environments.rst b/docs/other/using-libcloud-in-multithreaded-and-async-environments.rst
new file mode 100644
index 0000000..26e1edb
--- /dev/null
+++ b/docs/other/using-libcloud-in-multithreaded-and-async-environments.rst
@@ -0,0 +1,69 @@
+Using Libcloud in multi-threaded and async environments
+=======================================================
+
+Libcloud's primary task is to communicate with different provider APIs using
+HTTP. This means most of the work is not CPU intensive, but performing all
+those HTTP requests includes a lot of waiting which makes the library I/O
+bound.
+
+Most of the time you want to perform more operations in parallel or just
+want your code to finish faster (for example starting a lot of servers or
+periodically polling for node status).
+
+Problems like this are usually solved using threads or async libraries such
+as Twisted, Tornado or gevent.
+
+This page contains some information and tips about how to use Libcloud in
+such environments.
+
+Libcloud and thread-safety
+--------------------------
+
+Important thing to keep in mind when dealing with threads is thread-safety.
+Libcloud driver instance is **not** thread safe. This means if you don't want
+to deal with complex (and usually inefficient) locking the easiest solution
+is to create a new driver instance inside each thread.
+
+Using Libcloud with gevent
+--------------------------
+
+gevent has an ability to monkey patch and replace functions in the Python
+``socket``, ``urllib2``, ``httplib`` and ``time`` module with its own
+functions which don't block.
+
+You need to do two things when you want to use Libcloud with gevent:
+
+* Enable monkey patching
+
+.. sourcecode:: python
+
+ from gevent import monkey
+ monkey.patch_all()
+
+* Create a separate driver instance for each Greenlet. This is necessary
+ because a driver instance reuses the same Connection class.
+
+For an example see Efficiently download multiple files using gevent.
+
+Using Libcloud with Twisted
+---------------------------
+
+Libcloud has no Twisted support included in the core which means you need
+to be careful when you use it with Twisted and some other async frameworks.
+
+If you don't use it properly it can block the whole reactor (similar as
+any other blocking library or a long CPU-intensive task) which means the
+execution of other pending tasks in the event queue will be blocked.
+
+A simple solution to prevent blocking the reactor is to run Libcloud
+calls inside a thread. In Twisted this can be achieved using
+``threads.deferToThread`` which runs a provided method inside the Twisted
+thread pool.
+
+The example bellow demonstrates how to create a new node inside a thread
+without blocking the whole reactor.
+
+.. literalinclude:: /examples/misc/twist_create_node.py
+ :language: python
+
+
[2/7] git commit: Update travis config.
Posted by to...@apache.org.
Update travis config.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/6746570c
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/6746570c
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/6746570c
Branch: refs/heads/trunk
Commit: 6746570c9a22a98de2712b70a0fbb85c44a05d3b
Parents: a8627b4
Author: Tomaz Muraus <to...@apache.org>
Authored: Sat Aug 3 17:10:27 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sat Aug 3 17:10:27 2013 +0200
----------------------------------------------------------------------
.travis.yml | 1 +
1 file changed, 1 insertion(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/6746570c/.travis.yml
----------------------------------------------------------------------
diff --git a/.travis.yml b/.travis.yml
index 1d5d44f..f8ea6f0 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -8,6 +8,7 @@ env:
- TOX_ENV=py32
- TOX_ENV=py33
- TOX_ENV=docs
+ - TOX_ENV=examples
install:
- pip install tox