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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: firebase_functions
-Version: 0.1.2
+Version: 0.2.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.2.0}/src/firebase_functions/__init__.py

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

{firebase_functions-0.1.2 → firebase_functions-0.2.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.2.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.2.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.2.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"

{firebase_functions-0.1.2 → firebase_functions-0.2.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):
     """

firebase_functions-0.2.0/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))

{firebase_functions-0.1.2 → firebase_functions-0.2.0}/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

{firebase_functions-0.1.2 → firebase_functions-0.2.0}/src/firebase_functions/private/_identity_fn.py

@@ -114,7 +114,7 @@ def _auth_user_record_from_token_data(token_data: dict[str, _typing.Any]):
     return AuthUserRecord(
         uid=token_data["uid"],
         email=token_data.get("email"),
-        email_verified=token_data.get("email_verified"),
+        email_verified=bool(token_data.get("email_verified")),
         display_name=token_data.get("display_name"),
         photo_url=token_data.get("photo_url"),
         phone_number=token_data.get("phone_number"),
@@ -165,6 +165,7 @@ def _additional_user_info_from_token_data(token_data: dict[str, _typing.Any]):
         profile=profile,
         username=username,
         is_new_user=is_new_user,
+        recaptcha_score=token_data.get("recaptcha_score"),
     )
 
 
@@ -302,9 +303,35 @@ def _validate_auth_response(
         auth_response_dict["customClaims"] = auth_response["custom_claims"]
     if "session_claims" in auth_response_keys:
         auth_response_dict["sessionClaims"] = auth_response["session_claims"]
+    if "recaptcha_action_override" in auth_response_keys:
+        auth_response_dict["recaptchaActionOverride"] = auth_response[
+            "recaptcha_action_override"]
     return auth_response_dict
 
 
+def _generate_response_payload(
+    auth_response_dict: dict[str, _typing.Any] | None
+) -> dict[str, _typing.Any]:
+    if not auth_response_dict:
+        return {}
+
+    formatted_auth_response = auth_response_dict.copy()
+    recaptcha_action_override = formatted_auth_response.pop(
+        "recaptchaActionOverride", None)
+    result = {}
+    update_mask = ",".join(formatted_auth_response.keys())
+
+    if len(update_mask) != 0:
+        result["userRecord"] = {
+            **formatted_auth_response, "updateMask": update_mask
+        }
+
+    if recaptcha_action_override is not None:
+        result["recaptchaActionOverride"] = recaptcha_action_override
+
+    return result
+
+
 def before_operation_handler(
     func: _typing.Callable,
     event_type: str,
@@ -329,13 +356,7 @@ def before_operation_handler(
         if not auth_response:
             return _jsonify({})
         auth_response_dict = _validate_auth_response(event_type, auth_response)
-        update_mask = ",".join(auth_response_dict.keys())
-        result = {
-            "userRecord": {
-                **auth_response_dict,
-                "updateMask": update_mask,
-            }
-        }
+        result = _generate_response_payload(auth_response_dict)
         return _jsonify(result)
     # Disable broad exceptions lint since we want to handle all exceptions.
     # pylint: disable=broad-except

{firebase_functions-0.1.2 → firebase_functions-0.2.0}/src/firebase_functions/private/util.py

@@ -387,6 +387,8 @@ def timestamp_conversion(time: str) -> _dt.datetime:
     elif precision_timestamp == PrecisionTimestamp.SECONDS:
         return second_timestamp_conversion(time)
 
+    raise ValueError("Invalid timestamp")
+
 
 def microsecond_timestamp_conversion(time: str) -> _dt.datetime:
     """Converts a microsecond timestamp and returns a datetime object of the current time in UTC"""

{firebase_functions-0.1.2 → firebase_functions-0.2.0}/src/firebase_functions/pubsub_fn.py

@@ -157,7 +157,7 @@ def _message_handler(
 @_util.copy_func_kwargs(PubSubOptions)
 def on_message_published(**kwargs) -> _typing.Callable[[_C1], _C1]:
     """
-    Event handler which triggers on a message being published to a Pub/Sub topic.
+    Event handler that triggers on a message being published to a Pub/Sub topic.
 
     Example:
 

{firebase_functions-0.1.2 → firebase_functions-0.2.0}/src/firebase_functions/remote_config_fn.py

@@ -141,8 +141,8 @@ class ConfigUpdateData:
 
     rollback_source: int | None = None
     """
-    Only present if this version is the result of a rollback, and will be
-    the version number of the Remote Config template that was rolled-back to.
+    Only present if this version is the result of a rollback, and is
+    the version number of the Remote Config template that was rolled back to.
     """
 
 

{firebase_functions-0.1.2 → firebase_functions-0.2.0}/src/firebase_functions/storage_fn.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 """
-Cloud functions to handle events from Google Cloud Storage.
+Functions to handle events from Google Cloud Storage.
 """
 # pylint: disable=protected-access
 import dataclasses as _dataclasses

{firebase_functions-0.1.2 → firebase_functions-0.2.0}/src/firebase_functions/tasks_fn.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Cloud functions to handle Tasks enqueued with Google Cloud Tasks."""
+"""Functions to handle Tasks enqueued with Google Cloud Tasks."""
 
 # pylint: disable=protected-access
 import typing as _typing

{firebase_functions-0.1.2 → firebase_functions-0.2.0}/src/firebase_functions.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: firebase-functions
-Version: 0.1.2
+Version: 0.2.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.2.0}/src/firebase_functions.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/firebase_functions/eventarc_fn.py
 src/firebase_functions/firestore_fn.py
 src/firebase_functions/https_fn.py
 src/firebase_functions/identity_fn.py
+src/firebase_functions/logger.py
 src/firebase_functions/options.py
 src/firebase_functions/params.py
 src/firebase_functions/pubsub_fn.py
@@ -37,6 +38,7 @@ src/firebase_functions/private/serving.py
 src/firebase_functions/private/token_verifier.py
 src/firebase_functions/private/util.py
 tests/test_eventarc_fn.py
+tests/test_logger.py
 tests/test_manifest.py
 tests/test_options.py
 tests/test_params.py

firebase_functions-0.2.0/tests/test_logger.py

@@ -0,0 +1,81 @@
+"""
+Logger module tests.
+"""
+
+import pytest
+import json
+from firebase_functions import logger
+
+
+class TestLogger:
+    """
+    Tests for the logger module.
+    """
+
+    def test_format_should_be_valid_json(self,
+                                         capsys: pytest.CaptureFixture[str]):
+        logger.log(foo="bar")
+        raw_log_output = capsys.readouterr().out
+        try:
+            json.loads(raw_log_output)
+        except json.JSONDecodeError:
+            pytest.fail("Log output was not valid JSON.")
+
+    def test_log_should_have_severity(self, capsys: pytest.CaptureFixture[str]):
+        logger.log(foo="bar")
+        raw_log_output = capsys.readouterr().out
+        log_output = json.loads(raw_log_output)
+        assert "severity" in log_output
+
+    def test_severity_should_be_debug(self, capsys: pytest.CaptureFixture[str]):
+        logger.debug(foo="bar")
+        raw_log_output = capsys.readouterr().out
+        log_output = json.loads(raw_log_output)
+        assert log_output["severity"] == "DEBUG"
+
+    def test_severity_should_be_notice(self,
+                                       capsys: pytest.CaptureFixture[str]):
+        logger.log(foo="bar")
+        raw_log_output = capsys.readouterr().out
+        log_output = json.loads(raw_log_output)
+        assert log_output["severity"] == "NOTICE"
+
+    def test_severity_should_be_info(self, capsys: pytest.CaptureFixture[str]):
+        logger.info(foo="bar")
+        raw_log_output = capsys.readouterr().out
+        log_output = json.loads(raw_log_output)
+        assert log_output["severity"] == "INFO"
+
+    def test_severity_should_be_warning(self,
+                                        capsys: pytest.CaptureFixture[str]):
+        logger.warn(foo="bar")
+        raw_log_output = capsys.readouterr().out
+        log_output = json.loads(raw_log_output)
+        assert log_output["severity"] == "WARNING"
+
+    def test_severity_should_be_error(self, capsys: pytest.CaptureFixture[str]):
+        logger.error(foo="bar")
+        raw_log_output = capsys.readouterr().err
+        log_output = json.loads(raw_log_output)
+        assert log_output["severity"] == "ERROR"
+
+    def test_log_should_have_message(self, capsys: pytest.CaptureFixture[str]):
+        logger.log("bar")
+        raw_log_output = capsys.readouterr().out
+        log_output = json.loads(raw_log_output)
+        assert "message" in log_output
+
+    def test_log_should_have_other_keys(self,
+                                        capsys: pytest.CaptureFixture[str]):
+        logger.log(foo="bar")
+        raw_log_output = capsys.readouterr().out
+        log_output = json.loads(raw_log_output)
+        assert "foo" in log_output
+
+    def test_message_should_be_space_separated(
+            self, capsys: pytest.CaptureFixture[str]):
+        logger.log("bar", "qux")
+        expected_message = "bar qux"
+        raw_log_output = capsys.readouterr().out
+        log_output = json.loads(raw_log_output)
+        assert log_output["message"] == expected_message