Several minor issues (#127)

Fixes #125
Fixes #124
Fixes #122
Fixes #119
Fixes #118
Fixes #117
Fixes #115
Fixes #114
Fixes #110
Fixes #103
Fixes #92
Fixes #40

Author: cretz

.github/workflows/ci.yml

@@ -59,17 +59,8 @@ jobs:
         run: poe gen-docs
       - name: Deploy prod API docs
         if: ${{ github.ref == 'refs/heads/main' && matrix.docsTarget }}
-        uses: netlify/actions/cli@master
-        with:
-          args: deploy --dir=build/apidocs --prod
-        env:
-          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
-          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
-      - name: Deploy draft API docs
-        if: ${{ github.ref != 'refs/heads/main' && matrix.docsTarget }}
-        uses: netlify/actions/cli@master
-        with:
-          args: deploy --dir=build/apidocs
+        # Using NPX instead of action due to https://github.com/netlify/actions/issues/60
+        run: npx netlify-cli deploy --build --dir=build/apidocs --prod
         env:
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

pyproject.toml

@@ -141,6 +141,7 @@ add_ignore = [
 add-package = ["temporalio"]
 docformat = "google"
 html-output = "build/apidocs"
+html-viewsource-base = "https://github.com/temporalio/sdk-python/tree/main"
 intersphinx = [
   "https://docs.python.org/3/objects.inv",
   "https://googleapis.dev/python/protobuf/latest/objects.inv",
@@ -158,7 +159,7 @@ privacy = [
   "HIDDEN:temporalio.worker.workflow_instance",
   "HIDDEN:**.*_pb2*",
 ]
-project-name = "Temporal"
+project-name = "Temporal Python"
 sidebar-expand-depth = 2
 
 [build-system]

scripts/gen_protos.py

@@ -12,9 +12,10 @@
 proto_dir = base_dir / "temporalio" / "bridge" / "sdk-core" / "protos"
 api_proto_dir = proto_dir / "api_upstream"
 core_proto_dir = proto_dir / "local"
+health_proto_dir = proto_dir / "grpc"
 testsrv_proto_dir = proto_dir / "testsrv_upstream"
 
-# Exclude testsrv dependencies
+# Exclude testsrv dependencies protos
 proto_paths = (
     v
     for v in proto_dir.glob("**/*.proto")
@@ -77,7 +78,7 @@ def fix_generated_output(base_path: Path):
     with (base_path / "__init__.py").open("w") as f:
         # Add docstring to API's init
         if str(base_path.as_posix()).endswith("/temporal/api"):
-            f.write('"""gRPC API."""\n')
+            f.write('"""Temporal API protobuf models."""\n')
         # Non-gRPC imports
         message_names = []
         for stem, messages in imports.items():
@@ -124,13 +125,17 @@ def fix_generated_output(base_path: Path):
                 f"--proto_path={api_proto_dir}",
                 f"--proto_path={core_proto_dir}",
                 f"--proto_path={testsrv_proto_dir}",
+                f"--proto_path={health_proto_dir}",
                 f"--python_out={temp_dir}",
                 f"--grpc_python_out={temp_dir}",
                 f"--mypy_out={temp_dir}",
                 f"--mypy_grpc_out={temp_dir}",
                 *map(str, proto_paths),
             ]
         )
+        # Remove health gRPC parts
+        (temp_dir / "health" / "v1" / "health_pb2_grpc.py").unlink()
+        (temp_dir / "health" / "v1" / "health_pb2_grpc.pyi").unlink()
         # Apply fixes before moving code
         fix_generated_output(temp_dir)
         # Move protos
@@ -142,4 +147,6 @@ def fix_generated_output(base_path: Path):
         for p in (temp_dir / "temporal" / "sdk" / "core").iterdir():
             shutil.rmtree(sdk_out_dir / p.name, ignore_errors=True)
             p.replace(sdk_out_dir / p.name)
+        shutil.rmtree(sdk_out_dir / "health", ignore_errors=True)
+        (temp_dir / "health").replace(sdk_out_dir / "health")
     print("Done", file=sys.stderr)

temporalio/__init__.py

@@ -1,4 +1,12 @@
-"""Python SDK for Temporal."""
+"""Python SDK for Temporal.
+
+See the
+`Temporal Application Development Guide <https://docs.temporal.io/application-development/?lang=python>`_
+and the `GitHub project <https://github.com/temporalio/sdk-python>`_.
+
+Most users will use :py:mod:`client` for creating a client to Temporal and
+:py:mod:`worker` to run workflows and activities.
+"""
 
 from .service import __version__ as __sdk_version
 

temporalio/activity.py

@@ -21,12 +21,13 @@
 from typing import (
     Any,
     Callable,
-    Iterable,
     Mapping,
     MutableMapping,
     NoReturn,
     Optional,
+    Sequence,
     Tuple,
+    Union,
     overload,
 )
 
@@ -81,7 +82,7 @@ class Info:
     activity_type: str
     attempt: int
     current_attempt_scheduled_time: datetime
-    heartbeat_details: Iterable[Any]
+    heartbeat_details: Sequence[Any]
     heartbeat_timeout: Optional[timedelta]
     is_local: bool
     schedule_to_close_timeout: Optional[timedelta]
@@ -227,7 +228,7 @@ async def wait_for_cancelled() -> None:
     await _Context.current().cancelled_event.wait()
 
 
-def wait_for_cancelled_sync(timeout: Optional[float] = None) -> None:
+def wait_for_cancelled_sync(timeout: Optional[Union[timedelta, float]] = None) -> None:
     """Synchronously block while waiting for a cancellation request on this
     activity.
 
@@ -239,7 +240,9 @@ def wait_for_cancelled_sync(timeout: Optional[float] = None) -> None:
     Raises:
         RuntimeError: When not in an activity.
     """
-    _Context.current().cancelled_event.wait_sync(timeout)
+    _Context.current().cancelled_event.wait_sync(
+        timeout.total_seconds() if isinstance(timeout, timedelta) else timeout
+    )
 
 
 def is_worker_shutdown() -> bool:
@@ -263,7 +266,9 @@ async def wait_for_worker_shutdown() -> None:
     await _Context.current().worker_shutdown_event.wait()
 
 
-def wait_for_worker_shutdown_sync(timeout: Optional[float] = None) -> None:
+def wait_for_worker_shutdown_sync(
+    timeout: Optional[Union[timedelta, float]] = None
+) -> None:
     """Synchronously block while waiting for shutdown to be called on the
     worker.
 
@@ -276,7 +281,9 @@ def wait_for_worker_shutdown_sync(timeout: Optional[float] = None) -> None:
     Raises:
         RuntimeError: When not in an activity.
     """
-    _Context.current().worker_shutdown_event.wait_sync(timeout)
+    _Context.current().worker_shutdown_event.wait_sync(
+        timeout.total_seconds() if isinstance(timeout, timedelta) else timeout
+    )
 
 
 def raise_complete_async() -> NoReturn:

temporalio/api/__init__.py

@@ -1 +1 @@
-"""gRPC API."""
+"""Temporal API protobuf models."""

temporalio/api/batch/__init__.py

@@ -0,0 +1,13 @@
+from .message_pb2 import (
+    BatchOperationCancellation,
+    BatchOperationInfo,
+    BatchOperationSignal,
+    BatchOperationTermination,
+)
+
+__all__ = [
+    "BatchOperationCancellation",
+    "BatchOperationInfo",
+    "BatchOperationSignal",
+    "BatchOperationTermination",
+]