{"id":5443,"library":"python-swiftclient","title":"OpenStack Object Storage (Swift) Client","description":"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.","status":"active","version":"4.10.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/python-swiftclient","tags":["openstack","swift","object-storage","cloud","api-client"],"install":[{"cmd":"pip install python-swiftclient","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core HTTP client for making API calls.","package":"requests","optional":false},{"reason":"Commonly used for authentication against Keystone identity service, often a de-facto dependency for modern OpenStack deployments.","package":"keystoneauth1","optional":true}],"imports":[{"note":"Directly import the Connection class for the low-level API.","wrong":"import swiftclient.client","symbol":"Connection","correct":"from swiftclient.client import Connection"},{"note":"Directly import the SwiftService class for the high-level API.","wrong":"import swiftclient.service","symbol":"SwiftService","correct":"from swiftclient.service import SwiftService"}],"quickstart":{"code":"import os\nfrom swiftclient.client import Connection\n\n# --- Environment Variables for Authentication ---\n# Set these environment variables before running, e.g., using an OpenStack RC file\n# or directly:\n# export OS_AUTH_URL=\"http://your-auth-url:5000/v3\"\n# export OS_USERNAME=\"your-username\"\n# export OS_PASSWORD=\"your-password\"\n# export OS_PROJECT_NAME=\"your-project-name\"\n# export OS_USER_DOMAIN_NAME=\"Default\" # Or your specific user domain\n# export OS_PROJECT_DOMAIN_NAME=\"Default\" # Or your specific project domain\n# export OS_REGION_NAME=\"RegionOne\" # Or your specific region\n\nauth_url = os.environ.get('OS_AUTH_URL', 'http://localhost:5000/v3')\nusername = os.environ.get('OS_USERNAME', 'test_user')\npassword = os.environ.get('OS_PASSWORD', 'test_password')\nproject_name = os.environ.get('OS_PROJECT_NAME', 'test_project')\nuser_domain_name = os.environ.get('OS_USER_DOMAIN_NAME', 'Default')\nproject_domain_name = os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default')\nregion_name = os.environ.get('OS_REGION_NAME', 'RegionOne')\n\n# Ensure auth_version is specified, especially for Keystone v3\n# os_options are crucial for domain-scoped authentication\nos_options = {\n    'user_domain_name': user_domain_name,\n    'project_domain_name': project_domain_name,\n    'project_name': project_name,\n    'region_name': region_name\n}\n\ntry:\n    # Establish connection\n    conn = Connection(\n        authurl=auth_url,\n        user=username,\n        key=password,\n        os_options=os_options,\n        auth_version='3' # Crucial: always specify auth_version for v3 or v2 auth\n    )\n\n    # Example: List containers\n    _resp_headers, containers = conn.get_account()\n    print(f\"Successfully connected. Found {len(containers)} containers:\")\n    for container in containers:\n        print(f\"  - {container['name']} (Bytes: {container['bytes']}, Count: {container['count']})\")\n\n    # Example: Create a new container\n    container_name = \"my-new-test-container\"\n    try:\n        conn.put_container(container_name)\n        print(f\"Container '{container_name}' created (or already exists).\")\n    except Exception as e:\n        print(f\"Error creating container {container_name}: {e}\")\n    \n    # Example: Upload an object (simple string content)\n    object_name = \"hello_world.txt\"\n    object_content = b\"Hello, Swift Object Storage!\"\n    try:\n        conn.put_object(container_name, object_name, object_content)\n        print(f\"Object '{object_name}' uploaded to '{container_name}'.\")\n    except Exception as e:\n        print(f\"Error uploading object {object_name}: {e}\")\n\nfinally:\n    # Always close the connection\n    if 'conn' in locals():\n        conn.close()\n        print(\"Connection closed.\")\n","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly when interacting with non-v1 auth endpoints."},{"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.","message":"Support for Python 3.6 was dropped in version 4.8.0. Earlier, support for Python 2 was completely removed.","severity":"breaking","affected_versions":"4.8.0 and later (Python 3.6), all versions (Python 2)"},{"fix":"Explicitly configure the storage URLs in your client configuration or environment variables, rather than relying on `SERVICENET`.","message":"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.","severity":"deprecated","affected_versions":"4.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"4.8.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"< 3.8.1 (sending fixed, receiving might still be an issue)"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}