FileUploadMixin

class FileUploadMixin

Bases: object

Methods Summary

delete_storage_file(storage_url)	Delete a stored file.
get_storage_file(storage_url)	Return the content of a stored file.
new_storage_file(bucket, data[, filename])	Store the content of a file in a storage bucket.
new_storage_file_from_name(bucket, filename)	Read a local file and store its content in a storage bucket.

Methods Documentation

delete_storage_file(storage_url)

Delete a stored file.

Parameters:

storage_url – Storage URL of the file to delete. The bucket it refers to has to be configured with enable_api = True, otherwise the request is rejected.

Returns:

An empty dictionary. A successful deletion is confirmed by the status code rather than by a response body, so treat the absence of an error as confirmation.

Raises:

• NotFoundError – If no file exists at storage_url.

• ClientError – If the bucket is configured with enable_api = False.

• UnknownError – If the bucket does not exist, or exists without an explicit enable_api setting, as localfile does.

Warning

Deleting a file from the newsletter bucket also removes its storage_url from the squirro_newsletter email template.

get_storage_file(storage_url)

Return the content of a stored file.

Reading is not restricted by the enable_api setting of the bucket, so a file can be read from any bucket.

Parameters:

storage_url – Storage URL of the file, as returned by new_storage_file(), for example storage://project_pictures/c4/36/a99c856defd26454/c436a99c856defd264541883519ad6a8eead80a6.

Returns:

The file content as bytes.

Raises:

• NotFoundError – If no file exists at storage_url.

• UnknownError – If the request fails for any other reason.

new_storage_file(bucket, data, filename=None)

Store the content of a file in a storage bucket.

For choosing a bucket, and for a walkthrough of storing, downloading, and deleting files, see the Upload and Manage Storage Files page.

Parameters:

• bucket – Name of the target storage bucket, for example project_pictures. Use the bare name: the storage_ prefix belongs to the section title in storage.ini only. The bucket has to be configured with enable_api = True, otherwise the request is rejected. The default bucket, localfile, is not configured for API access.

• data – Content to store, as bytes.

• filename – Name to store the file under. Applies only to a bucket configured with preserve_filename = True, and is ignored otherwise. Defaults to None, in which case Squirro assigns a generated name. The newsletter bucket is a special case: it ignores preserve_filename and stores the file under <content hash>_<filename>.

Returns:

A dictionary with a storage_url entry identifying the stored file, and an external_url entry giving the address it can be downloaded from. The form of external_url depends on the bucket, and it is None for a bucket that does not serve its files externally. For what it contains and how to handle it, see the Upload and Manage Storage Files page.

Raises:

• ClientError – If the bucket is configured with enable_api = False.

• UnknownError – If the bucket does not exist, or exists without an explicit enable_api setting, as localfile does.

Note

Uploads are not deduplicated. Storing the same content a second time creates a second entry under a new storage_url.

Warning

Storing a file in the newsletter bucket also writes the new storage_url into the squirro_newsletter email template, and does not report whether that write succeeded. delete_storage_file() removes it again.

Example:

>>> with open('project-logo.png', 'rb') as handle:
...     data = handle.read()
>>> client.new_storage_file('project_pictures', data)
{'storage_url': 'storage://project_pictures/c4/36/a99c856defd26454/c436a99c856defd264541883519ad6a8eead80a6',
 'external_url': '/storage/project_pictures/c4/36/a99c856defd26454/c436a99c856defd264541883519ad6a8eead80a6'}

new_storage_file_from_name(bucket, filename)

Read a local file and store its content in a storage bucket.

Parameters:

• bucket – Name of the target storage bucket. The same requirements as for new_storage_file() apply.

• filename – Path of the local file to read.

Returns:

A dictionary with storage_url and external_url entries, as returned by new_storage_file().

Raises:

ValueError – If filename does not exist.

Note

The name of the local file is not used as the stored file name. To choose the stored name on a bucket configured with preserve_filename = True, call new_storage_file() with an explicit filename argument instead.