API Documentation

swiftly

Client for Swift

Copyright 2012-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.

swiftly.VERSION = '2.07'

Version str for Swiftly: "major.minor".

If the second number is even, it's an official release. If the second number is odd, it's a development release.

swiftly.cli

Contains swiftly.cli.cli.CLI that implements the swiftly command line interface and all the surrounding implementation modules.

CLI is imported here for convenience.

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.

swiftly.cli.auth

Contains a CLICommand that authenticates and then outputs the resulting information.

Uses the following from swiftly.cli.context.CLIContext:

client_manager For connecting to Swift.
io_manager For directing output.
class swiftly.cli.auth.CLIAuth(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand that authenticates and then outputs the resulting information.

See the output of swiftly help auth for more information.

__call__(args)
swiftly.cli.auth.cli_auth(context)

Authenticates and then outputs the resulting information.

See swiftly.cli.auth for context usage information.

See CLIAuth for more information.

swiftly.cli.cli

Contains the CLI class that handles the original command line.

class swiftly.cli.cli.CLI(commands=None)

Bases: object

Handles the original command line.

An example script is swiftly itself:

#!/usr/bin/env python
import sys
import swiftly.cli
sys.exit(swiftly.cli.CLI()())

See the output of swiftly help for more information.

Parameters:commands -- The list of commands available; if None COMMANDS will be used.
__call__(args=None)
commands = None

A dictionary of the available commands and their CLICommand instances.

context = None

The overall CLIContext containing attributes generated by the initial main_options parsing.

The available attributes are:

cdn True if the CDN URL should be used instead of the default Storage URL.
client_manager The swiftly.client.manager.ClientManager to use for obtaining clients.
concurrency Number of concurrent actions to allow.
io_manager The swiftly.cli.iomanager.IOManager to use for input and output.
eventlet True if Eventlet is in use.
original_args The original args used by the CLI.
original_begin The original time.time() when the CLI was called.
verbose Function to call when you want to (optionally) emit verbose output. verbose(msg, *args) where the output will be constructed with msg % args.
verbosity Level of verbosity. Just None or 1 right now.
option_parser = None

The main OptionParser.

swiftly.cli.cli.COMMANDS = ['swiftly help auth', 'swiftly help decrypt', 'swiftly help delete', 'swiftly help encrypt', 'swiftly help fordo', 'swiftly help get', 'swiftly help head', '', 'swiftly help ping', 'swiftly help post', 'swiftly help put', 'swiftly help tempurl', 'swiftly help trans']

The list of CLICommand classes avaiable to CLI. You'll want to add any new CLICommand you create to this list.

swiftly.cli.cli.TRUE_VALUES = ['1', 'on', 't', 'true', 'y', 'yes']

A list of lowercase string values that equate to True.

swiftly.cli.command

Contains the CLICommand class that can be subclassed to create new Swiftly commands.

class swiftly.cli.command.CLICommand(cli, name, min_args=None, max_args=None, usage=None)

Bases: object

Subclass this to create new Swiftly commands.

Don't forget to add your new class to swiftly.cli.cli.COMMANDS.

Your subclass will be created by swiftly.cli.cli.CLI with the CLI instance as the only parameter. You should then call this superclass with that CLI instance, your command's name, and any other options desired.

See the implemention for other commands like swiftly.cli.auth.CLIAuth for good starting points.

Parameters:
  • cli -- The swiftly.cli.cli.CLI instance.
  • name -- The name of the command.
  • min_args -- The minimum number of arguments required.
  • max_args -- The maximum number of arguments allowed.
  • usage -- The usage string for OptionParser.
options_list_to_lowered_dict(options_list)

Helper function that will convert an options list into a dict of key/values.

This is used for the quite common -hheader:value and -qparameter=value command line options, like this:

context.headers = self.options_list_to_lowered_dict(options.header)
context.query = self.options_list_to_lowered_dict(options.query)

For a full example, see swiftly.cli.get.CLIGet.__call__().

parse_args_and_create_context(args)

Helper method that will parse the args into options and remaining args as well as create an initial swiftly.cli.context.CLIContext.

The new context will be a copy of swiftly.cli.cli.CLI.context with the following attributes added:

muted_account_headers The headers to omit when outputting account headers.
muted_container_headers The headers to omit when outputting container headers.
muted_object_headers The headers to omit when outputting object headers.
Returns:options, args, context
exception swiftly.cli.command.ReturnCode(text=None, code=1)

Bases: exceptions.Exception

Raise this to indicate the desire to exit.

Parameters:
  • text -- The text to report as the reason for exiting. Default: None
  • code -- The return code to give back to the shell. Default: 1

swiftly.cli.context

Contains the CLIContext class used to pass contextual information to CLI functions.

class swiftly.cli.context.CLIContext

Bases: object

Used to pass contextual information to CLI functions.

An instance of this class will allow almost any attribute access, even if that attribute did not previously exist. It offers an easy way to set new attributes on the fly for different use cases without having to create a whole new subclasses.

copy()

Returns a new CLIContext instance that is a shallow copy of the original, much like dict's copy method.

write_headers(fp, headers, mute=None)

Convenience function to output headers in a formatted fashion to a file-like fp, optionally muting any headers in the mute list.

swiftly.cli.decrypt

Contains a CLICommand for decrypting stdin to stdout.

Uses the following from swiftly.cli.context.CLIContext:

io_manager For directing output.
class swiftly.cli.decrypt.CLIDecrypt(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand for decrypting stdin and sending that to stdout.

See the output of swiftly help decrypt for more information.

__call__(args)
swiftly.cli.decrypt.cli_decrypt(context, key)

Decrypts context.io_manager's stdin and sends that to context.io_manager's stdout.

See swiftly.cli.decrypt for context usage information.

See CLIDecrypt for more information.

swiftly.cli.delete

Contains a CLICommand that can issue DELETE requests.

Uses the following from swiftly.cli.context.CLIContext:

cdn True if the CDN Management URL should be used instead of the Storage URL.
client_manager For connecting to Swift.
concurrency The number of concurrent actions that can be performed.
headers A dict of headers to send.
ignore_404 True if 404s should be silently ignored.
io_manager For directing output.
query A dict of query parameters to send.
class swiftly.cli.delete.CLIDelete(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand that can issue DELETE requests.

See the output of swiftly help delete for more information.

__call__(args)
swiftly.cli.delete.cli_delete(context, path, body=None, recursive=False, yes_empty_account=False, yes_delete_account=False, until_empty=False)

Deletes the item (account, container, or object) at the path.

See swiftly.cli.delete for context usage information.

See CLIDelete for more information.

Parameters:
  • context -- The swiftly.cli.context.CLIContext to use.
  • path -- The path of the item (acount, container, or object) to delete.
  • body -- The body to send with the DELETE request. Bodies are not normally sent with DELETE requests, but this can be useful with bulk deletes for instance.
  • recursive -- If True and the item is an account or container, deletes will be issued for any containing items as well. This does one pass at the deletion; so if objects revert to previous versions or if new objects otherwise arise during the process, the container(s) may not be empty once done. Set until_empty to True if you want multiple passes to keep trying to fully empty the containers.
  • until_empty -- If True and recursive is True, this will cause Swiftly to keep looping through the deletes until the containers are completely empty. Useful if you have object versioning turned on or otherwise have objects that seemingly reappear after being deleted. It could also run forever if you have something that's uploading objects at a faster rate than they are deleted.
  • yes_empty_account -- This must be set to True for verification when the item is an account and recursive is True.
  • yes_delete_account -- This must be set to True for verification when the item is an account and you really wish a delete to be issued for the account itself.
swiftly.cli.delete.cli_empty_account(context, yes_empty_account=False, until_empty=False)

Deletes all objects and containers in the account.

You must set yes_empty_account to True to verify you really want to do this.

By default, this will perform one pass at deleting all objects and containers; so if objects revert to previous versions or if new objects or containers otherwise arise during the process, the account may not be empty once done.

Set until_empty to True if you want multiple passes to keep trying to fully empty and delete the containers. Note until_empty=True could run forever if something else is making new items faster than they're being deleted.

See swiftly.cli.delete for context usage information.

See CLIDelete for more information.

swiftly.cli.delete.cli_empty_container(context, path, until_empty=False)

Deletes all objects in the container.

By default, this will perform one pass at deleting all objects in the container; so if objects revert to previous versions or if new objects otherwise arise during the process, the container may not be empty once done.

Set until_empty to True if you want multiple passes to keep trying to fully empty the container. Note until_empty=True could run forever if something else is making new objects faster than they're being deleted.

See swiftly.cli.delete for context usage information.

See CLIDelete for more information.

swiftly.cli.encrypt

Contains a CLICommand for encrypting stdin to stdout.

Uses the following from swiftly.cli.context.CLIContext:

io_manager For directing output.
class swiftly.cli.encrypt.CLIEncrypt(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand for encrypting stdin and sending that to stdout.

This can be useful to encrypt to disk before attempting to upload, allowing uploads retries and segmented encrypted objects.

See the output of swiftly help encrypt for more information.

__call__(args)
swiftly.cli.encrypt.cli_encrypt(context, key)

Encrypts context.io_manager's stdin and sends that to context.io_manager's stdout.

This can be useful to encrypt to disk before attempting to upload, allowing uploads retries and segmented encrypted objects.

See swiftly.cli.encrypt for context usage information.

See CLIEncrypt for more information.

swiftly.cli.fordo

Contains a CLICommand that can issue other commands for each item in an account or container listing.

Uses the following from swiftly.cli.context.CLIContext:

cdn True if the CDN Management URL should be used instead of the Storage URL.
client_manager For connecting to Swift.
concurrency The number of concurrent actions that can be performed.
headers A dict of headers to send.
ignore_404 True if 404s should be silently ignored.
io_manager For directing output.
query A dict of query parameters to send. Of important use are limit, delimiter, prefix, marker, and end_marker as they are common listing query parameters.
remaining_args The list of command line args to issue to the sub-CLI instance; the first arg that equals '<item>' will be replaced with each item the for encounters. Any additional instances of '<item>' will be left alone, as you might be calling a nested "for ... do".
original_main_args Used when constructing sub-CLI instances.
output_names If True, outputs the name of each item just before calling [command] with it. To ensure easier parsing, the name will be url encoded and prefixed with "Item Name: ". For commands that have output of their own, this is usually only useful with single concurrency; otherwise the item names and the command output will get interspersed and impossible to associate.
class swiftly.cli.fordo.CLIForDo(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand that can issue other commands for each item in an account or container listing.

See the output of swiftly help for for more information.

__call__(args)
swiftly.cli.fordo.cli_fordo(context, path=None)

Issues commands for each item in an account or container listing.

See swiftly.cli.fordo for context usage information.

See CLIForDo for more information.

swiftly.cli.get

Contains a CLICommand that can issue GET requests.

Uses the following from swiftly.cli.context.CLIContext:

all_objects True if instead of the listing itself you want all objects that the listing references to be output.
cdn True if the CDN Management URL should be used instead of the Storage URL.
client_manager For connecting to Swift.
concurrency The number of concurrent actions that can be performed.
full True if you want a full listing (additional information like object count, bytes used, and upload date) instead of just the item names.
headers A dict of headers to send.
ignore_404 True if 404s should be silently ignored.
io_manager For directing output.
muted_account_headers The headers to omit when outputting account response headers.
muted_container_headers The headers to omit when outputting container response headers.
muted_object_headers The headers to omit when outputting object response headers.
output_headers True if you want the headers from the response to also be output.
query A dict of query parameters to send. Of important use are limit, delimiter, prefix, marker, and end_marker as they are common listing query parameters.
raw Normally the result of the GET is translated as a listing and formatted output is generated. Setting this to True will skip any formatting a just output the raw contents from the response. Note that this will also just issue a single request and will not try additional follow-on marker requests.
remove_empty_files True if files created on disk should be removed if they result in an empty file. This can be useful with sub_commands that only output information for matches.
suppress_container_name True if files created on disk should have the container name stripped from the file name. When downloading a single container, this is usually desired.
write_headers A function used to output the response headers if output_headers is set True.
class swiftly.cli.get.CLIGet(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand that can issue GET requests.

See the output of swiftly help get for more information.

__call__(args)
swiftly.cli.get.cli_get(context, path=None)

Performs a GET on the item (account, container, or object).

See swiftly.cli.get for context usage information.

See CLIGet for more information.

swiftly.cli.get.cli_get_account_listing(context)

Performs a GET on the account as a listing request.

See swiftly.cli.get for context usage information.

See CLIGet for more information.

swiftly.cli.get.cli_get_container_listing(context, path=None)

Performs a GET on the container as a listing request.

See swiftly.cli.get for context usage information.

See CLIGet for more information.

swiftly.cli.head

Contains a CLICommand that can issue HEAD requests.

Uses the following from swiftly.cli.context.CLIContext:

cdn True if the CDN Management URL should be used instead of the Storage URL.
client_manager For connecting to Swift.
headers A dict of headers to send.
ignore_404 True if 404s should be silently ignored.
io_manager For directing output.
muted_account_headers The headers to omit when outputting account response headers.
muted_container_headers The headers to omit when outputting container response headers.
muted_object_headers The headers to omit when outputting object response headers.
query A dict of query parameters to send.
write_headers A function used to output the response headers.
class swiftly.cli.head.CLIHead(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand that can issue HEAD requests.

See the output of swiftly help head for more information.

__call__(args)
swiftly.cli.head.cli_head(context, path=None)

Performs a HEAD on the item (account, container, or object).

See swiftly.cli.head for context usage information.

See CLIHead for more information.

swiftly.cli.help

Contains a CLICommand that outputs help information.

Uses the following from swiftly.cli.context.CLIContext:

io_manager For directing output.
class swiftly.cli.help.CLIHelp(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand that outputs help information.

See the output of swiftly help help for more information.

__call__(args)
swiftly.cli.help.cli_help(context, command_name, general_parser, command_parsers)

Outputs help information.

See swiftly.cli.help for context usage information.

See CLIHelp for more information.

Parameters:
  • context -- The swiftly.cli.context.CLIContext to use.
  • command_name -- The command_name to output help information for, or set to None or an empty string to output the general help information.
  • general_parser -- The swiftly.cli.optionparser.OptionParser for general usage.
  • command_parsers -- A dict of (name, CLICommand) for specific command usage.

swiftly.cli.iomanager

Contains IOManager for managing access to input, output, error, and debug file-like objects.

class swiftly.cli.iomanager.IOManager(stdin=None, stdout=None, stderr=None, debug=None, stdin_root=None, stdout_root=None, stderr_root=None, debug_root=None, stdin_sub_command=None, stdout_sub_command=None, stderr_sub_command=None, debug_sub_command=None, subprocess_module=None, verbose=None)

Bases: object

Manages access to IO in ways that are mostly specific to swiftly.cli but might be generally useful.

Parameters:
  • stdin -- The file-like object to use for default stdin or sys.stdin if None.
  • stdout -- The file-like object to use for default stdout or sys.stdout if None.
  • stderr -- The file-like object to use for default stderr or sys.stderr if None.
  • debug -- The file-like object to use for default debug output or sys.stderr if None.
  • stdin_root -- The root path to use for requests for pathed stdin file-like objects.
  • stdout_root -- The root path to use for requests for pathed stdout file-like objects.
  • stderr_root -- The root path to use for requests for pathed stderr file-like objects.
  • debug_root -- The root path to use for requests for pathed debug file-like objects.
  • stdin_sub_command -- A shell line to pipe any stdin file-like objects through.
  • stdout_sub_command -- A shell line to pipe any stdout file-like objects through.
  • stderr_sub_command -- A shell line to pipe any stderr file-like objects through.
  • debug_sub_command -- A shell line to pipe any debug file-like objects through.
  • subprocess_module -- The subprocess module to use; for instance, you might use eventlet.green.subprocess instead of the standard subprocess module.
  • verbose -- A function to call with (msg) when waiting for subcommands to complete and for logging the subcommands' return codes.
client_path_to_os_path(client_path)

Converts a client path into the operating system's path by replacing instances of '/' with os.path.sep.

Note: If the client path contains any instances of os.path.sep already, they will be replaced with '-'.

get_debug(os_path=None, skip_sub_command=False)

Returns a debug-output-suitable file-like object based on the optional os_path and optionally skipping any configured sub-command.

get_stderr(os_path=None, skip_sub_command=False)

Returns a stderr-suitable file-like object based on the optional os_path and optionally skipping any configured sub-command.

get_stdin(os_path=None, skip_sub_command=False)

Returns a stdin-suitable file-like object based on the optional os_path and optionally skipping any configured sub-command.

get_stdout(os_path=None, skip_sub_command=False)

Returns a stdout-suitable file-like object based on the optional os_path and optionally skipping any configured sub-command.

os_path_to_client_path(os_path)

Converts an operating system path into a client path by replacing instances of os.path.sep with '/'.

Note: If the client path contains any instances of '/' already, they will be replaced with '-'.

with_debug(*args, **kwds)

A context manager yielding a debug-output-suitable file-like object based on the optional os_path and optionally skipping any configured sub-command.

Parameters:
  • os_path -- Optional path to base the file-like object on.
  • skip_sub_command -- Set True to skip any configured sub-command filter.
  • disk_closed_callback -- If the backing of the file-like object is an actual file that will be closed, disk_closed_callback (if set) will be called with the on-disk path just after closing it.
with_stderr(*args, **kwds)

A context manager yielding a stderr-suitable file-like object based on the optional os_path and optionally skipping any configured sub-command.

Parameters:
  • os_path -- Optional path to base the file-like object on.
  • skip_sub_command -- Set True to skip any configured sub-command filter.
  • disk_closed_callback -- If the backing of the file-like object is an actual file that will be closed, disk_closed_callback (if set) will be called with the on-disk path just after closing it.
with_stdin(*args, **kwds)

A context manager yielding a stdin-suitable file-like object based on the optional os_path and optionally skipping any configured sub-command.

Parameters:
  • os_path -- Optional path to base the file-like object on.
  • skip_sub_command -- Set True to skip any configured sub-command filter.
  • disk_closed_callback -- If the backing of the file-like object is an actual file that will be closed, disk_closed_callback (if set) will be called with the on-disk path just after closing it.
with_stdout(*args, **kwds)

A context manager yielding a stdout-suitable file-like object based on the optional os_path and optionally skipping any configured sub-command.

Parameters:
  • os_path -- Optional path to base the file-like object on.
  • skip_sub_command -- Set True to skip any configured sub-command filter.
  • disk_closed_callback -- If the backing of the file-like object is an actual file that will be closed, disk_closed_callback (if set) will be called with the on-disk path just after closing it.

swiftly.cli.optionparser

Contains an extended optparse.OptionParser that works better with command line applications that may call other command line applications or use multiple parsers.

class swiftly.cli.optionparser.OptionParser(usage=None, option_list=None, option_class=<class optparse.Option at 0x7fe69ad59390>, version=None, conflict_handler='error', description=None, formatter=None, add_help_option=True, prog=None, epilog=None, io_manager=None, raw_epilog='', error_prefix='')

Bases: optparse.OptionParser, object

Extended optparse.OptionParser that supports an io_manager, raw_epilog output, and an error prefix. It also does not exit automatically on error and instead sets an instance bool of error_encountered.

error(msg, file=None)

Outputs the error msg to the file if specified, or to the io_manager's stderr if available, or to sys.stderr.

error_encountered = None

True if an error was encountered while parsing.

error_prefix = None

Output just before any error. This can be useful in identification when multiple parsers are in use.

exit(status=0, msg=None)

Immediately exits Python with the given status (or 0) as the exit code and optionally outputs the msg using self.error.

print_help(file=None)

Outputs help information to the file if specified, or to the io_manager's stdout if available, or to sys.stdout.

print_usage(file=None)

Outputs usage information to the file if specified, or to the io_manager's stdout if available, or to sys.stdout.

print_version(file=None)

Outputs version information to the file if specified, or to the io_manager's stdout if available, or to sys.stdout.

raw_epilog = None

Output just after the standard print_help output, in it's raw form. This is different than epilog in that epilog is reformatted.

swiftly.cli.ping

Contains a CLICommand that implements ping test functionality.

Uses the following from swiftly.cli.context.CLIContext:

client_manager For connecting to Swift.
concurrency The number of concurrent actions that can be performed.
io_manager For directing output.
limit The maximum number of Swift nodes to output information about.
object_ring An instance of swift.common.ring.ring.Ring if you want a report based on Swift nodes with implied usage during the ping test.
ping_begin The first time.time() when the entire ping test began.
ping_begin_last The time.time() the last ping task started.
ping_count The number of objects to use.
ping_verbose True if you want a full ping report rather than just the overall time.
threshold Defines the threshold for the threshold node report. This is the multiplier over the average request time.
class swiftly.cli.ping.CLIPing(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand that implements ping test functionality.

See the output of swiftly help ping for more information.

__call__(args)
swiftly.cli.ping.cli_ping(context, prefix)

Performs a ping test.

See swiftly.cli.ping for context usage information.

See CLIPing for more information.

Parameters:

swiftly.cli.post

Contains a CLICommand that can issue POST requests.

Uses the following from swiftly.cli.context.CLIContext:

cdn True if the CDN Management URL should be used instead of the Storage URL.
client_manager For connecting to Swift.
headers A dict of headers to send.
io_manager For directing output.
query A dict of query parameters to send.
class swiftly.cli.post.CLIPost(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand that can issue POST requests.

See the output of swiftly help post for more information.

__call__(args)
swiftly.cli.post.cli_post(context, path, body=None)

Performs a POST on the item (account, container, or object).

See swiftly.cli.post for context usage information.

See CLIPost for more information.

Parameters:

swiftly.cli.put

Contains a CLICommand that can issue PUT requests.

Uses the following from swiftly.cli.context.CLIContext:

cdn True if the CDN Management URL should be used instead of the Storage URL.
client_manager For connecting to Swift.
concurrency The number of concurrent actions that can be performed.
different Set to True to check if the local file is different than an existing object before uploading.
empty Set to True if you wish to send an empty body with the PUT rather than reading from the io_manager's stdin.
headers A dict of headers to send.
input_ A string representing where input should be obtained from. If None, the io_manager's stdin will be used. If a directory path is specified, a set of PUTs will be generated for each item in the directory structure. If a file path is specified, that single file will be used as input.
io_manager For directing output and obtaining input if needed.
newer Set to True to check if the local file is newer than an existing object before uploading.
query A dict of query parameters to send.
seek Where to seek to in the input_ before uploading; usually just used by recursive calls with segmented objects.
segment_size The max size of a file before switching to a segmented object and the max size of each object segment.
static_segments Set to True to use static large object support instead of dynamic large object support.
class swiftly.cli.put.CLIPut(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand that can issue PUT requests.

See the output of swiftly help put for more information.

__call__(args)
swiftly.cli.put.cli_put(context, path)

Performs a PUT on the item (account, container, or object).

See swiftly.cli.put for context usage information.

See CLIPut for more information.

swiftly.cli.put.cli_put_account(context)

Performs a PUT on the account.

See swiftly.cli.put for context usage information.

See CLIPut for more information.

swiftly.cli.put.cli_put_container(context, path)

Performs a PUT on the container.

See swiftly.cli.put for context usage information.

See CLIPut for more information.

swiftly.cli.put.cli_put_directory_structure(context, path)

Performs PUTs rooted at the path using a directory structure pointed to by context.input_.

See swiftly.cli.put for context usage information.

See CLIPut for more information.

swiftly.cli.put.cli_put_object(context, path)

Performs a PUT on the object.

See swiftly.cli.put for context usage information.

See CLIPut for more information.

swiftly.cli.tempurl

Contains a CLICommand for generating TempURLs.

Uses the following from swiftly.cli.context.CLIContext:

io_manager For directing output.
client_manager For connecting to Swift.
class swiftly.cli.tempurl.CLITempURL(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand for generating TempURLs.

See the output of swiftly help tempurl for more information.

__call__(args)
swiftly.cli.tempurl.cli_tempurl(context, method, path, seconds=None, use_container=False)

Generates a TempURL and sends that to the context.io_manager's stdout.

See swiftly.cli.tempurl for context usage information.

See CLITempURL for more information.

Parameters:
  • context -- The swiftly.cli.context.CLIContext to use.
  • method -- The method for the TempURL (GET, PUT, etc.)
  • path -- The path the TempURL should direct to.
  • seconds -- The number of seconds the TempURL should be good for. Default: 3600
  • use_container -- If True, will create a container level TempURL useing X-Container-Meta-Temp-Url-Key instead of X-Account-Meta-Temp-Url-Key.

swiftly.cli.trans

Contains a CLICommand for translating transaction identifiers.

Uses the following from swiftly.cli.context.CLIContext:

io_manager For directing output.
class swiftly.cli.trans.CLITrans(cli)

Bases: swiftly.cli.command.CLICommand

A CLICommand for translating transaction identifiers.

See the output of swiftly help trans for more information.

__call__(args)
swiftly.cli.trans.cli_trans(context, x_trans_id)

Translates any information that can be determined from the x_trans_id and sends that to the context.io_manager's stdout.

See swiftly.cli.trans for context usage information.

See CLITrans for more information.

swiftly.client

Contains tools for connecting to Swift services.

For convenience, the following names are imported from submodules:

StandardClient swiftly.client.standardclient.StandardClient
DirectClient swiftly.client.directclient.DirectClient
LocalClient swiftly.client.localclient.LocalClient
ClientManager swiftly.client.manager.ClientManager
generate_temp_url swiftly.client.utils.generate_temp_url()
get_trans_id_time swiftly.client.utils.get_trans_id_time()

Copyright 2011-2013 Gregory Holt Portions Copyright (c) 2010-2012 OpenStack Foundation

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.

swiftly.client.client

Contains the base Client class for accessing Swift services.

class swiftly.client.client.Client

Bases: object

The base class for accessing Swift services.

For concrete examples, see swiftly.client.standardclient.StandardClient and swiftly.client.directclient.DirectClient.

To form a new concrete subclass, you would need to implement request() and get_account_hash() minimally and optionally reset() and auth().

auth()

Just performs any authentication steps 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)

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)

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)

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, decode_json=True)

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.
  • decode_json -- If set False, the usual decoding of the JSON response will be skipped and the raw contents will be returned instead.
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 decoded JSON response or the raw str for the HTTP body.

get_account_hash()

Returns the account identifier for the Swift account being accessed.

get_container(container, headers=None, prefix=None, delimiter=None, marker=None, end_marker=None, limit=None, query=None, cdn=False, decode_json=True)

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.
  • decode_json -- If set False, the usual decoding of the JSON response will be skipped and the raw contents will be returned instead.
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 decoded JSON response or the raw str for the HTTP body.

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

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)

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)

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)

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.

no_content_methods = None

These HTTP methods do not allow contents

post_account(headers=None, query=None, cdn=False, body=None)

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)

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)

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)

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)

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)

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 verification 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.

