Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/WoolDoughnut310/micropython-firebase-firestore

Firebase Firestore implementation for Micropython.
https://github.com/WoolDoughnut310/micropython-firebase-firestore

Last synced: 2 months ago
JSON representation

Firebase Firestore implementation for Micropython.

Lists

README 

        
# micropython-firebase-firestore



Firebase Firestore implementation for Micropython.



**Firebase implementation** based on [REST API](https://firebase.google.com/docs/firestore/reference/rest), based on [micropython-firebase-realtime-database](https://github.com/ckoever/micropython-firebase-realtime-database) from ckoever.



### Installation



You can use **uPip** to install library from **PyPi**



```python

import upip

upip.install("micropython-firebase-firestore")

```



or you can just upload `ufirestore/ufirestore.py` to your microcontroller:



```bash

python pyboard.py -d PORT -f cp ufirestore.py :

```



### Commands that are implemented



```

- set_project_id

- set_access_token

- patch

- create

- get

- getfile

- delete

- list

- list_collection_ids

- run_query

```



### Required modules



```

ujson, urequests, _thread

```



### Connect to Wifi



```python

import time

import network



wlan = network.WLAN(network.STA_IF)

wlan.active(True)

if not wlan.isconnected():

    wlan.connect("ssid", "pass")

    print("Waiting for Wi-Fi connection", end="...")

    while not wlan.isconnected():

        print(".", end="")

        time.sleep(1)

    print()

```



### Example Usage



Reads a field from a stored document



```python

import ufirestore



ufirestore.set_project_id("INSERT_PROJECT_ID")

ufirestore.set_access_token("INSERT_ACCESS_TOKEN")

raw_doc = ufirestore.get("DOCUMENT_PATH")

doc = FirebaseJson.from_raw(raw_doc)



if doc["fields"].exists("FIELD"):

    print("The field value is: %s" % doc["fields"].get("FIELD"))

```



The project ID is required, read about it [here](https://firebase.google.com/docs/projects/learn-more#project-id)

or you can find it at `Project Settings > General` in your project's [console](https://console.firebase.google.com)

The access token is obtained from the Firebase Auth API, which can be harnessed with my [auth library](https://github.com/WoolDoughnut310/micropython-firebase-auth), or reading can be done [here](https://firebase.google.com/docs/firestore/use-rest-api#authentication_and_authorization)



## Functions



### set_project_id



```python

ufirestore.set_project_id("INSERT_PROJECT_ID")

```



Set the ID of your Firebase project



### set_access_token



```python

ufirestore.set_access_token("INSERT_ACCESS_TOKEN")

```



Sets the access token to use for authentication



### patch



```python

ufirestore.patch(PATH, DOC, update_mask=[], bg=True, cb=None)

```



Updates or inserts a document `DOC` at the location `PATH`



-   Set the fields to update with `update_mask`

-   Optional run in the background with `bg`

-   Set a callback function after getting data with `cb`



#### Example



```python

doc = FirebaseJson()

doc.set("age/integerValue", 21)



response = ufirestore.patch("users/234", doc, ["age"], False)

print(response)

```



### create



```python

ufirestore.create(PATH, DOC, document_id=None, bg=True, cb=None)

```



Creates a new document `DOC` at the collection at location `PATH`



-   `document_id` - The document ID to use for the document. If not specified, an ID will be generated

-   Optional run in the background with `bg`

-   Set a callback function after getting data with `cb`



#### Example



```python

doc = FirebaseJson()

doc.set("name/stringValue", "Jane Doe")

doc.set("age/integerValue", 25)

doc.set("height/integerValue", 165)



response = ufirestore.create("users", doc, bg=False)

print(response)

```



### get



```python

ufirestore.get(PATH, mask=None, bg=True, cb=None)

```



Gets a single document at location `PATH`



-   `document_id` - The document ID to use for the document. If not specified, an ID will be generated

-   `mask` - The fields to return

-   Optional run in the background with `bg`

-   Set a callback function after getting data with `cb`



#### Example



```python

response = ufirestore.get("users/129", bg=False)

doc = FirebaseJson.from_raw(response)



if doc.exists("fields/name"):

    print("Hello, %s" % doc.get("fields/name"))

```



### getfile



```python

ufirestore.getfile(PATH, FILENAME, mask=None, bg=True, cb=None)

```



Gets a single document at location `PATH` and writes it to file `FILENAME`



-   `document_id` - The document ID to use for the document. If not specified, an ID will be generated

-   `mask` - The fields to return

-   Optional run in the background with `bg`

-   Set a callback function after getting data with `cb`



#### Example



```python

ufirestore.getfile("users/129", "user.json")

```



### delete



```python

ufirestore.delete(PATH, bg=True, cb=None)

```



Deletes a document at location `PATH`



-   Optional run in the background with `bg`

-   Set a callback function after getting data with `cb`



#### Example



```python

success = ufirestore.delete("users/129")



if success:

    print("User data successfully deleted.")

```



### list



```python

ufirestore.list(PATH, page_size=None, page_token=None, order_by=None, mask=None, show_missing=None, bg=True, cb=None)

```



Lists documents at location `PATH`



-   `page_size` - The number of documents to return

-   `page_token` - The `next_page_token` returned from a previous `list` option

-   `order_by` - The order to sort results by. For example: `priority desc, name`

-   `mask` - The fields to return. If not set, return all fields

-   `show_missing` - If the list should show missing documents

-   Optional run in the background with `bg`

-   Set a callback function after getting data with `cb`



#### Example



```python

documents, next_page_token = ufirestore.list("users", bg=False)



for document in documents:

    doc = FirebaseJson.from_raw(document)

    if doc.exists("fields/age"):

        print("Age: %s" % doc.get("fields/age"))

```



### list_collection_ids



```python

ufirestore.list_collection_ids(PATH, page_size=None, page_token=None, bg=True, cb=None)

```



Lists all the collection IDs underneath a document at `PATH`



-   `page_size` - The maximum number of results to return

-   `page_token` - A page token

-   Optional run in the background with `bg`

-   Set a callback function after getting data with `cb`



#### Example



```python

collection_ids, next_page_token = ufirestore.list_collection_ids("rooms/28", bg=False)



for collection_id in collection_ids:

    print("ID: %s" % collection_id)

```



### run_query



```python

ufirestore.run_query(PATH, query, bg=True, cb=None)

```



Runs a query at location `PATH`



-   Optional run in the background with `bg`

-   Set a callback function after getting data with `cb`



#### Example



```python

from ufirestore.json import FirebaseJson, Query



query = Query().from_("users").where("age", ">=", 18)

raw_doc = ufirestore.run_query("", query, bg=False)

doc = FirebaseJson.from_raw(raw_doc)



if doc.exists("fields/name"):

    print("Resulted with user named %s" % doc.get("fields/name"))

```



## FirebaseJson



A simple helper class for Firebase document JSON data



### set



```python

doc.set(path, value, with_type=False)

```



Edit, overwrite or create new node at the specified path



-   `with_type` - If set to `True`, the value's type will be inferred and applied accordingly, as per a Firestore Document [Value](https://cloud.google.com/firestore/docs/reference/rest/v1/Value)



### get



```python

doc.get(path, default=None)

```



Get the node value at a given path, returning `default` if the path does not exist



### add



```python

doc.add(path, name, value)

```



Add a new node at the path, with name `name` and contents `value`



### add_item



```python

doc.add_item(path, value)

```



Adds an array item to the node at the path



### remove



```python

doc.remove(path)

```



Removes the node at the path



### exists



```python

doc.exists(path)

```



Checks whether a node exists at the path



### process



```python

doc.process(resource_name)

```



Processes json instance into a `dict` for usage with Firestore API



NOTE: All the functions in this library that require a document actually require the `FirebaseJon` instance and runs `process` behind the scenes



### FirebaseJson.from_raw



```python

FirebaseJson.from_raw(raw_doc)

```



Parses a raw document object from the Firestore API into a `FirebaseJson` instance



### Extra methods



### FirebaseJson.to_value_type



```python

FirebaseJson.to_value_type(value)

```



Infers the type of `value` and returns a `dict` in the format of a Firestore Document [Value](https://cloud.google.com/firestore/docs/reference/rest/v1/Value)



#### Example



```python

value = 35



data = FirebaseJson.to_value_type(value)



print(data) # Returns {"integerValue": "35"}

```



### FirebaseJson.from_value_type



```python

FirebaseJson.from_value_type(value)

```



Takes a Firestore Document [Value](https://cloud.google.com/firestore/docs/reference/rest/v1/Value) object and returns its value, casted to the correct type



#### Example



```python

# Example data from API

data = {

    "arrayValue": {

        "values": [

            {"stringValue": "a"},

            {"stringValue": "b"},

            {"integerValue": "3"}

        ]

    }

}



print(value) # Returns ["a", "b", 3]

```



## Query



Wrapper over `FirebaseJson` to easily create document queries



Extends all `FirebaseJson` methods



### from\_



```python

query.from_(collection_id, all_descendants=False)

```



-   `collection_id` - When set, selects only collections with this ID

-   `all_descendants` - When `True`, selects all descendant collections, when `False`, selects collections that are immediate children of the `parent` the query will be run on



### select



```python

query.select(field)

```



Adds a document field to return



### order_by



```python

query.order_by(field, direction="DESCENDING")

```



-   `field` - The field to order by

-   `direction` - The direction to order by (`ASCENDING` or `DESCENDING`)



### limit



```python

query.limit(value)

```



The maximum number of results to return, `value` must be >= 0



### where



```python

query.where(field, op, value)

```



Applies a filter on a specific field.



-   `field` - The field to filter by

-   `op` - The operation to filter by, is one of `<`, `<=`, `>`, `>=`, `==`, `!=`, `array-contains`, `in`, `array-contains-any`, `not-in`

-   `value` - The value to compare to, type is inferred with `FirebaseJson.to_value_type`



### process



```python

query.process()

```



Returns `dict` data of query for use with Firestore API



NOTE: This function is already used in the `run_query` function