swiftly.client

Client API to Swift

Copyright 2011-2013 Gregory Holt

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class swiftly.client.Client(auth_url=None, auth_user=None, auth_key=None, proxy=None, snet=False, retries=4, swift_proxy=None, swift_proxy_storage_path=None, cache_path=None, eventlet=None, swift_proxy_cdn_path=None, region=None, verbose=None, verbose_id='', auth_tenant=None, auth_methods=None)[source]

Bases: object

Client code to work with Swift.

Parameters:
  • auth_url – The URL to the auth system.
  • auth_user – The user to authenticate as.
  • auth_key – The key to use when authenticating.
  • proxy – The URL to the proxy to use. Default: None.
  • snet – Prepends “snet-” to the host name of the storage URL given once authenticated. This is usually only useful when working with Rackspace Cloud Files and wanting to use Rackspace ServiceNet. Default: False.
  • retries – The number of times to retry requests if a server error ocurrs (5xx response). Default: 4 (for a total of 5 attempts).
  • swift_proxy – Default: None. If set, the swift.proxy.server.Application given will be used instead of connecting to an external proxy server. You can also set it to True and the Swift proxy will be created with default values.
  • swift_proxy_storage_path – If swift_proxy is set, swift_proxy_storage_path is the path to the Swift account to use (example: /v1/AUTH_test).
  • cache_path – Default: None. If set to a path, the storage URL and auth token are cached in the file for reuse. If there is already cached values in the file, they are used without authenticating first.
  • eventlet – Default: None. If True, Eventlet will be used if installed. If False, Eventlet will not be used even if installed. If None, the default, Eventlet will be used if installed and its version is at least 0.11.0 when a CPU usage bug was fixed.
  • swift_proxy_cdn_path – If swift_proxy is set, swift_proxy_cdn_path is the path to the Swift account to use for CDN management (example: /v1/AUTH_test).
  • region – The region to access, if supported by auth (Example: DFW).
  • verbose – Set to a func(msg, *args) that will be called with debug messages. Constructing a string for output can be done with msg % args.
  • verbose_id – Set to a string you wish verbose messages to be prepended with; can help in identifying output when multiple Clients are in use.
  • auth_tenant – The tenant to authenticate as, if needed. Default (if needed): same as auth_user.
  • auth_methods – Auth methods to use with the auth system, example: auth2key,auth2password,auth2password_force_tenant,auth1 If not specified, the best order will try to be determined; but if you notice it keeps making useless auth attempts and that drives you crazy, you can override that here. All the available auth methods are listed in the example.
auth()[source]

Just performs the authentication step without making an actual request to the Swift system.

delete_account(headers=None, yes_i_mean_delete_the_account=False, query=None, cdn=False, body=None)[source]

Sends a DELETE request to the account and returns the results.

With query['bulk-delete'] = '' this might mean a bulk delete request where the body of the request is new-line separated, url-encoded list of names to delete. Be careful with this! One wrong move and you might mark your account for deletion of you have the access to do so!

For a plain DELETE to the account, on clusters that support it and, assuming you have permissions to do so, the account will be marked as deleted and immediately begin removing the objects from the cluster in the backgound.

THERE IS NO GOING BACK!

Parameters:
  • headers – Additional headers to send with the request.
  • yes_i_mean_delete_the_account – Set to True to verify you really mean to delete the entire account. This is required unless body and 'bulk-delete' in query.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
  • body – Some account DELETE requests, like the bulk delete request, take a body.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

delete_container(container, headers=None, query=None, cdn=False, body=None)[source]

DELETEs the container and returns the results.

Parameters:
  • container – The name of the container.
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
  • body – Some container DELETE requests might take a body in the future.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

delete_object(container, obj, headers=None, query=None, cdn=False, body=None)[source]

DELETEs the object and returns the results.

Parameters:
  • container – The name of the container.
  • obj – The name of the object.
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
  • body – Some object DELETE requests might take a body in the future.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

