tessl/pypi-python-swiftclient

OpenStack Object Storage API Client Library

Overview

Eval results

Files

Command Line Interface

Name: tessl/pypi-python-swiftclient
Author: tessl

The swift command-line client provides complete Swift functionality from the terminal, offering an alternative to the Python API for all Swift operations including upload, download, listing, and management tasks.

Capabilities

Basic Authentication

All CLI commands support comprehensive authentication options.

swift --help
swift --os-username <user> --os-password <password> --os-auth-url <auth_url> <command>
swift --os-storage-url <url> --os-auth-token <token> <command>

Common authentication environment variables:

OS_USERNAME, OS_PASSWORD
OS_AUTH_URL, OS_AUTH_VERSION
OS_TENANT_NAME, OS_PROJECT_NAME
OS_STORAGE_URL, OS_AUTH_TOKEN

Object Operations

Upload, download, and manage objects in Swift containers.

# Upload files and directories
swift upload <container> <file_or_dir> [<file_or_dir>] [...]
    --object-name <object_name>     # Custom object name
    --segment-size <size>           # Large object segment size
    --use-slo                       # Use Static Large Objects
    --segment-container <container> # Custom segment container
    --header <header:value>         # Custom headers
    --meta <name:value>             # Object metadata
    --object-threads <threads>      # Upload threads (default 10)

# Download objects
swift download <container> [<object>] [...]
    --all                           # Download all objects
    --marker <marker>               # Start after this object
    --prefix <prefix>               # Objects starting with prefix
    --output-dir <dir>              # Download directory
    --object-threads <threads>      # Download threads (default 10)
    --container-threads <threads>   # Container threads (default 10)
    --no-download                   # List only, don't download
    --remove-prefix                 # Remove prefix from local names
    --header <header:value>         # Custom request headers

# Delete objects
swift delete <container> [<object>] [...]
    --all                           # Delete all containers and objects
    --leave-segments                # Don't delete manifest segments
    --object-threads <threads>      # Delete threads (default 10)
    --container-threads <threads>   # Container threads (default 10)
    --prefix <prefix>               # Delete objects with prefix
    --versions                      # Delete all object versions
    --version-id <id>               # Delete specific version
    --header <header:value>         # Custom request headers

# Copy objects
swift copy <container> <object> [...]
    --destination <dest_container/dest_object> # Copy destination
    --fresh-metadata                # Replace metadata, don't merge
    --meta <name:value>             # Set metadata on copy
    --header <header:value>         # Custom request headers

Container Operations

Create, list, and manage Swift containers.

# List containers and objects
swift list [<container>]
    --long                          # Long listing format
    --totals                        # Show totals
    --prefix <prefix>               # Filter by prefix
    --delimiter <delimiter>         # Delimiter for pseudo-directories
    --marker <marker>               # Start listing after marker
    --end-marker <marker>           # Stop listing before marker
    --limit <limit>                 # Limit number of results
    --header <header:value>         # Custom request headers

# Update container/object metadata
swift post <container> [<object>]
    --read-acl <acl>                # Container read ACL
    --write-acl <acl>               # Container write ACL
    --sync-to <container>           # Container sync destination
    --sync-key <key>                # Container sync key
    --meta <name:value>             # Set metadata
    --header <header:value>         # Custom headers
    --versions-location <container>  # Enable versioning
    --history-location <container>   # Set history location

Information and Statistics

Get detailed information about accounts, containers, and objects.

# Show statistics
swift stat [<container>] [<object>]
    --lh                            # Human readable sizes
    --header <header:value>         # Custom request headers
    --version-id <id>               # Show specific version

# Show capabilities
swift capabilities [<url>]
    --json                          # Output in JSON format

# Show authentication info
swift auth
    --json                          # Output in JSON format

Advanced Features

Generate temporary URLs and enable shell completion.

# Generate temporary URLs
swift tempurl <method> <seconds> <path> <key>
    --absolute                      # Use absolute expiration time
    --prefix-based                  # Allow prefix-based access
    --iso8601                       # Use ISO 8601 timestamp format
    --ip-range <range>              # Restrict to IP range
    --digest <algorithm>            # Digest algorithm (sha1, sha256, sha512)

# Enable bash completion
swift bash_completion

Usage Examples

Basic Object Management

# Set authentication via environment variables
export OS_USERNAME=myuser
export OS_PASSWORD=mypass
export OS_AUTH_URL=https://identity.example.com:5000/v3
export OS_PROJECT_NAME=myproject
export OS_USER_DOMAIN_NAME=mydomain
export OS_PROJECT_DOMAIN_NAME=mydomain

# List all containers
swift list

# Create a container and upload a file
swift upload documents report.pdf

# Download all objects from a container
swift download documents

# List objects in a container with details
swift list --long documents

# Get container statistics
swift stat documents

# Delete an object
swift delete documents report.pdf

Large File Uploads

# Upload large file using Static Large Objects
swift upload videos --use-slo --segment-size 100M movie.mp4

# Upload directory with custom segment container
swift upload backups --segment-container backup-segments /path/to/data/

Temporary URLs

# Generate 1-hour temporary download URL
swift tempurl GET 3600 /v1/AUTH_account/container/object.jpg secret_key

# Generate temporary upload URL with IP restriction
swift tempurl PUT 1800 /v1/AUTH_account/uploads/newfile.dat upload_key --ip-range 192.168.1.0/24

Bulk Operations

# Download all objects matching a prefix
swift download --prefix photos/2023/ gallery

# Delete all objects in a container
swift delete --all mycontainer

# Upload multiple files with metadata
swift upload docs --meta category:reports *.pdf

Container Sync and Versioning

# Enable container versioning
swift post container --versions-location container-versions

# Set up container sync
swift post source-container --sync-to target-container --sync-key sync_secret

# Set container ACLs
swift post public-container --read-acl ".r:*,.rlistings"

Global Options

All commands support these global authentication and configuration options:

--os-username <username>        # OpenStack username
--os-password <password>        # OpenStack password
--os-tenant-name <tenant>       # OpenStack tenant name
--os-auth-url <auth_url>        # OpenStack auth URL
--os-auth-version <version>     # Auth version (1, 2, 3)
--os-storage-url <url>          # Storage URL (bypass auth)
--os-auth-token <token>         # Auth token (bypass auth)
--os-region-name <region>       # OpenStack region
--insecure                      # Allow insecure SSL connections
--no-ssl                        # Use HTTP instead of HTTPS
--ssl-compression               # Enable SSL compression
--retries <count>               # Number of retries (default 5)
--retry-on-ratelimit           # Retry on rate limit responses
--timeout <seconds>             # Connection timeout
--verbose                       # Verbose output
--debug                         # Debug output
--quiet                         # Suppress output
--json                          # JSON formatted output

Install with Tessl CLI

npx tessl i tessl/pypi-python-swiftclient

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

tessl/pypi-python-swiftclient