Merge pull request #60 from invertase/schedule

feat: scheduler fn support

Author: taeold

samples/basic_scheduler/.firebaserc

@@ -0,0 +1,5 @@
+{
+  "projects": {
+    "default": "python-functions-testing"
+  }
+}

samples/basic_scheduler/.gitignore

@@ -0,0 +1,66 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+firebase-debug.log*
+firebase-debug.*.log*
+
+# Firebase cache
+.firebase/
+
+# Firebase config
+
+# Uncomment this if you'd like others to create their own Firebase project.
+# For a team working on the same Firebase project(s), it is recommended to leave
+# it commented so all members can deploy to the same project(s) in .firebaserc.
+# .firebaserc
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env

samples/basic_scheduler/__init__.py

@@ -0,0 +1,3 @@
+# Required to avoid a 'duplicate modules' mypy error
+# in monorepos that have multiple main.py files.
+# https://github.com/python/mypy/issues/4008

samples/basic_scheduler/firebase.json

@@ -0,0 +1,11 @@
+{
+  "functions": [
+    {
+      "source": "functions",
+      "codebase": "default",
+      "ignore": [
+        "venv"
+      ]
+    }
+  ]
+}

samples/basic_scheduler/functions/.gitignore

@@ -0,0 +1,13 @@
+# pyenv
+.python-version
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Environments
+.env
+.venv
+venv/
+venv.bak/
+__pycache__

samples/basic_scheduler/functions/main.py

@@ -0,0 +1,12 @@
+"""Firebase Scheduled Cloud Functions example."""
+
+from firebase_functions import scheduler_fn
+
+
+@scheduler_fn.on_schedule(
+    schedule="* * * * *",
+    timezone=scheduler_fn.Timezone("America/Los_Angeles"),
+)
+def example(event: scheduler_fn.ScheduledEvent) -> None:
+    print(event.job_name)
+    print(event.schedule_time)

samples/basic_scheduler/functions/requirements.txt

@@ -0,0 +1,8 @@
+# Not published yet,
+# firebase-functions-python >= 0.0.1
+# so we use a relative path during development:
+./../../../
+# Or switch to git ref for deployment testing:
+# git+https://github.com/firebase/firebase-functions-python.git@main#egg=firebase-functions
+
+firebase-admin >= 6.0.1

src/firebase_functions/options.py

@@ -20,12 +20,16 @@
 import dataclasses as _dataclasses
 import re as _re
 import typing as _typing
+from zoneinfo import ZoneInfo as _ZoneInfo
 
 import firebase_functions.private.manifest as _manifest
 import firebase_functions.private.util as _util
 import firebase_functions.private.path_pattern as _path_pattern
 from firebase_functions.params import SecretParam, Expression
 
+Timezone = _ZoneInfo
+"""An alias of the zoneinfo.ZoneInfo for convenience."""
+
 RESET_VALUE = _util.Sentinel(
     "Special configuration value to reset configuration to platform default.")
 """Special configuration value to reset configuration to platform default."""
@@ -409,7 +413,7 @@ def _endpoint(
             maxDispatchesPerSecond=self.rate_limits.max_dispatches_per_second,
         ) if self.rate_limits is not None else None
 
-        retry_config: _manifest.RetryConfig | None = _manifest.RetryConfig(
+        retry_config: _manifest.RetryConfigTasks | None = _manifest.RetryConfigTasks(
             maxAttempts=self.retry_config.max_attempts,
             maxRetrySeconds=self.retry_config.max_retry_seconds,
             maxBackoffSeconds=self.retry_config.max_backoff_seconds,
@@ -498,6 +502,86 @@ def _endpoint(
                 **kwargs, event_filters=event_filters, event_type=event_type))))
 
 
