pyrax
Python Bindings for the Rackspace Cloud
 All Classes Namespaces Files Functions Variables Properties
Public Member Functions | Public Attributes | Static Public Attributes | Properties
CFClient Class Reference

Wraps the calls to swiftclient with objects representing Containers and StorageObjects. More...

List of all members.

Public Member Functions

def __init__
def get_account_metadata
def set_account_metadata
 Accepts a dictionary of metadata key/value pairs and updates the specified account metadata with them.
def get_temp_url_key
 Returns the current TempURL key, or None if it has not been set.
def set_temp_url_key
 Sets the key for the Temporary URL for the account.
def get_temp_url
 Given a storage object in a container, returns a URL that can be used to access that object.
def delete_object_in_seconds
 Sets the object in the specified container to be deleted after the specified number of seconds.
def get_container_metadata
 Returns a dictionary containing the metadata for the container.
def set_container_metadata
 Accepts a dictionary of metadata key/value pairs and updates the specified container metadata with them.
def remove_container_metadata_key
 Removes the specified key from the container's metadata.
def get_container_cdn_metadata
 Returns a dictionary containing the CDN metadata for the container.
def set_container_cdn_metadata
 Accepts a dictionary of metadata key/value pairs and updates the specified container metadata with them.
def get_object_metadata
 Retrieves any metadata for the specified object.
def set_object_metadata
 Accepts a dictionary of metadata key/value pairs and updates the specified object metadata with them.
def remove_object_metadata_key
 Removes the specified key from the storage object's metadata.
def create_container
 Creates a container with the specified name.
def delete_container
 Deletes the specified container.
def delete_object
 Deletes the specified object from the container.
def get_object
 Returns a StorageObject instance for the object in the container.
def store_object
 Creates a new object in the specified container, and populates it with the given data.
def copy_object
 Copies the object to the new container, optionally giving it a new name.
def move_object
 Works just like copy_object, except that the source object is deleted after a successful copy.
def change_object_content_type
 Copies object to itself, but applies a new content-type.
def upload_file
 Uploads the specified file to the container.
def upload_folder
 Convenience method for uploading an entire folder, including any sub-folders, to Cloud Files.
def sync_folder_to_container
 Compares the contents of the specified folder, and checks to make sure that the corresponding object is present in the specified container.
def get_uploaded
 Returns the number of bytes uploaded for the specified process.
def cancel_folder_upload
 Cancels any folder upload happening in the background.
def fetch_object
 Fetches the object from storage.
def download_object
 Fetches the object from storage, and writes it to the specified directory.
def get_all_containers
def get_container
def get_container_objects
 Return a list of StorageObjects representing the objects in the container.
def get_container_object_names
def get_info
 Returns a tuple for the number of containers and total bytes in the account.
def list_containers
 Returns a list of all container names as strings.
def list_containers_info
 Returns a list of info on Containers.
def list_public_containers
 Returns a list of all CDN-enabled containers.
def make_container_public
 Enables CDN access for the specified container.
def make_container_private
 Disables CDN access to a container.
def set_cdn_log_retention
 Defer the logic to the container.
def get_container_streaming_uri
 Returns the URI for streaming content, or None if CDN is not enabled.
def get_container_ios_uri
 Returns the iOS URI, or None if CDN is not enabled.
def set_container_web_index_page
 Sets the header indicating the index page in a container when creating a static website.
def set_container_web_error_page
 Sets the header indicating the error page in a container when creating a static website.
def purge_cdn_object

Public Attributes

 connection
 cdn_connection

Static Public Attributes

string account_meta_prefix = "X-Account-Meta-"
string container_meta_prefix = "X-Container-Meta-"
string object_meta_prefix = "X-Object-Meta-"
string cdn_meta_prefix = "X-Cdn-"
 cdn_enabled = False
int default_cdn_ttl = 86400
int max_file_size = 5368709119
dictionary folder_upload_status = {}

Properties

 user_agent = property(_get_user_agent, _set_user_agent)
 http_log_debug

Detailed Description

Wraps the calls to swiftclient with objects representing Containers and StorageObjects.

These classes allow a developer to work with regular Python objects instead of calling functions that return primitive types.


Constructor & Destructor Documentation