request(method, path, contents, headers, decode_json=False, stream=False, query=None, cdn=False)

Performs a direct HTTP request to the Swift service.

Parameters:
  • method -- The request method ('GET', 'HEAD', etc.)
  • path -- The request path.
  • contents -- The body of the request. May be a string or a file-like object.
  • headers -- A dict of request headers and values.
  • decode_json -- If set True, the response body will be treated as JSON and decoded result returned instead of the raw contents.
  • stream -- If set True, the response body will return as a file-like object; otherwise, the response body will be read in its entirety and returned as a string. Overrides decode_json.
  • query -- A dict of query parameters and values to append to the path.
  • cdn -- If set True, the request will be sent to the CDN management endpoint instead of the default storage endpoint.
Returns:

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

status:An int for the HTTP status code.
reason:The str for the HTTP status (ex: "Ok").
headers:A dict with all lowercase keys of the HTTP headers; if a header has multiple values, it will be a list.
contents:Depending on the decode_json and stream settings, this will either be the raw response string, the JSON decoded object, or a file-like object.

reset()

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.

user_agent = None

The string to use for the User-Agent request header.

swiftly.client.directclient

Provides a direct client by using loaded Swift Proxy Server code to work with Swift.

class swiftly.client.directclient.DirectClient(swift_proxy=None, swift_proxy_storage_path=None, swift_proxy_cdn_path=None, attempts=5, eventlet=None, chunk_size=65536, verbose=None, verbose_id='', direct_object_ring=None)

