update README.md

Author: kengoon

README.md

@@ -1,3 +1,5 @@
+from turtle import Screen
+
 # sj-firebase-python
  Implement Firebase Java SDK in Python
 
@@ -11,8 +13,8 @@
 ## Usage
 ### Buildozer Android project
 ```properties
-android.gradle_dependencies = io.github.simplejnius:sjfirebase:0.3.0
-requirements = https://github.com/SimpleJnius/sj-firebase-python/archive/refs/heads/master.zip
+android.gradle_dependencies = io.github.simplejnius:sjfirebase:1.3.2
+requirements = sjfirebase
 ```
 The current version of [python-for-android](https://github.com/kivy/python-for-android) 
 lacks support for incorporating bom dependencies, modifying the classpath, and copying the `google-service.json`. 
@@ -22,7 +24,7 @@ make adjustments to the specified section using the provided values below:
 ```properties
 android.api = 34
 android.enable_androidx = True
-android.gradle_dependencies = io.github.simplejnius:sjfirebase:1.0.0,
+android.gradle_dependencies = io.github.simplejnius:sjfirebase:1.3.2,
     com.google.firebase:firebase-auth,com.google.firebase:firebase-database,
     com.google.firebase:firebase-firestore,com.google.firebase:firebase-storage,
     com.google.firebase:firebase-analytics
@@ -39,6 +41,113 @@ pip install sjfirebase
 # buildozer.spec
 requirements = sjfirebase
 ```
+
+## Sample Code Documentation
+
+**To add, set, update, and delete a document in a collection**
+```python
+from kivy.uix.screenmanager import Screen  # noqa
+from sjfirebase.tools.mixin import FirestoreMixin
+
+
+class MyScreen(Screen, FirestoreMixin):
+    
+    def on_event1(self):
+        data = dict(name=self.ids.name.text, email=self.ids.email.text)
+        
+        # creates a new document in "individual" collection and
+        # passes a success(True/False) and error(None or FirebaseException)
+        # parameters to your callback
+        self.add_document("individuals", data, lambda success, error: print(success, error))
+    
+    def on_event2(self):
+        data = dict(name=self.ids.name.text, email=self.ids.email.text)
+        
+        # creates a new or overwrite document "custom_document_id" in collection
+        # and passes a success(True/False) and error(None or FirebaseException)
+        # parameters to your callback
+        self.set_document("individual/custom_document_id", data, lambda success, error: print(success, error))
+    
+    def on_event3(self):
+        data = dict(name=self.ids.name.text, email=self.ids.email.text)
+        
+        # creates a new or update document "custom_document_id" in collection
+        # and passes a success(True/False) and error(None or FirebaseException)
+        # parameters to your callback
+        self.set_document("individual/custom_document_id", data, lambda success, error: print(success, error), merge=True)
+    
+    def on_event4(self):
+        data = ["name", self.ids.name.text, "email", self.ids.email.text]
+        
+        # creates a new or overwrite document "custom_document_id" in collection
+        # and passes a success(True/False) and error(None or FirebaseException)
+        # parameters to your callback.
+        # Notice the data is a list, and this list must be an even length and not odd length.
+        # Every odd values are the key while the even values are the value.
+        # E.g in the above `data` `name` is the key while `self.ids.name.text` is the value
+        # same goes with the email. It's this way due to the varargs nature of the Firestore `update` method
+        # signature
+        self.update_document("individual/custom_document_id", data, lambda success, error: print(success, error))
+        
+    def on_event5(self):
+        # deletes document "custom_document_id"
+        self.delete_document("individual/custom_document_id", lambda success, error: print(success, error))
+
+# NB: You can instantiate the FirestoreMixing directly
+# E.g
+f = FirestoreMixin()
+f.add_document(...)
+f.set_document(...)
+# etc..
+```
+
+**To get-data, paginate-data, and get-realtime-updates**
+```python
+from kivy.uix.screenmanager import Screen  # noqa
+from sjfirebase.tools.mixin import FirestoreMixin
+
+
+class MyScreen(Screen, FirestoreMixin):
+    def on_event1(self):
+        # gets a dictionary of data from "document_id" if any data and passes
+        # `success` (True/False) and `data` (dict/errorMessage).
+        # always check if success is True before accessing items from data,
+        # or check if data is an instance of dict. Else log the data to see the error message
+        self.get_document("individual/document_id", lambda success, data: print(success, data))
+    
+    def on_event2(self):
+        # everything @on_event1 plus `source` that states where the data should be fetched.
+        # either cache, server or default. cache gets from firebase data stored locally
+        # on the device for offline purposes while server gets from firebase cloud directly.
+        # default can be either cache or cloud depending on your configuration.
+        self.get_document("individual/document_id", lambda success, data: print(success, data), source="cache")
+    
+    def on_event3(self):
+        # gets all document at "individual" collection and passes success and data argument.
+        # here, data is a list of dict. before accessing, refer to @on_event1
+        self.get_collection_of_documents("individual", lambda success, data: print(success, data))
+    
+    def on_event4(self):
+        # refer to @on_event2 for "source" and @on_event3 for functionality description
+        self.get_collection_of_documents("individual", lambda success, data: print(success, data), source="cache")
+
+    def on_event5(self):
+        # refer to @on_event3 for functionality description. The new thing here is `limit`.
+        # limit is used to limit the amount of data you fetch from firebase and paginate as you go.
+        self.get_pagination_of_documents("individual", 10, lambda success, data: print(success, data))
+
+    def on_event6(self):
+        # listens for document changes and returns a dict of data and location
+        # where the data is coming from. `data`(dict/errorMessage), where("Local"/"Server")
+        self.add_document_snapshot_listener("individual/document_id", lambda data, where: print(data, where))
+    
+    def on_event7(self):
+        # same as @on_event6 but gets a list of document with information on whether they were
+        # added, removed or modified
+        self.add_collection_snapshot_listener("individual", lambda data, where: print(data, where))
+```
+
+
 ### Python API
 #### ActionCodeSettings
 ```python

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sjfirebase"
-version = "1.4.0"
+version = "1.5.0"
 description = "Implement Firebase Java SDK in python"
 authors = ["Kenechukwu Akubue <kengoon19@gmail.com>"]
 readme = "README.md"