Powerful exec command (#53)

* More docs

* command line params

* exec command

Author: lsbardel

.vscode/launch.json

@@ -33,5 +33,22 @@
                 "RedirectOutput"
             ]
         },
+        {
+            "name": "AIO-FLUID EXAMPLE exec",
+            "type": "python",
+            "request": "launch",
+            "program": "${workspaceFolder}/examples",
+            "cwd": "${workspaceFolder}",
+            "justMyCode": false,
+            "args": [
+                "exec",
+                "add",
+                "--a",
+                "1",
+            ],
+            "debugOptions": [
+                "RedirectOutput"
+            ]
+        },
     ]
 }

docs/reference/task_cli.md

@@ -0,0 +1,20 @@
+# Task Manager Cli
+
+Command line tools for task manager applications.
+
+This modules requires the `cli` extra to be installed.
+
+```bash
+$ pip install aio-fluid[cli]
+```
+It can be imported from `fluid.scheduler.cli`:
+
+```python
+from fastapi.scheduler.cli import TaskManagerCLI
+
+if __name__ == "__main__":
+    cli = TaskManagerCLI("path.to:task_app")
+    cli()
+```
+
+::: fluid.scheduler.cli.TaskManagerCLI

docs/reference/task_manager.md

@@ -8,7 +8,6 @@ from fastapi.scheduler import TaskManager
 
 ::: fluid.scheduler.TaskManager
 
-
 ::: fluid.scheduler.TaskManagerConfig
 
 ::: fluid.scheduler.consumer.TaskDispatcher

docs/reference/task_scheduler.md

@@ -0,0 +1,13 @@
+# Task Scheduler
+
+The task scheduler [TaskScheduler][fluid.scheduler.TaskScheduler] inherits
+from the [TaskConsumer][fluid.scheduler.TaskConsumer] to add scheduling of
+periodic tasks.
+
+It can be imported from `fluid.scheduler`:
+
+```python
+from fastapi.scheduler import TaskScheduler
+```
+
+::: fluid.scheduler.TaskScheduler

docs/reference/utils.md

@@ -0,0 +1,3 @@
+# Utils
+
+::: fluid.utils.lazy.LazyGroup

docs/tutorials/task_app.md

@@ -0,0 +1,87 @@
+# Task Queue App
+
+The `fluid.scheduler` module is a simple yet powerful distributed task producer ([TaskScheduler][fluid.scheduler.TaskScheduler]) and consumer ([TaskConsumer][fluid.scheduler.TaskConsumer]) system for executing tasks.
+The middleware for distributing tasks can be configured via the [TaskBroker][fluid.scheduler.TaskBroker] interface.
+
+A redis task broker is provided for convenience.
+
+## Tasks Consumer
+
+Create a task consumer, register tasks from modules, and run the consumer.
+
+```python
+import asyncio
+from typing import Any
+from fluid.scheduler import TaskConsumer
+import task_module_a, task_module_b
+
+
+def task_consumer(**kwargs: Any) -> TaskConsumer:
+    consumer = TaskConsumer(**kwargs)
+    consumer.register_from_module(task_module_a)
+    consumer.register_from_module(task_module_b)
+    return consumer
+
+
+if __name__ == "__main__":
+    consumer = task_consumer()
+    asyncio.run(consumer.run())
+```
+
+## FastAPI Integration
+
+The `TaskConsumer` can be integrated with FastAPI so that
+tasks can be queued via HTTP requests.
+
+```python
+import uvicorn
+from fluid.scheduler.endpoints import setup_fastapi
+
+if __name__ == "__main__":
+    consumer = task_consumer()
+    app = setup_fastapi(consumer)
+    uvicorn.run(app)
+```
+
+You can test via the example provided
+
+```bash
+$ python -m examples.simple_fastapi
+```
+
+and check the openapi UI at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
+
+
+## Task App Command Line
+
+The [TaskConsumer][fluid.scheduler.TaskConsumer] or [TaskScheduler][fluid.scheduler.TaskScheduler] can be run with the command line tool to allow for an even richer API.
+
+```python
+from fluid.scheduler.cli import TaskManagerCLI
+
+if __name__ == "__main__":
+    consumer = task_consumer()
+    TaskManagerCLI(setup_fastapi(consumer))()
+```
+
+This features requires to install the package with the `cli` extra.
+
+```bash
+$ pip install aio-fluid[cli]
+```
+
+```bash
+$ python -m examples.simple_cli
+Usage: python -m examples.simple_cli [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  exec   Execute a registered task
+  ls     List all tasks with their schedules
+  serve  Start app server
+```
+
+The command line tools provides a powerful interface to execute tasks, parameters are
+passed as optional arguments using he standard click interface.

docs/tutorials/task_queue.md

@@ -1,10 +1,4 @@
-# Task Queue
-
-The `fluid.scheduler` module is a simple yet powerful distributed task producer (TaskScheduler) and consumer (TaskConsumer) system for executing tasks.
-The middleware for distributing tasks can be configured via the Broker interface.
-A redis broker is provided for convenience.
-
-## Tasks
+# Tasks
 
 Tasks are standard python async functions decorated with the [@task][fluid.scheduler.task] decorator.
 
@@ -42,7 +36,7 @@ async def say_hi(ctx: TaskRun[TaskParams]) -> None:
 
 ## Task Types
 
-There are two types of tasks implemented
+There are few types of tasks implemented, lets take a look at them.
 
 ### IO Bound Tasks
 
@@ -89,10 +83,22 @@ Both IO and CPU bound tasks can be periodically scheduled via the `schedule` key
 There are two types of scheduling, the most common is the [every][fluid.scheduler.every] function that takes a `timedelta` object.
 
 ```python
+import asyncio
 from datetime import timedelta
-from fluid.scheduler import task, TaskContext, every
+from fluid.scheduler import task, TaskRun, every
 
 @task(schedule=every(timedelta(seconds=1)))
 async def scheduled(ctx: TaskRun) -> None:
     await asyncio.sleep(0.1)
 ```
+
+You can also use the [crontab][fluid.scheduler.crontab] function to schedule tasks using cron expressions.
+
+```python
+import asyncio
+from fluid.scheduler import task, TaskRun, crontab
+
+@task(schedule=crontab(hours='*/2'))
+async def scheduled(ctx: TaskRun) -> None:
+    await asyncio.sleep(0.1)
+```

examples/simple.py

@@ -0,0 +1,8 @@
+import asyncio
+
+from examples.tasks import task_scheduler
+from fluid.utils import log
+
+if __name__ == "__main__":
+    log.config()
+    asyncio.run(task_scheduler().run())

examples/simple_cli.py

@@ -0,0 +1,12 @@
+import dotenv
+
+dotenv.load_dotenv()
+
+from fluid.scheduler.cli import TaskManagerCLI  # isort:skip    # noqa: E402
+
+
+if __name__ == "__main__":
+    from examples.tasks import task_app
+
+    task_manager_cli = TaskManagerCLI(task_app())
+    task_manager_cli()

examples/simple_fastapi.py

@@ -0,0 +1,10 @@
+import uvicorn
+
+from examples.tasks import task_scheduler
+from fluid.scheduler.endpoints import setup_fastapi
+from fluid.utils import log
+
+if __name__ == "__main__":
+    log.config()
+    app = setup_fastapi(task_scheduler())
+    uvicorn.run(app)