Skip to content

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_time
  • StorageReference: 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-only bucket, path, name, size, md5_hash, generation, metageneration, time_created, updated, is_file, gs_url
  • StorageTask (StorageUploadTask, StorageDownloadTask): observe(status, handler), remove_observer(handle), pause(), resume(), cancel(), snapshot
  • StorageTaskSnapshot: status, bytes_transferred, total_bytes, fraction_completed, metadata, error, reference; StorageTaskStatus
  • StorageListResult (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

StorageMetadata: a file's content type, cache settings and custom metadata.

reference

StorageReference: a file or folder in Cloud Storage, and what you can do with it.

storage

Storage: a Cloud Storage bucket, its settings and the emulator.

task

Upload and download tasks: progress, pause, resume and cancel.

Classes:

Name Description
Storage

Cloud Storage for one bucket. Get it with Storage.storage().

StorageError

An error from Cloud Storage.

StorageErrorCode

The error.code values of Cloud Storage errors (FIRStorageErrorCode).

StorageMetadata

A file's metadata.

StorageListResult

One page of StorageReference.list / list_all.

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 StorageTask.observe.

StorageUploadTask

A running upload.

Attributes:

Name Type Description
STORAGE_ERROR_DOMAIN Final

The error.domain of Cloud Storage errors.

STORAGE_ERROR_DOMAIN module-attribute

STORAGE_ERROR_DOMAIN: Final = 'FIRStorageErrorDomain'

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 FIRStorage.

required

Methods:

Name Description
storage

The shared Storage for a bucket.

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 FIRStorage.

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).

native property

native: ObjCObject

The FIRStorage.

max_upload_retry_time property writable

max_upload_retry_time: float

Seconds an upload keeps retrying before it fails (default 600).

max_download_retry_time property writable

max_download_retry_time: float

Seconds a download keeps retrying before it fails (default 600).

max_operation_retry_time property writable

max_operation_retry_time: float

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 "gs://my-other-bucket", or None for the app's default bucket (STORAGE_BUCKET in GoogleService-Info.plist).

None

Returns:

Type Description
Storage

The same Storage for the same bucket.

reference

reference() -> StorageReference

The root of the bucket.

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 "users/ada/avatar.jpg".

required

Returns:

Type Description
StorageReference

A StorageReference. Nothing is read or written.

reference_for_url

reference_for_url(url: str) -> StorageReference

A reference from a file's URL.

Parameters:

Name Type Description Default
url str

a gs://bucket/path URL, or an https:// Firebase Storage download URL. Its bucket must be this Storage's bucket.

required

Returns:

Type Description
StorageReference

A StorageReference.

use_emulator

use_emulator(
    host: str = "127.0.0.1", port: int = 9199
) -> None

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" works in the iOS Simulator; on a device, use the Mac's LAN address.

'127.0.0.1'
port int

the emulator's port (firebase emulators:start uses 9199).

9199

StorageError

Bases: FirebaseError

An error from Cloud Storage.

Attributes:

Name Type Description
name str

