pyrax
Python Bindings for the Rackspace Cloud
 All Classes Namespaces Files Functions Variables Properties
Classes | Functions | Variables
pyrax::utils Namespace Reference

Classes

class  SelfDeletingTempfile
 Convenience class for dealing with temporary files. More...
class  SelfDeletingTempDirectory
 Convenience class for dealing with temporary folders and the files within them. More...
class  _WaitThread
 Threading class to wait for object status in the background. More...

Functions

def runproc
 Convenience method for executing operating system commands.
def get_checksum
 Returns the MD5 checksum in hex for the given content.
def random_name
 Generates a random name; useful for testing.
def coerce_string_to_list
 For parameters that can take either a single string or a list of strings, this function will ensure that the result is a list containing the passed values.
def folder_size
 Returns the total bytes for the specified path, optionally ignoring any files which match the 'ignore' parameter.
def add_method
 Adds an instance method to an object.
def wait_until
 When changing the state of an object, it will commonly be in a transitional state until the change is complete.
def wait_for_build
 Designed to handle the most common use case for wait_until: an object whose 'status' attribute will end up in either 'ACTIVE' or 'ERROR' state.
def iso_time_string
 Takes either a date, datetime or a string, and returns the standard ISO formatted string for that date/time, with any fractional second portion removed.
def to_timestamp
 Takes a value that is either a Python date, datetime, or a string representation of a date/datetime value.
def get_id
 Returns the 'id' attribute of 'id_or_obj' if present; if not, returns 'id_or_obj'.
def get_name
 Returns the 'name' attribute of 'name_or_obj' if present; if not, returns 'name_or_obj'.
def params_to_dict
 Given a set of optional parameter names, constructs a dictionary with the parameter name as the key, and the value for that key in the local_dict as the value, for all non-None values.
def match_pattern
 Compares `nm` with the supplied patterns, and returns True if it matches at least one.
def update_exc
 Adds additional text to an exception's error message.
def env
 Returns the first environment variable set if none are non-empty, defaults to "" or keyword arg default.
def unauthenticated
 Adds 'unauthenticated' attribute to decorated function.
def isunauthenticated
 Checks to see if the function is marked as not requiring authentication with the decorator.
def safe_issubclass
 Like issubclass, but will just return False if not a class.
def import_class
 Returns a class from a string including module and class.
def slugify
 Normalizes string, converts to lowercase, removes non-alpha characters, and converts spaces to hyphens.

Variables

 trace = pudb.set_trace

Function Documentation

def pyrax.utils.add_method (   obj,
  func,
  name = None 
)

Adds an instance method to an object.

For parameters that can take either a single string or a list of strings, this function will ensure that the result is a list containing the passed values.

def pyrax.utils.env (   args,
  kwargs 
)

Returns the first environment variable set if none are non-empty, defaults to "" or keyword arg default.

def pyrax.utils.folder_size (   pth,
  ignore = None 
)

Returns the total bytes for the specified path, optionally ignoring any files which match the 'ignore' parameter.

'ignore' can either be a single string pattern, or a list of such patterns.

def pyrax.utils.get_checksum (   content,
  encoding = "utf8",
  block_size = 8192 
)

Returns the MD5 checksum in hex for the given content.

If 'content' is a file-like object, the content will be obtained from its read() method. If 'content' is a file path, that file is read and its contents used. Otherwise, 'content' is assumed to be the string whose checksum is desired. If the content is unicode, it will be encoded using the specified encoding.

To conserve memory, files and file-like objects will be read in blocks, with the default block size of 8192 bytes, which is 64 * the digest block size of md5 (128). This is optimal for most cases, but you can change this by passing in a different value for `block_size`.

def pyrax.utils.get_id (   id_or_obj)

Returns the 'id' attribute of 'id_or_obj' if present; if not, returns 'id_or_obj'.

def pyrax.utils.get_name (   name_or_obj)

Returns the 'name' attribute of 'name_or_obj' if present; if not, returns 'name_or_obj'.

def pyrax.utils.import_class (   import_str)

Returns a class from a string including module and class.

def pyrax.utils.iso_time_string (   val,
  show_tzinfo = False 
)

Takes either a date, datetime or a string, and returns the standard ISO formatted string for that date/time, with any fractional second portion removed.

Checks to see if the function is marked as not requiring authentication with the decorator.

