firebase-functions 0.1.2__tar.gz → 0.3.0__tar.gz

{firebase_functions-0.1.2 → firebase_functions-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: firebase_functions
-Version: 0.1.2
+Version: 0.3.0
 Summary: Firebase Functions Python SDK
 Home-page: https://github.com/firebase/firebase-functions-python
 Author: Firebase Team

{firebase_functions-0.1.2 → firebase_functions-0.3.0}/setup.py

@@ -56,6 +56,8 @@ setup(
     extras_require={'dev': dev_requires},
     packages=find_packages(where='src'),
     package_dir={'': 'src'},
+    include_package_data=True,
+    package_data={'firebase_functions': ['py.typed']},
     python_requires='>=3.10',
     classifiers=[
         'Development Status :: 4 - Beta',

{firebase_functions-0.1.2 → firebase_functions-0.3.0}/src/firebase_functions/__init__.py

@@ -15,4 +15,4 @@
 Firebase Functions for Python.
 """
 
-__version__ = "0.1.2"
+__version__ = "0.3.0"

{firebase_functions-0.1.2 → firebase_functions-0.3.0}/src/firebase_functions/alerts_fn.py

@@ -46,7 +46,7 @@ class AlertEvent(_CloudEvent[T]):
     app_id: str | None
     """
     The Firebase App ID that's associated with the alert. This is optional,
-    and only present when the alert is targeting at a specific Firebase App.
+    and only present when the alert is targeting a specific Firebase App.
     """
 
 
@@ -66,7 +66,7 @@ def on_alert_published(
     **kwargs
 ) -> _typing.Callable[[OnAlertPublishedCallable], OnAlertPublishedCallable]:
     """
-    Event handler which triggers when a Firebase Alerts event is published.
+    Event handler that triggers when a Firebase Alerts event is published.
 
     Example:
 

{firebase_functions-0.1.2 → firebase_functions-0.3.0}/src/firebase_functions/core.py

@@ -25,7 +25,7 @@ T = _typing.TypeVar("T")
 class CloudEvent(_typing.Generic[T]):
     """
     A CloudEvent is the base of a cross-platform format for encoding a serverless event.
-    More information can be found at https://github.com/cloudevents/spec
+    More information can be found at https://github.com/cloudevents/spec.
     """
 
     specversion: str

{firebase_functions-0.1.2 → firebase_functions-0.3.0}/src/firebase_functions/db_fn.py

@@ -61,7 +61,7 @@ class Event(_core.CloudEvent[T]):
 
     params: dict[str, str]
     """
-    An dict containing the values of the path patterns.
+    A dict containing the values of the path patterns.
     Only named capture groups are populated - {key}, {key=*}, {key=**}
     """
 
@@ -125,7 +125,7 @@ def _db_endpoint_handler(
 @_util.copy_func_kwargs(DatabaseOptions)
 def on_value_written(**kwargs) -> _typing.Callable[[_C1], _C1]:
     """
-    Event handler which triggers when data is created, updated, or deleted in Realtime Database.
+    Event handler that triggers when data is created, updated, or deleted in Realtime Database.
 
     Example:
 
@@ -175,7 +175,7 @@ def on_value_written(**kwargs) -> _typing.Callable[[_C1], _C1]:
 @_util.copy_func_kwargs(DatabaseOptions)
 def on_value_updated(**kwargs) -> _typing.Callable[[_C1], _C1]:
     """
-    Event handler which triggers when data is updated in Realtime Database.
+    Event handler that triggers when data is updated in Realtime Database.
 
     Example:
 
@@ -225,7 +225,7 @@ def on_value_updated(**kwargs) -> _typing.Callable[[_C1], _C1]:
 @_util.copy_func_kwargs(DatabaseOptions)
 def on_value_created(**kwargs) -> _typing.Callable[[_C2], _C2]:
     """
-    Event handler which triggers when data is created in Realtime Database.
+    Event handler that triggers when data is created in Realtime Database.
 
     Example:
 
@@ -275,7 +275,7 @@ def on_value_created(**kwargs) -> _typing.Callable[[_C2], _C2]:
 @_util.copy_func_kwargs(DatabaseOptions)
 def on_value_deleted(**kwargs) -> _typing.Callable[[_C2], _C2]:
     """
-    Event handler which triggers when data is deleted in Realtime Database.
+    Event handler that triggers when data is deleted in Realtime Database.
 
     Example:
 

{firebase_functions-0.1.2 → firebase_functions-0.3.0}/src/firebase_functions/firestore_fn.py

@@ -38,6 +38,11 @@ _event_type_created = "google.cloud.firestore.document.v1.created"
 _event_type_updated = "google.cloud.firestore.document.v1.updated"
 _event_type_deleted = "google.cloud.firestore.document.v1.deleted"
 
+_event_type_written_with_auth_context = "google.cloud.firestore.document.v1.written.withAuthContext"
+_event_type_created_with_auth_context = "google.cloud.firestore.document.v1.created.withAuthContext"
+_event_type_updated_with_auth_context = "google.cloud.firestore.document.v1.updated.withAuthContext"
+_event_type_deleted_with_auth_context = "google.cloud.firestore.document.v1.deleted.withAuthContext"
+
 
 @_dataclass.dataclass(frozen=True)
 class Event(_core.CloudEvent[_core.T]):
@@ -82,9 +87,26 @@ _E2 = Event[DocumentSnapshot | None]
 _C1 = _typing.Callable[[_E1], None]
 _C2 = _typing.Callable[[_E2], None]
 
+AuthType = _typing.Literal["service_account", "api_key", "system",
+                           "unauthenticated", "unknown"]
+
+
+@_dataclass.dataclass(frozen=True)
+class AuthEvent(Event[_core.T]):
+    auth_type: AuthType
+    """The type of principal that triggered the event"""
+    auth_id: str | None
+    """The unique identifier for the principal"""
+
+
+_E3 = AuthEvent[Change[DocumentSnapshot | None]]
+_E4 = AuthEvent[DocumentSnapshot | None]
+_C3 = _typing.Callable[[_E3], None]
+_C4 = _typing.Callable[[_E4], None]
+
 
 def _firestore_endpoint_handler(
-    func: _C1 | _C2,
+    func: _C1 | _C2 | _C3 | _C4,
     event_type: str,
     document_pattern: _path_pattern.PathPattern,
     raw: _ce.CloudEvent,
@@ -94,12 +116,14 @@ def _firestore_endpoint_handler(
     firestore_event_data: _firestore.DocumentEventData
     content_type: str = event_attributes["datacontenttype"]
     if "application/json" in content_type or isinstance(event_data, dict):
-        firestore_event_data = _firestore.DocumentEventData.from_json(
-            event_data)
+        firestore_event_data = _typing.cast(
+            _firestore.DocumentEventData,
+            _firestore.DocumentEventData.from_json(event_data))
     elif "application/protobuf" in content_type or isinstance(
             event_data, bytes):
-        firestore_event_data = _firestore.DocumentEventData.deserialize(
-            event_data)
+        firestore_event_data = _typing.cast(
+            _firestore.DocumentEventData,
+            _firestore.DocumentEventData.deserialize(event_data))
     else:
         actual_type = type(event_data)
         raise TypeError(f"Firestore: Cannot parse event payload of data type "
@@ -110,6 +134,8 @@ def _firestore_endpoint_handler(
     event_namespace = event_attributes["namespace"]
     event_document = event_attributes["document"]
     event_database = event_attributes["database"]
+    event_auth_type = event_attributes["authtype"]
+    event_auth_id = event_attributes["authid"]
 
     time = event_attributes["time"]
     event_time = _util.timestamp_conversion(time)
@@ -146,18 +172,23 @@ def _firestore_endpoint_handler(
             firestore_event_data.old_value.update_time,
         )
     if event_type == _event_type_deleted:
-        firestore_event_data = old_value_snapshot
+        firestore_event_data = _typing.cast(_firestore.DocumentEventData,
+                                            old_value_snapshot)
     if event_type == _event_type_created:
-        firestore_event_data = value_snapshot
+        firestore_event_data = _typing.cast(_firestore.DocumentEventData,
+                                            value_snapshot)
     if event_type in (_event_type_written, _event_type_updated):
-        firestore_event_data = Change(
-            before=old_value_snapshot,
-            after=value_snapshot,
-        )
+        firestore_event_data = _typing.cast(
+            _firestore.DocumentEventData,
+            Change(
+                before=old_value_snapshot,
+                after=value_snapshot,
+            ))
 
     params: dict[str, str] = {
         **document_pattern.extract_matches(event_document),
     }
+
     database_event = Event(
         project=event_project,
         namespace=event_namespace,
@@ -173,7 +204,15 @@ def _firestore_endpoint_handler(
         subject=event_attributes["subject"],
         params=params,
     )
-    func(database_event)
+
+    if event_type.endswith(".withAuthContext"):
+        database_event_with_auth_context = AuthEvent(**vars(database_event),
+                                                     auth_type=event_auth_type,
+                                                     auth_id=event_auth_id)
+        func(database_event_with_auth_context)
+    else:
+        # mypy cannot infer that the event type is correct, hence the cast
+        _typing.cast(_C1 | _C2, func)(database_event)
 
 
 @_util.copy_func_kwargs(FirestoreOptions)
@@ -224,6 +263,57 @@ def on_document_written(**kwargs) -> _typing.Callable[[_C1], _C1]:
     return on_document_written_inner_decorator
 
 
+@_util.copy_func_kwargs(FirestoreOptions)
+def on_document_written_with_auth_context(**kwargs
+                                         ) -> _typing.Callable[[_C1], _C1]:
+    """
+    Event handler that triggers when a document is created, updated, or deleted in Firestore.
+    This trigger will also provide the authentication context of the principal who triggered 
+    the event.
+
+    Example:
+
+    .. code-block:: python
+
+      @on_document_written_with_auth_context(document="*")
+      def example(event: AuthEvent[Change[DocumentSnapshot]]) -> None:
+          pass
+
+    :param \\*\\*kwargs: Firestore options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.FirestoreOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.firestore_fn.AuthEvent` \\[
+            :exc:`firebase_functions.db.Change` \\] \\], `None` \\]
+            A function that takes a Firestore event and returns ``None``.
+    """
+    options = FirestoreOptions(**kwargs)
+
+    def on_document_written_with_auth_context_inner_decorator(func: _C1):
+        document_pattern = _path_pattern.PathPattern(
+            _util.normalize_path(options.document))
+
+        @_functools.wraps(func)
+        def on_document_written_with_auth_context_wrapped(raw: _ce.CloudEvent):
+            return _firestore_endpoint_handler(
+                func,
+                _event_type_written_with_auth_context,
+                document_pattern,
+                raw,
+            )
+
+        _util.set_func_endpoint_attr(
+            on_document_written_with_auth_context_wrapped,
+            options._endpoint(
+                event_type=_event_type_written,
+                func_name=func.__name__,
+                document_pattern=document_pattern,
+            ),
+        )
+        return on_document_written_with_auth_context_wrapped
+
+    return on_document_written_with_auth_context_inner_decorator
+
+
 @_util.copy_func_kwargs(FirestoreOptions)
 def on_document_updated(**kwargs) -> _typing.Callable[[_C1], _C1]:
     """
@@ -272,6 +362,57 @@ def on_document_updated(**kwargs) -> _typing.Callable[[_C1], _C1]:
     return on_document_updated_inner_decorator
 
 
+@_util.copy_func_kwargs(FirestoreOptions)
+def on_document_updated_with_auth_context(**kwargs
+                                         ) -> _typing.Callable[[_C1], _C1]:
+    """
+    Event handler that triggers when a document is updated in Firestore.
+    This trigger will also provide the authentication context of the principal who triggered 
+    the event.
+
+    Example:
+
+    .. code-block:: python
+
+      @on_document_updated_with_auth_context(document="*")
+      def example(event: AuthEvent[Change[DocumentSnapshot]]) -> None:
+          pass
+
+    :param \\*\\*kwargs: Firestore options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.FirestoreOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.firestore_fn.AuthEvent` \\[
+            :exc:`firebase_functions.db.Change` \\] \\], `None` \\]
+            A function that takes a Firestore event and returns ``None``.
+    """
+    options = FirestoreOptions(**kwargs)
+
+    def on_document_updated_with_auth_context_inner_decorator(func: _C1):
+        document_pattern = _path_pattern.PathPattern(
+            _util.normalize_path(options.document))
+
+        @_functools.wraps(func)
+        def on_document_updated_with_auth_context_wrapped(raw: _ce.CloudEvent):
+            return _firestore_endpoint_handler(
+                func,
+                _event_type_updated_with_auth_context,
+                document_pattern,
+                raw,
+            )
+
+        _util.set_func_endpoint_attr(
+            on_document_updated_with_auth_context_wrapped,
+            options._endpoint(
+                event_type=_event_type_updated_with_auth_context,
+                func_name=func.__name__,
+                document_pattern=document_pattern,
+            ),
+        )
+        return on_document_updated_with_auth_context_wrapped
+
+    return on_document_updated_with_auth_context_inner_decorator
+
+
 @_util.copy_func_kwargs(FirestoreOptions)
 def on_document_created(**kwargs) -> _typing.Callable[[_C2], _C2]:
     """
@@ -320,6 +461,57 @@ def on_document_created(**kwargs) -> _typing.Callable[[_C2], _C2]:
     return on_document_created_inner_decorator
 
 
+@_util.copy_func_kwargs(FirestoreOptions)
+def on_document_created_with_auth_context(**kwargs
+                                         ) -> _typing.Callable[[_C2], _C2]:
+    """
+    Event handler that triggers when a document is created in Firestore.
+    This trigger will also provide the authentication context of the principal who triggered 
+    the event.
+
+    Example:
+
+    .. code-block:: python
+
+        @on_document_created_with_auth_context(document="*")
+        def example(event: AuthEvent[DocumentSnapshot]):
+          pass
+
+    :param \\*\\*kwargs: Firestore options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.FirestoreOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.firestore_fn.AuthEvent` \\[
+            :exc:`object` \\] \\], `None` \\]
+            A function that takes a Firestore event and returns ``None``.
+    """
+    options = FirestoreOptions(**kwargs)
+
+    def on_document_created_with_auth_context_inner_decorator(func: _C2):
+        document_pattern = _path_pattern.PathPattern(
+            _util.normalize_path(options.document))
+
+        @_functools.wraps(func)
+        def on_document_created_with_auth_context_wrapped(raw: _ce.CloudEvent):
+            return _firestore_endpoint_handler(
+                func,
+                _event_type_created_with_auth_context,
+                document_pattern,
+                raw,
+            )
+
+        _util.set_func_endpoint_attr(
+            on_document_created_with_auth_context_wrapped,
+            options._endpoint(
+                event_type=_event_type_created_with_auth_context,
+                func_name=func.__name__,
+                document_pattern=document_pattern,
+            ),
+        )
+        return on_document_created_with_auth_context_wrapped
+
+    return on_document_created_with_auth_context_inner_decorator
+
+
 @_util.copy_func_kwargs(FirestoreOptions)
 def on_document_deleted(**kwargs) -> _typing.Callable[[_C2], _C2]:
     """
@@ -366,3 +558,54 @@ def on_document_deleted(**kwargs) -> _typing.Callable[[_C2], _C2]:
         return on_document_deleted_wrapped
 
     return on_document_deleted_inner_decorator
+
+
+@_util.copy_func_kwargs(FirestoreOptions)
+def on_document_deleted_with_auth_context(**kwargs
+                                         ) -> _typing.Callable[[_C2], _C2]:
+    """
+    Event handler that triggers when a document is deleted in Firestore.
+    This trigger will also provide the authentication context of the principal who triggered 
+    the event.
+
+    Example:
+
+    .. code-block:: python
+
+      @on_document_deleted_with_auth_context(document="*")
+      def example(event: AuthEvent[DocumentSnapshot]) -> None:
+          pass
+
+    :param \\*\\*kwargs: Firestore options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.FirestoreOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.firestore_fn.AuthEvent` \\[
+            :exc:`object` \\] \\], `None` \\]
+            A function that takes a Firestore event and returns ``None``.
+    """
+    options = FirestoreOptions(**kwargs)
+
+    def on_document_deleted_with_auth_context_inner_decorator(func: _C2):
+        document_pattern = _path_pattern.PathPattern(
+            _util.normalize_path(options.document))
+
+        @_functools.wraps(func)
+        def on_document_deleted_with_auth_context_wrapped(raw: _ce.CloudEvent):
+            return _firestore_endpoint_handler(
+                func,
+                _event_type_deleted_with_auth_context,
+                document_pattern,
+                raw,
+            )
+
+        _util.set_func_endpoint_attr(
+            on_document_deleted_with_auth_context_wrapped,
+            options._endpoint(
+                event_type=_event_type_deleted_with_auth_context,
+                func_name=func.__name__,
+                document_pattern=document_pattern,
+            ),
+        )
+        return on_document_deleted_with_auth_context_wrapped
+
+    return on_document_deleted_with_auth_context_inner_decorator

{firebase_functions-0.1.2 → firebase_functions-0.3.0}/src/firebase_functions/https_fn.py

@@ -119,9 +119,9 @@ class FunctionsErrorCode(str, _enum.Enum):
 
     INTERNAL = "internal"
     """
-    Internal errors. Means some invariants expected by
+    Internal errors. Means some invariants expected by the
     underlying system have been broken. If you see one of these errors,
-    something is very broken.
+    something is severely broken.
     """
 
     UNAVAILABLE = "unavailable"
@@ -135,6 +135,9 @@ class FunctionsErrorCode(str, _enum.Enum):
     Unrecoverable data loss or corruption.
     """
 
+    def __str__(self) -> str:
+        return self.value
+
 
 class _CanonicalErrorCodeName(str, _enum.Enum):
     """The canonical error code name for a given error code."""
@@ -157,6 +160,9 @@ class _CanonicalErrorCodeName(str, _enum.Enum):
     UNAVAILABLE = "UNAVAILABLE"
     DATA_LOSS = "DATA_LOSS"
 
+    def __str__(self) -> str:
+        return self.value
+
 
 @_dataclasses.dataclass(frozen=True)
 class _HttpErrorCode:
@@ -280,7 +286,7 @@ class AuthData:
     The interface for Auth tokens verified in Callable functions
     """
 
-    uid: str
+    uid: str | None
     """
     User ID of the ID token.
     """
@@ -346,8 +352,10 @@ _C1 = _typing.Callable[[Request], Response]
 _C2 = _typing.Callable[[CallableRequest[_typing.Any]], _typing.Any]
 
 
-def _on_call_handler(func: _C2, request: Request,
-                     enforce_app_check: bool) -> Response:
+def _on_call_handler(func: _C2,
+                     request: Request,
+                     enforce_app_check: bool,
+                     verify_token: bool = True) -> Response:
     try:
         if not _util.valid_on_call_request(request):
             _logging.error("Invalid request, unable to process.")
@@ -357,7 +365,8 @@ def _on_call_handler(func: _C2, request: Request,
             data=_json.loads(request.data)["data"],
         )
 
-        token_status = _util.on_call_check_tokens(request)
+        token_status = _util.on_call_check_tokens(request,
+                                                  verify_token=verify_token)
 
         if token_status.auth == _util.OnCallTokenState.INVALID:
             raise HttpsError(FunctionsErrorCode.UNAUTHENTICATED,
@@ -377,8 +386,10 @@ def _on_call_handler(func: _C2, request: Request,
         if token_status.auth_token is not None:
             context = _dataclasses.replace(
                 context,
-                auth=AuthData(token_status.auth_token["uid"],
-                              token_status.auth_token),
+                auth=AuthData(
+                    token_status.auth_token["uid"]
+                    if "uid" in token_status.auth_token else None,
+                    token_status.auth_token),
             )
 
         instance_id = request.headers.get("Firebase-Instance-ID-Token")
@@ -399,7 +410,7 @@ def _on_call_handler(func: _C2, request: Request,
     # pylint: disable=broad-except
     except Exception as err:
         if not isinstance(err, HttpsError):
-            _logging.error("Unhandled error", err)
+            _logging.error("Unhandled error: %s", err)
             err = HttpsError(FunctionsErrorCode.INTERNAL, "INTERNAL")
         status = err._http_error_code.status
         return _make_response(_jsonify(error=err._as_dict()), status)

{firebase_functions-0.1.2 → firebase_functions-0.3.0}/src/firebase_functions/identity_fn.py

@@ -36,7 +36,7 @@ class AuthUserInfo:
     """The user identifier for the linked provider."""
 
     provider_id: str
-    """The linked provider ID (e.g., "google.com" for the Google provider)."""
+    """The linked provider ID (such as "google.com" for the Google provider)."""
 
     display_name: str | None = None
     """The display name for the linked provider."""
@@ -110,7 +110,7 @@ class AuthMultiFactorSettings:
 @_dataclasses.dataclass(frozen=True)
 class AuthUserRecord:
     """
-    The UserRecord passed to auth blocking Cloud Functions from the identity platform.
+    The UserRecord passed to auth blocking functions from the identity platform.
     """
 
     uid: str
@@ -155,7 +155,7 @@ class AuthUserRecord:
 
     provider_data: list[AuthUserInfo]
     """
-    An array of providers (e.g., Google, Facebook) linked to the user.
+    An array of providers (such as Google or Facebook) linked to the user.
     """
 
     password_hash: str | None
@@ -203,6 +203,9 @@ class AdditionalUserInfo:
     is_new_user: bool
     """A boolean indicating if the user is new or not."""
 
+    recaptcha_score: float | None
+    """The user's reCAPTCHA score, if available."""
+
 
 @_dataclasses.dataclass(frozen=True)
 class Credential:
@@ -243,7 +246,7 @@ class AuthBlockingEvent:
 
     data: AuthUserRecord
     """
-    The UserRecord passed to auth blocking Cloud Functions from the identity platform.
+    The UserRecord passed to auth blocking functions from the identity platform.
     """
 
     locale: str | None
@@ -282,6 +285,12 @@ class AuthBlockingEvent:
     The time the event was triggered."""
 
 
+RecaptchaActionOptions = _typing.Literal["ALLOW", "BLOCK"]
+"""
+The reCAPTCHA action options.
+"""
+
+
 class BeforeCreateResponse(_typing.TypedDict, total=False):
     """
     The handler response type for 'before_user_created' blocking events.
@@ -302,6 +311,8 @@ class BeforeCreateResponse(_typing.TypedDict, total=False):
     custom_claims: dict[str, _typing.Any] | None
     """The user's custom claims object if available."""
 
+    recaptcha_action_override: RecaptchaActionOptions | None
+
 
 class BeforeSignInResponse(BeforeCreateResponse, total=False):
     """