The StorageErrorCode name of code (for example

name instance-attribute

name: str

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 max_size in get_data.

CANCELLED Final

The task was cancelled.

OBJECT_NOT_FOUND class-attribute instance-attribute

OBJECT_NOT_FOUND: Final = -13010

No file at that path.

UNAUTHENTICATED class-attribute instance-attribute

UNAUTHENTICATED: Final = -13020

The rules need a signed-in user.

UNAUTHORIZED class-attribute instance-attribute

UNAUTHORIZED: Final = -13021

The security rules do not allow this.

RETRY_LIMIT_EXCEEDED class-attribute instance-attribute

RETRY_LIMIT_EXCEEDED: Final = -13030

The operation kept failing for longer than the max retry time.

DOWNLOAD_SIZE_EXCEEDED class-attribute instance-attribute

DOWNLOAD_SIZE_EXCEEDED: Final = -13032

The file is bigger than max_size in get_data.

CANCELLED class-attribute instance-attribute

CANCELLED: Final = -13040

The task was cancelled.

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 "image/jpeg".

None
cache_control str | None

the Cache-Control header, for example "public, max-age=3600".

None
content_disposition str | None

the Content-Disposition header.

None
content_encoding str | None

the Content-Encoding header, for example "gzip".

None
content_language str | None

the Content-Language header, for example "en".

None
custom_metadata Mapping[str, str] | None

your own string keys and values.

None
native ObjCObject | None

a native FIRStorageMetadata to wrap (instead of the fields above).

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 FIRStorageMetadata.

content_type str | None

The MIME type, for example "image/jpeg".

cache_control str | None

The Cache-Control header served with the file.

content_disposition str | None

The Content-Disposition header served with the file.

content_encoding str | None

The Content-Encoding header served with the file.

content_language str | None

The Content-Language header served with the file.

bucket str | None

The bucket, for example "my-app.appspot.com".

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 None.

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 gs://bucket/path URL of the file.

custom_metadata property writable

custom_metadata: dict[str, str]

Your own string keys and values (a copy: assign a new dict to change it).

native property

native: ObjCObject

The FIRStorageMetadata.

content_type property writable

content_type: str | None

The MIME type, for example "image/jpeg".

cache_control property writable

cache_control: str | None

The Cache-Control header served with the file.

content_disposition property writable

content_disposition: str | None

The Content-Disposition header served with the file.

content_encoding property writable

content_encoding: str | None

The Content-Encoding header served with the file.

content_language property writable

content_language: str | None

The Content-Language header served with the file.

bucket property

bucket: str | None

The bucket, for example "my-app.appspot.com".

path property

path: str | None

The file's full path in the bucket.

name property

name: str | None

The last part of the path.

size property

size: int

The size in bytes.

md5_hash property

md5_hash: str | None

The MD5 hash of the content (base64), or None.

generation property

generation: int

The content's version: changes each time the file is replaced.

metageneration property

metageneration: int

The metadata's version: changes each time the metadata is updated.

time_created property

time_created: datetime | None

When the file was created (UTC).

updated property

updated: datetime | None

When the file or its metadata last changed (UTC).

is_file property

is_file: bool

True for a file.

gs_url property

gs_url: str

The gs://bucket/path URL of the file.

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 FIRStorageListResult.

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 list for the next page; None on the last page.

items instance-attribute

items: list[StorageReference]

The files directly in the folder.

prefixes instance-attribute

prefixes: list[StorageReference]

The sub-folders directly in the folder.

page_token instance-attribute

page_token: str | None

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 FIRStorageListResult.

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 FIRStorageReference.

required

Methods:

Name Description
root

The root of the bucket.

parent

The folder this is in, or None at the root.

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 https:// download URL for the file.

get_metadata

Get the file's metadata.

update_metadata

Change the file's metadata. Only the fields changed on metadata

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 FIRStorageReference, for SDK calls this wrapper does not cover.

full_path str

The path in the bucket, for example "users/ada/avatar.jpg" (""

name str

The last part of the path.

bucket str

The bucket name.

storage Storage

The Storage this reference belongs to.

gs_url str

The gs://bucket/path URL.

native property

native: ObjCObject

The FIRStorageReference, for SDK calls this wrapper does not cover.

full_path property

full_path: str

The path in the bucket, for example "users/ada/avatar.jpg" ("" for the root).

name property

name: str

The last part of the path.

bucket property

bucket: str

The bucket name.

storage property

storage: Storage

The Storage this reference belongs to.

gs_url property

gs_url: str

The gs://bucket/path URL.

root

root() -> StorageReference

The root of the bucket.

parent

parent() -> StorageReference | None

The folder this is in, or None at the root.

child

child(path: str) -> StorageReference

A reference below this one.

Parameters:

Name Type Description Default
path str

a relative path, for example "avatar.jpg" or "images/2026/a.jpg". Leading, trailing and repeated / are ignored.

required

Returns:

Type Description
StorageReference

A new StorageReference.

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 "text/plain" (a shortcut for metadata.content_type).

None
callback MetadataCallback | None

gets (StorageMetadata, None) when done, or (None, error).

None
metadata StorageMetadata | None

metadata to upload with (content type, cache control, custom metadata...).

None

Returns:

Type Description
StorageUploadTask

A StorageUploadTask: observe progress, pause, resume or cancel.

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 "image/jpeg". Without it, Storage guesses from the file extension.

None
callback MetadataCallback | None

gets (StorageMetadata, None) when done, or (None, error).

None
metadata StorageMetadata | None

metadata to upload with.

None

Returns:

Type Description
StorageUploadTask

A StorageUploadTask.

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 DOWNLOAD_SIZE_EXCEEDED (checked by the SDK while downloading, and again on the bytes received).

required
callback Callable[[bytes | None, StorageError | None], None]

gets (bytes, None), or (None, error).

required

Returns:

Type Description
StorageDownloadTask

A StorageDownloadTask.

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 (local_path, None), or (None, error).

None

Returns:

Type Description
StorageDownloadTask

A StorageDownloadTask.

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 (url, None), or (None, error).

required

get_metadata

get_metadata(callback: MetadataCallback) -> None

Get the file's metadata.

Parameters:

Name Type Description Default
callback MetadataCallback

gets (StorageMetadata, None), or (None, error).

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 (StorageMetadata(...)), or one from get_metadata with fields changed.

required
callback MetadataCallback | None

gets (StorageMetadata, None) with the result, or (None, error).

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 (StorageListResult, None), or (None, error).

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 (StorageListResult, None), or (None, error).

required
page_token str | None

the previous page's page_token, or None for the first page.

None

delete

delete(callback: ErrorCallback | None = None) -> None

Delete the file.

Parameters:

Name Type Description Default
callback ErrorCallback | None

gets None or the error (OBJECT_NOT_FOUND if there is no file).

None

StorageDownloadTask

StorageDownloadTask(native: ObjCObject)

Bases: StorageTask

A running download.

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 FIRStorageUploadTask / FIRStorageDownloadTask.

required

Methods:

Name Description
observe

Call handler each time the task reaches status.

remove_observer

Stop one observer.

pause

Pause the task (resume continues it).

resume

Continue a paused task.

cancel

Stop the task. Its completion gets a CANCELLED error.

Attributes:

Name Type Description
native ObjCObject

The native task.

snapshot StorageTaskSnapshot

The task's current state.

native property

native: ObjCObject

The native task.

snapshot property

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 StorageTaskStatus value.

required
handler Callable[[StorageTaskSnapshot], None]

gets a StorageTaskSnapshot.

required

Returns:

Type Description
str

A handle for remove_observer.

remove_observer

remove_observer(handle: str) -> None

Stop one observer.

Parameters:

Name Type Description Default
handle str

what observe returned.

required

pause

pause() -> None

Pause the task (resume continues it).

resume

resume() -> None

Continue a paused task.

cancel

cancel() -> None

Stop the task. Its completion gets a CANCELLED error.

StorageTaskSnapshot

StorageTaskSnapshot(native: ObjCObject)

A task's state at one moment.

Parameters:

Name Type Description Default
native ObjCObject

the native FIRStorageTaskSnapshot.

required

Attributes:

Name Type Description
status int

A StorageTaskStatus value.

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 (FAILURE), or None.

reference StorageReference

The file the task is for.

status property

status: int

A StorageTaskStatus value.

bytes_transferred property

bytes_transferred: int

Bytes sent (uploads) or received (downloads) so far.

total_bytes property

total_bytes: int

The total size, or -1 if not known yet.

fraction_completed property

fraction_completed: float

From 0.0 to 1.0.

metadata property

metadata: StorageMetadata | None

The file's metadata, once known (uploads: after success).

error property

error: StorageError | None

Why the task failed (FAILURE), or None.

reference property

reference: StorageReference

The file the task is for.

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 snapshot.error).

RESUME class-attribute instance-attribute

RESUME: Final = 1

The task started or resumed.

PROGRESS class-attribute instance-attribute

PROGRESS: Final = 2

More bytes were sent or received.

PAUSE class-attribute instance-attribute

PAUSE: Final = 3

The task was paused.

SUCCESS class-attribute instance-attribute

SUCCESS: Final = 4

The task finished.

FAILURE class-attribute instance-attribute

FAILURE: Final = 5

The task failed or was cancelled (see snapshot.error).

StorageUploadTask

StorageUploadTask(native: ObjCObject)

Bases: StorageTask

A running upload.