Returns True if decorator is set to True, False otherwise.

def pyrax.utils.match_pattern (   nm,
  patterns 
)

Compares `nm` with the supplied patterns, and returns True if it matches at least one.

Patterns are standard file-name wildcard strings, as defined in the `fnmatch` module. For example, the pattern "*.py" will match the names of all Python scripts.

def pyrax.utils.params_to_dict (   params,
  dct,
  local_dict 
)

Given a set of optional parameter names, constructs a dictionary with the parameter name as the key, and the value for that key in the local_dict as the value, for all non-None values.

def pyrax.utils.random_name (   length = 20,
  ascii_only = False 
)

Generates a random name; useful for testing.

By default it will return an encoded string containing unicode values up to code point 1000. If you only need or want ASCII values, pass True to the ascii_only parameter.

def pyrax.utils.runproc (   cmd)

Convenience method for executing operating system commands.

Accepts a single string that would be the command as executed on the command line.

Returns a 2-tuple consisting of the output of (STDOUT, STDERR). In your code you should check for an empty STDERR output to determine if your command completed successfully.

Like issubclass, but will just return False if not a class.

def pyrax.utils.slugify (   value)

Normalizes string, converts to lowercase, removes non-alpha characters, and converts spaces to hyphens.

From Django's "django/template/defaultfilters.py".

def pyrax.utils.to_timestamp (   val)

Takes a value that is either a Python date, datetime, or a string representation of a date/datetime value.

Returns a standard Unix timestamp corresponding to that value.

Adds 'unauthenticated' attribute to decorated function.

Usage: def mymethod(fnc): ...

def pyrax.utils.update_exc (   exc,
  msg,
  before = True,
  separator = "\n" 
)

Adds additional text to an exception's error message.

The new text will be added before the existing text by default; to append it after the original text, pass False to the `before` parameter.

By default the old and new text will be separated by a newline. If you wish to use a different separator, pass that as the `separator` parameter.

def pyrax.utils.wait_for_build (   obj,
  att = None,
  desired = None,
  callback = None,
  interval = None,
  attempts = None,
  verbose = None,
  verbose_atts = None 
)

Designed to handle the most common use case for wait_until: an object whose 'status' attribute will end up in either 'ACTIVE' or 'ERROR' state.

Since builds don't happen very quickly, the interval will default to 20 seconds to avoid excess polling.

def pyrax.utils.wait_until (   obj,
  att,
  desired,
  callback = None,
  interval = 5,
  attempts = 0,
  verbose = False,
  verbose_atts = None 
)

When changing the state of an object, it will commonly be in a transitional state until the change is complete.

This will reload the object every `interval` seconds, and check its `att` attribute until the `desired` value is reached, or until the maximum number of attempts is reached. The updated object is returned. It is up to the calling program to check the returned object to make sure that it successfully reached the desired state.

Once the desired value of the attribute is reached, the method returns. If not, it will re-try until the attribute's value matches one of the `desired` values. By default (attempts=0) it will loop infinitely until the attribute reaches the desired value. You can optionally limit the number of times that the object is reloaded by passing a positive value to `attempts`. If the attribute has not reached the desired value by then, the method will exit.

If `verbose` is True, each attempt will print out the current value of the watched attribute and the time that has elapsed since the original request. Also, if `verbose_atts` is specified, the values of those attributes will also be output. If `verbose` is False, then `verbose_atts` has no effect.

Note that `desired` can be a list of values; if the attribute becomes equal to any of those values, this will succeed. For example, when creating a new cloud server, it will initially have a status of 'BUILD', and you can't work with it until its status is 'ACTIVE'. However, there might be a problem with the build process, and the server will change to a status of 'ERROR'. So for this case you need to set the `desired` parameter to `['ACTIVE', 'ERROR']`. If you simply pass 'ACTIVE' as the desired state, this will loop indefinitely if a build fails, as the server will never reach a status of 'ACTIVE'.

Since this process of waiting can take a potentially long time, and will block your program's execution until the desired state of the object is reached, you may specify a callback function. The callback can be any callable that accepts a single parameter; the parameter it receives will be either the updated object (success), or None (failure). If a callback is specified, the program will return immediately after spawning the wait process in a separate thread.


Variable Documentation

trace = pudb.set_trace
 All Classes Namespaces Files Functions Variables Properties