Bases: swiftly.client.client.Client

Direct client by using loaded Swift Proxy Server code to work with Swift.

Parameters:
  • swift_proxy -- Default: None. If set, the swift.proxy.server.Application given will be used instead of creating a default Swift proxy application.
  • swift_proxy_storage_path -- The path to the Swift account to use (example: /v1/AUTH_test).
  • swift_proxy_cdn_path -- The path to the Swift account to use for CDN management (example: /v1/AUTH_test).
  • attempts -- The number of times to try requests if a server error occurs (5xx response). Default: 5
  • 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.
  • chunk_size -- Maximum size to read or write at one time.
  • 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.
  • direct_object_ring -- The path to custom object ring to used by the DirectClient
get_account_hash()

See swiftly.client.client.Client.get_account_hash()

request(method, path, contents, headers, decode_json=False, stream=False, query=None, cdn=False)

See swiftly.client.client.Client.request()

swiftly.client.localclient

A client that uses the local file system pretending to be Swift.

class swiftly.client.localclient.LocalClient(local_path=None, chunk_size=65536, verbose=None, verbose_id='')

Bases: swiftly.client.client.Client

A client that uses the local file system pretending to be Swift.

Note

This is a really early implementation and no-ops a lot of stuff. With time it will become a more complete representation.

