refactor: improve docstrings for sphinx

Author: Salakar

src/firebase_functions/core.py

@@ -65,20 +65,3 @@ class CloudEvent(_typing.Generic[T]):
     The resource, provided by source, that this event relates to
     """
 
-
-@_dataclass.dataclass(frozen=True)
-class Change(_typing.Generic[T]):
-    """
-    * The Functions interface for events that change state, such as
-    * Realtime Database `on_value_written`.
-    """
-
-    before: T
-    """
-    The state of data before the change.
-    """
-
-    after: T
-    """
-    The state of data after the change.
-    """

src/firebase_functions/db.py

@@ -11,8 +11,6 @@
 # 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.
-
-
 """
 Module for Cloud Functions that are triggered by the Firebase Realtime Database.
 """
@@ -21,18 +19,36 @@
 import functools as _functools
 import typing as _typing
 import datetime as _dt
-import firebase_functions.options as _options
 import firebase_functions.private.util as _util
 import firebase_functions.core as _core
 import cloudevents.http as _ce
-from firebase_functions.core import Change  # Exported for user ease of typing events
+
+from firebase_functions.options import DatabaseOptions
 
 _event_type_written = "google.firebase.database.ref.v1.written"
 _event_type_created = "google.firebase.database.ref.v1.created"
 _event_type_updated = "google.firebase.database.ref.v1.updated"
 _event_type_deleted = "google.firebase.database.ref.v1.deleted"
 
 
+@_dataclass.dataclass(frozen=True)
+class Change(_typing.Generic[_core.T]):
+    """
+    * The Functions interface for events that change state, such as
+    * Realtime Database `on_value_written`.
+    """
+
+    before: _core.T
+    """
+    The state of data before the change.
+    """
+
+    after: _core.T
+    """
+    The state of data after the change.
+    """
+
+
 @_dataclass.dataclass(frozen=True)
 class Event(_core.CloudEvent[_core.T]):
     """
