feat(firestore): add add() method

Author: AsifArmanRahman

firebase/firestore/__init__.py

@@ -17,7 +17,7 @@
 from google.cloud.firestore import Client
 from google.cloud.firestore_v1._helpers import *
 
-from ._utils import _from_datastore
+from ._utils import _from_datastore, _to_datastore
 from firebase._exception import raise_detailed_error
 
 
@@ -96,6 +96,50 @@ def __init__(self, collection_path, api_key, credentials, project_id, requests):
 		if self._credentials:
 			self.__datastore = Client(credentials=self._credentials, project=self._project_id)
 
+	def add(self, data, token=None):
+		""" Create a document in the Firestore database with the
+		provided data using an auto generated ID for the document.
+
+
+		:type data: dict
+		:param data: Data to be stored in firestore.
+
+		:type token: str
+		:param token: (Optional) Firebase Auth User ID Token, defaults
+			to :data:`None`.
+
+
+		:return: returns the auto generated document ID, used to store
+			the data.
+		:rtype: str
+		"""
+
+		path = self._path.copy()
+		self._path.clear()
+
+		if self._credentials:
+			db_ref = _build_db(self.__datastore, path)
+
+			response = db_ref.add(data)
+
+			return response[1].id
+
+		else:
+			req_ref = f"{self._base_url}/{'/'.join(path)}?key={self._api_key}"
+
+			if token:
+				headers = {"Authorization": "Firebase " + token}
+				response = self._requests.post(req_ref, headers=headers, json=_to_datastore(data))
+
+			else:
+				response = self._requests.post(req_ref, json=_to_datastore(data))
+
+			raise_detailed_error(response)
+
+			doc_id = response.json()['name'].split('/')
+
+			return doc_id.pop()
+
 	def document(self, document_id):
 		""" A reference to a document in a collection.
 

firebase/firestore/_utils.py

@@ -5,7 +5,9 @@
 # --------------------------------------------------------------------------------------
 
 
-from base64 import b64decode
+from datetime import datetime
+from base64 import b64encode, b64decode
+from google.protobuf.json_format import MessageToDict
 from google.cloud.firestore_v1._helpers import GeoPoint
 from google.api_core.datetime_helpers import DatetimeWithNanoseconds
 
@@ -92,3 +94,96 @@ def _decode_datastore(value):
 
 	else:
 		raise TypeError("Cannot convert to a Python Value", value, "Invalid type", type(value))
+
+
+def _to_datastore(data):
+	""" Converts a Python dictionary ``data``-s to map of Firestore.
+
+
+	:type data: dict
+	:param data: A Python dictionary containing data.
+
+
+	:return: A map of Firebase values converted from the ``data``.
+	:rtype: dict
+
+	:raises ValueError: Raised when a key in the python dictionary is
+		Non-alphanum char without *`* (ticks) at start and end.
+	"""
+
+	restructured_data = {}
+
+	for key, val in data.items():
+
+		if ' ' in key and (not key.startswith('`') or not key.endswith('`')):
+			raise ValueError(f'Non-alphanum char in element with leading alpha: {key}')
+
+		key = str(key)
+
+		if isinstance(val, dict):
+			restructured_data[key] = {'mapValue': _to_datastore(val)}
+
+		elif isinstance(val, list):
+			arr = []
+
+			for x in val:
+				arr.append(_encode_datastore_value(x))
+
+			restructured_data[key] = {'arrayValue': {'values': arr}}
+
+		else:
+			restructured_data[key] = _encode_datastore_value(val)
+
+	return {'fields': restructured_data}
+
+
+def _encode_datastore_value(value):
+	""" Converts a Python ``value`` to a Firebase value.
+
+
+	:type value: :data:`None` or :class:`bool` or :class:`bytes`
+		or :class:`int` or :class:`float` or :class:`str` or
+		:class:`dict` or :class:`~datetime.datetime` or
+		:class:`~google.api_core.datetime_helpers.DatetimeWithNanoseconds`
+		or  :class:`~google.cloud.firestore_v1._helpers.GeoPoint`.
+	:param value: A Python data to be encoded/converted to Firebase.
+
+
+	:return: A Firebase value converted from ``value``.
+	:rtype: dict
+
+	:raises TypeError: Raised when unsupported data type given.
+	"""
+
+	if value is None:
+		return {'nullValue': value}
+
+	elif isinstance(value, bytes):
+		return {'bytesValue': b64encode(value).decode('utf-8')}
+
+	elif isinstance(value, bool):
+		return {'booleanValue': value}
+
+	elif isinstance(value, int):
+		return {'integerValue': value}
+
+	elif isinstance(value, float):
+		return {'doubleValue': value}
+
+	elif isinstance(value, str):
+		return {'stringValue': value}
+
+	elif isinstance(value, dict):
+		return {'mapValue': _to_datastore(value)}
+
+	elif isinstance(value, datetime):
+		return {'timestampValue': value.strftime("%Y-%m-%dT%H:%M:%S.%fZ")}
+
+	elif isinstance(value, DatetimeWithNanoseconds):
+		return {'timestampValue': value.rfc3339()}
+
+	elif isinstance(value, GeoPoint):
+		return {'geoPointValue': MessageToDict(value.to_protobuf())}
+	else:
+
+		raise TypeError("Cannot convert to a Firestore Value", value, "Invalid type", type(value))