Cloud Storage reference¶
At a glance¶
Storage.storage(url=None):reference(),reference_with_path(path),reference_for_url(url),use_emulator(host, port),max_upload_retry_time,max_download_retry_time,max_operation_retry_timeStorageReference:full_path,name,bucket,gs_url,storage,root(),parent(),child(path);put_data(data, content_type, callback, *, metadata),put_file(path, ...)→StorageUploadTask;get_data(max_size, cb),write_to_file(path, cb)→StorageDownloadTask;download_url(cb),get_metadata(cb),update_metadata(metadata, cb),list_all(cb),list(max_results, cb, page_token),delete(cb)StorageMetadata(content_type, cache_control, content_disposition, content_encoding, content_language, custom_metadata); read-onlybucket,path,name,size,md5_hash,generation,metageneration,time_created,updated,is_file,gs_urlStorageTask(StorageUploadTask,StorageDownloadTask):observe(status, handler),remove_observer(handle),pause(),resume(),cancel(),snapshotStorageTaskSnapshot:status,bytes_transferred,total_bytes,fraction_completed,metadata,error,reference;StorageTaskStatusStorageListResult(items,prefixes,page_token),StorageError(name),StorageErrorCode
pyios_firebase.storage¶
Cloud Storage for Firebase: upload and download files.
from pyios_firebase.storage import Storage, StorageMetadata, StorageTaskStatus
ref = Storage.storage().reference().child(f"users/{uid}/avatar.jpg")
task = ref.put_file("/path/to/avatar.jpg", "image/jpeg", callback=on_uploaded)
task.observe(StorageTaskStatus.PROGRESS, lambda s: print(f"{s.fraction_completed:.0%}"))
ref.download_url(lambda url, error: ...)
Callbacks get Python values and a StorageError (or None).
Needs the FirebaseStorage framework.
Modules:
| Name | Description |
|---|---|
errors |
Cloud Storage errors. |
metadata |
|
reference |
|
storage |
|
task |
Upload and download tasks: progress, pause, resume and cancel. |
Classes:
| Name | Description |
|---|---|
Storage |
Cloud Storage for one bucket. Get it with |
StorageError |
An error from Cloud Storage. |
StorageErrorCode |
The |
StorageMetadata |
A file's metadata. |
StorageListResult |
One page of |
StorageReference |
Points to a file or folder in Cloud Storage. Nothing is read or written |
StorageDownloadTask |
A running download. |
StorageTask |
A running upload or download. Upload and download methods give one back. |
StorageTaskSnapshot |
A task's state at one moment. |
StorageTaskStatus |
What happened to a task: pass one to |
StorageUploadTask |
A running upload. |
Attributes:
| Name | Type | Description |
|---|---|---|
STORAGE_ERROR_DOMAIN |
Final
|
The |
STORAGE_ERROR_DOMAIN
module-attribute
¶
The error.domain of Cloud Storage errors.
Storage
¶
Storage(native: ObjCObject)
Cloud Storage for one bucket. Get it with Storage.storage().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
native
|
ObjCObject
|
the native |
required |
Methods:
| Name | Description |
|---|---|
storage |
The shared |
reference |
The root of the bucket. |
reference_with_path |
A reference by path in this bucket. |
reference_for_url |
A reference from a file's URL. |
use_emulator |
Send this bucket's requests to the local Storage emulator. Call it |
Attributes:
| Name | Type | Description |
|---|---|---|
native |
ObjCObject
|
The |
max_upload_retry_time |
float
|
Seconds an upload keeps retrying before it fails (default 600). |
max_download_retry_time |
float
|
Seconds a download keeps retrying before it fails (default 600). |
max_operation_retry_time |
float
|
Seconds other operations (metadata, delete, list) keep retrying (default 120). |
max_upload_retry_time
property
writable
¶
Seconds an upload keeps retrying before it fails (default 600).
max_download_retry_time
property
writable
¶
Seconds a download keeps retrying before it fails (default 600).
max_operation_retry_time
property
writable
¶
Seconds other operations (metadata, delete, list) keep retrying (default 120).
storage
classmethod
¶
storage(url: str | None = None) -> Storage
The shared Storage for a bucket.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
str | None
|
a bucket URL such as |
None
|
Returns:
| Type | Description |
|---|---|
Storage
|
The same |
reference_with_path
¶
reference_with_path(path: str) -> StorageReference
A reference by path in this bucket.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
the path, for example |
required |
Returns:
| Type | Description |
|---|---|
StorageReference
|
A |
reference_for_url
¶
reference_for_url(url: str) -> StorageReference
A reference from a file's URL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
str
|
a |
required |
Returns:
| Type | Description |
|---|---|
StorageReference
|
A |
use_emulator
¶
Send this bucket's requests to the local Storage emulator. Call it before any other use; only in development and test builds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
str
|
the emulator's host. |
'127.0.0.1'
|
port
|
int
|
the emulator's port ( |
9199
|
StorageError
¶
Bases: FirebaseError
An error from Cloud Storage.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The |
name
instance-attribute
¶
The StorageErrorCode name of code (for example
"OBJECT_NOT_FOUND"), or "" for errors from other domains.
StorageErrorCode
¶
The error.code values of Cloud Storage errors (FIRStorageErrorCode).
Attributes:
| Name | Type | Description |
|---|---|---|
OBJECT_NOT_FOUND |
Final
|
No file at that path. |
UNAUTHENTICATED |
Final
|
The rules need a signed-in user. |
UNAUTHORIZED |
Final
|
The security rules do not allow this. |
RETRY_LIMIT_EXCEEDED |
Final
|
The operation kept failing for longer than the max retry time. |
DOWNLOAD_SIZE_EXCEEDED |
Final
|
The file is bigger than |
CANCELLED |
Final
|
The task was cancelled. |
OBJECT_NOT_FOUND
class-attribute
instance-attribute
¶
No file at that path.
UNAUTHENTICATED
class-attribute
instance-attribute
¶
The rules need a signed-in user.
UNAUTHORIZED
class-attribute
instance-attribute
¶
The security rules do not allow this.
RETRY_LIMIT_EXCEEDED
class-attribute
instance-attribute
¶
The operation kept failing for longer than the max retry time.
DOWNLOAD_SIZE_EXCEEDED
class-attribute
instance-attribute
¶
The file is bigger than max_size in get_data.
StorageMetadata
¶
StorageMetadata(
content_type: str | None = None,
cache_control: str | None = None,
content_disposition: str | None = None,
content_encoding: str | None = None,
content_language: str | None = None,
custom_metadata: Mapping[str, str] | None = None,
*,
native: ObjCObject | None = None,
)
A file's metadata.
Make one to upload with, or get one from an upload, get_metadata or
update_metadata. The settable fields can be changed and passed to
StorageReference.update_metadata; set one to None to delete it.
::
metadata = StorageMetadata(content_type="image/jpeg", custom_metadata={"owner": uid})
ref.put_data(jpeg_bytes, metadata=metadata)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content_type
|
str | None
|
the MIME type, for example |
None
|
cache_control
|
str | None
|
the |
None
|
content_disposition
|
str | None
|
the |
None
|
content_encoding
|
str | None
|
the |
None
|
content_language
|
str | None
|
the |
None
|
custom_metadata
|
Mapping[str, str] | None
|
your own string keys and values. |
None
|
native
|
ObjCObject | None
|
a native |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
custom_metadata |
dict[str, str]
|
Your own string keys and values (a copy: assign a new dict to change it). |
native |
ObjCObject
|
The |
content_type |
str | None
|
The MIME type, for example |
cache_control |
str | None
|
The |
content_disposition |
str | None
|
The |
content_encoding |
str | None
|
The |
content_language |
str | None
|
The |
bucket |
str | None
|
The bucket, for example |
path |
str | None
|
The file's full path in the bucket. |
name |
str | None
|
The last part of the path. |
size |
int
|
The size in bytes. |
md5_hash |
str | None
|
The MD5 hash of the content (base64), or |
generation |
int
|
The content's version: changes each time the file is replaced. |
metageneration |
int
|
The metadata's version: changes each time the metadata is updated. |
time_created |
datetime | None
|
When the file was created (UTC). |
updated |
datetime | None
|
When the file or its metadata last changed (UTC). |
is_file |
bool
|
True for a file. |
gs_url |
str
|
The |
custom_metadata
property
writable
¶
Your own string keys and values (a copy: assign a new dict to change it).
cache_control
property
writable
¶
The Cache-Control header served with the file.
content_disposition
property
writable
¶
The Content-Disposition header served with the file.
content_encoding
property
writable
¶
The Content-Encoding header served with the file.
content_language
property
writable
¶
The Content-Language header served with the file.
generation
property
¶
The content's version: changes each time the file is replaced.
metageneration
property
¶
The metadata's version: changes each time the metadata is updated.
StorageListResult
dataclass
¶
StorageListResult(
items: list[StorageReference],
prefixes: list[StorageReference],
page_token: str | None,
)
One page of StorageReference.list / list_all.
Methods:
| Name | Description |
|---|---|
from_native |
Copy a native |
Attributes:
| Name | Type | Description |
|---|---|---|
items |
list[StorageReference]
|
The files directly in the folder. |
prefixes |
list[StorageReference]
|
The sub-folders directly in the folder. |
page_token |
str | None
|
Pass it to |
prefixes
instance-attribute
¶
prefixes: list[StorageReference]
The sub-folders directly in the folder.
page_token
instance-attribute
¶
Pass it to list for the next page; None on the last page.
from_native
classmethod
¶
from_native(native: ObjCObject) -> StorageListResult
Copy a native FIRStorageListResult.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
native
|
ObjCObject
|
the |
required |
StorageReference
¶
StorageReference(native: ObjCObject)
Points to a file or folder in Cloud Storage. Nothing is read or written until you call a method.
Get references from Storage or child; you do not make them yourself.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
native
|
ObjCObject
|
the native |
required |
Methods:
| Name | Description |
|---|---|
root |
The root of the bucket. |
parent |
The folder this is in, or |
child |
A reference below this one. |
put_data |
Upload bytes, replacing the file if it exists. |
put_file |
Upload a local file, replacing the file in Storage if it exists. |
get_data |
Download the file into memory. |
write_to_file |
Download the file to a local file (for large files). |
download_url |
Get a long-lived |
get_metadata |
Get the file's metadata. |
update_metadata |
Change the file's metadata. Only the fields changed on |
list_all |
Everything directly in this folder (files and sub-folders). |
list |
One page of what is directly in this folder. |
delete |
Delete the file. |
Attributes:
| Name | Type | Description |
|---|---|---|
native |
ObjCObject
|
The |
full_path |
str
|
The path in the bucket, for example |
name |
str
|
The last part of the path. |
bucket |
str
|
The bucket name. |
storage |
Storage
|
The |
gs_url |
str
|
The |
native
property
¶
native: ObjCObject
The FIRStorageReference, for SDK calls this wrapper does not cover.
full_path
property
¶
The path in the bucket, for example "users/ada/avatar.jpg" (""
for the root).
child
¶
child(path: str) -> StorageReference
A reference below this one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
a relative path, for example |
required |
Returns:
| Type | Description |
|---|---|
StorageReference
|
A new |
put_data
¶
put_data(
data: bytes | bytearray | memoryview,
content_type: str | None = None,
callback: MetadataCallback | None = None,
*,
metadata: StorageMetadata | None = None,
) -> StorageUploadTask
Upload bytes, replacing the file if it exists.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
bytes | bytearray | memoryview
|
the bytes. |
required |
content_type
|
str | None
|
the MIME type, for example |
None
|
callback
|
MetadataCallback | None
|
gets |
None
|
metadata
|
StorageMetadata | None
|
metadata to upload with (content type, cache control, custom metadata...). |
None
|
Returns:
| Type | Description |
|---|---|
StorageUploadTask
|
A |
put_file
¶
put_file(
local_path: str,
content_type: str | None = None,
callback: MetadataCallback | None = None,
*,
metadata: StorageMetadata | None = None,
) -> StorageUploadTask
Upload a local file, replacing the file in Storage if it exists.
Large files are uploaded in chunks and survive network changes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
local_path
|
str
|
the file's path on the device. |
required |
content_type
|
str | None
|
the MIME type, for example |
None
|
callback
|
MetadataCallback | None
|
gets |
None
|
metadata
|
StorageMetadata | None
|
metadata to upload with. |
None
|
Returns:
| Type | Description |
|---|---|
StorageUploadTask
|
A |
get_data
¶
get_data(
max_size: int,
callback: Callable[
[bytes | None, StorageError | None], None
],
) -> StorageDownloadTask
Download the file into memory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_size
|
int
|
the most bytes to accept. A bigger file fails with
|
required |
callback
|
Callable[[bytes | None, StorageError | None], None]
|
gets |
required |
Returns:
| Type | Description |
|---|---|
StorageDownloadTask
|
A |
write_to_file
¶
write_to_file(
local_path: str,
callback: Callable[
[str | None, StorageError | None], None
]
| None = None,
) -> StorageDownloadTask
Download the file to a local file (for large files).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
local_path
|
str
|
where to save it on the device. Its folder must exist. |
required |
callback
|
Callable[[str | None, StorageError | None], None] | None
|
gets |
None
|
Returns:
| Type | Description |
|---|---|
StorageDownloadTask
|
A |
download_url
¶
download_url(
callback: Callable[
[str | None, StorageError | None], None
],
) -> None
Get a long-lived https:// download URL for the file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
Callable[[str | None, StorageError | None], None]
|
gets |
required |
get_metadata
¶
Get the file's metadata.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
MetadataCallback
|
gets |
required |
update_metadata
¶
update_metadata(
metadata: StorageMetadata,
callback: MetadataCallback | None = None,
) -> None
Change the file's metadata. Only the fields changed on metadata
are sent; set one to None to delete it.
::
def got(metadata, error):
metadata.cache_control = "public, max-age=300"
metadata.content_language = None # delete it
ref.update_metadata(metadata, on_updated)
ref.get_metadata(got)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
metadata
|
StorageMetadata
|
new metadata ( |
required |
callback
|
MetadataCallback | None
|
gets |
None
|
list_all
¶
list_all(
callback: Callable[
[StorageListResult | None, StorageError | None],
None,
],
) -> None
Everything directly in this folder (files and sub-folders).
Needs rules version 2. For big folders, prefer list with pages.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
Callable[[StorageListResult | None, StorageError | None], None]
|
gets |
required |
list
¶
list(
max_results: int,
callback: Callable[
[StorageListResult | None, StorageError | None],
None,
],
page_token: str | None = None,
) -> None
One page of what is directly in this folder.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_results
|
int
|
the most results in the page (1 to 1000). |
required |
callback
|
Callable[[StorageListResult | None, StorageError | None], None]
|
gets |
required |
page_token
|
str | None
|
the previous page's |
None
|
delete
¶
Delete the file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
callback
|
ErrorCallback | None
|
gets |
None
|
StorageDownloadTask
¶
StorageDownloadTask(native: ObjCObject)
StorageTask
¶
StorageTask(native: ObjCObject)
A running upload or download. Upload and download methods give one back.
Observer callbacks stay alive until you remove them or the task finishes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
native
|
ObjCObject
|
the native |
required |
Methods:
| Name | Description |
|---|---|
observe |
Call |
remove_observer |
Stop one observer. |
pause |
Pause the task ( |
resume |
Continue a paused task. |
cancel |
Stop the task. Its completion gets a |
Attributes:
| Name | Type | Description |
|---|---|---|
native |
ObjCObject
|
The native task. |
snapshot |
StorageTaskSnapshot
|
The task's current state. |
observe
¶
observe(
status: int,
handler: Callable[[StorageTaskSnapshot], None],
) -> str
Call handler each time the task reaches status.
::
task.observe(StorageTaskStatus.PROGRESS, lambda s: bar.set(s.fraction_completed))
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
status
|
int
|
a |
required |
handler
|
Callable[[StorageTaskSnapshot], None]
|
gets a |
required |
Returns:
| Type | Description |
|---|---|
str
|
A handle for |
remove_observer
¶
Stop one observer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
handle
|
str
|
what |
required |
StorageTaskSnapshot
¶
StorageTaskSnapshot(native: ObjCObject)
A task's state at one moment.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
native
|
ObjCObject
|
the native |
required |
Attributes:
| Name | Type | Description |
|---|---|---|
status |
int
|
A |
bytes_transferred |
int
|
Bytes sent (uploads) or received (downloads) so far. |
total_bytes |
int
|
The total size, or -1 if not known yet. |
fraction_completed |
float
|
From 0.0 to 1.0. |
metadata |
StorageMetadata | None
|
The file's metadata, once known (uploads: after success). |
error |
StorageError | None
|
Why the task failed ( |
reference |
StorageReference
|
The file the task is for. |
bytes_transferred
property
¶
Bytes sent (uploads) or received (downloads) so far.
metadata
property
¶
metadata: StorageMetadata | None
The file's metadata, once known (uploads: after success).
StorageTaskStatus
¶
What happened to a task: pass one to StorageTask.observe.
Attributes:
| Name | Type | Description |
|---|---|---|
RESUME |
Final
|
The task started or resumed. |
PROGRESS |
Final
|
More bytes were sent or received. |
PAUSE |
Final
|
The task was paused. |
SUCCESS |
Final
|
The task finished. |
FAILURE |
Final
|
The task failed or was cancelled (see |
FAILURE
class-attribute
instance-attribute
¶
The task failed or was cancelled (see snapshot.error).