def __init__ (   self,
  auth_endpoint,
  username,
  api_key = None,
  password = None,
  tenant_name = None,
  preauthurl = None,
  preauthtoken = None,
  auth_version = "2",
  os_options = None,
  verify_ssl = True,
  http_log_debug = False 
)

Member Function Documentation

def cancel_folder_upload (   self,
  upload_key 
)

Cancels any folder upload happening in the background.

If there is no such upload in progress, calling this method has no effect.

def change_object_content_type (   self,
  container,
  obj,
  new_ctype,
  guess = False,
  extra_info = None 
)

Copies object to itself, but applies a new content-type.

The guess feature requires the container to be CDN-enabled. If not then the content-type must be supplied. If using guess with a CDN-enabled container, new_ctype can be set to None. Failure during the put will result in a swift exception.

def copy_object (   self,
  container,
  obj,
  new_container,
  new_obj_name = None,
  extra_info = None 
)

Copies the object to the new container, optionally giving it a new name.

If you copy to the same container, you must supply a different name.

def create_container (   self,
  name,
  extra_info = None 
)

Creates a container with the specified name.

extra_info is an optional dictionary which will be populated with 'status', 'reason', and 'headers' keys from the underlying swiftclient call.

def delete_container (   self,
  container,
  del_objects = False,
  extra_info = None 
)

Deletes the specified container.

This will fail if the container still has objects stored in it; if that's the case and you want to delete the container anyway, set del_objects to True, and the container's objects will be deleted before the container is deleted.

extra_info is an optional dictionary which will be populated with 'status', 'reason', and 'headers' keys from the underlying swiftclient call.

def delete_object (   self,
  container,
  name,
  extra_info = None 
)

Deletes the specified object from the container.

extra_info is an optional dictionary which will be populated with 'status', 'reason', and 'headers' keys from the underlying swiftclient call.

def delete_object_in_seconds (   self,
  cont,
  obj,
  seconds,
  extra_info = None 
)

Sets the object in the specified container to be deleted after the specified number of seconds.

def download_object (   self,
  container,
  obj,
  directory,
  structure = True 
)

Fetches the object from storage, and writes it to the specified directory.

The directory must exist before calling this method.

If the object name represents a nested folder structure, such as "foo/bar/baz.txt", that folder structure will be created in the target directory by default. If you do not want the nested folders to be created, pass `structure=False` in the parameters.

def fetch_object (   self,
  container,
  obj,
  include_meta = False,
  chunk_size = None,
  extra_info = None 
)

Fetches the object from storage.

If 'include_meta' is False, only the bytes representing the file is returned.

Note: if 'chunk_size' is defined, you must fully read the object's contents before making another request.

When 'include_meta' is True, what is returned from this method is a 2-tuple: Element 0: a dictionary containing metadata about the file. Element 1: a stream of bytes representing the object's contents.

extra_info is an optional dictionary which will be populated with 'status', 'reason', and 'headers' keys from the underlying swiftclient call.

def get_account_metadata (   self)
def get_all_containers (   self,
  limit = None,
  marker = None,
  parms 
)
def get_container (   self,
  container 
)
def get_container_cdn_metadata (   self,
  container 
)

Returns a dictionary containing the CDN metadata for the container.

def get_container_ios_uri (   self,
  container 
)

Returns the iOS URI, or None if CDN is not enabled.

def get_container_metadata (   self,
  container 
)

Returns a dictionary containing the metadata for the container.

def get_container_object_names (   self,
  container,
  marker = None,
  limit = None,
  prefix = None,
  delimiter = None,
  full_listing = False 
)
def get_container_objects (   self,
  container,
  marker = None,
  limit = None,
  prefix = None,
  delimiter = None,
  full_listing = False 
)

Return a list of StorageObjects representing the objects in the container.

You can use the marker and limit params to handle pagination, and the prefix and delimiter params to filter the objects returned. Also, by default only the first 10,000 objects are returned; if you set full_listing to True, all objects in the container are returned.

def get_container_streaming_uri (   self,
  container 
)

Returns the URI for streaming content, or None if CDN is not enabled.

def get_info (   self)

Returns a tuple for the number of containers and total bytes in the account.

def get_object (   self,
  container,
  obj 
)

Returns a StorageObject instance for the object in the container.

def get_object_metadata (   self,
  container,
  obj 
)

Retrieves any metadata for the specified object.

def get_temp_url (   self,
  container,
  obj,
  seconds,
  method = "GET" 
)

