API Reference¶

GoogleStorage¶

class flask_googlestorage.GoogleStorage(*buckets: Tuple[Bucket, ...], app: Flask | None = None)¶

This is the main extension class. Typically you should create one instance per application passing your defined buckets (instances of flask_googlestorage.Bucket). Make sure you call init_app() before start using your buckets. If the application instance is given at creation time, init_app() is called for you.

init_app(app: Flask)¶

Initialize the extension for the given flask.Flask application instance

Parameters:: app – The application instance

Buckets¶

class flask_googlestorage.Bucket(name: str, allows: Callable | None = None)¶

This class represents a bucket of files with either local or cloud storage under the hood.

Parameters:

name – The name for the bucket.
allows – An optional callable to decide whether a given file is allowed in this bucket or not. If given it will be called passing the file to be saved and the secured path to be used.

allows(file_storage: FileStorage, path: PurePath) → bool¶

Returns whether the given file is allowed in this bucket. By default, all files are allowed unless you create the bucket passing the allows parameter. In that case, it returns the value returned by such a callable.

Parameters:

file_storage – The file to be saved.
path – The secured path where to be used.

Returns:

Whether the file is allowed in this bucket or not.

delete(filename: str)¶

Delete the file with the given name if it exists.

Parameters:: name – The name of the file to be deleted.

name¶: The name of this bucket

save(file_storage: FileStorage, name: str | None = None, public: bool = False, uuid_name: bool = True) → PurePath¶

Save the given file in this bucket and returns its relative path

Parameters:

storage – The file to be saved.
name – The relative path to be used. It could contain nested folders to be created. This name will be passed to flask_googlestorage.utils.secure_path() to ensure it’s safe to use it or to get a secure version of it. If not given, either a UUID name or the original filename (or a secure version of it) will be used.
public – Whether to make the uploaded file publicly available or not.
uuid_name – If set to True and name is not give a UUID name is preferred over the original filename.

Returns:

The relative path where the file was saved.

Raises:

TypeError – If the given file is not an instance of werkzeug.datastructures.FileStorage.
NotAllowedUploadError – If the given file is not allowed in this bucket.

signed_url(filename: str) → str¶

Returns the signed URL returned by the current storage object.

Parameters:: name – The name of the file to be downloaded from the bucket
Returns:: The signed URL to download the file.

property storage: LocalBucket | CloudBucket¶

Returns either self._storage or the storage object for this bucket from the extension state for the current application instance.

Returns:: The current configured storage for this bucket

storage_ctx(storage: LocalBucket | CloudBucket)¶

Context manager to set the given storage object as the current storage for this bucket. Note that is your responsability to set a storage object that implements the required API. This is particulary useful for testing:

bucket = Bucket("files")
with bucket.storage_ctx(mock.MagicMock()) as storage_mock:
    assert bucket.storage is storage_mock
    bucket.save(file_storage)

storage_mock.save.assert_called_once()

Parameters:: storage – The storage object to be set
Yields:: The current being set

url(filename: str) → str¶

Returns the public URL returned by the current storage object.

Parameters:: name – The name of the file to be downloaded from the bucket
Returns:: The public URL to download the file.

class flask_googlestorage.LocalBucket(name: str, destination: Path, resolve_conflicts: bool = False)¶

This class represents a local bucket and is mainly used for temporary storage before uploading to Google Cloud Storage. However, if the authentication with Google Cloud Storage fails or the bucket id is not found, this class provides local storage. This is particularly useful in development.

Parameters:

name – The name for this bucket.
destination – The absolute path to use for local storage.
resolve_conflicts – Whether to resolve name conflicts or not.

delete(filename: str)¶

Delete the file with the given filename if it exists.

Parameters:: filename – The name of the file to be deleted.

destination¶: The destination root path of this bucket

name¶: The name of this bucket

resolve_conflicts¶: Whether to resolve name conflicts or not

save(storage: FileStorage, path: PurePath, **kwargs) → PurePath¶

Save the given file in this bucket and returns its relative path

Parameters:

storage – The file to be saved
path – The relative path where to save the file in this bucket. It will be modified in case of conflicts if flask_googlestorage.LocalBucket.resolve_conflicts is set to True. Note that the path should be secured beforehand. You may use flask_googlestorage.utils.secure_path() for this.

Returns:

The relative path where the file was saved. You may use this value to get the URL or delete the file later.