@@ -87,7 +103,7 @@ def _db_endpoint_handler(
         # Merge delta into data to generate an 'after' view of the data.
         if isinstance(before, dict) and isinstance(after, dict):
             after = _util.prune_nones({**before, **after})
-        database_event_data = _core.Change(
+        database_event_data = Change(
             before=before,
             after=after,
         )
@@ -111,7 +127,7 @@ def _db_endpoint_handler(
     func(database_event)
 
 
-@_util.copy_func_kwargs(_options.DatabaseOptions)
+@_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.
@@ -124,8 +140,14 @@ def on_value_written(**kwargs) -> _typing.Callable[[_C1], _C1]:
       def example(event: Event[Change[object]]) -> None:
           pass
 
+    :param \\*\\*kwargs: Database options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.DatabaseOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.db.Event` \\[
+            :exc:`firebase_functions.db.Change` \\] \\], `None` \\]
+            A function that takes a Database Event and returns None.
     """
-    options = _options.DatabaseOptions(**kwargs)
+    options = DatabaseOptions(**kwargs)
 
     def on_value_written_inner_decorator(func: _C1):
 
@@ -143,7 +165,7 @@ def on_value_written_wrapped(raw: _ce.CloudEvent):
     return on_value_written_inner_decorator
 
 
-@_util.copy_func_kwargs(_options.DatabaseOptions)
+@_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.
@@ -156,8 +178,14 @@ def on_value_updated(**kwargs) -> _typing.Callable[[_C1], _C1]:
       def example(event: Event[Change[object]]) -> None:
           pass
 
+    :param \\*\\*kwargs: Database options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.DatabaseOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.db.Event` \\[
+            :exc:`firebase_functions.db.Change` \\] \\], `None` \\]
+            A function that takes a Database Event and returns None.
     """
-    options = _options.DatabaseOptions(**kwargs)
+    options = DatabaseOptions(**kwargs)
 
     def on_value_updated_inner_decorator(func: _C1):
 
@@ -175,7 +203,7 @@ def on_value_updated_wrapped(raw: _ce.CloudEvent):
     return on_value_updated_inner_decorator
 
 
-@_util.copy_func_kwargs(_options.DatabaseOptions)
+@_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.
@@ -185,10 +213,17 @@ def on_value_created(**kwargs) -> _typing.Callable[[_C2], _C2]:
     .. code-block:: python
 
         @on_value_created(reference="*")
-        def example(event):
+        def example(event: Event[object]):
           pass
+
+    :param \\*\\*kwargs: Database options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.DatabaseOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.db.Event` \\[
+            :exc:`object` \\] \\], `None` \\]
+            A function that takes a Database Event and returns None.
     """
-    options = _options.DatabaseOptions(**kwargs)
+    options = DatabaseOptions(**kwargs)
 
     def on_value_created_inner_decorator(func: _C2):
 
@@ -206,7 +241,7 @@ def on_value_created_wrapped(raw: _ce.CloudEvent):
     return on_value_created_inner_decorator
 
 
-@_util.copy_func_kwargs(_options.DatabaseOptions)
+@_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.
@@ -219,8 +254,14 @@ def on_value_deleted(**kwargs) -> _typing.Callable[[_C2], _C2]:
       def example(event: Event[object]) -> None:
           pass
 
+    :param \\*\\*kwargs: Database options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.DatabaseOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.db.Event` \\[
+            :exc:`object` \\] \\], `None` \\]
+            A function that takes a Database Event and returns None.
     """
-    options = _options.DatabaseOptions(**kwargs)
+    options = DatabaseOptions(**kwargs)
 
     def on_value_deleted_inner_decorator(func: _C2):
 

src/firebase_functions/https.py

@@ -11,8 +11,6 @@
 # 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.
-
-
 """Module for Cloud Functions that listen to HTTPS endpoints.
 These can be raw web requests and Callable RPCs.
 """
@@ -23,11 +21,11 @@
 import typing_extensions as _typing_extensions
 import enum as _enum
 import json as _json
-import firebase_functions.options as _options
 import firebase_functions.private.util as _util
 import firebase_functions.core as _core
 from functions_framework import logging as _logging
 
+from firebase_functions.options import HttpsOptions
 from flask import Request, Response, make_response as _make_response, jsonify as _jsonify
 from flask_cors import cross_origin as _cross_origin
 
@@ -407,7 +405,7 @@ def _on_call_handler(func: _C2, request: Request) -> Response:
         return _make_response(_jsonify(error=err._as_dict()), status)
 
 
-@_util.copy_func_kwargs(_options.HttpsOptions)
+@_util.copy_func_kwargs(HttpsOptions)
 def on_request(**kwargs) -> _typing.Callable[[_C1], _C1]:
     """
     Handler which handles HTTPS requests.
@@ -421,8 +419,12 @@ def on_request(**kwargs) -> _typing.Callable[[_C1], _C1]:
       def example(request: Request) -> Response:
           pass
 
+    :param \\*\\*kwargs: Https options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.HttpsOptions`
+    :rtype: :exc:`typing.Callable` \\[ \\[ :exc:`flask.Request` \\], :exc:`flask.Response` \\]
+            A function that takes a :exc:`flask.Request` and returns a :exc:`flask.Response`.
     """
-    options = _options.HttpsOptions(**kwargs)
+    options = HttpsOptions(**kwargs)
 
     def on_request_inner_decorator(func: _C1):
 
@@ -444,7 +446,7 @@ def on_request_wrapped(request: Request) -> Response:
     return on_request_inner_decorator
 
 
-@_util.copy_func_kwargs(_options.HttpsOptions)
+@_util.copy_func_kwargs(HttpsOptions)
 def on_call(**kwargs) -> _typing.Callable[[_C2], _C2]:
     """
     Declares a callable method for clients to call using a Firebase SDK.
@@ -456,10 +458,16 @@ def on_call(**kwargs) -> _typing.Callable[[_C2], _C2]:
 
       @on_call()
       def example(request: CallableRequest) -> Any:
-          pass
+          return "Hello World"
 
+    :param \\*\\*kwargs: Https options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.HttpsOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.https.CallableRequest` \\[
+            :exc:`object` \\] \\], :exc:`object` \\]
+            A function that takes a CallableRequest and returns an :exc:`object`.
     """
-    options = _options.HttpsOptions(**kwargs)
+    options = HttpsOptions(**kwargs)
 
     def on_call_inner_decorator(func: _C2):
         origins: _typing.Any = "*"

src/firebase_functions/pubsub.py

@@ -23,9 +23,10 @@
 import base64 as _base64
 import cloudevents.http as _ce
 
-import firebase_functions.options as _options
 import firebase_functions.private.util as _util
+
 from firebase_functions.core import CloudEvent, T
+from firebase_functions.options import PubSubOptions
 
 
 @_dataclasses.dataclass(frozen=True)
@@ -153,7 +154,7 @@ def _message_handler(
     func(event)
 
 
-@_util.copy_func_kwargs(_options.PubSubOptions)
+@_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.
@@ -166,8 +167,15 @@ def on_message_published(**kwargs) -> _typing.Callable[[_C1], _C1]:
       def example(event: CloudEvent[MessagePublishedData[object]]) -> None:
           pass
 
+    :param \\*\\*kwargs: Pub/Sub options.
+    :type \\*\\*kwargs: as :exc:`firebase_functions.options.PubSubOptions`
+    :rtype: :exc:`typing.Callable`
+            \\[ \\[ :exc:`firebase_functions.core.CloudEvent` \\[
+            :exc:`firebase_functions.pubsub.MessagePublishedData` \\[
+            :exc:`typing.Any` \\] \\] \\], `None` \\]
+            A function that takes a CloudEvent and returns None.
     """
-    options = _options.PubSubOptions(**kwargs)
+    options = PubSubOptions(**kwargs)
 
     def on_message_published_inner_decorator(func: _C1):