docs and short description (#50)

* docs and short description

* build 3.13

* Allow to use python 3.13

Author: lsbardel

.github/workflows/build.yml

@@ -16,7 +16,7 @@ jobs:
       PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
     strategy:
       matrix:
-        python-version: ["3.11", "3.12"]
+        python-version: ["3.11", "3.12", "3.13"]
 
     services:
       postgres:

Makefile

@@ -62,7 +62,7 @@ docs-publish:		## publish the book to github pages
 
 .PHONY: docs-serve
 docs-serve:		## serve documentation
-	@poetry run mkdocs serve
+	@poetry run mkdocs serve -w fluid
 
 
 .PHONY: readme

docs/CNAME

@@ -0,0 +1 @@
+fluid.quantmind.com

docs/reference/task.md

@@ -0,0 +1,19 @@
+# Task
+
+A Task defines the implementation given operation, the inputs required and the scheduling metadata.
+Usually, a Task is not created directly, but rather through the use of the `@task` decorator.
+
+## Example
+
+```python
+from fluid.scheduler import task, TaskRun
+
+@task
+def hello(ctx: TaskRun) -> None:
+    print("Hello, world!")
+```
+
+
+::: fluid.scheduler.task
+
+::: fluid.scheduler.Task

docs/reference/workers.md

@@ -4,7 +4,7 @@ Workers are the main building block for asynchronous programming with `aio-fluid
 There are several worker classes which can be imported from `fluid.utils.worker`:
 
 ```python
-from fastapi.utils.worker import StoppingWorker
+from fluid.utils.worker import StoppingWorker
 ```
 
 ::: fluid.utils.worker.Worker

examples/tasks/__init__.py

@@ -44,7 +44,10 @@ async def disabled(context: TaskRun) -> float:
 
 @task(cpu_bound=True, schedule=every(timedelta(seconds=5)))
 async def cpu_bound(context: TaskRun) -> None:
-    """A CPU bound task running on subprocess"""
+    """A CPU bound task running on subprocess
+
+    CPU bound tasks are executed on a subprocess to avoid blocking the event loop.
+    """
     time.sleep(1)
     broker = cast(RedisTaskBroker, context.task_manager.broker)
     redis = broker.redis_cli

fluid/__init__.py

@@ -1,3 +1,3 @@
 """Reusable server side python modules"""
 
-__version__ = "1.2.1"
+__version__ = "1.2.2"

fluid/scheduler/cli.py

@@ -53,14 +53,18 @@ def ls(ctx: click.Context) -> None:
     table.add_column("Name", style="cyan", no_wrap=True)
     table.add_column("Schedule", style="magenta")
     table.add_column("CPU bound", style="magenta")
+    table.add_column("Timeout secs", style="green")
+    table.add_column("Priority", style="magenta")
     table.add_column("Description", style="green")
     for name in sorted(task_manager.registry):
         task = task_manager.registry[name]
         table.add_row(
             name,
             str(task.schedule),
             "yes" if task.cpu_bound else "no",
-            task.description,
+            str(task.timeout_seconds),
+            str(task.priority),
+            task.short_description,
         )
     console = Console()
     console.print(table)

fluid/scheduler/crontab.py

@@ -5,7 +5,6 @@
 from abc import ABC, abstractmethod
 from datetime import datetime
 from typing import NamedTuple, Set, Union
-
 from zoneinfo import ZoneInfo
 
 from fluid.utils.dates import UTC

fluid/scheduler/models.py

@@ -105,26 +105,38 @@ class QueuedTask(BaseModel):
 
 
 class Task(NamedTuple):
-    """A Task execute any time it is invoked"""
+    """A Task executes any time it is invoked"""
 
     name: str
+    """Task name - unique identifier"""
     executor: TaskExecutor
+    """Task executor function"""
     logger: logging.Logger
+    """Task logger"""
     module: str = ""
+    """Task python module"""
+    short_description: str = ""
+    """Short task description - one line"""
     description: str = ""
+    """Task description - obtained from the executor docstring if not provided"""
     schedule: Scheduler | None = None
+    """Task schedule - None means the task is not scheduled"""
     randomize: RandomizeType | None = None
     params_model: type[BaseModel] | None = None
     max_concurrency: int = 0
     """how many tasks can run in each consumer concurrently - 0 means no limit"""
     timeout_seconds: int = 60
+    """Task timeout in seconds - how long the task can run before being aborted"""
     priority: TaskPriority = TaskPriority.medium
+    """Task priority - high, medium, low"""
 
     @property
     def cpu_bound(self) -> bool:
+        """True if the task is CPU bound"""
         return self.executor is run_in_subprocess
 
     def params_dump_json(self, params: dict[str, Any]) -> str:
+        """Dumps task parameters as JSON string"""
         if params_model := self.params_model:
             return params_model(**params).model_dump_json()
         return json.dumps(params)
@@ -141,7 +153,10 @@ def info(self, **params: Any) -> TaskInfo:
 
 
 class TaskRun(BaseModel, arbitrary_types_allowed=True):
-    """A TaskRun contains all the data generated by a Task run"""
+    """A TaskRun contains all the data generated by a Task run
+
+    This model is never initialized directly, it is created by the TaskManager
+    """
 
     id: str
     task: Task
@@ -298,6 +313,7 @@ def task(
     *,
     name: str | None = None,
     schedule: Scheduler | None = None,
+    short_description: str | None = None,
     description: str | None = None,
     randomize: RandomizeType | None = None,
     max_concurrency: int = 1,
@@ -310,6 +326,13 @@ def task(
 
 # implementation of the task decorator
 def task(executor: TaskExecutor | None = None, **kwargs: Any) -> Task | TaskConstructor:
+    """Decorator to create a Task
+
+    This decorator can be used in two ways:
+
+    - As a simple decorator of the executor function
+    - As a function with keyword arguments
+    """
     if kwargs and executor:
         raise TaskDecoratorError("cannot use positional parameters")
     elif kwargs:
@@ -355,12 +378,15 @@ def cpu_bound_task(self, executor: TaskExecutor) -> Task:
 
     def kwargs_defaults(self, executor: TaskExecutor) -> dict[str, Any]:
         module = inspect.getmodule(executor)
-        return {
-            "name": get_name(executor),
-            "module": module.__name__ if module else "",
-            "description": trim_docstring(inspect.getdoc(executor) or ""),
-            "executor": executor,
-        }
+        description = trim_docstring(inspect.getdoc(executor) or "")
+        short_description = description.split("\n")[0].strip()
+        return dict(
+            name=get_name(executor),
+            module=module.__name__ if module else "",
+            description=description,
+            short_description=short_description,
+            executor=executor,
+        )
 
 
 def get_name(o: Any) -> str:

fluid/utils/dates.py

@@ -1,6 +1,5 @@
 from datetime import date, datetime, timezone
 from typing import Any
-
 from zoneinfo import ZoneInfo
 
 UTC = ZoneInfo("UTC")