Given a storage object in a container, returns a URL that can be used to access that object.

The URL will expire after `seconds` seconds.

The only methods supported are GET and PUT. Anything else will raise an InvalidTemporaryURLMethod exception.

def get_temp_url_key (   self)

Returns the current TempURL key, or None if it has not been set.

def get_uploaded (   self,
  upload_key 
)

Returns the number of bytes uploaded for the specified process.

def list_containers (   self,
  limit = None,
  marker = None,
  parms 
)

Returns a list of all container names as strings.

def list_containers_info (   self,
  limit = None,
  marker = None,
  parms 
)

Returns a list of info on Containers.

For each container, a dict containing the following keys is returned:

             name - the name of the container
             count - the number of objects in the container
             bytes - the total bytes in the container
def list_public_containers (   self)

Returns a list of all CDN-enabled containers.

def make_container_private (   self,
  container 
)

Disables CDN access to a container.

It may still appear public until its TTL expires.

def make_container_public (   self,
  container,
  ttl = None 
)

Enables CDN access for the specified container.

def move_object (   self,
  container,
  obj,
  new_container,
  new_obj_name = None 
)

Works just like copy_object, except that the source object is deleted after a successful copy.

def purge_cdn_object (   self,
  container,
  name,
  email_addresses = None 
)
def remove_container_metadata_key (   self,
  container,
  key,
  extra_info = None 
)

Removes the specified key from the container's metadata.

If the key does not exist in the metadata, nothing is done.

def remove_object_metadata_key (   self,
  container,
  obj,
  key 
)

Removes the specified key from the storage object's metadata.

If the key does not exist in the metadata, nothing is done.

def set_account_metadata (   self,
  metadata,
  clear = False,
  extra_info = None 
)

Accepts a dictionary of metadata key/value pairs and updates the specified account metadata with them.

If 'clear' is True, any existing metadata is deleted and only the passed metadata is retained. Otherwise, the values passed here update the account's metadata.

extra_info is an optional dictionary which will be populated with 'status', 'reason', and 'headers' keys from the underlying swiftclient call.

def set_cdn_log_retention (   self,
  container,
  enabled 
)

Defer the logic to the container.

It will end up calling _set_cdn_log_retention() to change it on Cloud Files.

def set_container_cdn_metadata (   self,
  container,
  metadata 
)

Accepts a dictionary of metadata key/value pairs and updates the specified container metadata with them.

NOTE: arbitrary metadata headers are not allowed. The only metadata you can update are: X-Log-Retention, X-CDN-enabled, and X-TTL.

def set_container_metadata (   self,
  container,
  metadata,
  clear = False,
  extra_info = None 
)

Accepts a dictionary of metadata key/value pairs and updates the specified container metadata with them.

If 'clear' is True, any existing metadata is deleted and only the passed metadata is retained. Otherwise, the values passed here update the container's metadata.

extra_info is an optional dictionary which will be populated with 'status', 'reason', and 'headers' keys from the underlying swiftclient call.

def set_container_web_error_page (   self,
  container,
  page 
)

Sets the header indicating the error page in a container when creating a static website.

Note: the container must be CDN-enabled for this to have any effect.

def set_container_web_index_page (   self,
  container,
  page 
)

Sets the header indicating the index page in a container when creating a static website.

Note: the container must be CDN-enabled for this to have any effect.

def set_object_metadata (   self,
  container,
  obj,
  metadata,
  clear = False,
  extra_info = None 
)

Accepts a dictionary of metadata key/value pairs and updates the specified object metadata with them.

If 'clear' is True, any existing metadata is deleted and only the passed metadata is retained. Otherwise, the values passed here update the object's metadata.

extra_info is an optional dictionary which will be populated with 'status', 'reason', and 'headers' keys from the underlying swiftclient call.

def set_temp_url_key (   self,
  key = None 
)

Sets the key for the Temporary URL for the account.

It should be a key that is secret to the owner.

If no key is provided, a UUID value will be generated and used. It can later be obtained by calling get_temp_url_key().

def store_object (   self,
  container,
  obj_name,
  data,
  content_type = None,
  etag = None,
  content_encoding = None,
  ttl = None,
  return_none = False,
  extra_info = None 
)

Creates a new object in the specified container, and populates it with the given data.

A StorageObject reference to the uploaded file will be returned, unless 'return_none' is set to True.

