{"id":13802635,"url":"https://github.com/WoolDoughnut310/micropython-firebase-firestore","last_synced_at":"2025-05-13T13:32:30.933Z","repository":{"id":57441484,"uuid":"456382981","full_name":"WoolDoughnut310/micropython-firebase-firestore","owner":"WoolDoughnut310","description":"Firebase Firestore implementation for Micropython.","archived":false,"fork":false,"pushed_at":"2022-12-23T06:31:46.000Z","size":11,"stargazers_count":8,"open_issues_count":7,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-22T22:07:33.757Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WoolDoughnut310.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-07T06:22:07.000Z","updated_at":"2024-04-02T17:41:10.000Z","dependencies_parsed_at":"2023-01-30T17:45:29.726Z","dependency_job_id":null,"html_url":"https://github.com/WoolDoughnut310/micropython-firebase-firestore","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoolDoughnut310%2Fmicropython-firebase-firestore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoolDoughnut310%2Fmicropython-firebase-firestore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoolDoughnut310%2Fmicropython-firebase-firestore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WoolDoughnut310%2Fmicropython-firebase-firestore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WoolDoughnut310","download_url":"https://codeload.github.com/WoolDoughnut310/micropython-firebase-firestore/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253950265,"owners_count":21989332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T00:01:49.043Z","updated_at":"2025-05-13T13:32:30.695Z","avatar_url":"https://github.com/WoolDoughnut310.png","language":"Python","funding_links":[],"categories":["Libraries"],"sub_categories":["Storage"],"readme":"# micropython-firebase-firestore\n\nFirebase Firestore implementation for Micropython.\n\n**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.\n\n### Installation\n\nYou can use **uPip** to install library from **PyPi**\n\n```python\nimport upip\nupip.install(\"micropython-firebase-firestore\")\n```\n\nor you can just upload `ufirestore/ufirestore.py` to your microcontroller:\n\n```bash\npython pyboard.py -d PORT -f cp ufirestore.py :\n```\n\n### Commands that are implemented\n\n```\n- set_project_id\n- set_access_token\n- patch\n- create\n- get\n- getfile\n- delete\n- list\n- list_collection_ids\n- run_query\n```\n\n### Required modules\n\n```\nujson, urequests, _thread\n```\n\n### Connect to Wifi\n\n```python\nimport time\nimport network\n\nwlan = network.WLAN(network.STA_IF)\nwlan.active(True)\nif not wlan.isconnected():\n    wlan.connect(\"ssid\", \"pass\")\n    print(\"Waiting for Wi-Fi connection\", end=\"...\")\n    while not wlan.isconnected():\n        print(\".\", end=\"\")\n        time.sleep(1)\n    print()\n```\n\n### Example Usage\n\nReads a field from a stored document\n\n```python\nimport ufirestore\n\nufirestore.set_project_id(\"INSERT_PROJECT_ID\")\nufirestore.set_access_token(\"INSERT_ACCESS_TOKEN\")\nraw_doc = ufirestore.get(\"DOCUMENT_PATH\")\ndoc = FirebaseJson.from_raw(raw_doc)\n\nif doc[\"fields\"].exists(\"FIELD\"):\n    print(\"The field value is: %s\" % doc[\"fields\"].get(\"FIELD\"))\n```\n\nThe project ID is required, read about it [here](https://firebase.google.com/docs/projects/learn-more#project-id)\nor you can find it at `Project Settings \u003e General` in your project's [console](https://console.firebase.google.com)\nThe 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)\n\n## Functions\n\n### set_project_id\n\n```python\nufirestore.set_project_id(\"INSERT_PROJECT_ID\")\n```\n\nSet the ID of your Firebase project\n\n### set_access_token\n\n```python\nufirestore.set_access_token(\"INSERT_ACCESS_TOKEN\")\n```\n\nSets the access token to use for authentication\n\n### patch\n\n```python\nufirestore.patch(PATH, DOC, update_mask=[], bg=True, cb=None)\n```\n\nUpdates or inserts a document `DOC` at the location `PATH`\n\n-   Set the fields to update with `update_mask`\n-   Optional run in the background with `bg`\n-   Set a callback function after getting data with `cb`\n\n#### Example\n\n```python\ndoc = FirebaseJson()\ndoc.set(\"age/integerValue\", 21)\n\nresponse = ufirestore.patch(\"users/234\", doc, [\"age\"], False)\nprint(response)\n```\n\n### create\n\n```python\nufirestore.create(PATH, DOC, document_id=None, bg=True, cb=None)\n```\n\nCreates a new document `DOC` at the collection at location `PATH`\n\n-   `document_id` - The document ID to use for the document. If not specified, an ID will be generated\n-   Optional run in the background with `bg`\n-   Set a callback function after getting data with `cb`\n\n#### Example\n\n```python\ndoc = FirebaseJson()\ndoc.set(\"name/stringValue\", \"Jane Doe\")\ndoc.set(\"age/integerValue\", 25)\ndoc.set(\"height/integerValue\", 165)\n\nresponse = ufirestore.create(\"users\", doc, bg=False)\nprint(response)\n```\n\n### get\n\n```python\nufirestore.get(PATH, mask=None, bg=True, cb=None)\n```\n\nGets a single document at location `PATH`\n\n-   `document_id` - The document ID to use for the document. If not specified, an ID will be generated\n-   `mask` - The fields to return\n-   Optional run in the background with `bg`\n-   Set a callback function after getting data with `cb`\n\n#### Example\n\n```python\nresponse = ufirestore.get(\"users/129\", bg=False)\ndoc = FirebaseJson.from_raw(response)\n\nif doc.exists(\"fields/name\"):\n    print(\"Hello, %s\" % doc.get(\"fields/name\"))\n```\n\n### getfile\n\n```python\nufirestore.getfile(PATH, FILENAME, mask=None, bg=True, cb=None)\n```\n\nGets a single document at location `PATH` and writes it to file `FILENAME`\n\n-   `document_id` - The document ID to use for the document. If not specified, an ID will be generated\n-   `mask` - The fields to return\n-   Optional run in the background with `bg`\n-   Set a callback function after getting data with `cb`\n\n#### Example\n\n```python\nufirestore.getfile(\"users/129\", \"user.json\")\n```\n\n### delete\n\n```python\nufirestore.delete(PATH, bg=True, cb=None)\n```\n\nDeletes a document at location `PATH`\n\n-   Optional run in the background with `bg`\n-   Set a callback function after getting data with `cb`\n\n#### Example\n\n```python\nsuccess = ufirestore.delete(\"users/129\")\n\nif success:\n    print(\"User data successfully deleted.\")\n```\n\n### list\n\n```python\nufirestore.list(PATH, page_size=None, page_token=None, order_by=None, mask=None, show_missing=None, bg=True, cb=None)\n```\n\nLists documents at location `PATH`\n\n-   `page_size` - The number of documents to return\n-   `page_token` - The `next_page_token` returned from a previous `list` option\n-   `order_by` - The order to sort results by. For example: `priority desc, name`\n-   `mask` - The fields to return. If not set, return all fields\n-   `show_missing` - If the list should show missing documents\n-   Optional run in the background with `bg`\n-   Set a callback function after getting data with `cb`\n\n#### Example\n\n```python\ndocuments, next_page_token = ufirestore.list(\"users\", bg=False)\n\nfor document in documents:\n    doc = FirebaseJson.from_raw(document)\n    if doc.exists(\"fields/age\"):\n        print(\"Age: %s\" % doc.get(\"fields/age\"))\n```\n\n### list_collection_ids\n\n```python\nufirestore.list_collection_ids(PATH, page_size=None, page_token=None, bg=True, cb=None)\n```\n\nLists all the collection IDs underneath a document at `PATH`\n\n-   `page_size` - The maximum number of results to return\n-   `page_token` - A page token\n-   Optional run in the background with `bg`\n-   Set a callback function after getting data with `cb`\n\n#### Example\n\n```python\ncollection_ids, next_page_token = ufirestore.list_collection_ids(\"rooms/28\", bg=False)\n\nfor collection_id in collection_ids:\n    print(\"ID: %s\" % collection_id)\n```\n\n### run_query\n\n```python\nufirestore.run_query(PATH, query, bg=True, cb=None)\n```\n\nRuns a query at location `PATH`\n\n-   Optional run in the background with `bg`\n-   Set a callback function after getting data with `cb`\n\n#### Example\n\n```python\nfrom ufirestore.json import FirebaseJson, Query\n\nquery = Query().from_(\"users\").where(\"age\", \"\u003e=\", 18)\nraw_doc = ufirestore.run_query(\"\", query, bg=False)\ndoc = FirebaseJson.from_raw(raw_doc)\n\nif doc.exists(\"fields/name\"):\n    print(\"Resulted with user named %s\" % doc.get(\"fields/name\"))\n```\n\n## FirebaseJson\n\nA simple helper class for Firebase document JSON data\n\n### set\n\n```python\ndoc.set(path, value, with_type=False)\n```\n\nEdit, overwrite or create new node at the specified path\n\n-   `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)\n\n### get\n\n```python\ndoc.get(path, default=None)\n```\n\nGet the node value at a given path, returning `default` if the path does not exist\n\n### add\n\n```python\ndoc.add(path, name, value)\n```\n\nAdd a new node at the path, with name `name` and contents `value`\n\n### add_item\n\n```python\ndoc.add_item(path, value)\n```\n\nAdds an array item to the node at the path\n\n### remove\n\n```python\ndoc.remove(path)\n```\n\nRemoves the node at the path\n\n### exists\n\n```python\ndoc.exists(path)\n```\n\nChecks whether a node exists at the path\n\n### process\n\n```python\ndoc.process(resource_name)\n```\n\nProcesses json instance into a `dict` for usage with Firestore API\n\nNOTE: All the functions in this library that require a document actually require the `FirebaseJon` instance and runs `process` behind the scenes\n\n### FirebaseJson.from_raw\n\n```python\nFirebaseJson.from_raw(raw_doc)\n```\n\nParses a raw document object from the Firestore API into a `FirebaseJson` instance\n\n### Extra methods\n\n### FirebaseJson.to_value_type\n\n```python\nFirebaseJson.to_value_type(value)\n```\n\nInfers 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)\n\n#### Example\n\n```python\nvalue = 35\n\ndata = FirebaseJson.to_value_type(value)\n\nprint(data) # Returns {\"integerValue\": \"35\"}\n```\n\n### FirebaseJson.from_value_type\n\n```python\nFirebaseJson.from_value_type(value)\n```\n\nTakes a Firestore Document [Value](https://cloud.google.com/firestore/docs/reference/rest/v1/Value) object and returns its value, casted to the correct type\n\n#### Example\n\n```python\n# Example data from API\ndata = {\n    \"arrayValue\": {\n        \"values\": [\n            {\"stringValue\": \"a\"},\n            {\"stringValue\": \"b\"},\n            {\"integerValue\": \"3\"}\n        ]\n    }\n}\n\nprint(value) # Returns [\"a\", \"b\", 3]\n```\n\n## Query\n\nWrapper over `FirebaseJson` to easily create document queries\n\nExtends all `FirebaseJson` methods\n\n### from\\_\n\n```python\nquery.from_(collection_id, all_descendants=False)\n```\n\n-   `collection_id` - When set, selects only collections with this ID\n-   `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\n\n### select\n\n```python\nquery.select(field)\n```\n\nAdds a document field to return\n\n### order_by\n\n```python\nquery.order_by(field, direction=\"DESCENDING\")\n```\n\n-   `field` - The field to order by\n-   `direction` - The direction to order by (`ASCENDING` or `DESCENDING`)\n\n### limit\n\n```python\nquery.limit(value)\n```\n\nThe maximum number of results to return, `value` must be \u003e= 0\n\n### where\n\n```python\nquery.where(field, op, value)\n```\n\nApplies a filter on a specific field.\n\n-   `field` - The field to filter by\n-   `op` - The operation to filter by, is one of `\u003c`, `\u003c=`, `\u003e`, `\u003e=`, `==`, `!=`, `array-contains`, `in`, `array-contains-any`, `not-in`\n-   `value` - The value to compare to, type is inferred with `FirebaseJson.to_value_type`\n\n### process\n\n```python\nquery.process()\n```\n\nReturns `dict` data of query for use with Firestore API\n\nNOTE: This function is already used in the `run_query` function\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWoolDoughnut310%2Fmicropython-firebase-firestore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWoolDoughnut310%2Fmicropython-firebase-firestore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWoolDoughnut310%2Fmicropython-firebase-firestore/lists"}