feat(rq): add section on task queues

docs/docs/05_flask_smorest/02_data_model_improvements/README.md

@@ -108,14 +108,14 @@ Next, let's create the `.flaskenv` file:
 
 ```txt title=".flaskenv"
 FLASK_APP=app
-FLASK_ENV=development
+FLASK_DEBUG=True
 ```
 
 If we have the `python-dotenv` library installed, when we run the `flask run` command, Flask will read the variables inside `.flaskenv` and use them to configure the Flask app.
 
-The configuration that we'll do is to define the Flask app file (here, `app.py`). Then we'll also set the Flask environment to `development`, which does a couple things:
+The configuration that we'll do is to define the Flask app file (here, `app.py`). Then we'll also set the `FLASK_DEBUG` flag to `True`, which does a couple things:
 
-- Sets debug mode to true, which makes the app give us better error messages
+- Makes the app give us better error messages and return a traceback when we make requests if there's an error.
 - Sets the app reloading to true, so the app restarts when we make code changes
 
 We don't want debug mode to be enabled in production (when we deploy our app), but while we're doing development it's definitely a time-saving tool!

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/README.md

@@ -0,0 +1,85 @@
+# How to send emails with Python and Mailgun
+
+To send e-mails using Python, we are going to use Mailgun, a third party service which actually delivers the messages.
+
+You could use [your own personal account and the built-in `email` and `smtp` libraries](https://blog.teclado.com/learn-python-send-emails/), but most personal e-mail providers will limit how many e-mails you can send per day. Plus, you won't get analytics and a host of other features that you can get with an email service like Mailgun.
+
+There are two ways to use the Mailgun service: [via SMTP or via their API](https://www.mailgun.com/blog/email/difference-between-smtp-and-api/). I'll show you how to use the API since it's a bit easier and has the same functionality.
+
+Sending an e-mail with Mailgun is just a matter of sending a request to their API. To do this, we'll use the `requests` library:
+
+```bash
+pip install requests
+```
+
+Remember to add it to your `requirements.txt` as well:
+
+```text title="requirements.txt"
+requests
+```
+
+## Setting up for Mailgun
+
+Before we can send any emails, we need to set up our Mailgun account. First, register over at [https://mailgun.com](https://mailgun.com).
+
+Once you have registered, select your sandbox domain. It's in [your dashboard](https://app.mailgun.com/app/dashboard), at the bottom. It looks like this: `sandbox847487f8g78.mailgun.org`. 
+
+Then at the top right, enter your personal email address under "Authorized recipients".
+
+You will get an email to confirm. Click the button that you see in that email to add your personal email to the list of authorized recipients.
+
+Next up, grab your API key. You can find it by clicking on this button (my domain and API key are blurred in this screenshot):
+
+![Click the 'Select' button to reveal your Mailgun API key](./assets/mailgun-api-key.png)
+
+## Sending emails with Mailgun
+
+To make the API request which sends an email, we'll use a function that looks very much like this one (taken from their documentation):
+
+```py
+def send_simple_message():
+    return requests.post(
+        "https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages",
+        auth=("api", "YOUR_API_KEY"),
+        data={"from": "Excited User <mailgun@YOUR_DOMAIN_NAME>",
+            "to": ["[email protected]", "YOU@YOUR_DOMAIN_NAME"],
+            "subject": "Hello",
+            "text": "Testing some Mailgun awesomness!"})
+```
+
+So let's go into our User resource and add a couple of imports and this function. Make sure to replace "Your Name" with your actual name or that of your application:
+
+```py title="resources/user.py"
+import os
+import requests
+
+...
+
+def send_simple_message(to, subject, body):
+    domain = os.getenv("MAILGUN_DOMAIN")
+    return requests.post(
+        f"https://api.mailgun.net/v3/{domain}/messages",
+        auth=("api", os.getenv("MAILGUN_API_KEY")),
+        data={
+            "from": f"Your Name <mailgun@{domain}>",
+            "to": [to],
+            "subject": subject,
+            "text": body,
+        },
+    )
+```
+
+Then let's go to the `.env` file and add your Mailgun API key and domain:
+
+```text title=".env"
+MAILGUN_API_KEY="<insert your api key here>"
+MAILGUN_DOMAIN="<insert your domain here>"
+```
+
+:::info
+The API Key should look something like this: `"1f1ahfjhf4878797887187j-5ac54n"`.
+
+The Domain should look something like this: `"sandbox723b05d9.mailgun.org"`
+:::
+
+With this, we're ready to actually send emails!

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/.env.example

@@ -0,0 +1,3 @@
+DATABASE_URL=
+MAILGUN_API_KEY=
+MAILGUN_DOMAIN=

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/.flaskenv

@@ -0,0 +1,2 @@
+FLASK_APP=app
+FLASK_ENV=development

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/.gitignore

@@ -0,0 +1,7 @@
+.env
+.venv
+.vscode
+__pycache__
+data.db
+*.pyc
+.DS_Store

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# CONTRIBUTING
+
+## How to run the Dockerfile locally
+
+```
+docker run -dp 5000:5000 -w /app -v "$(pwd):/app" IMAGE_NAME sh -c "flask run"
+```

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.10
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+COPY . .
+CMD ["/bin/bash", "docker-entrypoint.sh"]

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/README.md

@@ -0,0 +1,3 @@
+# REST APIs Recording Project
+
+Nothing here yet!

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/app.py

@@ -0,0 +1,109 @@
+import os
+
+from flask import Flask, jsonify
+from flask_smorest import Api
+from flask_jwt_extended import JWTManager
+from flask_migrate import Migrate
+from dotenv import load_dotenv
+
+
+from db import db
+from blocklist import BLOCKLIST
+import models
+
+from resources.item import blp as ItemBlueprint
+from resources.store import blp as StoreBlueprint
+from resources.tag import blp as TagBlueprint
+from resources.user import blp as UserBlueprint
+
+
+def create_app(db_url=None):
+    app = Flask(__name__)
+    load_dotenv()
+
+    app.config["PROPAGATE_EXCEPTIONS"] = True
+    app.config["API_TITLE"] = "Stores REST API"
+    app.config["API_VERSION"] = "v1"
+    app.config["OPENAPI_VERSION"] = "3.0.3"
+    app.config["OPENAPI_URL_PREFIX"] = "/"
+    app.config["OPENAPI_SWAGGER_UI_PATH"] = "/swagger-ui"
+    app.config["OPENAPI_SWAGGER_UI_URL"] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist/"
+    app.config["SQLALCHEMY_DATABASE_URI"] = db_url or os.getenv("DATABASE_URL", "sqlite:///data.db")
+    app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+    db.init_app(app)
+    migrate = Migrate(app, db)
+    api = Api(app)
+
+    app.config["JWT_SECRET_KEY"] = "jose"
+    jwt = JWTManager(app)
+
+    @jwt.token_in_blocklist_loader
+    def check_if_token_in_blocklist(jwt_header, jwt_payload):
+        return jwt_payload["jti"] in BLOCKLIST
+
+    @jwt.revoked_token_loader
+    def revoked_token_callback(jwt_header, jwt_payload):
+        return (
+            jsonify(
+                {"description": "The token has been revoked.", "error": "token_revoked"}
+            ),
+            401,
+        )
+
+    @jwt.needs_fresh_token_loader
+    def token_not_fresh_callback(jwt_header, jwt_payload):
+        return (
+            jsonify(
+                {
+                    "description": "The token is not fresh.",
+                    "error": "fresh_token_required",
+                }
+            ),
+            401,
+        )
+
+    @jwt.additional_claims_loader
+    def add_claims_to_jwt(identity):
+        # Look in the database and see whether the user is an admin
+        if identity == 1:
+            return {"is_admin": True}
+        return {"is_admin": False}
+
+    @jwt.expired_token_loader
+    def expired_token_callback(jwt_header, jwt_payload):
+        return (
+            jsonify({"message": "The token has expired.", "error": "token_expired"}),
+            401,
+        )
+
+    @jwt.invalid_token_loader
+    def invalid_token_callback(error):
+        return (
+            jsonify(
+                {"message": "Signature verification failed.", "error": "invalid_token"}
+            ),
+            401,
+        )
+
+    @jwt.unauthorized_loader
+    def missing_token_callback(error):
+        return (
+            jsonify(
+                {
+                    "description": "Request does not contain an access token.",
+                    "error": "authorization_required",
+                }
+            ),
+            401,
+        )
+
+    @app.before_first_request
+    def create_tables():
+        db.create_all()
+
+    api.register_blueprint(ItemBlueprint)
+    api.register_blueprint(StoreBlueprint)
+    api.register_blueprint(TagBlueprint)
+    api.register_blueprint(UserBlueprint)
+
+    return app

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/blocklist.py

@@ -0,0 +1,9 @@
+"""
+blocklist.py
+
+This file just contains the blocklist of the JWT tokens. It will be imported by
+app and the logout resource so that tokens can be added to the blocklist when the
+user logs out.
+"""
+
+BLOCKLIST = set()

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/db.py

@@ -0,0 +1,3 @@
+from flask_sqlalchemy import SQLAlchemy
+
+db = SQLAlchemy()

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/docker-entrypoint.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+flask db upgrade
+
+exec gunicorn --bind 0.0.0.0:80 "app:create_app()"

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/migrations/README

@@ -0,0 +1 @@
+Single-database configuration for Flask.

docs/docs/12_task_queues_emails/01_send_emails_python_mailgun/end/migrations/alembic.ini

@@ -0,0 +1,50 @@
+# A generic, single database configuration.
+
+[alembic]
+# template used to generate migration files
+# file_template = %%(rev)s_%%(slug)s
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic,flask_migrate
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[logger_flask_migrate]
+level = INFO
+handlers =
+qualname = flask_migrate
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S