+@_dataclasses.dataclass(frozen=True, kw_only=True)
+class ScheduleOptions(RuntimeOptions):
+    """
+    Options that can be set on a Schedule trigger.
+    """
+
+    schedule: str
+    """
+    The schedule, in Unix Crontab or AppEngine syntax.
+    """
+
+    timezone: Timezone | Expression[str] | _util.Sentinel | None = None
+    """
+    The timezone that the schedule executes in.
+    """
+
+    retry_count: int | Expression[int] | _util.Sentinel | None = None
+    """
+    The number of retry attempts for a failed run.
+    """
+
+    max_retry_seconds: int | Expression[int] | _util.Sentinel | None = None
+    """
+    The time limit for retrying.
+    """
+
+    max_backoff_seconds: int | Expression[int] | _util.Sentinel | None = None
+    """
+    The maximum amount of time to wait between attempts.
+    """
+
+    max_doublings: int | Expression[int] | _util.Sentinel | None = None
+    """
+    The maximum number of times to double the backoff between
+    retries.
+    """
+
+    min_backoff_seconds: int | Expression[int] | _util.Sentinel | None = None
+    """
+    The minimum time to wait between attempts.
+    """
+
+    def _endpoint(
+        self,
+        **kwargs,
+    ) -> _manifest.ManifestEndpoint:
+        retry_config: _manifest.RetryConfigScheduler = _manifest.RetryConfigScheduler(
+            retryCount=self.retry_count,
+            maxRetrySeconds=self.max_retry_seconds,
+            maxBackoffSeconds=self.max_backoff_seconds,
+            maxDoublings=self.max_doublings,
+            minBackoffSeconds=self.min_backoff_seconds,
+        )
+        time_zone: str | Expression[str] | _util.Sentinel | None = None
+        if isinstance(self.timezone, Timezone):
+            time_zone = self.timezone.key
+        else:
+            time_zone = self.timezone
+
+        kwargs_merged = {
+            **_dataclasses.asdict(super()._endpoint(**kwargs)),
+            "scheduleTrigger":
+                _manifest.ScheduleTrigger(
+                    schedule=self.schedule,
+                    timeZone=time_zone,
+                    retryConfig=retry_config,
+                ),
+        }
+        return _manifest.ManifestEndpoint(
+            **_typing.cast(_typing.Dict, kwargs_merged))
+
+    def _required_apis(self) -> list[_manifest.ManifestRequiredApi]:
+        return [
+            _manifest.ManifestRequiredApi(
+                api="cloudscheduler.googleapis.com",
+                reason="Needed for scheduled functions.",
+            )
+        ]
+
+
 @_dataclasses.dataclass(frozen=True, kw_only=True)
 class StorageOptions(RuntimeOptions):
     """

src/firebase_functions/private/manifest.py

@@ -65,12 +65,10 @@ class EventTrigger(_typing.TypedDict):
                                        _util.Sentinel]
 
 
-class RetryConfig(_typing.TypedDict):
+class RetryConfigBase(_typing.TypedDict):
     """
     Retry configuration for a endpoint.
     """
-    maxAttempts: _typing_extensions.NotRequired[int | _params.Expression[int] |
-                                                _util.Sentinel | None]
     maxRetrySeconds: _typing_extensions.NotRequired[int |
                                                     _params.Expression[int] |
                                                     _util.Sentinel | None]
@@ -84,6 +82,22 @@ class RetryConfig(_typing.TypedDict):
                                                       _util.Sentinel | None]
 
 
+class RetryConfigTasks(RetryConfigBase):
+    """
+    Retry configuration for a task.
+    """
+    maxAttempts: _typing_extensions.NotRequired[int | _params.Expression[int] |
+                                                _util.Sentinel | None]
+
+
+class RetryConfigScheduler(RetryConfigBase):
+    """
+    Retry configuration for a schedule.
+    """
+    retryCount: _typing_extensions.NotRequired[int | _params.Expression[int] |
+                                               _util.Sentinel | None]
+
+
 class RateLimits(_typing.TypedDict):
     maxConcurrentDispatches: int | _params.Expression[
         int] | _util.Sentinel | None
@@ -96,14 +110,14 @@ class TaskQueueTrigger(_typing.TypedDict):
     Trigger definitions for RPCs servers using the HTTP protocol defined at
     https://firebase.google.com/docs/functions/callable-reference
     """
-    retryConfig: RetryConfig | None
+    retryConfig: RetryConfigTasks | None
     rateLimits: RateLimits | None
 
 
 class ScheduleTrigger(_typing.TypedDict):
-    schedule: _typing_extensions.NotRequired[str | _params.Expression[str]]
-    timeZone: _typing_extensions.NotRequired[str | _params.Expression[str]]
-    retryConfig: _typing_extensions.NotRequired[RetryConfig]
+    schedule: str | _params.Expression[str]
+    timeZone: str | _params.Expression[str] | _util.Sentinel | None
+    retryConfig: RetryConfigScheduler | None
 
 
 class BlockingTrigger(_typing.TypedDict):