Skip to content

Core, types and helpers

pyios_firebase.core

Firebase Core: start Firebase once, when the app starts.

from pyios_firebase import core

core.configure()

Needs the FirebaseCore framework and GoogleService-Info.plist in the app.

Functions:

Name Description
configure

Start Firebase with the app's GoogleService-Info.plist.

default_app

The default FIRApp, or None if configure() was not called.

configure

configure() -> None

Start Firebase with the app's GoogleService-Info.plist.

Call it once, at app start, before using any other product. To use the App Check debug provider, call app_check.initialize_debug_appcheck() first.

default_app

default_app() -> ObjCObject | None

The default FIRApp, or None if configure() was not called.

pyios_firebase.types

Types shared by the whole package, for your own annotations.

Errors are dicts you can also read with dots (error.code or error["code"]). The classes below only tell editors and type checkers which keys they have::

from pyios_firebase.firestore import QuerySnapshot
from pyios_firebase.types import FirebaseError


def on_cities(snapshot: QuerySnapshot | None, error: FirebaseError | None) -> None:
    if error is not None:
        print(error.code, error.description)
        return
    assert snapshot is not None
    for doc in snapshot:
        print(doc.document_id, doc.data)

Callback aliases:

  • ErrorCallback: (error) for writes
  • ResultCallback[T]: (result, error); exactly one of them is None

Classes:

Name Description
QueryDict

A dict that can also be read and written with dots.

FirebaseError

An error from Firebase. Every callback error has these keys.

Attributes:

Name Type Description
ObjCObject TypeAlias

An Objective-C object, as Rubicon gives it (a rubicon.objc.ObjCInstance).

FirestoreData TypeAlias

Data you write to a document: a mapping of field names to Python values.

ErrorCallback TypeAlias

A callback for writes: gets the error, or None when it worked.

ResultCallback TypeAlias

A callback that gets (result, error). Exactly one of them is None.

ObjCObject module-attribute

ObjCObject: TypeAlias = Any

An Objective-C object, as Rubicon gives it (a rubicon.objc.ObjCInstance).

Typed as Any because Rubicon has no type information: its attributes are the Objective-C object's properties and methods, found at runtime.

FirestoreData module-attribute

FirestoreData: TypeAlias = Mapping[str, Any]

Data you write to a document: a mapping of field names to Python values.

ErrorCallback module-attribute

ErrorCallback: TypeAlias = Callable[
    [FirebaseError | None], None
]

A callback for writes: gets the error, or None when it worked.

ResultCallback module-attribute

ResultCallback: TypeAlias = Callable[
    [T | None, FirebaseError | None], None
]

A callback that gets (result, error). Exactly one of them is None.

QueryDict

Bases: dict[str, Any]

A dict that can also be read and written with dots.

::

d = QueryDict(code=1)
d.description = "x"  # same as d["description"] = "x"
d.code               # same as d["code"]

Reading a missing key with a dot raises AttributeError.

FirebaseError

Bases: QueryDict

An error from Firebase. Every callback error has these keys.

Attributes:

Name Type Description
code int

The error code (NSError.code). Its meaning depends on domain.

description str

A human-readable description (NSError.localizedDescription).

domain str

The error domain, for example "FIRFirestoreErrorDomain".

underlying_error ObjCObject

The nested NSError that caused this one, or None. For debugging.

code instance-attribute

code: int

The error code (NSError.code). Its meaning depends on domain.

description instance-attribute

description: str

A human-readable description (NSError.localizedDescription).

domain instance-attribute

domain: str

The error domain, for example "FIRFirestoreErrorDomain".

underlying_error instance-attribute

underlying_error: ObjCObject

The nested NSError that caused this one, or None. For debugging.

pyios_firebase.util

Helpers shared by every Firebase product wrapper.

Most apps never need this module. It is public for advanced use:

  • to_firestore / to_python: the value conversion every Firestore call uses, for values you pass to the SDK yourself.
  • nserror_to_dict: turns an NSError into a FirebaseError.
  • objc_class: looks up an Objective-C class the first time it is used, so importing a module never needs a framework you do not use.
  • one_shot_block / listener_block: keep a callback block alive until Firebase is done with it.

Classes:

Name Description
QueryDict

A dict that can also be read and written with dots.

Functions:

Name Description
objc_instance

Wrap a raw Objective-C pointer (for example a block argument) as an object.

objc_class

An Objective-C class, looked up by name on first use and then cached.

objc_protocols

The Objective-C protocols with these names that the app has.

one_shot_block

Make a block that Firebase calls once, for a completion handler.

listener_block

Make a block that Firebase may call many times (snapshot listeners,

nserror_to_dict

Turn an NSError into a FirebaseError.

error_from_pointer

nserror_to_dict for a raw block argument.

timestamp_to_datetime

Turn a FIRTimestamp into an aware datetime in UTC.

nsdate_to_datetime

Turn an NSDate into an aware datetime in UTC.

datetime_to_timestamp

Turn a datetime into a FIRTimestamp, to the microsecond.

to_firestore

Turn a Python value into what the Firestore SDK expects.

to_python

Turn a value from the Firebase SDK into plain Python.

QueryDict

Bases: dict[str, Any]

A dict that can also be read and written with dots.

::

d = QueryDict(code=1)
d.description = "x"  # same as d["description"] = "x"
d.code               # same as d["code"]

Reading a missing key with a dot raises AttributeError.

objc_instance

objc_instance(pointer: Any) -> ObjCObject

Wrap a raw Objective-C pointer (for example a block argument) as an object.

Parameters:

Name Type Description Default
pointer Any

an objc_id (or an address) that points to a live Objective-C object.

required

Returns:

Type Description
ObjCObject

A Rubicon object whose attributes are the Objective-C object's

ObjCObject

properties and methods.

objc_class cached

objc_class(name: str) -> ObjCObject

An Objective-C class, looked up by name on first use and then cached.

Parameters:

Name Type Description Default
name str

the class name, for example "FIRFirestore".

required

Returns:

Type Description
ObjCObject

The class, as a Rubicon object.

Raises:

Type Description
NameError

the app does not have the class (its framework is not linked).

objc_protocols

objc_protocols(*names: str) -> list[ObjCObject]

The Objective-C protocols with these names that the app has.

For the protocols= of a Python class that Firebase or UIKit calls: a protocol the app does not have (its framework is not linked) is left out.

Parameters:

Name Type Description Default
*names str

the protocol names, for example "FIRMessagingDelegate".

()

Returns:

Type Description
list[ObjCObject]

The protocols found, in order.

one_shot_block

one_shot_block(
    function: Callable[..., Any], *argtypes: Any
) -> Block

Make a block that Firebase calls once, for a completion handler.

The block is kept alive until that call, then released.

Parameters:

Name Type Description Default
function Callable[..., Any]

called with the block's arguments (raw objc_id pointers for objects).

required
*argtypes Any

the ctypes type of each block argument, for example objc_id.

()

listener_block

listener_block(
    function: Callable[..., Any],
    *argtypes: Any,
    restype: Any = None,
) -> tuple[Block, Callable[[], None]]

Make a block that Firebase may call many times (snapshot listeners, transaction functions).

Parameters:

Name Type Description Default
function Callable[..., Any]

called with the block's arguments on every call.

required
*argtypes Any

the ctypes type of each block argument.

()
restype Any

the ctypes type the block returns, or None for void.

None

Returns:

Type Description
Block

(block, release). Call release() once Firebase is done with the

Callable[[], None]

block; until then it is kept alive.

nserror_to_dict

nserror_to_dict(
    error: ObjCObject | None,
) -> FirebaseError | None

Turn an NSError into a FirebaseError.

Parameters:

Name Type Description Default
error ObjCObject | None

the NSError, or None.

required

Returns:

Type Description
FirebaseError | None

A FirebaseError with code, description and domain as

FirebaseError | None

plain int / str and underlying_error as the nested

FirebaseError | None

NSError (or None); None when error is None.

error_from_pointer

error_from_pointer(error_ptr: Any) -> FirebaseError | None

nserror_to_dict for a raw block argument.

Parameters:

Name Type Description Default
error_ptr Any

the NSError * a completion block received: an objc_id, or None / a null pointer when there was no error.

required

Returns:

Type Description
FirebaseError | None

A FirebaseError, or None when there was no error.

timestamp_to_datetime

timestamp_to_datetime(ts: Any) -> datetime

Turn a FIRTimestamp into an aware datetime in UTC.

Integer math, so no microseconds are lost to float rounding (that happens for dates far from 1970). Nanoseconds below a microsecond are dropped: datetime cannot hold them.

Parameters:

Name Type Description Default
ts Any

a FIRTimestamp, or anything with seconds and nanoseconds attributes.

required

Returns:

Type Description
datetime

The same instant, with tzinfo=UTC.

nsdate_to_datetime

nsdate_to_datetime(
    value: ObjCObject | None,
) -> datetime | None

Turn an NSDate into an aware datetime in UTC.

Parameters:

Name Type Description Default
value ObjCObject | None

the NSDate, or None.

required

Returns:

Type Description
datetime | None

The same instant with tzinfo=UTC (to the microsecond), or None.

datetime_to_timestamp

datetime_to_timestamp(value: datetime) -> ObjCObject

Turn a datetime into a FIRTimestamp, to the microsecond.

Parameters:

Name Type Description Default
value datetime

the date and time. A naive datetime (no tzinfo) is read as UTC, like the Firebase Admin SDK for Python does; pass an aware datetime to be explicit.

required

Returns:

Type Description
ObjCObject

A FIRTimestamp for the same instant.

to_firestore

to_firestore(value: Any) -> Any

Turn a Python value into what the Firestore SDK expects.

Converts inside dicts, lists and tuples too. The opposite of to_python.

  • datetime becomes a FIRTimestamp (naive datetimes are read as UTC)
  • None becomes NSNull (Firestore null)
  • tuples become arrays
  • DocumentReference becomes the native reference
  • FieldValue sentinels and other Objective-C objects pass through

Parameters:

Name Type Description Default
value Any

the value: str, int, float, bool, None, bytes, datetime, DocumentReference, a FieldValue, or a dict (with str keys), list or tuple of those.

required

Returns:

Type Description
Any

The Objective-C value (NSDictionary, NSArray, ...).

Raises:

Type Description
TypeError

the value cannot be stored in Firestore (for example a date, a set, or a field name that is not a str). The message starts with the path of the bad field, for example "events[0].at". Nothing is sent to Firestore.

to_python

to_python(value: Any) -> Any

Turn a value from the Firebase SDK into plain Python.

Converts inside dictionaries and arrays too. The opposite of to_firestore.

  • NSDictionary / NSArray become dict / list
  • NSString becomes str, NSData becomes bytes
  • NSNumber becomes bool, int or float (booleans stay bool)
  • NSNull becomes None
  • NSDate and FIRTimestamp become an aware datetime (UTC)
  • FIRDocumentReference becomes a DocumentReference
  • anything else that is still Objective-C (for example FIRGeoPoint) is left as it is

Parameters:

Name Type Description Default
value Any

an Objective-C object, or a Python value (dict, list, ...) that may still hold some.

required

Returns:

Type Description
Any

The value as plain Python.