CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-python-swiftclient

OpenStack Object Storage API Client Library

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Python SwiftClient

A comprehensive Python client library for the OpenStack Swift Object Storage API, providing both a programmatic Python API and a command-line interface. It enables developers to interact with OpenStack Swift object storage services through a clean, well-documented interface that supports all core Swift operations including object upload/download, container management, metadata handling, and authentication.

Package Information

  • Package Name: python-swiftclient
  • Language: Python
  • Installation: pip install python-swiftclient
  • Python Requirements: >= 3.7

Core Imports

import swiftclient

For high-level operations:

from swiftclient import Connection

For bulk operations:

from swiftclient.service import SwiftService

For low-level HTTP operations:

from swiftclient import (
    get_auth, get_account, get_container, get_object,
    put_container, put_object, delete_object
)

Basic Usage

High-Level Connection API

from swiftclient import Connection

# Create connection with authentication
conn = Connection(
    authurl='https://identity.example.com:5000/v3',
    user='myuser',
    key='mypassword',
    auth_version='3',
    os_options={
        'project_name': 'myproject',
        'user_domain_name': 'mydomain',
        'project_domain_name': 'mydomain',
    }
)

# Account operations
headers, containers = conn.get_account()

# Container operations
conn.put_container('mycontainer')
headers, objects = conn.get_container('mycontainer')

# Object operations
conn.put_object('mycontainer', 'myobject', 'Hello World!')
headers, content = conn.get_object('mycontainer', 'myobject')
print(content.decode('utf-8'))  # 'Hello World!'

# Cleanup
conn.delete_object('mycontainer', 'myobject')
conn.delete_container('mycontainer')

Bulk Operations with SwiftService

from swiftclient.service import SwiftService, SwiftUploadObject

# Upload multiple objects
with SwiftService() as swift:
    # Upload local files
    upload_objects = [
        SwiftUploadObject('path/to/file1.txt', object_name='file1.txt'),
        SwiftUploadObject('path/to/file2.txt', object_name='file2.txt')
    ]

    for result in swift.upload('mycontainer', upload_objects):
        if result['success']:
            print(f"Uploaded {result['object']}")
        else:
            print(f"Failed to upload {result['object']}: {result['error']}")

Architecture

The python-swiftclient library provides multiple levels of abstraction for Swift operations:

  • Connection: High-level client with automatic retry, authentication handling, and connection management
  • Low-level Functions: Direct HTTP operations (get_object, put_object, etc.) for fine-grained control
  • SwiftService: Bulk operations with multi-threading, progress reporting, and automatic retries
  • Command Line: Full-featured CLI tool for all Swift operations

This multi-layered architecture allows developers to choose the appropriate abstraction level for their needs, from simple single operations to complex bulk processing workflows.

Capabilities

Command Line Interface

Complete command-line client for all Swift operations including upload, download, container management, and administrative tasks.

swift upload <container> <file>     # Upload objects
swift download <container>          # Download objects
swift list [<container>]           # List containers/objects
swift delete <container> [<object>] # Delete objects/containers
swift stat [<container>] [<object>] # Show statistics
swift post <container> [<object>]   # Update metadata
swift copy <container> <object>     # Copy objects
swift capabilities [<url>]          # Show cluster capabilities
swift auth                          # Show authentication info
swift tempurl <method> <seconds> <path> <key>  # Generate temporary URLs
swift bash_completion               # Enable shell completion

Command Line Interface

Client Connection

High-level Swift client providing automatic authentication, connection pooling, retry logic, and convenient wrapper methods for all Swift operations.