Parameters:
  • local_path -- This is where the fake Swift will store its data. Default: Current working directory.
  • chunk_size -- Maximum size to read or write at one time.
  • 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.
get_account_hash()

See swiftly.client.client.Client.get_account_hash()

request(method, path, contents, headers, decode_json=False, stream=False, query=None, cdn=False)

See swiftly.client.client.Client.request()

swiftly.client.localclient.SUBS = [('_', '__'), ('.', '_.'), ('/', '_s'), ('\\', '_b'), (':', '_c'), ('*', '_S'), ("'", '_q'), ('"', '_d'), ('?', '_Q'), ('<', '_l'), ('>', '_g'), ('|', '_p')]

The list of strings in names to substitute for.

swiftly.client.localclient.lock_dir(*args, **kwds)

swiftly.client.localmemcache

Provides a local in-memory memcache client lookalike for use with Swift Proxy Server code. This can also be used as a WSGI app with the Brim.Net Core Package.

See swift.common.memcached.MemcacheRing for what this is acting as.

class swiftly.client.localmemcache.LocalMemcache(name=None, parsed_conf=None, next_app=None)

Bases: object

__call__(env, start_response)
decr(key, delta=1, timeout=0, time=0)
delete(key)
get(key)
get_multi(keys, server_key)
incr(key, delta=1, timeout=0, time=0)
classmethod parse_conf(name, conf)
set(key, value, serialize=True, timeout=0, time=0)
set_multi(mapping, server_key, serialize=True, timeout=0, time=0)

