Merge branch 'main' into supported-region-as-a-str-enum

Author: davidbuckman

Diff for: .github/workflows/release.yaml

@@ -74,7 +74,7 @@ jobs:
     #   4. the title prefix 'chore: Release '.
     if: >
       github.event.pull_request.merged &&
-      github.ref == 'main' &&
+      github.ref == 'refs/heads/main' &&
       contains(github.event.pull_request.labels.*.name, 'release:publish') &&
       startsWith(github.event.pull_request.title, 'chore: Release ')
 

Diff for: docs/generate.sh

@@ -93,6 +93,7 @@ PY_MODULES='firebase_functions.core
             firebase_functions.firestore_fn
             firebase_functions.https_fn
             firebase_functions.identity_fn
+            firebase_functions.logger
             firebase_functions.options
             firebase_functions.params
             firebase_functions.pubsub_fn

Diff for: src/firebase_functions/__init__.py

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

Diff for: 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:
 

Diff for: src/firebase_functions/core.py

@@ -25,7 +25,7 @@
 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

Diff for: 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_wrapped(raw: _ce.CloudEvent):
 @_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_wrapped(raw: _ce.CloudEvent):
 @_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_wrapped(raw: _ce.CloudEvent):
 @_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:
 

Diff for: src/firebase_functions/firestore_fn.py

@@ -112,12 +112,7 @@ def _firestore_endpoint_handler(
     event_database = event_attributes["database"]
 
     time = event_attributes["time"]
-    is_nanoseconds = _util.is_precision_timestamp(time)
-
-    if is_nanoseconds:
-        event_time = _util.nanoseconds_timestamp_conversion(time)
-    else:
-        event_time = _util.microsecond_timestamp_conversion(time)
+    event_time = _util.timestamp_conversion(time)
 
     if _DEFAULT_APP_NAME not in _apps:
         initialize_app()

Diff for: 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"

Diff for: src/firebase_functions/identity_fn.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 """Cloud functions to handle Eventarc events."""
 
-# pylint: disable=protected-access
+# pylint: disable=protected-access,cyclic-import
 import typing as _typing
 import functools as _functools
 import datetime as _dt
@@ -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."""
@@ -59,7 +59,7 @@ class AuthUserMetadata:
     creation_time: _dt.datetime
     """The date the user was created."""
 
-    last_sign_in_time: _dt.datetime
+    last_sign_in_time: _typing.Optional[_dt.datetime]
     """The date the user last signed in."""
 
 
@@ -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
@@ -123,7 +123,7 @@ class AuthUserRecord:
     The user's primary email, if set.
     """
 
-    email_verified: bool
+    email_verified: bool | None
     """
     Whether or not the user's primary email is verified.
     """
@@ -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,12 +246,12 @@ 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
     """
-    The application locale. You can set the locale using the client SDK, 
+    The application locale. You can set the locale using the client SDK,
     or by passing the locale header in the REST API.
     Example: 'fr' or 'sv-SE'
     """
@@ -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):
     """
@@ -345,7 +356,7 @@ def example(event: identity_fn.AuthBlockingEvent) -> identity_fn.BeforeSignInRes
     :param \\*\\*kwargs: Options.
     :type \\*\\*kwargs: as :exc:`firebase_functions.options.BlockingOptions`
     :rtype: :exc:`typing.Callable`
-            \\[ \\[ :exc:`firebase_functions.identity_fn.AuthBlockingEvent` \\], 
+            \\[ \\[ :exc:`firebase_functions.identity_fn.AuthBlockingEvent` \\],
             :exc:`firebase_functions.identity_fn.BeforeSignInResponse` \\| `None` \\]
             A function that takes a AuthBlockingEvent and optionally returns BeforeSignInResponse.
     """
@@ -399,7 +410,7 @@ def example(event: identity_fn.AuthBlockingEvent) -> identity_fn.BeforeCreateRes
     :param \\*\\*kwargs: Options.
     :type \\*\\*kwargs: as :exc:`firebase_functions.options.BlockingOptions`
     :rtype: :exc:`typing.Callable`
-            \\[ \\[ :exc:`firebase_functions.identity_fn.AuthBlockingEvent` \\], 
+            \\[ \\[ :exc:`firebase_functions.identity_fn.AuthBlockingEvent` \\],
             :exc:`firebase_functions.identity_fn.BeforeCreateResponse` \\| `None` \\]
             A function that takes a AuthBlockingEvent and optionally returns BeforeCreateResponse.
     """

Diff for: src/firebase_functions/logger.py

@@ -0,0 +1,130 @@
+"""
+Logger module for Firebase Functions.
+"""
+
+import enum as _enum
+import json as _json
+import sys as _sys
+import typing as _typing
+import typing_extensions as _typing_extensions
+
+
+class LogSeverity(str, _enum.Enum):
+    """
+    `LogSeverity` indicates the detailed severity of the log entry. See
+    `LogSeverity <https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity>`.
+    """
+
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    NOTICE = "NOTICE"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+    ALERT = "ALERT"
+    EMERGENCY = "EMERGENCY"
+
+
+class LogEntry(_typing.TypedDict):
+    """
+    `LogEntry` represents a log entry.
+    See `LogEntry <https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry>`_.
+    """
+
+    severity: _typing_extensions.Required[LogSeverity]
+    message: _typing_extensions.NotRequired[str]
+
+
+def _entry_from_args(severity: LogSeverity, *args, **kwargs) -> LogEntry:
+    """
+    Creates a `LogEntry` from the given arguments.
+    """
+
+    message: str = " ".join([
+        value
+        if isinstance(value, str) else _json.dumps(_remove_circular(value))
+        for value in args
+    ])
+
+    other: _typing.Dict[str, _typing.Any] = {
+        key: value if isinstance(value, str) else _remove_circular(value)
+        for key, value in kwargs.items()
+    }
+
+    entry: _typing.Dict[str, _typing.Any] = {"severity": severity, **other}
+    if message:
+        entry["message"] = message
+
+    return _typing.cast(LogEntry, entry)
+
+
+def _remove_circular(obj: _typing.Any,
+                     refs: _typing.Set[_typing.Any] | None = None):
+    """
+    Removes circular references from the given object and replaces them with "[CIRCULAR]".
+    """
+
+    if refs is None:
+        refs = set()
+
+    if id(obj) in refs:
+        return "[CIRCULAR]"
+
+    if not isinstance(obj, (str, int, float, bool, type(None))):
+        refs.add(id(obj))
+
+    if isinstance(obj, dict):
+        return {key: _remove_circular(value, refs) for key, value in obj.items()}
+    elif isinstance(obj, list):
+        return [_remove_circular(value, refs) for _, value in enumerate(obj)]
+    elif isinstance(obj, tuple):
+        return tuple(
+            _remove_circular(value, refs) for _, value in enumerate(obj))
+    else:
+        return obj
+
+
+def _get_write_file(severity: LogSeverity) -> _typing.TextIO:
+    if severity == LogSeverity.ERROR:
+        return _sys.stderr
+    return _sys.stdout
+
+
+def write(entry: LogEntry) -> None:
+    write_file = _get_write_file(entry["severity"])
+    print(_json.dumps(_remove_circular(entry)), file=write_file)
+
+
+def debug(*args, **kwargs) -> None:
+    """
+    Logs a debug message.
+    """
+    write(_entry_from_args(LogSeverity.DEBUG, *args, **kwargs))
+
+
+def log(*args, **kwargs) -> None:
+    """
+    Logs a log message.
+    """
+    write(_entry_from_args(LogSeverity.NOTICE, *args, **kwargs))
+
+
+def info(*args, **kwargs) -> None:
+    """
+    Logs an info message.
+    """
+    write(_entry_from_args(LogSeverity.INFO, *args, **kwargs))
+
+
+def warn(*args, **kwargs) -> None:
+    """
+    Logs a warning message.
+    """
+    write(_entry_from_args(LogSeverity.WARNING, *args, **kwargs))
+
+
+def error(*args, **kwargs) -> None:
+    """
+    Logs an error message.
+    """
+    write(_entry_from_args(LogSeverity.ERROR, *args, **kwargs))

Diff for: src/firebase_functions/params.py

@@ -144,18 +144,18 @@ class TextInput:
     """
     Specifies that a Param's value should be determined by prompting the user
     to type it in interactively at deploy-time. Input that does not match the provided
-    validation_regex, if present, will be retried.
+    validation_regex, if present, is retried.
     """
 
     example: str | None = None
     """
-    An example of the input required that will be displayed alongside the input prompt.
+    An example of the input required that is displayed alongside the input prompt.
     """
 
     validation_regex: str | None = None
     """
     Validation regex for the input.
-    Input that does not match this regex, if present, will be retried.
+    Input that does not match this regex, if present, is retried.
     """
 
     validation_error_message: str | None = None