3a5a25fe98
As a result of the Hackathon we have produced a new documentation structure for the python-swiftclient. This patch introduces the new structure and adds the required content. The intention is to document the CLI, the SwiftService and Connection API. Importantly, we also provide guidance on important considerations when using a swift object store, such as which aspect of the python-swiftclient to use for various use cases, common authentication patterns and some useful examples. Co-Authored-By: Alexandra Settle <alexandra.settle@rackspace.com> Co-Authored-By: Mohit Motiani <mohit.motiani@intel.com> Co-Authored-By: Hisashi Osanai <osanai.hisashi@jp.fujitsu.com> Change-Id: I9eb41f8e9137efa66cead67dc264a76a3c03fbda
178 lines
4.3 KiB
ReStructuredText
178 lines
4.3 KiB
ReStructuredText
==============================
|
|
The swiftclient.Connection API
|
|
==============================
|
|
|
|
A low level API that provides methods for authentication and methods that
|
|
correspond to the individual REST API calls described in the swift
|
|
documentation.
|
|
|
|
For usage details see the client docs: :mod:`swiftclient.client`.
|
|
|
|
Authentication
|
|
--------------
|
|
|
|
This section covers the various combinations of kwargs required when creating
|
|
and instance of the ``Connection`` object for communicating with a swift
|
|
object store. The combinations of options required for each authentication
|
|
version are detailed below, but are
|
|
just a subset of those that can be used to successfully authenticate. These
|
|
are the most common and recommended combinations.
|
|
|
|
Keystone v3
|
|
~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
_authurl = 'http://127.0.0.1:5000/v3/'
|
|
_auth_version = '3'
|
|
_user = 'tester'
|
|
_key = 'testing'
|
|
_os_options = {
|
|
'user_domain_name': 'Default',
|
|
'project_domain_name': 'Default',
|
|
'project_name': 'Default'
|
|
}
|
|
|
|
conn = Connection(
|
|
authurl=_authurl,
|
|
user=_user,
|
|
key=_key,
|
|
os_options=_os_options,
|
|
auth_version=_auth_version
|
|
)
|
|
|
|
.. code-block:: python
|
|
|
|
_authurl = 'http://127.0.0.1:5000/v3/'
|
|
_auth_version = '3'
|
|
_user = 'tester'
|
|
_key = 'testing'
|
|
_os_options = {
|
|
'user_domain_id': 'Default',
|
|
'project_domain_id': 'Default',
|
|
'project_id': 'Default'
|
|
}
|
|
|
|
conn = Connection(
|
|
authurl=_authurl,
|
|
user=_user,
|
|
key=_key,
|
|
os_options=_os_options,
|
|
auth_version=_auth_version
|
|
)
|
|
|
|
Keystone v2
|
|
~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
_authurl = 'http://127.0.0.1:5000/v2.0/'
|
|
_auth_version = '2'
|
|
_user = 'tester'
|
|
_key = 'testing'
|
|
_tenant_name = 'test'
|
|
|
|
conn = Connection(
|
|
authurl=_authurl,
|
|
user=_user,
|
|
key=_key,
|
|
tenant_name=_tenant_name,
|
|
auth_version=_auth_version
|
|
)
|
|
|
|
Legacy Auth
|
|
~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
_authurl = 'http://127.0.0.1:8080/'
|
|
_auth_version = '1'
|
|
_user = 'tester'
|
|
_key = 'testing'
|
|
_tenant_name = 'test'
|
|
|
|
conn = Connection(
|
|
authurl=_authurl,
|
|
user=_user,
|
|
key=_key,
|
|
tenant_name=_tenant_name,
|
|
auth_version=_auth_version
|
|
)
|
|
|
|
Examples
|
|
--------
|
|
|
|
In this section we present some simple code examples that demonstrate the usage
|
|
of the ``Connection`` API. You can find full details of the options and methods
|
|
available to the ``Connection`` API in the docstring generated documentation:
|
|
:mod:`swiftclient.client`.
|
|
|
|
List the available containers:
|
|
|
|
.. code-block:: python
|
|
|
|
resp_headers, containers = conn.get_account()
|
|
print("Response headers: %s" % resp_headers)
|
|
for container in containers:
|
|
print(container)
|
|
|
|
Create a new container:
|
|
|
|
.. code-block:: python
|
|
|
|
container = 'new-container'
|
|
conn.put_container(container)
|
|
resp_headers, containers = conn.get_account()
|
|
if container in containers:
|
|
print("The container was created")
|
|
|
|
Create a new object with the contents of a local text file:
|
|
|
|
.. code-block:: python
|
|
|
|
container = 'new-container'
|
|
with open('local.txt', 'r') as local:
|
|
conn.put_object(
|
|
container,
|
|
'local_object.txt',
|
|
contents=local,
|
|
content_type='text/plain'
|
|
)
|
|
|
|
Confirm presence of the object:
|
|
|
|
.. code-block:: python
|
|
|
|
obj = 'local_object.txt'
|
|
container = 'new-container'
|
|
try:
|
|
resp_headers = conn.head_object(container, obj)
|
|
print('The object was successfully created')
|
|
except ClientException as e:
|
|
if e.http_status = '404':
|
|
print('The object was not found')
|
|
else:
|
|
print('An error occurred checking for the existence of the object')
|
|
|
|
Download the created object:
|
|
|
|
.. code-block:: python
|
|
|
|
obj = 'local_object.txt'
|
|
container = 'new-container'
|
|
resp_headers, obj_contents = conn.get_object(container, obj)
|
|
with open('local_copy.txt', 'w') as local:
|
|
local.write(obj_contents)
|
|
|
|
Delete the created object:
|
|
|
|
.. code-block:: python
|
|
|
|
obj = 'local_object.txt'
|
|
container = 'new-container'
|
|
try:
|
|
conn.delete_object(container, obj)
|
|
print("Successfully deleted the object")
|
|
except ClientException as e:
|
|
print("Failed to delete the object with error: %s" % e)
|