swiftly.client.manager

Contains the ClientManager class that can be used to manage a set of clients.

class swiftly.client.manager.ClientManager(client_class, *args, **kwargs)

Bases: object

Can be used to manage a set of clients.

Parameters:
  • client_class -- The class to create when a new client is needed.
  • args -- The args for the client constructor.
  • kwargs -- The keyword args for the client constructor.
get_client()

Obtains a client for use, whether an existing unused client or a brand new one if none are available.

put_client(client)

Returns a client back into the pool for availability to future calls to get_client. This should only be called if get_client was used to obtain the client; with_client is a context manager that does this for you.

with_client(*args, **kwds)

A context manager that obtains a client for use, whether an existing unused client or a brand new one if none are available.

swiftly.client.nulllogger

Provides a logger lookalike that throws away everything sent to it for use with Swift Proxy Server code.

See swift.common.utils.LogAdapter for what this is acting as.

class swiftly.client.nulllogger.NullLogger

Bases: object

client_ip = 'client_ip'
debug(*args, **kwargs)
error(*args, **kwargs)
exception(*args, **kwargs)
increment(*args, **kwargs)
set_statsd_prefix(*args, **kwargs)
thread_locals = 'thread_locals'
txn_id = 'txn_id'
warn(*args, **kwargs)
warning(*args, **kwargs)