signed_url(filename: str) → str¶

Returns the URL served by the flask.Flask application.

Parameters:: filename – The filename to be downloaded from the bucket.
Returns:: The URL to download the file.

url(filename: str) → str¶

Returns the URL served by the flask.Flask application.

Parameters:: filename – The filename to be downloaded from the bucket.
Returns:: The URL to download the file.

class flask_googlestorage.CloudBucket(name: str, bucket: Bucket, destination: Path, resolve_conflicts: bool = False, delete_local: bool = True, signature: dict | None = None, tenacity: dict | None = None)¶

This class represents a bucket in Google Cloud Storage. Apart from the google.cloud.storage.Bucket instance, it takes all the arguments required and accepted by flask_googlestorage.LocalBucket in order to create a local bucket for temporary storage. Uploaded files will be first saved locally using the local bucket and then uploaded to the cloud.

Parameters:

name – The name for the local bucket.
bucket – The bucket instance.
destination – The absolute path to use for local storage.
resolve_conflicts – Whether to resolve name conflicts or not when saving locally.
delete_local – Whether to delete local files after uploading to the cloud.
signature – A dictionary specifying the keyword arguments for building the signed url using google.cloud.storage.blob.Blob.generate_signed_url().
tenaicy – A dictionary specifying the keyword arguments for the tenacity.retry() decorator.

bucket¶: The google.cloud.storage.Bucket instance.

delete(name: str)¶

Delete the blob with the given name if it exists.

Parameters:: name – The name of the blob to be deleted.

delete_local¶: Whether to delete local files after uploading to the cloud.

get_blob(name: str) → Blob¶

Get a google.cloud.storage.blob.Blob instance by name.

Parameters:: name – The blob name.
Returns:: The google.cloud.storage.blob.Blob instance.

local¶: The flask_googlestorage.LocalBucket instance used for temporary storage.

save(storage: FileStorage, path: PurePath, public: bool = False) → PurePath¶

Save the given file in this bucket and returns its relative path

Parameters:

storage – The file to be saved.
path – The relative path where to save the file in this bucket. It may be modified when calling flask_googlestorage.LocalBucket.save(). Note that the path should be secured beforehand. You may use flask_googlestorage.utils.secure_path() for this.
public – Whether to make the uploaded file publicly available or not.

Returns:

The relative path where the file was saved.

signature¶: Keyword arguments passed to google.cloud.storage.blob.Blob.generate_signed_url()

signed_url(name: str) → str¶

Returns the signed URL served by Google Cloud Storage. Use either GOOGLE_STORAGE_SIGNATURE (for all buckets) or GOOGLE_STORAGE_X_SIGNATURE (for bucket X) to configure the arguments passed to google.cloud.storage.blob.Blob.generate_signed_url().

Parameters:: name – The blob name to be downloaded from the bucket
Returns:: The signed URL to download the file.

tenacity¶: Keyword arguments passed to tenacity.retry().

url(name: str) → str¶

Returns the public URL served by Google Cloud Storage. The blob should be publicly available in order to actually use this URL.

Parameters:: name – The blob name to be downloaded from the bucket
Returns:: The public URL to download the file.

Utils¶

flask_googlestorage.utils.get_state(app: Flask) → dict¶

Gets the extension state for the given application

Parameters:: app – The application instance
Returns:: The extension state for the given application

flask_googlestorage.utils.secure_path(filename: str, name: str | None = None, uuid_name: bool = True) → PurePath¶

This is a helper used by flask_googlestorage.Bucket.save() to get a secured path. with the file extension in lower case.

Parameters:

filename – The original filename.
name – A name preferred over the original filename which could contain nested folders.
uuid_name – If set to True a UUID name is preferred over the original filename.

Returns:

A secured filename with the extension in lower case

Exceptions¶

exception flask_googlestorage.exceptions.NotAllowedUploadError¶: This exception is raised if the upload file is not allowed in the bucket.

exception flask_googlestorage.exceptions.NotFoundBucketError¶: This exception is raised is the user reads a bucket not configured in the current application

exception flask_googlestorage.exceptions.NotFoundDestinationError¶: This exception is raised if the GOOGLE_STORAGE_LOCAL_DEST configuration variable is unset

API Reference¶

GoogleStorage¶

Buckets¶

Utils¶

Exceptions¶

Contents

Navigation