get_account(headers=None, prefix=None, delimiter=None, marker=None, end_marker=None, limit=None, query=None, cdn=False)[source]

GETs the account and returns the results. This is done to list the containers for the account. Some useful headers are also returned:

x-account-bytes-used Object storage used for the account, in bytes.
x-account-container-count The number of containers in the account.
x-account-object-count The number of objects in the account.

Also, any user headers beginning with x-account-meta- are returned.

These values can be delayed depending the Swift cluster.

Parameters:
  • headers – Additional headers to send with the request.
  • prefix – The prefix container names must match to be listed.
  • delimiter

    The delimiter for the listing. Delimiters indicate how far to progress through container names before “rolling them up”. For instance, a delimiter=’.’ query on an account with the containers:

    one.one
    one.two
    two
    three.one
    

    would return the JSON value of:

    [{'subdir': 'one.'},
     {'count': 0, 'bytes': 0, 'name': 'two'},
     {'subdir': 'three.'}]
    

    Using this with prefix can allow you to traverse a psuedo hierarchy.

  • marker – Only container names after this marker will be returned. Swift returns a limited number of containers per request (often 10,000). To get the next batch of names, you issue another query with the marker set to the last name you received. You can continue to issue requests until you receive no more names.
  • end_marker – Only container names before this marker will be returned.
  • limit – Limits the size of the list returned per request. The default and maximum depends on the Swift cluster (usually 10,000).
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

get_account_hash()[source]
get_container(container, headers=None, prefix=None, delimiter=None, marker=None, end_marker=None, limit=None, query=None, cdn=False)[source]

GETs the container and returns the results. This is done to list the objects for the container. Some useful headers are also returned:

x-container-bytes-used Object storage used for the container, in bytes.
x-container-object-count The number of objects in the container.

Also, any user headers beginning with x-container-meta- are returned.

These values can be delayed depending the Swift cluster.

Parameters:
  • container – The name of the container.
  • headers – Additional headers to send with the request.
  • prefix – The prefix object names must match to be listed.
  • delimiter

    The delimiter for the listing. Delimiters indicate how far to progress through object names before “rolling them up”. For instance, a delimiter=’/’ query on an container with the objects:

    one/one
    one/two
    two
    three/one
    

    would return the JSON value of:

    [{'subdir': 'one/'},
     {'count': 0, 'bytes': 0, 'name': 'two'},
     {'subdir': 'three/'}]
    

    Using this with prefix can allow you to traverse a psuedo hierarchy.

  • marker – Only object names after this marker will be returned. Swift returns a limited number of objects per request (often 10,000). To get the next batch of names, you issue another query with the marker set to the last name you received. You can continue to issue requests until you receive no more names.
  • end_marker – Only object names before this marker will be returned.
  • limit – Limits the size of the list returned per request. The default and maximum depends on the Swift cluster (usually 10,000).
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

get_object(container, obj, headers=None, stream=True, query=None, cdn=False)[source]

GETs the object and returns the results.

Parameters:
  • container – The name of the container.
  • obj – The name of the object.
  • headers – Additional headers to send with the request.
  • stream – Indicates whether to stream the contents or preread them fully and return them as a str. Default: True to stream the contents. When streaming, contents will have the standard file-like-object read function, which accepts an optional size parameter to limit how much data is read per call. When streaming is on, be certain to fully read the contents before issuing another request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:if stream was True, contents is a file-like-object of the contents of the HTTP body. If stream was False, contents is just a simple str of the HTTP body.

head_account(headers=None, query=None, cdn=False)[source]

HEADs the account and returns the results. Useful headers returned are:

x-account-bytes-used Object storage used for the account, in bytes.
x-account-container-count The number of containers in the account.
x-account-object-count The number of objects in the account.

Also, any user headers beginning with x-account-meta- are returned.

These values can be delayed depending the Swift cluster.

Parameters:
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

head_container(container, headers=None, query=None, cdn=False)[source]

