From acf0933d0821b85caf276981dde62cfb71dc46f0 Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Sun, 16 Jul 2023 09:51:05 -0700 Subject: [PATCH 1/5] Style, format, and naming edits. --- src/firebase_functions/firestore_fn.py | 20 ++--- src/firebase_functions/options.py | 110 ++++++++++++------------- src/firebase_functions/pubsub_fn.py | 4 +- src/firebase_functions/scheduler_fn.py | 14 ++-- 4 files changed, 74 insertions(+), 74 deletions(-) diff --git a/src/firebase_functions/firestore_fn.py b/src/firebase_functions/firestore_fn.py index 53f281b..935f27d 100644 --- a/src/firebase_functions/firestore_fn.py +++ b/src/firebase_functions/firestore_fn.py @@ -42,12 +42,12 @@ @_dataclass.dataclass(frozen=True) class Event(_core.CloudEvent[_core.T]): """ - A CloudEvent that contains a DocumentSnapshot or a Change. + A CloudEvent that contains a ``DocumentSnapshot`` or a ``Change``. """ location: str """ - The location of the database + The location of the database. """ project: str @@ -184,7 +184,7 @@ def _firestore_endpoint_handler( @_util.copy_func_kwargs(FirestoreOptions) def on_document_written(**kwargs) -> _typing.Callable[[_C1], _C1]: """ - Event handler which triggers when a document is created, updated, or deleted in Firestore. + Event handler that triggers when a document is created, updated, or deleted in Firestore. Example: @@ -199,7 +199,7 @@ def example(event: Event[Change[DocumentSnapshot]]) -> None: :rtype: :exc:`typing.Callable` \\[ \\[ :exc:`firebase_functions.firestore_fn.Event` \\[ :exc:`firebase_functions.db.Change` \\] \\], `None` \\] - A function that takes a Firestore Event and returns None. + A function that takes a Firestore event and returns ``None``. """ options = FirestoreOptions(**kwargs) @@ -232,7 +232,7 @@ def on_document_written_wrapped(raw: _ce.CloudEvent): @_util.copy_func_kwargs(FirestoreOptions) def on_document_updated(**kwargs) -> _typing.Callable[[_C1], _C1]: """ - Event handler which triggers when a document is updated in Firestore. + Event handler that triggers when a document is updated in Firestore. Example: @@ -247,7 +247,7 @@ def example(event: Event[Change[DocumentSnapshot]]) -> None: :rtype: :exc:`typing.Callable` \\[ \\[ :exc:`firebase_functions.firestore_fn.Event` \\[ :exc:`firebase_functions.db.Change` \\] \\], `None` \\] - A function that takes a Firestore Event and returns None. + A function that takes a Firestore event and returns ``None``. """ options = FirestoreOptions(**kwargs) @@ -280,7 +280,7 @@ def on_document_updated_wrapped(raw: _ce.CloudEvent): @_util.copy_func_kwargs(FirestoreOptions) def on_document_created(**kwargs) -> _typing.Callable[[_C2], _C2]: """ - Event handler which triggers when a document is created in Firestore. + Event handler that triggers when a document is created in Firestore. Example: @@ -295,7 +295,7 @@ def example(event: Event[DocumentSnapshot]): :rtype: :exc:`typing.Callable` \\[ \\[ :exc:`firebase_functions.firestore_fn.Event` \\[ :exc:`object` \\] \\], `None` \\] - A function that takes a Firestore Event and returns None. + A function that takes a Firestore event and returns ``None``. """ options = FirestoreOptions(**kwargs) @@ -328,7 +328,7 @@ def on_document_created_wrapped(raw: _ce.CloudEvent): @_util.copy_func_kwargs(FirestoreOptions) def on_document_deleted(**kwargs) -> _typing.Callable[[_C2], _C2]: """ - Event handler which triggers when a document is deleted in Firestore. + Event handler that triggers when a document is deleted in Firestore. Example: @@ -343,7 +343,7 @@ def example(event: Event[DocumentSnapshot]) -> None: :rtype: :exc:`typing.Callable` \\[ \\[ :exc:`firebase_functions.firestore_fn.Event` \\[ :exc:`object` \\] \\], `None` \\] - A function that takes a Firestore Event and returns None. + A function that takes a Firestore event and returns ``None``. """ options = FirestoreOptions(**kwargs) diff --git a/src/firebase_functions/options.py b/src/firebase_functions/options.py index a8d7247..d5a32b8 100644 --- a/src/firebase_functions/options.py +++ b/src/firebase_functions/options.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. """ -Module for options that can be used to configure Firebase Cloud Functions +Module for options that can be used to configure Cloud Functions deployments. """ # pylint: disable=protected-access @@ -43,7 +43,7 @@ class VpcEgressSetting(str, _enum.Enum): class IngressSetting(str, _enum.Enum): - """What kind of traffic can access the Cloud Function.""" + """What kind of traffic can access the function.""" ALLOW_ALL = "ALLOW_ALL" ALLOW_INTERNAL_ONLY = "ALLOW_INTERNAL_ONLY" @@ -53,23 +53,23 @@ class IngressSetting(str, _enum.Enum): @_dataclasses.dataclass(frozen=True) class CorsOptions: """ - CORS options for Https functions. - Internally this maps to Flask-Cors configuration see: + CORS options for HTTP functions. + Internally this maps to Flask-Cors configuration. See: https://flask-cors.corydolphin.com/en/latest/configuration.html """ cors_origins: str | list[str] | _re.Pattern | None = None """ The origin(s) to allow requests from. An origin configured here that matches the value of - the Origin header in a preflight OPTIONS request is returned as the value of the - Access-Control-Allow-Origin response header. + the ``Origin`` header in a preflight ``OPTIONS`` request is returned as the value of the + ``Access-Control-Allow-Origin`` response header. """ cors_methods: str | list[str] | None = None """ The method(s) which the allowed origins are allowed to access. - These are included in the Access-Control-Allow-Methods response headers - to the preflight OPTIONS requests. + These are included in the ``Access-Control-Allow-Methods`` response headers + to the preflight ``OPTIONS`` requests. """ @@ -130,14 +130,14 @@ class RateLimits(): int] | _util.Sentinel | None = None """ The maximum number of requests that can be outstanding at a time. - If left unspecified, will default to 1000. + If left unspecified, defaults to 1000. """ max_dispatches_per_second: int | Expression[ int] | _util.Sentinel | None = None """ The maximum number of requests that can be invoked per second. - If left unspecified, will default to 500. + If left unspecified, defaults to 500. """ @@ -150,25 +150,25 @@ class RetryConfig(): max_attempts: int | Expression[int] | _util.Sentinel | None = None """ The maximum number of times a request should be attempted. - If left unspecified, will default to 3. + If left unspecified, defaults to 3. """ max_retry_seconds: int | Expression[int] | _util.Sentinel | None = None """ - The maximum amount of time for retrying failed task. + The maximum amount of time for retrying a failed task. If left unspecified will retry indefinitely. """ max_backoff_seconds: int | Expression[int] | _util.Sentinel | None = None """ The maximum amount of time to wait between attempts. - If left unspecified will default to 1hr. + If left unspecified defaults to 1hr. """ max_doublings: int | Expression[int] | _util.Sentinel | None = None """ The maximum number of times to double the backoff between - retries. If left unspecified will default to 16. + retries. If left unspecified defaults to 16. """ min_backoff_seconds: int | Expression[int] | _util.Sentinel | None = None @@ -180,7 +180,7 @@ class RetryConfig(): @_dataclasses.dataclass(frozen=True, kw_only=True) class RuntimeOptions: """ - RuntimeOptions are options that can be set on any function or globally. + ``RuntimeOptions`` are options that can be set on any function or globally. Internal use only. """ @@ -193,40 +193,40 @@ class RuntimeOptions: memory: int | MemoryOption | Expression[int] | _util.Sentinel | None = None """ Amount of memory to allocate to a function. - A value of RESET_VALUE restores the defaults of 256MB. + A value of ``RESET_VALUE`` restores the defaults of 256MB. """ timeout_sec: int | Expression[int] | _util.Sentinel | None = None """ - Timeout for the function in sections, possible values are 0 to 540. - HTTPS functions can specify a higher timeout. - A value of RESET_VALUE restores the default of 60s - The minimum timeout for a gen 2 function is 1s. The maximum timeout for a + Timeout for the function in sections. Ppossible values are 0 to 540. + HTTP functions can specify a higher timeout. + A value of ``RESET_VALUE`` restores the default of 60s + The minimum timeout for a 2nd gen function is 1s. The maximum timeout for a function depends on the type of function: Event handling functions have a - maximum timeout of 540s (9 minutes). HTTPS and callable functions have a + maximum timeout of 540s (9 minutes). HTTP and callable functions have a maximum timeout of 3,600s (1 hour). Task queue functions have a maximum timeout of 1,800s (30 minutes) """ min_instances: int | Expression[int] | _util.Sentinel | None = None """ - Min number of actual instances to be running at a given time. - Instances will be billed for memory allocation and 10% of CPU allocation + Mininum number of actual instances to be running at a given time. + Instances are billed for memory allocation and 10% of CPU allocation while idle. - A value of RESET_VALUE restores the default min instances. + A value of ``RESET_VALUE`` restores the default minimum instances. """ max_instances: int | Expression[int] | _util.Sentinel | None = None """ - Max number of instances to be running in parallel. - A value of RESET_VALUE restores the default max instances. + Maximum number of instances to be running in parallel. + A value of ``RESET_VALUE`` restores the default max instances. """ concurrency: int | Expression[int] | _util.Sentinel | None = None """ Number of requests a function can serve at once. - Can only be applied to functions running on Cloud Functions (2nd gen). - A value of RESET_VALUE restores the default concurrency (80 when CPU >= 1, 1 otherwise). + Can be applied only to functions running on Cloud Functions (2nd gen). + A value of ``RESET_VALUE`` restores the default concurrency (80 when CPU >= 1, 1 otherwise). Concurrency cannot be set to any value other than 1 if `cpu` is less than 1. The maximum value for concurrency is 1,000. """ @@ -236,33 +236,33 @@ class RuntimeOptions: Fractional number of CPUs to allocate to a function. Defaults to 1 for functions with <= 2GB RAM and increases for larger memory sizes. This is different from the defaults when using the gcloud utility and is different from - the fixed amount assigned in Google Cloud Functions generation 1. - To revert to the CPU amounts used in gcloud or in Cloud Functions generation 1, set this + the fixed amount assigned in Cloud Functions (1st gen). + To revert to the CPU amounts used in gcloud or in Cloud Functions (1st gen), set this to the value "gcf_gen1" """ vpc_connector: str | _util.Sentinel | None = None """ - Connect cloud function to specified VPC connector. - A value of RESET_VALUE removes the VPC connector. + Connect function to specified VPC connector. + A value of ``RESET_VALUE`` removes the VPC connector. """ vpc_connector_egress_settings: VpcEgressSetting | _util.Sentinel | None = None """ Egress settings for VPC connector. - A value of RESET_VALUE turns off VPC connector egress settings. + A value of ``RESET_VALUE`` turns off VPC connector egress settings. """ service_account: str | _util.Sentinel | None = None """ Specific service account for the function to run as. - A value of RESET_VALUE restores the default service account. + A value of ``RESET_VALUE`` restores the default service account. """ ingress: IngressSetting | _util.Sentinel | None = None """ Ingress settings which control where this function can be called from. - A value of RESET_VALUE turns off ingress settings. + A value of ``RESET_VALUE`` turns off ingress settings. """ labels: dict[str, str] | None = None @@ -280,7 +280,7 @@ class RuntimeOptions: Determines whether Firebase AppCheck is enforced. When true, requests with invalid tokens auto respond with a 401 Unauthorized response. - When false, requests with invalid tokens set event.app to None. + When false, requests with invalid tokens set ``event.app`` to ``None``. """ preserve_external_changes: bool | None = None @@ -289,8 +289,8 @@ class RuntimeOptions: Internally defaults to false. When setting configuration available in the underlying platform that is not yet available - in the Firebase Functions SDK, we highly recommend setting `preserve_external_changes` to - `True`. Otherwise, when the Firebase Functions SDK releases a new version of the SDK + in the Cloud Functions SDK, we highly recommend setting `preserve_external_changes` to + `True`. Otherwise, when the SDK releases a new version with support for the missing configuration, your function's manually configured setting may inadvertently be wiped out. """ @@ -406,7 +406,7 @@ def convert_secret( @_dataclasses.dataclass(frozen=True, kw_only=True) class TaskQueueOptions(RuntimeOptions): """ - Options specific to Tasks function types. + Options specific to tasks function types. """ retry_config: RetryConfig | None = None @@ -470,7 +470,7 @@ def _required_apis(self) -> list[_manifest.ManifestRequiredApi]: @_dataclasses.dataclass(frozen=True, kw_only=True) class EventHandlerOptions(RuntimeOptions): """ - Options specific to any event handling Cloud function. + Options specific to any event handling function. Internal use only. """ @@ -529,7 +529,7 @@ def _endpoint( class AlertType(str, _enum.Enum): """ - The underlying alert type of the Firebase Alerts provider. + The underlying alert type of the Firebase alerts provider. """ CRASHLYTICS_NEW_FATAL_ISSUE = "crashlytics.newFatalIssue" @@ -591,13 +591,13 @@ class AlertType(str, _enum.Enum): @_dataclasses.dataclass(frozen=True, kw_only=True) class FirebaseAlertOptions(EventHandlerOptions): """ - Options specific to Firebase Alert function types. + Options specific to Firebase alert function types. Internal use only. """ alert_type: str | AlertType """ - The Firebase Alert type to listen to. Can be an AlertType enum + The Firebase alert type to listen to. Can be an ``AlertType`` enum or string. """ @@ -736,7 +736,7 @@ class EventarcTriggerOptions(EventHandlerOptions): function and `us-central1` as location will be used: `{channel-id}` - If not specified, the default Firebase channel will be used: + If not specified, the default Firebase channel is used: `projects/{project}/locations/us-central1/channels/firebase` """ @@ -775,7 +775,7 @@ def _required_apis(self) -> list[_manifest.ManifestRequiredApi]: @_dataclasses.dataclass(frozen=True, kw_only=True) class ScheduleOptions(RuntimeOptions): """ - Options that can be set on a Schedule trigger. + Options that can be set on a ``Schedule`` trigger. """ schedule: str @@ -855,7 +855,7 @@ def _required_apis(self) -> list[_manifest.ManifestRequiredApi]: @_dataclasses.dataclass(frozen=True, kw_only=True) class StorageOptions(RuntimeOptions): """ - Options specific to Storage function types. + Options specific to CLoud Storage function types. Internal use only. """ @@ -900,7 +900,7 @@ def _endpoint( @_dataclasses.dataclass(frozen=True, kw_only=True) class DatabaseOptions(RuntimeOptions): """ - Options specific to Database function types. + Options specific to Realtime Database function types. Internal use only. """ @@ -956,7 +956,7 @@ def _endpoint( @_dataclasses.dataclass(frozen=True, kw_only=True) class BlockingOptions(RuntimeOptions): """ - Options that can be set on an Auth Blocking Trigger. + Options that can be set on an Auth Blocking trigger. Internal use only. """ @@ -967,12 +967,12 @@ class BlockingOptions(RuntimeOptions): access_token: bool | None = None """ - Pass the Access Token credential to the function. + Pass the access token credential to the function. """ refresh_token: bool | None = None """ - Pass the Refresh Token credential to the function. + Pass the refresh token credential to the function. """ def _endpoint( @@ -1071,25 +1071,25 @@ def _endpoint( @_dataclasses.dataclass(frozen=True, kw_only=True) class HttpsOptions(RuntimeOptions): """ - Options specific to Http function types. + Options specific to HTTP function types. Internal use only. """ invoker: str | list[str] | _typing.Literal["public", "private"] | None = None """ - Invoker to set access control on https functions. + Invoker to set access control on HTTP functions. """ cors: CorsOptions | None = None """ - Optionally set CORS options for Https functions. + Optionally set CORS options for HTTP functions. """ def _asdict_with_global_options(self) -> dict: """ - Returns the Https options merged with globally defined options and - client only options like "cors" removed. + Returns the HTTP options merged with globally defined options and + client-only options like "cors" removed. """ merged_options = super()._asdict_with_global_options() # "cors" is only used locally by the functions framework diff --git a/src/firebase_functions/pubsub_fn.py b/src/firebase_functions/pubsub_fn.py index 8a4c313..3eb6027 100644 --- a/src/firebase_functions/pubsub_fn.py +++ b/src/firebase_functions/pubsub_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 Pub/Sub. +Functions to handle events from Google Cloud Pub/Sub. """ # pylint: disable=protected-access import dataclasses as _dataclasses @@ -173,7 +173,7 @@ def example(event: CloudEvent[MessagePublishedData[object]]) -> None: \\[ \\[ :exc:`firebase_functions.core.CloudEvent` \\[ :exc:`firebase_functions.pubsub_fn.MessagePublishedData` \\[ :exc:`typing.Any` \\] \\] \\], `None` \\] - A function that takes a CloudEvent and returns None. + A function that takes a CloudEvent and returns ``None``. """ options = PubSubOptions(**kwargs) diff --git a/src/firebase_functions/scheduler_fn.py b/src/firebase_functions/scheduler_fn.py index 7912b2a..3cc67ee 100644 --- a/src/firebase_functions/scheduler_fn.py +++ b/src/firebase_functions/scheduler_fn.py @@ -35,23 +35,23 @@ @_dataclasses.dataclass(frozen=True) class ScheduledEvent: """ - A ScheduleEvent that is passed to the function handler + A `ScheduleEvent` that is passed to the function handler. """ job_name: str | None """ The Cloud Scheduler job name. - Populated via the X-CloudScheduler-JobName header. - If invoked manually, this field is None. + Populated via the ``X-CloudScheduler-JobName`` header. + If invoked manually, this field is `None`. """ schedule_time: _dt.datetime """ For Cloud Scheduler jobs specified in the unix-cron format, this is the job schedule time in RFC3339 UTC "Zulu" format. - Populated via the X-CloudScheduler-ScheduleTime header. + Populated via the ``X-CloudScheduler-ScheduleTime`` header. - If the schedule is manually triggered, this field will be + If the schedule is manually triggered, this field is the function execution time. """ @@ -63,7 +63,7 @@ class ScheduledEvent: def on_schedule(**kwargs) -> _typing.Callable[[_C], _Response]: """ Creates a handler for tasks sent to a Google Cloud Tasks queue. - Requires a function that takes a CallableRequest. + Requires a function that takes a ``CallableRequest``. Example: @@ -85,7 +85,7 @@ def example(event: scheduler_fn.ScheduledEvent) -> None: :type \\*\\*kwargs: as :exc:`firebase_functions.options.ScheduleOptions` :rtype: :exc:`typing.Callable` \\[ \\[ :exc:`firebase_functions.schedule_fn.ScheduledEvent` \\], :exc:`None` \\] - A function that takes a ScheduledEvent and returns nothing. + A function that takes a ``ScheduledEvent`` and returns nothing. """ options = _options.ScheduleOptions(**kwargs) From 25ce72e4b506b2cb5414301f211ff5fbc014cadc Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Tue, 18 Jul 2023 15:37:07 -0700 Subject: [PATCH 2/5] Further tweaking some tweaks. --- src/firebase_functions/scheduler_fn.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/firebase_functions/scheduler_fn.py b/src/firebase_functions/scheduler_fn.py index 3cc67ee..4d3bcd7 100644 --- a/src/firebase_functions/scheduler_fn.py +++ b/src/firebase_functions/scheduler_fn.py @@ -35,7 +35,7 @@ @_dataclasses.dataclass(frozen=True) class ScheduledEvent: """ - A `ScheduleEvent` that is passed to the function handler. + A ``ScheduleEvent`` that is passed to the function handler. """ job_name: str | None @@ -81,7 +81,7 @@ def example(event: scheduler_fn.ScheduledEvent) -> None: print(event.schedule_time) - :param \\*\\*kwargs: ScheduleOptions options. + :param \\*\\*kwargs: `ScheduleOptions` options. :type \\*\\*kwargs: as :exc:`firebase_functions.options.ScheduleOptions` :rtype: :exc:`typing.Callable` \\[ \\[ :exc:`firebase_functions.schedule_fn.ScheduledEvent` \\], :exc:`None` \\] From 472ef75d7cf4e2a437f476e7603ec1f4a743eaec Mon Sep 17 00:00:00 2001 From: egilmorez Date: Tue, 1 Aug 2023 11:22:45 -0700 Subject: [PATCH 3/5] Update src/firebase_functions/options.py Co-authored-by: Russell Wheatley --- src/firebase_functions/options.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/firebase_functions/options.py b/src/firebase_functions/options.py index d5a32b8..6fa083a 100644 --- a/src/firebase_functions/options.py +++ b/src/firebase_functions/options.py @@ -210,7 +210,7 @@ class RuntimeOptions: min_instances: int | Expression[int] | _util.Sentinel | None = None """ - Mininum number of actual instances to be running at a given time. + Minimum number of actual instances to be running at a given time. Instances are billed for memory allocation and 10% of CPU allocation while idle. A value of ``RESET_VALUE`` restores the default minimum instances. From 78e504e3e44860541333c507899820be8330c81e Mon Sep 17 00:00:00 2001 From: egilmorez Date: Tue, 1 Aug 2023 11:23:16 -0700 Subject: [PATCH 4/5] Update src/firebase_functions/options.py Co-authored-by: Russell Wheatley --- src/firebase_functions/options.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/firebase_functions/options.py b/src/firebase_functions/options.py index 6fa083a..bb6235a 100644 --- a/src/firebase_functions/options.py +++ b/src/firebase_functions/options.py @@ -198,7 +198,7 @@ class RuntimeOptions: timeout_sec: int | Expression[int] | _util.Sentinel | None = None """ - Timeout for the function in sections. Ppossible values are 0 to 540. + Timeout for the function in sections. Possible values are 0 to 540. HTTP functions can specify a higher timeout. A value of ``RESET_VALUE`` restores the default of 60s The minimum timeout for a 2nd gen function is 1s. The maximum timeout for a From 8a27eea429ab130f8ce0f66e8b9991434de50626 Mon Sep 17 00:00:00 2001 From: egilmorez Date: Tue, 1 Aug 2023 11:23:28 -0700 Subject: [PATCH 5/5] Update src/firebase_functions/options.py Co-authored-by: Russell Wheatley --- src/firebase_functions/options.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/firebase_functions/options.py b/src/firebase_functions/options.py index bb6235a..d0dc9c0 100644 --- a/src/firebase_functions/options.py +++ b/src/firebase_functions/options.py @@ -855,7 +855,7 @@ def _required_apis(self) -> list[_manifest.ManifestRequiredApi]: @_dataclasses.dataclass(frozen=True, kw_only=True) class StorageOptions(RuntimeOptions): """ - Options specific to CLoud Storage function types. + Options specific to Cloud Storage function types. Internal use only. """