<commit_before>## Before using a deferred task, consider `run_after_response`

Deferred tasks are used to handle expensive tasks asynchronously in order to not block the serving of a response for a request. Before using a deferred task, consider the importance of retrying the task if an error should occur. If it's okay for the task to fail silently without retries (e.g. tracking an API request call), `backend.common.run_after_response` is a lighter-weight solution that is more appropriate.

Usage examples:

```
run_after_response(lambda: ...)
```

```
run_after_response(function_to_run)
```

```
@run_after_response
def function_to_run():
    ...
```

## Deferred Tasks

The Blue Alliances leverages [Google Cloud Task](https://cloud.google.com/tasks/docs/dual-overview) for deferred work. Examples of this work include any post-request tasks that need retrying should an error occur, such as dispatching push notifications. Locally, Google Cloud Tasks can be used by round-tripping requests upstream back to a local development container via ngrok, or more commonly swapped out for Redis/RQ.

`defer` is a drop-in replacement for [google.appengine.ext.deferred.deferred.defer](https://cloud.google.com/appengine/docs/standard/python/refdocs/google.appengine.ext.deferred.deferred). `defer` enqueues a method to be run later while automatically managing dispatching to the proper client based on the environment, getting a queue for a specified queue name, etc. Using `defer` is recommended unless you need some more fine-tuned control over tasks/queues. `defer` manages executing a task with the proper parameters both in development and in production. If an option is not supported in `defer` that is supported in the Google Cloud Task API protos, it is recommend to build this functionality in to `defer` and then leverage `defer`.

### Configuring Services for `defer`

Tasks executed with `defer` are just HTTP requests that are serialized + executed at a later time. By default, these tasks will use a use a `/_ah/queue/deferred.*` route when executing. A catch-all route for requests matching this regex can be installed for Flask apps by using the `install_defer_routes` method.

```python
from flask import Flask

from backend.common.deferred.handlers import install_defer_routes

app = Flask(__name__)
install_defer_routes(app)<commit_msg>Add syntax highlighting to run_after_response examples<commit_after>## Before using a deferred task, consider `run_after_response`

Deferred tasks are used to handle expensive tasks asynchronously in order to not block the serving of a response for a request. Before using a deferred task, consider the importance of retrying the task if an error should occur. If it's okay for the task to fail silently without retries (e.g. tracking an API request call), `backend.common.run_after_response` is a lighter-weight solution that is more appropriate.

Usage examples:

```python
run_after_response(lambda: ...)
```

```python
run_after_response(function_to_run)
```

```python
@run_after_response
def function_to_run():
    ...
```

## Deferred Tasks

The Blue Alliances leverages [Google Cloud Task](https://cloud.google.com/tasks/docs/dual-overview) for deferred work. Examples of this work include any post-request tasks that need retrying should an error occur, such as dispatching push notifications. Locally, Google Cloud Tasks can be used by round-tripping requests upstream back to a local development container via ngrok, or more commonly swapped out for Redis/RQ.

`defer` is a drop-in replacement for [google.appengine.ext.deferred.deferred.defer](https://cloud.google.com/appengine/docs/standard/python/refdocs/google.appengine.ext.deferred.deferred). `defer` enqueues a method to be run later while automatically managing dispatching to the proper client based on the environment, getting a queue for a specified queue name, etc. Using `defer` is recommended unless you need some more fine-tuned control over tasks/queues. `defer` manages executing a task with the proper parameters both in development and in production. If an option is not supported in `defer` that is supported in the Google Cloud Task API protos, it is recommend to build this functionality in to `defer` and then leverage `defer`.

### Configuring Services for `defer`

Tasks executed with `defer` are just HTTP requests that are serialized + executed at a later time. By default, these tasks will use a use a `/_ah/queue/deferred.*` route when executing. A catch-all route for requests matching this regex can be installed for Flask apps by using the `install_defer_routes` method.

```python
from flask import Flask

from backend.common.deferred.handlers import install_defer_routes

app = Flask(__name__)
install_defer_routes(app)
{'fraction_non_alphanumeric': 0.06832949067281492, 'fraction_numerical': 0.0, 'mean_word_length': 5.040506329113924, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3380132', 'n_tokens_mistral': 1242, 'n_tokens_neox': 1201, 'n_words': 603}