swiftly.client.standardclient

Provides the standard client for accessing Swift services.

class swiftly.client.standardclient.StandardClient(auth_methods=None, auth_url=None, auth_tenant=None, auth_user=None, auth_key=None, auth_cache_path=None, region=None, snet=False, attempts=5, eventlet=None, chunk_size=65536, http_proxy=None, verbose=None, verbose_id='')

Bases: swiftly.client.client.Client

The standard client for accessing Swift services.

Parameters:
  • 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_url -- The URL to the auth system.
  • auth_tenant -- The tenant to authenticate as, if needed. Default (if needed): same as auth_user.
  • auth_user -- The user to authenticate as.
  • auth_key -- The key to use when authenticating.
  • auth_cache_path -- Default: None. If set to a path, the storage URL and auth token are cached in the file for reuse. If there are already cached values in the file, they are used without authenticating first.
  • region -- The region to access, if supported by auth (Example: DFW).
  • snet -- Uses the internalURL if Auth v2 is used or prepends "snet-" to the host name of the storage URL if Auth v1 is used. This is usually only useful when working with Rackspace Cloud Files and wanting to use Rackspace ServiceNet. Default: False.
  • attempts -- The number of times to try requests if a server error occurs (5xx response). Default: 5
  • 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.
  • chunk_size -- Maximum size to read or write at one time.
  • http_proxy -- The URL to the tunnelling HTTP proxy to use. Default: None.
  • 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()