HEADs the container and returns the results. Useful headers returned are:

x-container-bytes-used Object storage used for the container, in bytes.
x-container-object-count The number of objects in the container.

Also, any user headers beginning with x-container-meta- are returned.

These values can be delayed depending the Swift cluster.

Parameters:
  • container – The name of the container.
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

head_object(container, obj, headers=None, query=None, cdn=False)[source]

HEADs the object and returns the results.

Parameters:
  • container – The name of the container.
  • obj – The name of the object.
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

post_account(headers=None, query=None, cdn=False, body=None)[source]

POSTs the account and returns the results. This is usually done to set X-Account-Meta-xxx headers. Note that any existing X-Account-Meta-xxx headers will remain untouched. To remove an X-Account-Meta-xxx header, send the header with an empty string as its value.

Parameters:
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
  • body – No known Swift POSTs take a body; but the option is there for the future.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

post_container(container, headers=None, query=None, cdn=False, body=None)[source]

POSTs the container and returns the results. This is usually done to set X-Container-Meta-xxx headers. Note that any existing X-Container-Meta-xxx headers will remain untouched. To remove an X-Container-Meta-xxx header, send the header with an empty string as its value.

Parameters:
  • container – The name of the container.
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
  • body – No known Swift POSTs take a body; but the option is there for the future.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

post_object(container, obj, headers=None, query=None, cdn=False, body=None)[source]

POSTs the object and returns the results. This is used to update the object’s header values. Note that all headers must be sent with the POST, unlike the account and container POSTs. With account and container POSTs, existing headers are untouched. But with object POSTs, any existing headers are removed. The full list of supported headers depends on the Swift cluster, but usually include Content-Type, Content-Encoding, and any X-Object-Meta-xxx headers.

Parameters:
  • container – The name of the container.
  • obj – The name of the object.
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
  • body – No known Swift POSTs take a body; but the option is there for the future.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

put_account(headers=None, query=None, cdn=False, body=None)[source]

PUTs the account and returns the results. This is usually done with the extract-archive bulk upload request and has no other use I know of (but the call is left open in case there ever is).

Parameters:
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
  • body – Some account PUT requests, like the extract-archive bulk upload request, take a body.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

put_container(container, headers=None, query=None, cdn=False, body=None)[source]

PUTs the container and returns the results. This is usually done to create new containers and can also be used to set X-Container-Meta-xxx headers. Note that if the container already exists, any existing X-Container-Meta-xxx headers will remain untouched. To remove an X-Container-Meta-xxx header, send the header with an empty string as its value.

Parameters:
  • container – The name of the container.
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
  • body – Some container PUT requests, like the extract-archive bulk upload request, take a body.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

put_object(container, obj, contents, headers=None, query=None, cdn=False)[source]

PUTs the object and returns the results. This is used to create or overwrite objects. X-Object-Meta-xxx can optionally be sent to be stored with the object. Content-Type, Content-Encoding and other standard HTTP headers can often also be set, depending on the Swift cluster.

Note that you can set the ETag header to the MD5 sum of the contents for extra verifification the object was stored correctly.

Parameters:
  • container – The name of the container.
  • obj – The name of the object.
  • contents – The contents of the object to store. This can be a simple str, or a file-like-object with at least a read function. If the file-like-object also has tell and seek functions, the PUT can be reattempted on any server error.
  • headers – Additional headers to send with the request.
  • query – Set to a dict of query values to send on the query string of the request.
  • cdn – If set True, the CDN management interface will be used.
Returns:

A tuple of (status, reason, headers, contents).

status:is an int for the HTTP status code.
reason:is the str for the HTTP status (ex: “Ok”).
headers:is a dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:is the str for the HTTP body.

reset()[source]

Resets the client, closing any connections and discarding any state. This can be useful if some exceptional condition occurred and the request/response state can no longer be certain.

Previous topic

swiftly.cli

Next topic

swiftly.concurrency

This Page