Model

class fsglue.model.BaseModel(doc_id, *parent_ids)[source]

Bases: object

Examples

import fsglue

class Fruit(fsglue.BaseModel):

    COLLECTION_PATH = "fruit"
    COLLECTION_PATH_PARAMS = []

    name = fsglue.StringProperty(required=True)
    price = fsglue.IntegerProperty(required=True)

# create
apple = Fruit.create_by_dict({"name": "apple", "price": 100})

# read
apple = Fruit.get_by_id(apple.doc_id)
apple = Fruit.where([[name, "==", "apple"]])[0]

# update
values = fetched_apple.to_dict()
values["price"] = 110
Fruit.update_by_dict(values)
fetched_apple = Fruit.get_by_id(fetched_apple.doc_id)
# delete
fetched_apple.delete()
COLLECTION_PATH = None
COLLECTION_PATH_PARAMS = []
DICT_ID_KEY = 'id'
ID_VALIDATION_PATTERN = '^[a-zA-Z0-9_]+$'
classmethod get_client()[source]

Return firestore.Clinet() instance. You can override this method to use another client per model.

property doc_id
to_dict(get_intact=False)[source]

Return dict values of instance propeties

Parameters

get_intact (bool) – if True return values before local change

Returns

document values

Return type

dict

classmethod create(*parent_ids)[source]

Create new model instance

Parameters

*parent_ids (list[str]) – List of parent_id defined by COLLECTION_PATH_PARAMS

Returns

model instance

Return type

obj

classmethod create_by_dict(values, *parent_ids, exclude=[], only=None, without_put=False)[source]

Create new firestore document by dict values, and return model instance.

Parameters

  • values (dict) – Model properties values.

  • *parent_ids (list[str]) – List of parent_id defined by COLLECTION_PATH_PARAMS

  • exclude (list[str], optional) – If specified, save property not listed.

  • only (list[str], optional) – If specified, save property only listed.

  • without_put (bool) – If True, do not save on firestore but create instance.

Returns

model instance

Return type

obj

classmethod update_by_dict(values, *parent_ids, exclude=[], only=None, without_put=False)[source]

Update firestore document by dict values, and return model instance.

Parameters

  • values (dict) – Model properties values. Must contain DICT_ID_KEY field.

  • *parent_ids (list[str]) – List of parent_id defined by COLLECTION_PATH_PARAMS

  • exclude (list[str], optional) – If specified, save property not listed.

  • only (list[str], optional) – If specified, save property only listed.

  • without_put (bool) – If True, do not save on firestore but update instance.

Returns

model instance

Return type

obj

classmethod upsert_by_dict(values, *parent_ids, exclude=[], only=None, without_put=False)[source]

Create or update firestore document by dict values, and return model instance.

Parameters

  • values (dict) – Model properties values. Must contain DICT_ID_KEY field.

  • *parent_ids (list[str]) – List of parent_id defined by COLLECTION_PATH_PARAMS

  • exclude (list[str], optional) – If specified, save property not listed.

  • only (list[str], optional) – If specified, save property only listed.

  • without_put (bool) – If True, do not save on firestore.

Returns

model instance

Return type

obj

validate()[source]

Validate model instance. Raise Exception if invalid

classmethod exists(doc_id, *parent_ids)[source]

Return the document exists or not by doc_id.

Parameters

  • doc_id (str) – Document id

  • *parent_ids (list[str]) – List of parent_id defined by COLLECTION_PATH_PARAMS

Returns

True if exists else False

Return type

bool

classmethod get_by_id(doc_id, *parent_ids)[source]

Fetch document from firestore by doc_id

Parameters

  • doc_id (str) – Document id

  • *parent_ids (list[str]) – List of parent_id defined by COLLECTION_PATH_PARAMS

Returns

model instance

Return type

obj

classmethod get_by_ids(doc_ids, *parent_ids)[source]

Fetch documents from firestore by doc_ids

Parameters

  • doc_ids (list[str]) – List of document id

  • *parent_ids (list[str]) – List of parent_id defined by COLLECTION_PATH_PARAMS

Returns

list of model instance

Return type

list

put(exclude=[], only=None, **kwargs)[source]

Save instance values to firestore

If doc_id is None, create new Document. If doc_id is not None, update existing Document.

Parameters

  • exclude (list[str], optional) – If specified, save property not listed.

  • only (list[str], optional) – If specified, save property only listed.

  • **kwargs – extra arguments pass to before_put, after_put

before_put(**kwargs)[source]

Hook before put() and return whether continue to put or not

Returns

whether continue to put or not

Return type

bool

after_put(created, **kwargs)[source]

Hook after put() succeeded.

Parameters

  • created (bool, optional) – True if put() created new document else False

  • **kwargs – extra arguments passed from put()

delete()[source]

Delete document in firestore

is_deletable()[source]

Determine whether continue to delete() or not.

Returns

continue to delete() or not

Return type

bool

before_delete()[source]

Hook before delete() and return whether continue to delete() or not.

Returns

continue to delete() or not

Return type

bool

after_delete()[source]

Hook after delete() succeeded.

delete_all()[source]

Delete document and subcollection recursively

classmethod where(conds, *parent_ids, to_dict=False, order_by=None, limit=100, offset=None, collection_id=None)[source]

Fetch documents which match the conditions.

Parameters

  • conds (list[]) – List of search conditions. Each condition must be list of [field, operator, value]. Each condition is passed to firestore .where() method.

  • *parent_ids (list[str]) – List of parent_id defined by COLLECTION_PATH_PARAMS

  • to_dict (bool) – Return list of dict instead of model instance if set True.

  • order_by (str) – Property name to sort the results. Add “-” prefix if descending order, like “-price”.

  • limit (int) – Number of max documents.

  • offset (int) – Number of offset to fetch the documents.

  • collection_id (str) – Set collection name to search by collection_group. If collection_id is specified, parent_ids are ignored.

Returns

instances or dicts of the model

Return type

list

classmethod all(*parent_ids, **kwargs)[source]

Fetch all documents.

Parameters
Returns

instances of the model

Return type

list

classmethod stream(*parent_ids, conds=[], collection_id=None)[source]

Generator for all documents.

Parameters

  • *parent_ids – Same as where()

  • conds (list[]) – Same as where()

  • collection_id (str) – Same as where()

Returns

yield instances of the model

Return type

generator

classmethod to_schema()[source]

Generate JsonSchema definition for the model

Returns

JsonSchema definition

Return type

dict