# 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: `swiftclient.client`.

## Authentication

This section covers the various combinations of kwargs required when creating an 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 Session

    from keystoneauth1 import session
    from keystoneauth1.identity import v3

    # Create a password auth plugin
    auth = v3.Password(auth_url='http://127.0.0.1:5000/v3/',
                       username='tester',
                       password='testing',
                       user_domain_name='Default',
                       project_name='Default',
                       project_domain_name='Default')

    # Create session
    keystone_session = session.Session(auth=auth)

    # Create swiftclient Connection
    swift_conn = Connection(session=keystone_session)

### Keystone v3

    _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
    )

### Keystone v2

    _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

    _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: `swiftclient.client`.

List the available containers:

    resp_headers, containers = conn.get_account()
    print("Response headers: %s" % resp_headers)
    for container in containers:
        print(container)

Create a new container:

    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:

    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:

    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:

    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:

    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)

this page last updated: 2026-02-27 11:33:45

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug