From 8e7bedf3f2d809c0dd47bfbf34349be94170752d Mon Sep 17 00:00:00 2001 From: Simon Kelly Date: Wed, 11 Oct 2023 17:39:39 +0200 Subject: [PATCH] update docs with cli basic ops and more --- docs/cli.md | 26 +++++++++++++++++--- docs/index.md | 4 +-- docs/python.md | 16 ++++++++++++ docs/web_example.md | 59 ++++++++++++++++++++++++++++++++++++++++++--- mkdocs.yml | 8 ++++++ 5 files changed, 105 insertions(+), 8 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 71ecff9..812af37 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -11,10 +11,18 @@ without the need to write any code. The CLI is bundled with the Python client library. To install it you need: -* Python > X +* Python > 3.7 + +The recommended approach is to install the CLI into a virtual environment using [pipx](https://pypa.github.io/pipx/): + +```shell +$ pipx install taskbadger +``` + +Alternatively you can install it into your user environment using pip: ```shell -$ python -m pip install -U taskbadger +$ python3 -m pip install --user taskbadger ``` ## Monitoring processes @@ -33,7 +41,19 @@ will be `success` if the command has a zero exit code. Any other exit code will result in an `error` status and the exit code will be saved in the task data under the `return_code` key. -### Actions +## Basic commands + +The CLI has a number of basic commands that allow you to interact with the Task Badger +API. The commands are: + +* `list` - List tasks +* `get` - Get a task +* `create` - Create a task +* `update` - Update a task + +For more details on these commands run `taskbadger --help`. + +## Actions You can create actions for CLI tasks using the `--action` (`-a`) argument. The format for this argument is string with three components, separated by a space: diff --git a/docs/index.md b/docs/index.md index c488b7a..00a8279 100644 --- a/docs/index.md +++ b/docs/index.md @@ -202,6 +202,6 @@ The value may also be updated to 100. ``` Also check your email to see if you got the notification. -!!! tip "Up Next" +## A real example - Take a look at how to apply this to a real [example](web_example.md). +Take a look at how to apply this to a real [example](web_example.md). diff --git a/docs/python.md b/docs/python.md index 2044d16..9c00588 100644 --- a/docs/python.md +++ b/docs/python.md @@ -26,6 +26,9 @@ taskbadger.init( Details about these configuration parameters can be found [here](basics.md#organization-and-project) +If you attempt to use the SDK without configuring it you will get an error. To avoid this you can use the +[safe functions](#safe-functions) which will log any errors to the `taskbadger` logger. + ## Usage The SDK provides a [Task](#taskbadger.Task) class which offers a convenient interface to the API. @@ -61,6 +64,19 @@ task = Task.get(task_id) The task object provides methods for updating the properties of a task, adding custom data and adding actions. +### Connection management + +The SDK will open a new connection for each request and close it when the request is complete. For instances +where you wish to make multiple requests you can use the `taskbadger.Session` context manager: + +```python +from taskbadger import Session + +with Session() as session: + task = Task.create("my task") + task.update(status="success") +``` + ## Python Reference ::: taskbadger.Task diff --git a/docs/web_example.md b/docs/web_example.md index 619d7c3..1b60e7f 100644 --- a/docs/web_example.md +++ b/docs/web_example.md @@ -7,7 +7,15 @@ and then updated it as the task is processed on the backend. In the following example we'll be using Django and Celery. -## 1. Create the task in a view +!!! tip + + If using the Task Badger task for local progress tracking seems a bit heavy for your use case, you could + use [celery-progress](https://pypi.org/project/celery-progress/){:target="_blank"} for local tracking and + maintain the Task Badger task purerly for remote tracking, metrics, alerts, integrations etc. + +## Option 1: Use the Core API + +### 1. Create the task in a view ```python title="views.py" from django.conf import settings @@ -33,7 +41,7 @@ def export_data(request): In addition to creating the task, we've also added an action so that we will get notified if the task fails or does not complete. -## 2. Update the task +### 2. Update the task ```python title="tasks.py" from celery.app import shared_task @@ -55,7 +63,7 @@ def export_user_data(task_id, user_id): task.success(100) ``` -## 3. Expose the task status for the UI +### 3. Expose the task status for the UI ```python title="views.py" @require_GET @@ -68,3 +76,48 @@ def poll_task_status(request, task_id): "value_percent": task.value_percent }) ``` + + +## Option 2: Use the Celery integration + +Use the Task Badger Celery Task class as the base class for your Celery task: + +```python title="tasks.py" +from celery.app import shared_task +from taskbadger.celery import Task + +@shared_task(bind=True, base=Task, taskbadger_kwargs={ + "actions": [Action("error,stale", integration=EmailIntegration(to=settings.ADMINS[0][1]))], + "stale_timeout": 5 +}) +def export_user_data(self, user_id): + task = self.taskbadger_task + + try: + compile_export(task, user_id) # this also updates the task progress + except Exception as e: + task.error(data={ + "error": str(e) + }) + raise + + task.success(100) +``` + +In the view we can get the Task Badger task ID from the Celery task result: + +```python title="views.py" +from apps.export.tasks import export_user_data + + +@require_POST +def export_data(request): + task = export_user_data.delay(user_id=request.user.id, taskbadger_data={"user_id": request.user.id}) + tb_task_id = task.info.get("taskbadger_task_id") + return JsonResponse({"task_id": tb_task_id}) + + +@require_GET +def poll_task_status(request, task_id): + # same as above +``` diff --git a/mkdocs.yml b/mkdocs.yml index 0b1bd5e..1508ca8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,8 @@ theme: - content.code.copy - content.tabs.link - search.highlight + - navigation.instant + - navigation.footer markdown_extensions: - admonition - tables @@ -39,6 +41,12 @@ extra: analytics: provider: google property: G-018PZFQ3EE + social: + - icon: fontawesome/brands/twitter + link: https://twitter.com/@task_badger + - icon: fontawesome/brands/github + link: https://github.com/taskbadger +copyright: Copyright © 2020 - 2023 Simon Kelly nav: - 'index.md' - 'basics.md'