class Connection:
    def __init__(
        self,
        authurl=None,
        user=None,
        key=None,
        retries=5,
        preauthurl=None,
        preauthtoken=None,
        snet=False,
        starting_backoff=1,
        max_backoff=64,
        tenant_name=None,
        os_options=None,
        auth_version="1",
        cacert=None,
        insecure=False,
        cert=None,
        cert_key=None,
        ssl_compression=True,
        retry_on_ratelimit=True,
        timeout=None,
        session=None,
        force_auth_retry=False
    ): ...

    def get_account(self, marker=None, limit=None, prefix=None, end_marker=None, full_listing=False, headers=None, delimiter=None): ...
    def get_container(self, container, marker=None, limit=None, prefix=None, delimiter=None, end_marker=None, version_marker=None, path=None, full_listing=False, headers=None, query_string=None): ...
    def get_object(self, container, obj, resp_chunk_size=None, query_string=None, response_dict=None, headers=None): ...
    def put_container(self, container, headers=None, response_dict=None, query_string=None): ...
    def put_object(self, container, obj, contents, content_length=None, etag=None, chunk_size=None, content_type=None, headers=None, query_string=None, response_dict=None): ...
    def delete_object(self, container, obj, query_string=None, response_dict=None, headers=None): ...

Client Connection

Authentication

Comprehensive authentication support for Swift v1 auth, Keystone v2/v3, and session-based authentication with multiple credential types and authentication methods.

def get_auth(auth_url, user, key, **kwargs):
    """
    Get authentication/authorization credentials.

    Parameters:
    - auth_url: str, authentication URL
    - user: str, username for authentication
    - key: str, password/key for authentication
    - auth_version: str, auth version ('1', '2.0', '3')
    - os_options: dict, OpenStack identity service options
    - session: keystoneauth1 session object

    Returns:
    tuple: (storage_url, auth_token)
    """

Authentication

Low-Level Operations

Direct HTTP-level functions for Swift operations providing fine-grained control over requests, custom headers, and response handling.

def get_account(url, token, marker=None, limit=None, prefix=None, end_marker=None, http_conn=None, full_listing=False, service_token=None, headers=None, delimiter=None): ...
def get_container(url, token, container, marker=None, limit=None, prefix=None, delimiter=None, end_marker=None, version_marker=None, path=None, http_conn=None, full_listing=False, service_token=None, headers=None, query_string=None): ...
def get_object(url, token, container, name, http_conn=None, resp_chunk_size=None, query_string=None, response_dict=None, headers=None, service_token=None): ...
def put_object(url, token=None, container=None, name=None, contents=None, content_length=None, etag=None, chunk_size=None, content_type=None, headers=None, http_conn=None, proxy=None, query_string=None, response_dict=None, service_token=None): ...
def delete_object(url, token=None, container=None, name=None, http_conn=None, headers=None, proxy=None, query_string=None, response_dict=None, service_token=None): ...

Low-Level Operations

Bulk Operations Service

High-level service for bulk operations with multi-threading, progress reporting, automatic retries, and comprehensive error handling for upload, download, delete, and copy operations.

class SwiftService:
    def __init__(self, options=None): ...
    def upload(self, container, objects, options=None): ...
    def download(self, container=None, objects=None, options=None): ...
    def delete(self, container=None, objects=None, options=None): ...
    def copy(self, container=None, objects=None, options=None): ...
    def post(self, container=None, objects=None, options=None): ...
    def list(self, container=None, options=None): ...
    def stat(self, container=None, objects=None, options=None): ...
    def get_capabilities(self, url=None): ...

Bulk Operations Service

Utility Functions

Helper functions for temporary URLs, header processing, data formatting, and various Swift-specific operations.

def generate_temp_url(path, seconds, key, method, absolute=False, prefix_based=False, iso8601=False, ip_range=None, digest=None, auth_url=None): ...
def parse_api_response(headers, body): ...
def config_true_value(value): ...
def prt_bytes(num_bytes, human_flag): ...

Utility Functions

Exception Handling

Comprehensive error handling with detailed HTTP context, transaction IDs, and Swift-specific error information.

class ClientException(Exception):
    def __init__(
        self,
        msg,
        http_scheme='',
        http_host='',
        http_port='',
        http_path='',
        http_query='',
        http_status=None,
        http_reason='',
        http_device='',
        http_response_content='',
        http_response_headers=None
    ): ...

Exception Handling

docs

authentication.md

bulk-operations.md

client-connection.md

command-line-interface.md

exceptions.md

index.md

low-level-operations.md

utilities.md

tile.json