svn commit: r1197850 - in /libcloud/site/trunk/content/docs: storage-base-api.mdtext storage-overview.mdtext

[to...@apache.org]

Author: tomaz
Date: Sat Nov  5 00:53:44 2011
New Revision: 1197850

URL: http://svn.apache.org/viewvc?rev=1197850&view=rev
Log:
More docs.

Added:
    libcloud/site/trunk/content/docs/storage-base-api.mdtext
    libcloud/site/trunk/content/docs/storage-overview.mdtext

Added: libcloud/site/trunk/content/docs/storage-base-api.mdtext
URL: http://svn.apache.org/viewvc/libcloud/site/trunk/content/docs/storage-base-api.mdtext?rev=1197850&view=auto
==============================================================================
--- libcloud/site/trunk/content/docs/storage-base-api.mdtext (added)
+++ libcloud/site/trunk/content/docs/storage-base-api.mdtext Sat Nov  5 00:53:44 2011
@@ -0,0 +1,99 @@
+title: Storage -> Base API
+
+## Base API ##
+
+* [list_containers](#containers)
+* [list_container_object](#list_container_object)
+* [get_container](#get_container)
+* [get_object](#get_object)
+* [create_container](#create_container)
+* [upload_object](#upload_object)
+* [upload_object_via_stream](#upload_object_via_stream)
+* [download_object](#download_object)
+* [download_object_as_stream](#download_object_as_stream)
+* [delete_container](#delete_container)
+* [delete_object](#delete_object)
+
+<h3 id="list_containers">list_containers</h3>
+
+**Method signature**:
+[driver.list_containters()](/apidocs/current/libcloud.storage.base.StorageDriver.html#list_containters)  
+**Description**: Return a list of all the containers belonging to your account.
+The returned object is actually an instance of `LazyList` class which implements
+an iterator interface and transparently handles pagination for you.  
+
+
+<h3 id="list_container_object">list_container_object</h3>
+
+[driver.list_container_object()](/apidocs/current/libcloud.storage.base.StorageDriver.html#list_container_object)  
+**Description**: Return a list of all the object inside the container.
+Similar to the list_containers this method also returns a `LazyList` instance.  
+
+<h3 id="get_container">get_container></h3>
+
+[driver.get_container(container_name)](/apidocs/current/libcloud.storage.base.StorageDriver.html#get_container)  
+**Description**: Return a `Container` instance. This method is useful if you
+know the container name and want perform operations on it. Usually it is also
+more efficient then calling `list_containers()` and manually iterating over the
+list to find the container you are interested in.
+
+<h3 id="get_object">get_object</h3>
+
+[driver.get_container(container_name, object_name)](/apidocs/current/libcloud.storage.base.StorageDriver.html#get_container)  
+**Description**: Return an `Object` instance. Similar to the `get_container`
+this method is also useful if you know the name of the object and the container
+holding this object and you want to perform operations on it.
+
+<h3 id="create_container">create_container</h3>
+
+[driver.create_container(container_name)](/apidocs/current/libcloud.storage.base.StorageDriver.html#create_container)  
+**Description**: Create a new container.
+
+<h3 id="upload_object">upload_object</h3>
+
+[driver.upload_object(file_path, container, object_name, extra=None, verify_hash)](/apidocs/current/libcloud.storage.base.StorageDriver.html#upload_object),
+[container.upload_object(file_path, object_name, extra=None, verify_hash)](/apidocs/current/libcloud.storage.base.Container.html#upload_object)  
+**Description**: Upload a file stored on a disk.
+
+<h3 id="upload_object_via_stream">upload_object_via_stream</h3>
+
+[driver.upload_object_via_stream(iterator, container, object_name, extra)](/apidocs/current/libcloud.storage.base.StorageDriver.html#upload_object_via_stream),
+[container.upload_object_via_stream(file_path, object_name, extra=None, verify_hash)](/apidocs/current/libcloud.storage.base.Container.html#upload_object_via_stream)  
+**Description**: Upload an object using an iterator. If a provider supports
+chunked transfer encoding this method doesn't require you to know the object
+size in advance. This allows you to directly stream data to the provider without
+buffering it on disk.
+
+Good example of this are backups - you can directly stream tar output to the
+provider without buffering or temporary storing data on the disk.
+
+**Note: If the provider doesn't support chunked transfer encoding this function
+will first exhaust your iterator to determine the file size and then send it to
+the provider. Exhausting the iterator means that the whole iterator content
+must be buffered in the memory which might lead to the resource exhaustion.**
+
+<h3 id="download_object">download_object</h3>
+
+[driver.download_object(obj, destination_path, overwrite_existing, delete_on_failure)](/apidocs/current/libcloud.storage.base.StorageDriver.html#download_object),
+[container.download_object(obj, destination_path, overwrite_existing, delete_on_failure)](/apidocs/current/libcloud.storage.base.Container.html#download_object),
+[object.download(destination_path, overwrite_existing, delete_on_failure)](/apidocs/current/libcloud.storage.base.Object.html#download_object)  
+**Description**: Download an object and save it to a file on disk.
+
+<h3 id="download_object_as_stream">download_object_as_stream</h3>
+[driver.download_object_as_stream(obj, chunk_size)](/apidocs/current/libcloud.storage.base.StorageDriver.html#download_object_as_stream),
+[container.download_object_as_stream(obj, chunk_size)](/apidocs/current/libcloud.storage.base.Container.html#download_object_as_stream),
+[object.as_stream(chunk_size)](/apidocs/current/libcloud.storage.base.Object.html#as_stream)  
+**Description**: Return a generator which yields object data. This method is
+useful if you don't want to directly save object on disk and want to perform
+some other operations with it.
+
+<h3 id="delete_container">delete_container</h3>
+[driver.delete_container(container)](/apidocs/current/libcloud.storage.base.StorageDriver.html#delete_container),
+[container.delete()](/apidocs/current/libcloud.storage.base.Container.html#delete)  
+**Description**: Delete a container.
+
+<h3 id="delete_object">delete_object</h3>
+[driver.delete_object(obj)](/apidocs/current/libcloud.storage.base.StorageDriver.html#delete_object),
+[container.delete_object(obj)](/apidocs/current/libcloud.storage.base.Container.html#delete_object),
+[object.delete()](/apidocs/current/libcloud.storage.base.Object.html#delete)  
+**Description**: Delete an object.

Added: libcloud/site/trunk/content/docs/storage-overview.mdtext
URL: http://svn.apache.org/viewvc/libcloud/site/trunk/content/docs/storage-overview.mdtext?rev=1197850&view=auto
==============================================================================
--- libcloud/site/trunk/content/docs/storage-overview.mdtext (added)
+++ libcloud/site/trunk/content/docs/storage-overview.mdtext Sat Nov  5 00:53:44 2011
@@ -0,0 +1,14 @@
+title: Storage -> Overview
+
+## Overview ##
+
+Storage API allows you to manage cloud storage and services such as Amazon S3,
+Rackspace CloudFiles, Google Storage and <a href="/supported_providers.html">others</a>.
+
+### Terminology ###
+
+* **Object** - represents an object or so called BLOB.
+* **Container** - represents a container which can contain multiple objects. You
+can think of it as a folder on a file system. Difference between container and a
+folder on file system is that containers cannot be nested. Some APIs also call
+it a **Bucket**.