See swiftly.client.client.Client.auth()

get_account_hash()

See swiftly.client.client.Client.get_account_hash()

request(method, path, contents, headers, decode_json=False, stream=False, query=None, cdn=False)

See swiftly.client.client.Client.request()

reset()

See swiftly.client.client.Client.reset()

swiftly.client.utils

Contains general tools useful when accessing Swift services.

swiftly.client.utils.generate_temp_url(method, url, seconds, key)

Returns a TempURL good for the given request method, url, and number of seconds from now, signed by the given key.

swiftly.client.utils.get_trans_id_time(trans_id)

Returns the time.time() embedded in the trans_id or None if no time information is embedded.

Copied from the Swift codebase. Copyright (c) 2010-2012 OpenStack Foundation

swiftly.client.utils.headers_to_dict(headers)

Converts a sequence of (name, value) tuples into a dict where if a given name occurs more than once its value in the dict will be a list of values.

swiftly.client.utils.quote(value, safe='/:')

Much like parse.quote in that it returns a URL encoded string for the given value, protecting the safe characters; but this version also ensures the value is UTF-8 encoded.

swiftly.concurrency

Concurrency API for Swiftly.

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.concurrency.Concurrency(concurrency=10)

Bases: object

Convenience class to support concurrency, if Eventlet is available; otherwise it just performs at single concurrency.

