OpenStack Object Storage (Swift) Client

4.10.0 · active · verified Mon Apr 13

python-swiftclient is the official Python client library for interacting with the OpenStack Object Storage (Swift) API. It provides both a low-level Connection API for fine-grained control and a higher-level SwiftService API for common operations, including a command-line interface. Currently at version 4.10.0, the library is actively maintained with frequent updates, typically aligning with OpenStack release cycles.

Warnings

gotcha When using `swiftclient.client.Connection`, always explicitly specify the `auth_version` parameter (e.g., '2.0' or '3'). Omitting it can cause authentication failures as it defaults to '1.0', which may not be compatible with modern OpenStack Keystone deployments.
Fix: Pass `auth_version='3'` (or '2.0') to the `Connection` constructor, and ensure `authurl` is correctly formatted for the specified version (e.g., includes `/v3` for Keystone v3).
breaking Support for Python 3.6 was dropped in version 4.8.0. Earlier, support for Python 2 was completely removed.
Fix: Upgrade to Python 3.7 or newer to use python-swiftclient versions >= 4.8.0. For older python-swiftclient versions, ensure Python 3.x is used.
deprecated The provider-specific `SERVICENET` feature was removed in version 4.10.0. If your deployment relied on this, you will need to manually override your storage URLs.
Fix: Explicitly configure the storage URLs in your client configuration or environment variables, rather than relying on `SERVICENET`.
gotcha Debugging output (e.g., using `--debug` with the CLI or setting logging to DEBUG) truncates authentication tokens by default since version 4.8.0 for security reasons.
Fix: If full authentication token details are absolutely necessary for debugging, use the `--debug-with-secrets` flag (CLI) or ensure your logging configuration explicitly allows for full token display, understanding the security implications.
gotcha Handling of non-ASCII metadata keys on Python 3 has historically had issues, particularly with receiving such metadata. While some fixes have been implemented for sending, receiving might still be problematic in certain older versions.
Fix: Ensure you are on the latest stable version of `python-swiftclient`. If issues persist, consider encoding/decoding metadata keys to ASCII where possible, or consult the OpenStack Swift documentation for character set best practices.

Install

pip install python-swiftclient Install latest version

Imports

Connection
```
from swiftclient.client import Connection
```
Directly import the Connection class for the low-level API.
SwiftService
```
from swiftclient.service import SwiftService
```
Directly import the SwiftService class for the high-level API.

Quickstart

This quickstart demonstrates how to establish a connection to OpenStack Swift using the low-level `Connection` API, authenticate, list existing containers, create a new container, and upload an object. It relies on standard OpenStack environment variables for authentication details to avoid hardcoding credentials.

import os
from swiftclient.client import Connection

# --- Environment Variables for Authentication ---
# Set these environment variables before running, e.g., using an OpenStack RC file
# or directly:
# export OS_AUTH_URL="http://your-auth-url:5000/v3"
# export OS_USERNAME="your-username"
# export OS_PASSWORD="your-password"
# export OS_PROJECT_NAME="your-project-name"
# export OS_USER_DOMAIN_NAME="Default" # Or your specific user domain
# export OS_PROJECT_DOMAIN_NAME="Default" # Or your specific project domain
# export OS_REGION_NAME="RegionOne" # Or your specific region

auth_url = os.environ.get('OS_AUTH_URL', 'http://localhost:5000/v3')
username = os.environ.get('OS_USERNAME', 'test_user')
password = os.environ.get('OS_PASSWORD', 'test_password')
project_name = os.environ.get('OS_PROJECT_NAME', 'test_project')
user_domain_name = os.environ.get('OS_USER_DOMAIN_NAME', 'Default')
project_domain_name = os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default')
region_name = os.environ.get('OS_REGION_NAME', 'RegionOne')

# Ensure auth_version is specified, especially for Keystone v3
# os_options are crucial for domain-scoped authentication
os_options = {
    'user_domain_name': user_domain_name,
    'project_domain_name': project_domain_name,
    'project_name': project_name,
    'region_name': region_name
}

try:
    # Establish connection
    conn = Connection(
        authurl=auth_url,
        user=username,
        key=password,
        os_options=os_options,
        auth_version='3' # Crucial: always specify auth_version for v3 or v2 auth
    )

    # Example: List containers
    _resp_headers, containers = conn.get_account()
    print(f"Successfully connected. Found {len(containers)} containers:")
    for container in containers:
        print(f"  - {container['name']} (Bytes: {container['bytes']}, Count: {container['count']})")

    # Example: Create a new container
    container_name = "my-new-test-container"
    try:
        conn.put_container(container_name)
        print(f"Container '{container_name}' created (or already exists).")
    except Exception as e:
        print(f"Error creating container {container_name}: {e}")
    
    # Example: Upload an object (simple string content)
    object_name = "hello_world.txt"
    object_content = b"Hello, Swift Object Storage!"
    try:
        conn.put_object(container_name, object_name, object_content)
        print(f"Object '{object_name}' uploaded to '{container_name}'.")
    except Exception as e:
        print(f"Error uploading object {object_name}: {e}")

finally:
    # Always close the connection
    if 'conn' in locals():
        conn.close()
        print("Connection closed.")

view raw JSON →