openstack/python-swiftclient
Code Issues Proposed changes

Minor edits to the api page

Browse Source 
Change-Id: Ie65f73532e53a858ee9ab4b4634dcfcaf8a93c3b
This commit is contained in:
Alexandra
2016-02-29 13:50:10 +00:00
parent 1d94f9262d
commit 671d6febb2
1 changed files with 67 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
doc/source/apis.rst
View File

@@ -2,17 +2,17 @@
python-swiftclient API python-swiftclient API
====================== ======================
The python-swiftclient includes two levels of API; a low level client API that The python-swiftclient includes two levels of API. A low level client API that
provides simple python wrappers around the various authentication mechanisms provides simple python wrappers around the various authentication mechanisms,
and the individual HTTP requests, and a high level service API that provides the individual HTTP requests, and a high level service API that provides
methods for performing common operations in parallel on a thread pool. methods for performing common operations in parallel on a thread pool.
This document aims to provide guidance for choosing between these APIs and This document aims to provide guidance for choosing between these APIs and
examples of usage for the service API. examples of usage for the service API.
------------------------
Important Considerations Important Considerations
------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~
This section covers some important considerations, helpful hints, and things This section covers some important considerations, helpful hints, and things
to avoid when integrating an object store into your workflow. to avoid when integrating an object store into your workflow.
@@ -20,27 +20,30 @@ to avoid when integrating an object store into your workflow.
An Object Store is not a filesystem An Object Store is not a filesystem
----------------------------------- -----------------------------------
It cannot be stressed enough that your usage of the object store should reflect .. important::
the proper use case, and not treat the storage like a filesystem. There are 2
main restrictions to bear in mind here when designing your use of the object It cannot be stressed enough that your usage of the object store should reflect
the use case, and not treat the storage like a filesystem.
There are 2 main restrictions to bear in mind here when designing your use of the object
store: store:
* Objects cannot be renamed due to the way in which objects are stored and #. Objects cannot be renamed due to the way in which objects are stored and
references by the object store. This usually requires multiple copies of references by the object store. This usually requires multiple copies of
the data to be moved between physical storage devices. the data to be moved between physical storage devices.
As a result, a move operation is not provided. If the user wants to move an As a result, a move operation is not provided. If the user wants to move an
object they must re-upload to the new location and delete the object they must re-upload to the new location and delete the
original. original.
* Objects cannot be modified. Objects are stored in multiple locations and are #. Objects cannot be modified. Objects are stored in multiple locations and are
checked for integrity based on the ``MD5 sum`` calculated during upload. checked for integrity based on the ``MD5 sum`` calculated during upload.
Object creation is a 1-shot event, and in order to modify the contents of an Object creation is a 1-shot event, and in order to modify the contents of an
object the entire new contents must be re-uploaded. In certain special cases object the entire new contents must be re-uploaded. In certain special cases
it is possible to work around this restriction using large objects, but no it is possible to work around this restriction using large objects, but no
general file-like access is available to modify a stored object. general file-like access is available to modify a stored object.
------------------------------
The swiftclient.Connection API The swiftclient.Connection API
------------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A low level API that provides methods for authentication and methods that A low level API that provides methods for authentication and methods that
correspond to the individual REST API calls described in the swift correspond to the individual REST API calls described in the swift
@@ -48,12 +51,12 @@ documentation.
For usage details see the client docs: :mod:`swiftclient.client`. For usage details see the client docs: :mod:`swiftclient.client`.
--------------------------------
The swiftclient.SwiftService API The swiftclient.SwiftService API
-------------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A higher level API aimed at allowing developers an easy way to perform multiple A higher level API aimed at allowing developers an easy way to perform multiple
operations asynchronously using a configurable thread pool. Docs for each operations asynchronously using a configurable thread pool. Documentation for each
service method call can be found here: :mod:`swiftclient.service`. service method call can be found here: :mod:`swiftclient.service`.
Configuration Configuration
@@ -74,7 +77,7 @@ passed to the ``SwiftService`` during initialisation. The options available
in this dictionary are described below, along with their defaults: in this dictionary are described below, along with their defaults:
Options Options
~~~~~~~ ^^^^^^^
``retries``: ``5`` ``retries``: ``5``
The number of times that the library should attempt to retry HTTP The number of times that the library should attempt to retry HTTP
@@ -190,14 +193,14 @@ for an optional dictionary to override those specified at init time, and the
appropriate docstrings show which options modify each method's behaviour. appropriate docstrings show which options modify each method's behaviour.
Authentication Authentication
-------------- ~~~~~~~~~~~~~~
This section covers the various options for authenticating with a swift This section covers the various options for authenticating with a swift
object store. The combinations of options required for each authentication object store. The combinations of options required for each authentication
version are detailed below. version are detailed below.
Version 1.0 Auth Version 1.0 Auth
~~~~~~~~~~~~~~~~ ----------------
``auth_version``: ``environ.get('ST_AUTH_VERSION')`` ``auth_version``: ``environ.get('ST_AUTH_VERSION')``
@@ -208,8 +211,8 @@ Version 1.0 Auth
``key``: ``environ.get('ST_KEY')`` ``key``: ``environ.get('ST_KEY')``
Version 2.0 & 3.0 Auth Version 2.0 and 3.0 Auth
~~~~~~~~~~~~~~~~~~~~~~ ------------------------
``auth_version``: ``environ.get('ST_AUTH_VERSION')`` ``auth_version``: ``environ.get('ST_AUTH_VERSION')``
@@ -233,7 +236,7 @@ having options from different auth versions can cause unexpected behaviour.
authorization fails. authorization fails.
Operation Return Values Operation Return Values
----------------------- ~~~~~~~~~~~~~~~~~~~~~~~
Each operation provided by the service API may raise a ``SwiftError`` or Each operation provided by the service API may raise a ``SwiftError`` or
``ClientException`` for any call that fails completely (or a call which ``ClientException`` for any call that fails completely (or a call which
@@ -291,7 +294,7 @@ All the possible ``action`` values are detailed below:
] ]
Stat Stat
---- ~~~~
Stat can be called against an account, a container, or a list of objects to Stat can be called against an account, a container, or a list of objects to
get account stats, container stats or information about the given objects. In get account stats, container stats or information about the given objects. In
@@ -368,7 +371,7 @@ operation was not successful, and will include the keys below:
} }
Example Example
~~~~~~~ -------
The code below demonstrates the use of ``stat`` to retrieve the headers for a The code below demonstrates the use of ``stat`` to retrieve the headers for a
given list of objects in a container using 20 threads. The code creates a given list of objects in a container using 20 threads. The code creates a
@@ -396,7 +399,7 @@ mapping from object name to headers.
) )
List List
---- ~~~~
List can be called against an account or a container to retrieve the containers List can be called against an account or a container to retrieve the containers
or objects contained within them. Each call returns an iterator that returns or objects contained within them. Each call returns an iterator that returns
@@ -453,7 +456,7 @@ dictionary as described below:
} }
Example Example
~~~~~~~ -------
The code below demonstrates the use of ``list`` to list all items in a The code below demonstrates the use of ``list`` to list all items in a
container that are over 10MiB in size: container that are over 10MiB in size:
@@ -482,7 +485,7 @@ container that are over 10MiB in size:
output_manager.error(e.value) output_manager.error(e.value)
Post Post
---- ~~~~
Post can be called against an account, container or list of objects in order to Post can be called against an account, container or list of objects in order to
update the metadata attached to the given items. Each element of the object list update the metadata attached to the given items. Each element of the object list
@@ -494,7 +497,7 @@ an iterator over the results generated for each object post is returned. If the
given container or account does not exist, the ``post`` method will raise a given container or account does not exist, the ``post`` method will raise a
``SwiftError``. ``SwiftError``.
When a string is given for the object name, the options .. When a string is given for the object name, the options
Successful metadata update results are dictionaries as described below: Successful metadata update results are dictionaries as described below:
@@ -510,34 +513,31 @@ Successful metadata update results are dictionaries as described below:
} }
.. note:: .. note::
Updating user metadata keys will not only add any specified keys, but Updating user metadata keys will not only add any specified keys, but
will also remove user metadata that has previously been set. This means will also remove user metadata that has previously been set. This means
that each time user metadata is updated, the complete set of desired that each time user metadata is updated, the complete set of desired
key-value pairs must be specified. key-value pairs must be specified.
Example
~~~~~~~
.. Do we want to hide this section until it is complete?
TBD .. Example
.. -------
Download .. TBD
--------
.. Do we want to hide this section until it is complete? .. Download
.. ~~~~~~~~
TBD .. TBD
Example .. Example
~~~~~~~ .. -------
.. Do we want to hide this section until it is complete? .. TBD
TBD
Upload Upload
------ ~~~~~~
Upload is always called against an account and container and with a list of Upload is always called against an account and container and with a list of
objects to upload. Each element of the object list may be a plain string objects to upload. Each element of the object list may be a plain string
@@ -622,7 +622,7 @@ below:
} }
Example Example
~~~~~~~ -------
The code below demonstrates the use of ``upload`` to upload all files and The code below demonstrates the use of ``upload`` to upload all files and
folders in ``/tmp``, and renaming each object by replacing ``/tmp`` in the folders in ``/tmp``, and renaming each object by replacing ``/tmp`` in the
@@ -689,31 +689,30 @@ object or directory marker names with ``temporary-objects``:
except SwiftError as e: except SwiftError as e:
out_manager.error(e.value) out_manager.error(e.value)
Delete .. Delete
------ .. ~~~~~~
.. Do we want to hide this section until it is complete?
.. TBD
.. Example
.. -------
.. Do we want to hide this section until it is complete? .. Do we want to hide this section until it is complete?
TBD .. TBD
Example .. Capabilities
~~~~~~~ .. ~~~~~~~~~~~~
.. Do we want to hide this section until it is complete? .. Do we want to hide this section until it is complete?
TBD .. TBD
Capabilities .. Example
------------ .. -------
.. Do we want to hide this section until it is complete? .. Do we want to hide this section until it is complete?
TBD .. TBD
Example
~~~~~~~
.. Do we want to hide this section until it is complete?
TBD