@activity.defn support and other minor things

.gitignore

@@ -2,6 +2,7 @@
 __pycache__
 /build
 /dist
+/docs/_autosummary
 /docs/_build
 temporalio/api/*
 !temporalio/api/__init__.py

README.md

@@ -125,7 +125,9 @@ import asyncio
 import logging
 from temporalio.client import Client
 from temporalio.worker import Worker
+from temporalio import activity
 
+@activity.defn
 async def say_hello_activity(name: str) -> str:
     return f"Hello, {name}!"
 
@@ -135,7 +137,7 @@ async def main(stop_event: asyncio.Event):
   client = await Client.connect("http://localhost:7233", namespace="my-namespace")
 
   # Run the worker until the event is set
-  worker = Worker(client, task_queue="my-task-queue", activities={"say-hello-activity": say_hello_activity})
+  worker = Worker(client, task_queue="my-task-queue", activities=[say_hello_activity])
   async with worker:
     await stop_event.wait()
 ```
@@ -148,6 +150,7 @@ Some things to note about the above code:
 * Activities are passed as a mapping with the key as a string activity name and the value as a callable
 * While this example accepts a stop event and uses `async with`, `run()` and `shutdown()` may be used instead
 * Workers can have many more options not shown here (e.g. data converters and interceptors)
+* A custom name for the activity can be set with a decorator argument, e.g. `@activity.defn(name="my activity")`
 
 #### Types of Activities
 
@@ -276,4 +279,14 @@ The Python SDK is built to work with Python 3.7 and newer. It is built using
 
   ```bash
   poe test
-  ```
+  ```
+
+### Style
+
+* Mostly [Google Style Guide](https://google.github.io/styleguide/pyguide.html). Notable exceptions:
+  * We use [Black](https://github.com/psf/black) for formatting, so that takes precedence
+  * In tests and example code, can import individual classes/functions to make it more readable. Can also do this for
+    rarely in library code for some Python common items (e.g. `dataclass` or `partial`), but not allowed to do this for
+    any `temporalio` packages or any classes/functions that aren't clear when unqualified.
+  * We allow relative imports for private packages
+  * We allow `@staticmethod`

docs/_templates/custom_module_template.rst

@@ -0,0 +1,20 @@
+
+{{ fullname | escape | underline}}
+===============
+
+.. automodule:: {{ fullname }}
+   :members:
+
+{% block modules %}
+{% if fullname != "temporalio.worker" %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: custom_module_template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endif %}
+{% endblock %}

docs/conf.py

@@ -30,6 +30,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
 ]
@@ -54,12 +55,18 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_theme_options = {
+    "light_logo": "temporal-logo-light-mode.svg",
+    "dark_logo": "temporal-logo-dark-mode.svg",
+}
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None),
 }
 
+html_title = "API Documentation"
+
 autodoc_docstring_signature = True
 
 autodoc_typehints = "description"
@@ -75,3 +82,5 @@
 autodoc_default_options = {
     "special-members": "__aenter__,__aexit__,__init__",
 }
+
+autosummary_generate = True

docs/index.rst

@@ -1,22 +1,26 @@
-.. Temporal Python SDK documentation master file, created by
-   sphinx-quickstart on Fri Feb  4 11:52:42 2022.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Temporal Python SDK
-===================
+Temporal Python SDK API Documentation
+=====================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+Modules
+-------
 
-   api
-   direct_api
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom_module_template.rst
+   :recursive:
 
+   temporalio.client
+   temporalio.worker
+   temporalio.activity
+   temporalio.converter
+   temporalio.exceptions
+   temporalio.api
+   temporalio.workflow_service
 
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

pyproject.toml

@@ -40,13 +40,14 @@ isort = "^5.10.1"
 mypy = "^0.931"
 mypy-protobuf = "^3.2.0"
 pydocstyle = "^6.1.1"
-pytest = "^6.2.5"
+pytest = "^7.1.1"
 pytest-asyncio = "^0.18.0"
 pytest-timeout = "^2.1.0"
 setuptools = "^60.9.3"
 setuptools-rust = "^1.1.2"
 Sphinx = "^4.4.0"
 sphinxcontrib-napoleon = "^0.7"
+toml = "^0.10.2"
 twine = "^3.8.0"
 
 [tool.poe.tasks]

temporalio/activity.py

@@ -15,6 +15,7 @@
 import threading
 from dataclasses import dataclass
 from datetime import datetime, timedelta
+from functools import partial
 from typing import (
     Any,
     Callable,
@@ -24,12 +25,57 @@
     NoReturn,
     Optional,
     Tuple,
+    TypeVar,
+    overload,
 )
 
 import temporalio.api.common.v1
 import temporalio.common
 import temporalio.exceptions
 
+ActivityFunc = TypeVar("ActivityFunc", bound=Callable[..., Any])
+
+
+@overload
+def defn(fn: ActivityFunc) -> ActivityFunc:
+    ...
+
+
+@overload
+def defn(*, name: str) -> Callable[[ActivityFunc], ActivityFunc]:
+    ...
+
+
+def defn(fn: Optional[ActivityFunc] = None, *, name: Optional[str] = None):
+    """Decorator for activity functions.
+
+    Activities can be async or non-async.
+
+    Args:
+        fn: The function to decorate.
+        name: Name to use for the activity. Defaults to function ``__name__``.
+    """
+
+    def with_name(name: str, fn: ActivityFunc) -> ActivityFunc:
+        # Validate the activity
+        if not callable(fn):
+            raise TypeError("Activity is not callable")
+        elif not fn.__code__:
+            raise TypeError("Activity callable missing __code__")
+        elif fn.__code__.co_kwonlyargcount:
+            raise TypeError("Activity cannot have keyword-only arguments")
+        # Set the name
+        setattr(fn, "__temporal_activity_name", name)
+        return fn
+
+    # If name option is available, return decorator function
+    if name is not None:
+        return partial(with_name, name)
+    if fn is None:
+        raise RuntimeError("Cannot invoke defn without function or name")
+    # Otherwise just run decorator function
+    return with_name(fn.__name__, fn)
+
 
 @dataclass(frozen=True)
 class Info:

temporalio/api/__init__.py

@@ -0,0 +1 @@
+"""gRPC API."""

temporalio/converter.py

@@ -1,4 +1,4 @@
-"""Base converter and default implementations for conversion to/from values/payloads."""
+"""Base converter and implementations for data conversion."""
 
 import dataclasses
 import inspect