docs

docs/installation/production/manual/configuration/basic/static_and_workspaces.rst

@@ -83,11 +83,13 @@ The app workspaces directory is one location where all app workspaces are collec
 3. Collect the app workspaces to the ``TETHYS_WORKSPACES_ROOT`` location:
 
     .. code-block::
+
         tethys manage collectworkspaces
 
 .. tip::
 
     You can collect both the static files and the app workspaces with a single command:
 
     .. code-block::
+
             tethys manage collectall

docs/tethys_sdk/jobs.rst

@@ -71,7 +71,6 @@ You can now use the job manager to create a new job, or retrieve an existing job
 Creating and Executing a Job
 ----------------------------
 To create a new job call the ``create_job`` method on the job manager. The required arguments are:
-
     * ``name``: A unique string identifying the job
     * ``user``: A user object, usually from the request argument: `request.user`
     * ``job_type``: A string specifying on of the supported job types (see `Job Types`_)
@@ -119,13 +118,11 @@ Common Attributes
 Job attributes can be passed into the `create_job` method of the job manager or they can be specified after the job is instantiated. All jobs have a common set of attributes. Each job type may have additional attributes specific that are to that job type.
 
 The following attributes can be defined for *all* job types:
-
     * ``name`` (string, required): a unique identifier for the job. This should not be confused with the job template name. The template name identifies a template from which jobs can be created and is set when the template is created. The job ``name`` attribute is defined when the job is created (see `Creating and Executing a Job`_).
     * ``description`` (string): a short description of the job.
     * ``workspace`` (string): a path to a directory that will act as the workspace for the job. Each job type may interact with the workspace differently. By default the workspace is set to the user's workspace in the app that is creating the job.
     * ``extended_properties`` (dict): a dictionary of additional properties that can be used to create custom job attributes.
-    * ``status`` (string): a string representing the state of the job. Possible statuses are:
-
+    * ``status`` (string): a string representing the state of the job. When accessed the status will be updated if necessary. Possible statuses are:
         - 'Pending'
         - 'Submitted'
         - 'Running'
@@ -138,10 +135,12 @@ The following attributes can be defined for *all* job types:
         - 'Other'\**
 
         \*used for job types with multiple sub-jobs (e.g. CondorWorkflow).
+
         \**When  a custom job status is set the official status is 'Other', but the custom status is stored as an extended property of the job.
 
-All job types also have the following **read-only** attributes:
+    * ``cached_status`` (string): Same as the ``status`` attribute, except that the status is not actively updated. Rather the last known status is returned.
 
+All job types also have the following **read-only** attributes:
     * ``user`` (User): the user who created the job.
     * ``label`` (string): the package name of the Tethys App used to created the job.
     * ``creation_time`` (datetime): the time the job was created.
@@ -152,8 +151,7 @@ All job types also have the following **read-only** attributes:
 Job Types
 ---------
 
-The Jobs API is designed to support multiple job types. Each job type provides a different framework and environment for executing jobs. When creating a new job you must specify its type by passing in the `job_type` argument. Supported values for `job_type` are:
-
+The Jobs API is designed to support multiple job types. Each job type provides a different framework and environment for executing jobs. When creating a new job you must specify its type by passing in the ``job_type`` argument. Supported values for ``job_type`` are:
     * 'BASIC'
     * 'CONDOR' or 'CONDORJOB'
     * 'CONDORWORKFLOW'
@@ -193,7 +191,7 @@ Two methods are provided to retrieve jobs: ``list_jobs`` and ``get_job``. Jobs a
 
 Jobs Table Gizmo
 ----------------
-The Jobs Table Gizmo facilitates job management through the web interface and is designed to be used in conjunction with the Job Manager. It can be configured to list any of the properties of the jobs, and will automatically update the job status. It also can provide a list of actions that can be done on the a job. In addition to several build-in actions (including run, delete, viewing job results, etc.), developers can also create custom actions to include in the actions dropdown list. The following code sample shows how to use the job manager to populate the jobs table:
+The Jobs Table Gizmo facilitates job management through the web interface and is designed to be used in conjunction with the Job Manager. It can be configured to list any of the properties of the jobs, and will automatically update the job status. It also can provide a list of actions that can be done on the a job. In addition to several build-in actions (including run, delete, viewing job results, etc.), developers can also create custom actions to include in the actions dropdown list. Note that while none of the built-in actions are asynchronous on any of the built-in `Job Types`_, the Jobs Table supports both synchronous and asynchronous actions. Custom actions or the built-in actions of custom job types may be asynchronous. The following code sample shows how to use the job manager to populate the jobs table:
 
 ::
 

docs/tethys_sdk/routing.rst

@@ -118,7 +118,7 @@ Bokeh Integration in Tethys takes advantage of :ref:`websockets` and ``Django Ch
 
     Interactive ``Bokeh`` visualization tools can be entirely created using only Python with the help of ``Bokeh Server``. However, this usually requires the use of an additional server (``Tornado``). One of the alternatives to ``Tornado`` is using ``Django Channels``, which is already supported with Tethys. Therefore, interactive ``Bokeh`` models along with the all the advantages of using ``Bokeh Server`` can be leveraged in Tethys without the need of an additional server.
 
-Even though Bokeh uses :ref:`websockets`, routing with Bokeh endpoints is handled differently from other :ref:`websockets` that would normally be handled by a ``Consumer`` class and use the :ref:`consumer-decorator`. In contrast, Bokeh endpoints use a ``handler`` function that contains the main logic needed for a Bokeh model to be displayed. It contains the model or group of models as well as the callback functions that will help link them to the client. A ``handler`` function should be registered with the :ref:`handler-decorator`.
+Even though Bokeh uses :ref:`websockets`, routing with Bokeh endpoints is handled differently from other :ref:`websockets` that would normally be handled by a ``Consumer`` class and use the :ref:`consumer-decorator`. In contrast, Bokeh endpoints use a ``handler`` function that contains the main logic needed for a Bokeh model to be displayed. It contains the model or group of models as well as the callback functions that will help link them to the client. A ``handler`` function should be registered with the :ref:`handler-decorator`. Note that the :ref:`handler-decorator` supports both synchronous and asynchronous functions.
 
 ``Handlers`` are added to the ``Bokeh Document``, the smallest serialization unit in ``Bokeh Server``. This same ``Document`` is retrieved and added to the template variables in a ``controller`` function that is linked to the ``Handler function`` using Bokeh's ``server_document`` function. The ``controller`` function is created and registered automatically with the :ref:`handler-decorator`. However, you can manually create a ``controller`` function if custom logic is needed. In this case the ``controller`` function should not be decorated, but rather passed in as an argument to the :ref:`handler-decorator`.
 

tethys_apps/base/bokeh_handler.py

@@ -44,6 +44,11 @@
 
 
 def _add_request_to_doc(doc):
+    """
+    Adds a Django request object to a Bokeh document
+    Args:
+        doc: Bokeh document that Django request object should be added to
+    """
     bokeh_request = doc.session_context.request
     bokeh_request.pop("scheme")
     django_request = HttpRequest()
@@ -53,6 +58,12 @@ def _add_request_to_doc(doc):
 
 
 def _add_paths_to_doc(doc):
+    """
+    Adds several Tethys Paths to a Bokeh document
+
+    Args:
+        doc: Bokeh document to add Tethys Paths to
+    """
     app = _resolve_app_class(doc.request)
     user = doc.request.user
     doc.app_workspace = get_app_workspace(app)
@@ -64,6 +75,15 @@ def _add_paths_to_doc(doc):
 
 
 def with_request(handler):
+    """
+    Decorator for Bokeh handlers that adds the Django request object to the Bokeh document object
+    Args:
+        handler: decorated handler function (that accepts a document object). May be sync or async.
+
+    Returns: wrapped handler function (either sync or async to match the decorated function).
+
+    """
+
     @wraps(handler)
     def wrapper(doc: Document):
         _add_request_to_doc(doc)
@@ -98,6 +118,15 @@ def wrapper(doc: Document):
 
 
 def with_paths(handler):
+    """
+    Decorator for Bokeh handlers that adds Tethys paths to the Bokeh document object
+    Args:
+        handler: decorated handler function (that accepts a document object). May be sync or async.
+
+    Returns: wrapped handler function (either sync or async to match the decorated function).
+
+    """
+
     @with_request
     @wraps(handler)
     def wrapper(doc: Document):

tethys_apps/base/controller.py

@@ -457,7 +457,7 @@ def handler(
 ):
     """
     Decorator to register a handler function and connect it with a controller function
-    (by automatically registering a UrlMap for it).
+    (by automatically registering a UrlMap for it). Handler function may be synchronous or asynchronous.
 
     Args:
         controller: reference to controller function or string with dot-notation path to controller function. This is only required if custom logic is needed in the controller. Otherwise use `template` or `app_package`.
@@ -475,7 +475,13 @@ def handler(
         from tethys_sdk.routing import handler
 
         @handler
-        def my_app_handler(document):
+        async def my_app_handler(document):
+            ...
+
+        ------------
+
+        @handler
+        def my_sync_app_handler(document):
             ...
 
         ------------
@@ -484,7 +490,7 @@ def my_app_handler(document):
             name='home',
             app_package='my_app',
         )
-        def my_app_handler(document):
+        async def my_app_handler(document):
             ...
 
         ------------
@@ -552,7 +558,7 @@ def my_app_handler(document):
         @handler(
             with_paths=True
         )
-        def my_app_handler(document):
+        async def my_app_handler(document):
             # attributes available when using "with_paths" argument
             request = document.request
             user_workspace = document.user_workspace

tethys_gizmos/gizmo_options/jobs_table.py

@@ -58,8 +58,8 @@ class CustomJobAction:
 
     Attributes:
         label (str, required): The display name of the action that will show in the actions dropdown.
-        callback_or_url (str or callable, required if ``modal_url`` is not supplied): The name on a callable attribute
-            on the ``job_type`` object or a callable that accepts a ``TethysJob`` as an argument.
+        callback_or_url (str or callable, required if ``modal_url`` is not supplied): The name of a callable attribute
+            on the ``job_type`` object or a callable that accepts a ``TethysJob`` as an argument (may be asynchronous).
             Or it can be the name of a URL that the custom action option will link to.
         enabled_callback (callable): A callable that accepts a ``job_type`` object as an argument and returns True
             if the action should be enabled or False if it should be disabled.