Merge pull request #8 from taskbadger/update-pthon-dos

v1.0 docs

docs/python-celery.md

@@ -0,0 +1,116 @@
+# Celery Integration
+
+The Celery integration provides a task class that can be used to automatically create and update tasks in Task Badger
+from Celery tasks. Although you can use the basic SDK functions to create and update tasks from Celery tasks, the
+Celery integration simplifies the usage significantly.
+
+At the core of the integration is the `taskbadger.celery.Task` class which is a custom Celery task class which
+tells Task Badger that the task should be tracked. The task class also provides convenient access to the
+Task Badger task object within the body of the Celery task.
+
+## Basic Usage
+To use the integration simply set the `base` parameter of your Celery task to `taskbadger.celery.Task`:
+
+!!!note inline end ""
+
+    This works the same with the `@celery.shared_task` decorator.
+
+```python
+from celery import Celery
+from taskbadger.celery import Task
+
+app = Celery("tasks")
+
+@app.task(base=Task)
+def my_task():
+    pass
+
+result = my_task.delay()
+taskbadger_task_id = result.taskbadger_task_id
+taskbadger_task = result.get_taskbadger_task()
+```
+
+Having made this change, a task will now be automatically created in Task Badger when the celery task is published.
+The Task Badger task will also be updated when the task completes.
+
+!!! info
+
+    Note that Task Badger will only track the Celery task if it is run asynchronously. If the task is run
+    synchronously via `.apply()`, by calling the function directly, or if [`task_always_eager`][always_eager]{:target="_blank"} has been set,
+    the task will not be tracked.
+
+    This also means that the `taskbadger_task_id` attribute of the result as well as the return value
+    of `result.get_taskbadger_task()` will be `None` if the task is not being tracked by Task Badger.
+
+
+[always_eager]: https://docs.celeryq.dev/en/stable/userguide/configuration.html#std-setting-task_always_eager
+
+
+## Task Customization
+
+You can pass additional parameters to the Task Badger `Task` class which will be used when creating the task. 
+This can be done by passing keyword arguments prefixed with `taskbadger_` to the `.appy_async()` function or
+to the task decorator.
+
+```python
+# using the task decorator
+
+@app.task(base=Task, taskbadger_monitor_id="xyz")
+def my_task(arg1, arg2):
+    ...
+
+# using individual keyword arguments
+my_task.apply_async(
+    arg1, arg2,
+    taskbadger_name="my task",
+    taskbadger_value_max=1000,
+    taskbadger_data={"custom": "data"},
+)
+
+# using a dictionary
+my_task.apply_async(arg1, arg2, taskbadger_kwargs={
+    "name": "my task",
+    "value_max": 1000,
+    "data": {"custom": "data"}
+})
+```
+
+!!!note "Order of Precedence"
+    Values passed via `apply_async` take precedence over values passed in the task decorator.
+
+    In both the decorator and `apply_async`, if individual keyword arguments are used as well as
+    the `taskbadger_kwargs` dictionary, the individual arguments will take precedence.
+
+## Accessing the Task Object
+
+The `taskbadger.celery.Task` class provides access to the Task Badger task object via the `taskbadger_task` property
+of the Celery task. The Celery task instance can be accessed within a task function body by creating a
+[bound task][bound_task]{:target="_blank"}.
+
+[bound_task]: https://docs.celeryq.dev/en/stable/userguide/tasks.html#bound-tasks
+
+```python
+@app.task(bind=True, base=taskbadger.celery.Task)
+def my_task(self, items):
+    # Retrieve the Task Badger task
+    task = self.taskbadger_task
+
+    for i, item in enumerate(items):
+        do_something(item)
+
+        if i % 100 == 0:
+            # Track progress
+            task.update(value=i)
+
+    # Mark the task as complete
+    # This is normally handled automatically when the task completes but we call it here so that we
+    # can also update the `value` property or other task properties.
+    task.success(value=len(items))
+```
+
+!!!note
+
+    The `taskbadger_task` property will be `None` if the task is not being tracked by Task Badger.
+    This could indicate that the Task Badger API has not been [configured](python.md#configure), there was an error
+    creating the task, or the task is being run synchronously e.g. via `.apply()` or calling the task
+    using `.map` or `.starmap`, `.chunk`.

docs/python-decorator.md

@@ -0,0 +1,22 @@
+# Python Function Decorator
+
+In addition to the `taskbadger.Task` class and utility functions, there is also a
+function decorator that can be used to automatically create a task when a function is called.
+
+```python
+from taskbadger import track
+
+@track("my task")
+def my_function():
+    pass
+```
+
+Using the decorator will create a task with the name provided and automatically update the task
+status to `success` when the function completes or `error` if an exception is raised.
+
+The decorator also applies the `taskbadger.Session` context manager to the function.
+See [connection management](python.md#connection-management).
+
+## API Docs
+
+::: taskbadger.track

docs/python.md

@@ -77,6 +77,9 @@ with Session() as session:
     task.update(status="success")
 ```
 
+If you are using the [function decorator](python-decorator.md) or the [Celery integration](python-celery.md), 
+session management is handled automatically within the body of the function or Celery task.
+
 ## Python Reference
 
 ::: taskbadger.Task

mkdocs.yml

@@ -55,7 +55,10 @@ nav:
   - 'data_model.md'
   - 'api.md'
   - 'integrations.md'
-  - 'Python SDK': 'python.md'
+  - 'Python SDK':
+    - 'Basic Usage': 'python.md'
+    - 'Function Decorator': 'python-decorator.md'
+    - 'Celery Integration': 'python-celery.md'
 
 plugins:
 - mkdocstrings: