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 |
default_app |
The default |
configure
¶
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 writesResultCallback[T]:(result, error); exactly one of them isNone
Classes:
| Name | Description |
|---|---|
QueryDict |
A |
FirebaseError |
An error from Firebase. Every callback |
Attributes:
| Name | Type | Description |
|---|---|---|
ObjCObject |
TypeAlias
|
An Objective-C object, as Rubicon gives it (a |
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 |
ResultCallback |
TypeAlias
|
A callback that gets |
ObjCObject
module-attribute
¶
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
¶
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 ( |
description |
str
|
A human-readable description ( |
domain |
str
|
The error domain, for example |
underlying_error |
ObjCObject
|
The nested |
description
instance-attribute
¶
A human-readable description (NSError.localizedDescription).
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 anNSErrorinto aFirebaseError.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 |
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 |
error_from_pointer |
|
timestamp_to_datetime |
Turn a |
nsdate_to_datetime |
Turn an |
datetime_to_timestamp |
Turn a |
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 |
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 |
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 |
()
|
Returns:
| Type | Description |
|---|---|
list[ObjCObject]
|
The protocols found, in order. |
one_shot_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 |
required |
*argtypes
|
Any
|
the ctypes type of each block argument, for example
|
()
|
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
|
Returns:
| Type | Description |
|---|---|
Block
|
|
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 |
required |
Returns:
| Type | Description |
|---|---|
FirebaseError | None
|
A |
FirebaseError | None
|
plain |
FirebaseError | 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 |
required |
Returns:
| Type | Description |
|---|---|
FirebaseError | None
|
A |
timestamp_to_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 |
required |
Returns:
| Type | Description |
|---|---|
datetime
|
The same instant, with |
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 |
required |
Returns:
| Type | Description |
|---|---|
datetime | None
|
The same instant with |
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 |
required |
Returns:
| Type | Description |
|---|---|
ObjCObject
|
A |
to_firestore
¶
Turn a Python value into what the Firestore SDK expects.
Converts inside dicts, lists and tuples too. The opposite of
to_python.
datetimebecomes aFIRTimestamp(naive datetimes are read as UTC)NonebecomesNSNull(Firestorenull)- tuples become arrays
DocumentReferencebecomes the native referenceFieldValuesentinels and other Objective-C objects pass through
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
the value: |
required |
Returns:
| Type | Description |
|---|---|
Any
|
The Objective-C value ( |
Raises:
| Type | Description |
|---|---|
TypeError
|
the value cannot be stored in Firestore (for example a
|
to_python
¶
Turn a value from the Firebase SDK into plain Python.
Converts inside dictionaries and arrays too. The opposite of
to_firestore.
NSDictionary/NSArraybecomedict/listNSStringbecomesstr,NSDatabecomesbytesNSNumberbecomesbool,intorfloat(booleans staybool)NSNullbecomesNoneNSDateandFIRTimestampbecome an awaredatetime(UTC)FIRDocumentReferencebecomes aDocumentReference- 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. |