extra_info is an optional dictionary which will be populated with 'status', 'reason', and 'headers' keys from the underlying swiftclient call.

def sync_folder_to_container (   self,
  folder_path,
  container,
  delete = False,
  include_hidden = False,
  ignore = None,
  ignore_timestamps = False 
)

Compares the contents of the specified folder, and checks to make sure that the corresponding object is present in the specified container.

If there is no remote object matching the local file, it is created. If a matching object exists, the etag is examined to determine if the object in the container matches the local file; if they differ, the container is updated with the local file if the local file is newer when `ignore_timestamps' is False (default). If `ignore_timestamps` is True, the object is overwritten with the local file contents whenever the etags differ. NOTE: the timestamp of a remote object is the time it was uploaded, not the original modification time of the file stored in that object. Unless 'include_hidden' is True, files beginning with an initial period are ignored.

If the 'delete' option is True, any objects in the container that do not have corresponding files in the local folder are deleted.

You can selectively ignore files by passing either a single pattern or a list of patterns; these will be applied to the individual folder and file names, and any names that match any of the 'ignore' patterns will not be uploaded. The patterns should be standard *nix-style shell patterns; e.g., '*pyc' will ignore all files ending in 'pyc', such as 'program.pyc' and 'abcpyc'.

def upload_file (   self,
  container,
  file_or_path,
  obj_name = None,
  content_type = None,
  etag = None,
  return_none = False,
  content_encoding = None,
  ttl = None,
  extra_info = None,
  content_length = None 
)

Uploads the specified file to the container.

If no name is supplied, the file's name will be used. Either a file path or an open file-like object may be supplied. A StorageObject reference to the uploaded file will be returned, unless 'return_none' is set to True.

You may optionally set the `content_type` and `content_encoding` parameters; pyrax will create the appropriate headers when the object is stored.

If the size of the file is known, it can be passed as `content_length`.

If you wish for the object to be temporary, specify the time it should be stored in seconds in the `ttl` parameter. If this is specified, the object will be deleted after that number of seconds. Returns the size of a file-like object.

def upload_folder (   self,
  folder_path,
  container = None,
  ignore = None,
  ttl = None 
)

Convenience method for uploading an entire folder, including any sub-folders, to Cloud Files.

All files will be uploaded to objects with the same name as the file. In the case of nested folders, files will be named with the full path relative to the base folder. E.g., if the folder you specify contains a folder named 'docs', and 'docs' contains a file named 'install.html', that file will be uploaded to an object named 'docs/install.html'.

If 'container' is specified, the folder's contents will be uploaded to that container. If it is not specified, a new container with the same name as the specified folder will be created, and the files uploaded to this new container.

You can selectively ignore files by passing either a single pattern or a list of patterns; these will be applied to the individual folder and file names, and any names that match any of the 'ignore' patterns will not be uploaded. The patterns should be standard *nix-style shell patterns; e.g., '*pyc' will ignore all files ending in 'pyc', such as 'program.pyc' and 'abcpyc'.

The upload will happen asynchronously; in other words, the call to upload_folder() will generate a UUID and return a 2-tuple of (UUID, total_bytes) immediately. Uploading will happen in the background; your app can call get_uploaded(uuid) to get the current status of the upload. When the upload is complete, the value returned by get_uploaded(uuid) will match the total_bytes for the upload.

If you start an upload and need to cancel it, call cancel_folder_upload(uuid), passing the uuid returned by the initial call. It will then be up to you to either keep or delete the partially-uploaded content.

If you specify a `ttl` parameter, the uploaded files will be deleted after that number of seconds.


Member Data Documentation

string account_meta_prefix = "X-Account-Meta-" [static]
cdn_enabled = False [static]
string cdn_meta_prefix = "X-Cdn-" [static]
string container_meta_prefix = "X-Container-Meta-" [static]
int default_cdn_ttl = 86400 [static]
dictionary folder_upload_status = {} [static]
int max_file_size = 5368709119 [static]
string object_meta_prefix = "X-Object-Meta-" [static]

Property Documentation

http_log_debug [static]
Initial value:
property(_get_http_log_debug, _set_http_log_debug, None,
            "Determines if all http traffic is logged to the display "
            "for debugging.")
user_agent = property(_get_user_agent, _set_user_agent) [static]

The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Properties