Parameters:concurrency -- The level of concurrency desired. Default: 10
get_results()

Returns a dict of the results currently available. The keys are the ident values given with the calls to spawn. The values are tuples of (exc_type, exc_value, exc_tb, result) where:

exc_type The type of any exception raised.
exc_value The actual exception if any was raised.
exc_tb The traceback if any exception was raised.
result If no exception was raised, this will be the return value of the called function.
join()

Blocks until all currently pending functions have finished.

spawn(ident, func, *args, **kwargs)

Returns immediately to the caller and begins executing the func in the background. Use get_results and the ident given to retrieve the results of the func. If the func causes an exception, this exception will be caught and the sys.exc_info() will be returned via get_results.

Parameters:
  • ident -- An identifier to find the results of the func from get_results. This identifier can be anything unique to the Concurrency instance.
  • func -- The function to execute concurrently.
  • args -- The args to give the func.
  • kwargs -- The keyword args to the give the func.
Returns:

None

swiftly.dencrypt

Encryption routines for Swiftly.

Requires PyCrypto 2.6.1 or greater. <https://www.dlitz.net/software/pycrypto/>

Copyright 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.

swiftly.dencrypt.AES256CBC = '\x00'

Constant that can be used a preamble for algorithm detection.

swiftly.dencrypt.aes_decrypt(key, stdin, chunk_size=65536)

Generator that decrypts a content stream using AES 256 in CBC mode.

Parameters:
  • key -- Any string to use as the decryption key.
  • stdin -- Where to read the encrypted data from.
  • chunk_size -- Largest amount to read at once.
swiftly.dencrypt.aes_encrypt(key, stdin, preamble=None, chunk_size=65536, content_length=None)

Generator that encrypts a content stream using AES 256 in CBC mode.

Parameters:
  • key -- Any string to use as the encryption key.
  • stdin -- Where to read the contents from.
  • preamble -- str to yield initially useful for providing a hint for future readers as to the algorithm in use.
  • chunk_size -- Largest amount to read at once.
  • content_length -- The number of bytes to read from stdin. None or < 0 indicates reading until EOF.

swiftly.filelikeiter

Wraps an iterable to behave as a file-like object.

Copyright (c) 2010-2012 OpenStack Foundation

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.filelikeiter.FileLikeIter(iterable, limit=None)

Bases: object

Wraps an iterable to behave as a file-like object.

Taken from work I did for OpenStack Swift swift.common.utils.FileLikeIter, Copyright (c) 2010-2012 OpenStack Foundation.

close() → None or (perhaps) an integer. Close the file.

Sets data attribute .closed to True. A closed file cannot be used for further I/O operations. close() may be called more than once without error. Some kinds of file objects (for example, opened by popen()) may return an exit status upon closing.

is_empty()

Check whether the "file" is empty reading the single byte.

read([size]) → read at most size bytes, returned as a string.

If the size argument is negative or omitted, read until EOF is reached. Notice that when in non-blocking mode, less data than what was requested may be returned, even if no size parameter was given.

readline([size]) → next line from the file, as a string.

Retain newline. A non-negative size argument limits the maximum number of bytes to return (an incomplete line may be returned then). Return an empty string at EOF.

readlines([size]) → list of strings, each a line from the file.

Call readline() repeatedly and return a list of the lines so read. The optional size argument, if given, is an approximate bound on the total number of bytes in the lines returned.

reset_limit()

Resets the limit.