More docs and incorporate pydocstyle into CI/lint check

Author: cretz

pyproject.toml

@@ -37,7 +37,7 @@ build-bridge = "python scripts/build-bridge.py"
 format = [{cmd = "black ."}, {cmd = "isort ."}]
 gen-docs = "sphinx-build docs docs/_build"
 gen-protos = "python scripts/gen-protos.py"
-lint = [{cmd = "black --check ."}, {cmd = "isort --check-only ."}, "lint-types"] # TODO(cretz): Add lint-docs
+lint = [{cmd = "black --check ."}, {cmd = "isort --check-only ."}, "lint-types", "lint-docs"]
 lint-docs = "pydocstyle"
 lint-types = "mypy ."
 test = "pytest"
@@ -61,6 +61,11 @@ exclude = [
 convention = "google"
 # https://github.com/PyCQA/pydocstyle/issues/363#issuecomment-625563088
 match_dir = "^(?!(docs|scripts|tests|api|proto|\\.)).*"
+add_ignore = [
+  # We like to wrap at a certain number of chars, even long summary sentences.
+  # https://github.com/PyCQA/pydocstyle/issues/184
+  "D205", "D415"
+]
 
 [build-system]
 build-backend = "poetry.core.masonry.api"

temporalio/bridge/__init__.py

@@ -0,0 +1 @@
+"""Python interface to SDK Core."""

temporalio/bridge/client.py

@@ -1,3 +1,5 @@
+"""RPC client using SDK Core."""
+
 from __future__ import annotations
 
 from dataclasses import dataclass
@@ -10,6 +12,8 @@
 
 @dataclass
 class ClientTlsConfig:
+    """Python representation of the Rust struct for configuring TLS."""
+
     server_root_ca_cert: Optional[bytes]
     domain: Optional[str]
     client_cert: Optional[bytes]
@@ -18,6 +22,8 @@ class ClientTlsConfig:
 
 @dataclass
 class ClientRetryConfig:
+    """Python representation of the Rust struct for configuring retry."""
+
     initial_interval_millis: int
     randomization_factor: float
     multiplier: float
@@ -28,6 +34,8 @@ class ClientRetryConfig:
 
 @dataclass
 class ClientOptions:
+    """Python representation of the Rust struct for configuring the client."""
+
     target_url: str
     static_headers: Mapping[str, str]
     identity: str
@@ -43,13 +51,17 @@ class ClientOptions:
 
 
 class Client:
+    """RPC client using SDK Core."""
+
     @staticmethod
     async def connect(opts: ClientOptions) -> Client:
+        """Establish connection with server."""
         return Client(await temporal_sdk_bridge.connect_client(opts))
 
     _ref: temporal_sdk_bridge.ClientRef
 
     def __init__(self, ref: temporal_sdk_bridge.ClientRef):
+        """Initialize client with underlying SDK Core reference."""
         self._ref = ref
 
     async def rpc_call(
@@ -60,6 +72,7 @@ async def rpc_call(
         *,
         retry: bool = False,
     ) -> ProtoMessage:
+        """Make RPC call using SDK Core."""
         resp = resp_type()
         resp.ParseFromString(await self._ref.call(rpc, retry, req.SerializeToString()))
         return resp

temporalio/client.py

@@ -55,7 +55,7 @@ async def connect(
             Union[Interceptor, Callable[[OutboundInterceptor], OutboundInterceptor]]
         ] = [],
         default_workflow_query_reject_condition: Optional[
-            temporalio.common.WorkflowQueryRejectCondition
+            temporalio.common.QueryRejectCondition
         ] = None,
         tls_config: Optional[TLSConfig] = None,
         retry_config: Optional[RetryConfig] = None,
@@ -105,14 +105,6 @@ async def connect(
             data_converter=data_converter,
             interceptors=interceptors,
             default_workflow_query_reject_condition=default_workflow_query_reject_condition,
-            connect_options=ConnectOptions(
-                target_url=connect_options.target_url,
-                tls_config=connect_options.tls_config,
-                retry_config=connect_options.retry_config,
-                static_headers=connect_options.static_headers,
-                identity=connect_options.identity,
-                worker_binary_id=connect_options.worker_binary_id,
-            ),
         )
 
     def __init__(
@@ -125,16 +117,12 @@ def __init__(
             Union[Interceptor, Callable[[OutboundInterceptor], OutboundInterceptor]]
         ] = [],
         default_workflow_query_reject_condition: Optional[
-            temporalio.common.WorkflowQueryRejectCondition
+            temporalio.common.QueryRejectCondition
         ] = None,
-        connect_options: Optional[ConnectOptions] = None,
     ):
         """Create a Temporal client from a workflow service.
 
         See :py:meth:`connect` for details on the parameters.
-
-        Note, connect_options in this initializer are only for tracking and are
-        not used by this class in any way.
         """
         # Iterate over interceptors in reverse building the impl
         self._impl: OutboundInterceptor = _ClientImpl(self)
@@ -153,18 +141,14 @@ def __init__(
             data_converter=data_converter,
             interceptors=interceptors,
             default_workflow_query_reject_condition=default_workflow_query_reject_condition,
-            connect_options=connect_options,
         )
 
     def options(self) -> ClientOptions:
         """Options used to create this client as a dictionary.
 
         This makes a shallow copy of the options each call.
         """
-        options = self._options.copy()
-        if options["connect_options"]:
-            options["connect_options"] = options["connect_options"].copy()
-        return options
+        return self._options.copy()
 
     @property
     def service(self) -> temporalio.workflow_service.WorkflowService:
@@ -311,6 +295,9 @@ def get_workflow_handle(
             run_id: Run ID that will be used for all calls.
             first_execution_run_id: First execution run ID used for cancellation
                 and termination.
+
+        Returns:
+            The workflow handle.
         """
         return WorkflowHandle(
             self,
@@ -321,17 +308,6 @@ def get_workflow_handle(
         )
 
 
-class ConnectOptions(typing_extensions.TypedDict):
-    """TypedDict of options originally passed to :py:class:`Client`."""
-
-    target_url: str
-    tls_config: Optional[TLSConfig]
-    retry_config: Optional[RetryConfig]
-    static_headers: Mapping[str, str]
-    identity: str
-    worker_binary_id: str
-
-
 class ClientOptions(typing_extensions.TypedDict):
     """TypedDict of options originally passed to :py:meth:`Client`."""
 
@@ -342,9 +318,8 @@ class ClientOptions(typing_extensions.TypedDict):
         Union[Interceptor, Callable[[OutboundInterceptor], OutboundInterceptor]]
     ]
     default_workflow_query_reject_condition: Optional[
-        temporalio.common.WorkflowQueryRejectCondition
+        temporalio.common.QueryRejectCondition
     ]
-    connect_options: Optional[ConnectOptions]
 
 
 T = TypeVar("T")
@@ -571,21 +546,21 @@ async def cancel(self) -> None:
 
     async def describe(
         self,
-    ) -> "WorkflowDescription":
+    ) -> WorkflowDescription:
         """Get workflow details.
 
         This will get details for :py:attr:`run_id` if present. To use a
         different run ID, create a new handle with via
         :py:meth:`Client.get_workflow_handle`.
 
-        Returns:
-            Workflow details.
-
         .. warning::
             Handles created as a result of :py:meth:`Client.start_workflow` will
             describe the latest workflow with the same workflow ID even if it is
             unrelated to the started workflow.
 
+        Returns:
+            Workflow details.
+
         Raises:
             RPCError: Workflow details could not be fetched.
         """
@@ -606,12 +581,19 @@ async def query(
         self,
         query: str,
         *args: Any,
-        reject_condition: Optional[
-            temporalio.common.WorkflowQueryRejectCondition
-        ] = None,
+        reject_condition: Optional[temporalio.common.QueryRejectCondition] = None,
     ) -> Any:
         """Query the workflow.
 
+        This will query for :py:attr:`run_id` if present. To use a different
+        run ID, create a new handle with via
+        :py:meth:`Client.get_workflow_handle`.
+
+        .. warning::
+            Handles created as a result of :py:meth:`Client.start_workflow` will
+            query the latest workflow with the same workflow ID even if it is
+            unrelated to the started workflow.
+
         Args:
             query: Query name on the workflow.
             args: Query arguments.
@@ -624,15 +606,6 @@ async def query(
         Raises:
             WorkflowQueryRejectedError: A query reject condition was satisfied.
             RPCError: Workflow details could not be fetched.
-
-        This will query for :py:attr:`run_id` if present. To use a different
-        run ID, create a new handle with via
-        :py:meth:`Client.get_workflow_handle`.
-
-        .. warning::
-            Handles created as a result of :py:meth:`Client.start_workflow` will
-            query the latest workflow with the same workflow ID even if it is
-            unrelated to the started workflow.
         """
         return await self._client._impl.query_workflow(
             QueryWorkflowInput(
@@ -648,6 +621,15 @@ async def query(
     async def signal(self, name: str, *args: Any) -> None:
         """Send a signal to the workflow.
 
+        This will signal for :py:attr:`run_id` if present. To use a different
+        run ID, create a new handle with via
+        :py:meth:`Client.get_workflow_handle`.
+
+        .. warning::
+            Handles created as a result of :py:meth:`Client.start_workflow` will
+            signal the latest workflow with the same workflow ID even if it is
+            unrelated to the started workflow.
+
         Args:
             name: Signal name on the workflow.
             args: Signal arguments.
@@ -657,15 +639,6 @@ async def signal(self, name: str, *args: Any) -> None:
 
         Raises:
             RPCError: Workflow could not be signalled.
-
-        This will signal for :py:attr:`run_id` if present. To use a different
-        run ID, create a new handle with via
-        :py:meth:`Client.get_workflow_handle`.
-
-        .. warning::
-            Handles created as a result of :py:meth:`Client.start_workflow` will
-            signal the latest workflow with the same workflow ID even if it is
-            unrelated to the started workflow.
         """
         await self._client._impl.signal_workflow(
             SignalWorkflowInput(
@@ -683,13 +656,6 @@ async def terminate(
     ) -> None:
         """Terminate the workflow.
 
-        Args:
-            args: Details to store on the termination.
-            reason: Reason for the termination.
-
-        Raises:
-            RPCError: Workflow could not be terminated.
-
         This will issue a termination for :py:attr:`run_id` if present. This
         call will make sure to use the run chain starting from
         :py:attr:`first_execution_run_id` if present. To create handles with
@@ -699,6 +665,13 @@ async def terminate(
             Handles created as a result of :py:meth:`Client.start_workflow` with
             a start signal will terminate the latest workflow with the same
             workflow ID even if it is unrelated to the started workflow.
+
+        Args:
+            args: Details to store on the termination.
+            reason: Reason for the termination.
+
+        Raises:
+            RPCError: Workflow could not be terminated.
         """
         await self._client._impl.terminate_workflow(
             TerminateWorkflowInput(
@@ -718,6 +691,7 @@ def __init__(
         self,
         raw_message: temporalio.api.workflowservice.v1.DescribeWorkflowExecutionResponse,
     ):
+        """Create a workflow description from a describe response."""
         self._raw_message = raw_message
         status = raw_message.workflow_execution_info.status
         self._status = WorkflowExecutionStatus(status) if status else None
@@ -801,6 +775,7 @@ def __init__(self, new_execution_run_id: str) -> None:
 
     @property
     def new_execution_run_id(self) -> str:
+        """New execution run ID the workflow continued to"""
         return self._new_execution_run_id
 
 
@@ -856,7 +831,7 @@ class QueryWorkflowInput:
     run_id: Optional[str]
     query: str
     args: Iterable[Any]
-    reject_condition: Optional[temporalio.common.WorkflowQueryRejectCondition]
+    reject_condition: Optional[temporalio.common.QueryRejectCondition]
 
 
 @dataclass

temporalio/common.py

@@ -36,6 +36,7 @@ class RetryPolicy:
     """List of error types that are not retryable."""
 
     def apply_to_proto(self, proto: temporalio.api.common.v1.RetryPolicy) -> None:
+        """Apply the fields in this policy to the given proto object."""
         proto.initial_interval.FromTimedelta(self.initial_interval)
         proto.backoff_coefficient = self.backoff_coefficient
         proto.maximum_interval.FromTimedelta(
@@ -68,7 +69,7 @@ class WorkflowIDReusePolicy(IntEnum):
     """See :py:attr:`temporalio.api.enums.v1.WorkflowIdReusePolicy.WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE`."""
 
 
-class WorkflowQueryRejectCondition(IntEnum):
+class QueryRejectCondition(IntEnum):
     """Whether a query should be rejected in certain conditions.
 
     See :py:class:`temporalio.api.enums.v1.QueryRejectCondition`.

temporalio/converter.py

@@ -421,6 +421,9 @@ def default() -> CompositeDataConverter:
 async def decode_payloads(
     payloads: Optional[temporalio.api.common.v1.Payloads], converter: DataConverter
 ) -> List[Any]:
+    """Decode :py:class:`temporalio.api.common.v1.Payloads` with the given
+    converter.
+    """
     if not payloads or not payloads.payloads:
         return []
     return await converter.decode(payloads.payloads)