Metadata-Version: 2.1
Name: micropython-firebase-firestore
Version: 1.0.0
Summary: Firebase Firestore implementation for Micropython optimized for ESP32.
Home-page: https://github.com/WoolDoughnut310/micropython-firebase-firestore
Author: WoolDoughnut310
Author-email: wooldoughnutspi@outlook.com
License: UNKNOWN
Description: # 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
        
Platform: UNKNOWN
Description-Content-Type: text/markdown
