firebase-functions 0.2.0__tar.gz → 0.4.0__tar.gz

{firebase_functions-0.2.0 → firebase_functions-0.4.0}/PKG-INFO

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

{firebase_functions-0.2.0 → firebase_functions-0.4.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.2.0 → firebase_functions-0.4.0}/src/firebase_functions/__init__.py

@@ -15,4 +15,4 @@
 Firebase Functions for Python.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

{firebase_functions-0.2.0 → firebase_functions-0.4.0}/src/firebase_functions/alerts_fn.py

@@ -24,7 +24,7 @@ from firebase_functions.alerts import FirebaseAlertData
 
 import firebase_functions.private.util as _util
 
-from firebase_functions.core import T, CloudEvent as _CloudEvent
+from firebase_functions.core import T, CloudEvent as _CloudEvent, _with_init
 from firebase_functions.options import FirebaseAlertOptions
 
 # Explicitly import AlertType to make it available in the public API.
@@ -95,7 +95,7 @@ def on_alert_published(
         @_functools.wraps(func)
         def on_alert_published_wrapped(raw: _ce.CloudEvent):
             from firebase_functions.private._alerts_fn import alerts_event_from_ce
-            func(alerts_event_from_ce(raw))
+            _with_init(func)(alerts_event_from_ce(raw))
 
         _util.set_func_endpoint_attr(
             on_alert_published_wrapped,

{firebase_functions-0.2.0 → firebase_functions-0.4.0}/src/firebase_functions/core.py

@@ -18,6 +18,8 @@ import dataclasses as _dataclass
 import datetime as _datetime
 import typing as _typing
 
+from . import logger as _logger
+
 T = _typing.TypeVar("T")
 
 
@@ -80,3 +82,46 @@ class Change(_typing.Generic[T]):
     """
     The state of data after the change.
     """
+
+
+_did_init = False
+_init_callback: _typing.Callable[[], _typing.Any] | None = None
+
+
+def init(callback: _typing.Callable[[], _typing.Any]) -> None:
+    """
+     Registers a function that should be run when in a production environment
+     before executing any functions code.
+     Calling this decorator more than once leads to undefined behavior.
+    """
+
+    global _did_init
+    global _init_callback
+
+    if _did_init:
+        _logger.warn(
+            "Setting init callback more than once. Only the most recent callback will be called"
+        )
+
+    _init_callback = callback
+    _did_init = False
+
+
+def _with_init(
+    fn: _typing.Callable[...,
+                         _typing.Any]) -> _typing.Callable[..., _typing.Any]:
+    """
+    A decorator that runs the init callback before running the decorated function.
+    """
+
+    def wrapper(*args, **kwargs):
+        global _did_init
+
+        if not _did_init:
+            if _init_callback is not None:
+                _init_callback()
+            _did_init = True
+
+        return fn(*args, **kwargs)
+
+    return wrapper

{firebase_functions-0.2.0 → firebase_functions-0.4.0}/src/firebase_functions/db_fn.py

@@ -119,7 +119,7 @@ def _db_endpoint_handler(
         subject=event_attributes["subject"],
         params=params,
     )
-    func(database_event)
+    _core._with_init(func)(database_event)
 
 
 @_util.copy_func_kwargs(DatabaseOptions)

{firebase_functions-0.2.0 → firebase_functions-0.4.0}/src/firebase_functions/eventarc_fn.py

@@ -21,7 +21,7 @@ import cloudevents.http as _ce
 
 import firebase_functions.options as _options
 import firebase_functions.private.util as _util
-from firebase_functions.core import CloudEvent
+from firebase_functions.core import CloudEvent, _with_init
 
 
 @_util.copy_func_kwargs(_options.EventarcTriggerOptions)
@@ -73,7 +73,7 @@ def on_custom_event_published(
                 ),
                 type=event_dict["type"],
             )
-            func(event)
+            _with_init(func)(event)
 
         _util.set_func_endpoint_attr(
             on_custom_event_published_wrapped,

{firebase_functions-0.2.0 → firebase_functions-0.4.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,17 @@ def _firestore_endpoint_handler(
         subject=event_attributes["subject"],
         params=params,
     )
-    func(database_event)
+
+    func = _core._with_init(func)
+
+    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 +265,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 +364,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 +463,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 +560,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.2.0 → firebase_functions-0.4.0}/src/firebase_functions/https_fn.py

@@ -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")
@@ -392,14 +403,14 @@ def _on_call_handler(func: _C2, request: Request,
                 instance_id_token=request.headers.get(
                     "Firebase-Instance-ID-Token"),
             )
-        result = func(context)
+        result = _core._with_init(func)(context)
         return _jsonify(result=result)
     # Disable broad exceptions lint since we want to handle all exceptions here
     # and wrap as an HttpsError.
     # 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)
@@ -436,7 +447,7 @@ def on_request(**kwargs) -> _typing.Callable[[_C1], _C1]:
                     methods=options.cors.cors_methods,
                     origins=options.cors.cors_origins,
                 )(func)(request)
-            return func(request)
+            return _core._with_init(func)(request)
 
         _util.set_func_endpoint_attr(
             on_request_wrapped,

{firebase_functions-0.2.0 → firebase_functions-0.4.0}/src/firebase_functions/logger.py

@@ -24,6 +24,9 @@ class LogSeverity(str, _enum.Enum):
     ALERT = "ALERT"
     EMERGENCY = "EMERGENCY"
 
+    def __str__(self) -> str:
+        return self.value
+
 
 class LogEntry(_typing.TypedDict):
     """

{firebase_functions-0.2.0 → firebase_functions-0.4.0}/src/firebase_functions/options.py

@@ -41,6 +41,9 @@ class VpcEgressSetting(str, _enum.Enum):
     PRIVATE_RANGES_ONLY = "PRIVATE_RANGES_ONLY"
     ALL_TRAFFIC = "ALL_TRAFFIC"
 
+    def __str__(self) -> str:
+        return self.value
+
 
 class IngressSetting(str, _enum.Enum):
     """What kind of traffic can access the function."""
@@ -49,6 +52,9 @@ class IngressSetting(str, _enum.Enum):
     ALLOW_INTERNAL_ONLY = "ALLOW_INTERNAL_ONLY"
     ALLOW_INTERNAL_AND_GCLB = "ALLOW_INTERNAL_AND_GCLB"
 
+    def __str__(self) -> str:
+        return self.value
+
 
 @_dataclasses.dataclass(frozen=True)
 class CorsOptions:
@@ -88,6 +94,9 @@ class MemoryOption(int, _enum.Enum):
     GB_16 = 16 << 10
     GB_32 = 32 << 10
 
+    def __str__(self) -> str:
+        return f"{self.value}MB"
+
 
 class SupportedRegion(str, _enum.Enum):
     """
@@ -120,6 +129,9 @@ class SupportedRegion(str, _enum.Enum):
     US_WEST3 = "us-west3"
     US_WEST4 = "us-west4"
 
+    def __str__(self) -> str:
+        return self.value
+
 
 @_dataclasses.dataclass(frozen=True)
 class RateLimits():
@@ -587,6 +599,9 @@ class AlertType(str, _enum.Enum):
     Performance threshold alerts.
     """
 
+    def __str__(self) -> str:
+        return self.value
+
 
 @_dataclasses.dataclass(frozen=True, kw_only=True)
 class FirebaseAlertOptions(EventHandlerOptions):