descriptions

Author: rachel-mack

source/integrations/flask-celery-integration.txt

@@ -2,7 +2,7 @@
 .. original URL: https://www.mongodb.com/developer/products/mongodb/python-flask-celery-newsletter/
 
 ======================================
-Tutorial: Celery and Flask Integration
+Tutorial: Flask and Celery Integration
 ======================================
 
 .. contents:: On this page
@@ -21,38 +21,29 @@ Tutorial: Celery and Flask Integration
 Overview
 --------
 
-In this tutorial, you can learn how to use MongoDB, Celery, and Flask
-to build a newsletter platform. This application allows users to subscribe to
-newsletters, and administrators to manage and send batch emails asynchronously.
-
-Celery
-~~~~~~
-
-Celery is an open-source distributed task queue that handles large
-volumes of messages efficiently. It supports asynchronous processing and task
-scheduling. For more information, see the `Celery webpage
-<https://docs.celeryq.dev/en/main/index.html>`__.
+In this tutorial, you can learn how to use MongoDB, Flask, and Celery to build a newsletter platform. This application allows users to subscribe to newsletters, and administrators to manage and send batch emails asynchronously.
 
 Flask
 ~~~~~
 
 Flask is a lightweight web application framework with built-in configuration and
 convention defaults that provide consistency to developers across projects. For
-more information, see the `Flask webpage
-<https://flask.palletsprojects.com/en/stable/>`__. 
+more information, see the `Flask webpage <https://flask.palletsprojects.com/en/stable/>`__. 
+
+Celery
+~~~~~~
+
+Celery is an open-source distributed task queue that handles large volumes of messages efficiently. It supports asynchronous processing and task scheduling. For more information, see the `Celery webpage <https://docs.celeryq.dev/en/main/index.html>`__.
 
 Tutorial
 --------
 
-This tutorial creates a modified version of the sample application in the
-:github:`Newsletter Platform with JavaScript, Flask, and MongoDB sample project
-</mercybassey/newsletter-javascript-flask-mongodb>` GitHub repository.
+This tutorial creates a modified version of the sample application in the :github:`Newsletter Platform with JavaScript, Flask, and MongoDB sample project </mercybassey/newsletter-javascript-flask-mongodb>` GitHub repository.
 
 Prerequisites
 ~~~~~~~~~~~~~
 
-Ensure that you have the following components installed and set up before you start
-this tutorial:
+Ensure that you have the following components installed and set up before you start this tutorial:
 
 - A MongoDB cluster. We recommend that you use Atlas. To learn how
   to create an Atlas cluster, see the
@@ -65,7 +56,7 @@ this tutorial:
 - `Gmail <www.gmail.com>`__ to use as an SMTP server. For more information about
   SMTP servers, see the :wikipedia:`Simple Mail Transfer Protocol
   <Simple_Mail_Transfer_Protocol>` Wikipedia page. 
-- `Python 3.8 or later <https://www.python.org/downloads/>`__
+- `Python 3.9 or later <https://www.python.org/downloads/>`__
 
 Setup
 ~~~~~
@@ -130,20 +121,18 @@ Setup
 
       .. code-block:: bash
 
-         pip install Flask Flask-Mail pymongo celery
+         pip install flask-pymongo Flask-Mail celery
 
 Configure Your Application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``config.py`` file contains the settings and credentials to perform the
-following actions:
+The ``config.py`` file contains the settings and credentials to perform the following actions:
 
 - Connect Celery to RabbitMQ as its message broker
 - Configure Flask-Mail to use Gmail as its SMTP server
 - Connect your application to your MongoDB server
 
-Define the necessary configurations by adding the following code to your
-``config.py`` file:
+Define the necessary configurations by adding the following code to your ``config.py`` file:
 
 .. code-block:: python
 
@@ -160,25 +149,22 @@ Define the necessary configurations by adding the following code to your
       CELERY_BROKER_URL = 'amqp://guest:guest@localhost//'
       RESULT_BACKEND = MONGO_URI + '/celery_results'
 
-You must provide your Gmail credentials (``MAIL_USERNAME`` and ``MAIL_PASSWORD``) to
-enable your application to send emails. For security purposes, we recommend that
-you generate an app password to use, rather than using your primary password.
-For more information, see the `App Password settings
-<https://myaccount.google.com/apppasswords>`__ in your Google Account.
+You must provide your Gmail credentials (``MAIL_USERNAME`` and ``MAIL_PASSWORD``) to enable your application to send emails. For security purposes, we recommend that you generate an app password to use, rather than using your primary password. For more information, see the `App Password settings <https://myaccount.google.com/apppasswords>`__ in your Google Account.
 
-You must also create a connection string to set into the ``MONGO_URI``
-environment variable. For more information see the :ref:`Create a Connection
-String <pymongo-get-started-connection-string>` section of this guide.
+You must also create a connection string to set into the ``MONGO_URI`` environment variable. For more information see the :ref:`Create a Connection String <pymongo-get-started-connection-string>` section of this guide.
 
-The provided Celery broker URL (``CELERY_BROKER_URL``) specifies RabbitMQ as its broker,
-but you can customize this URL to support other implementations. For more
-information, see the `Broker Settings
-<https://docs.celeryq.dev/en/stable/userguide/configuration.html#broker-settings>`__
-section of the Celery documentation.
+The provided Celery broker URL (``CELERY_BROKER_URL``) specifies RabbitMQ as its broker, but you can customize this URL to support other implementations. For more information, see the `Broker Settings <https://docs.celeryq.dev/en/stable/userguide/configuration.html#broker-settings>`__ section of the Celery documentation.
 
 Initialize Flask, MongoDB, and Celery
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+The ``app.py`` file initializes and configures the core components of the Flask application. It performs the following tasks:
+
+- Creates a Flask application and loads configuration constants
+- Initializes a Flask-Mail instance with the app's mail server settings
+- Connects to the ``newsletter`` MongoDB database by using the {+driver-short+} driver
+- Creates a Celery instance configured with the Flask app and your chosen broker
+
 Initialize Flask, MongoDB, and Celery by adding the following code to your
 ``app.py`` file:
 
@@ -189,13 +175,18 @@ Initialize Flask, MongoDB, and Celery by adding the following code to your
    from pymongo import MongoClient
    from celery import Celery
 
+   # Create a Flask application
    app = Flask(__name__)
    app.config.from_object('config.Config')
 
+   # Create a Flask-Mail instance
    mail = Mail(app)
+
+   # Connect to MongoDB
    client = MongoClient(app.config['MONGO_URI'])
    db = client.get_database(name="newsletter")
 
+   # Create a Celery instance
    celery = Celery(app.name, broker=app.config['CELERY_BROKER_URL'])
    celery.conf.update(app.config)
 
@@ -205,13 +196,58 @@ Initialize Flask, MongoDB, and Celery by adding the following code to your
    if __name__ == '__main__':
       app.run(debug=True)
 
-This opens a connection to the ``newsletter`` database in your MongoDB cluster
-and configures your Celery task queue.
+Create a Celery Task
+~~~~~~~~~~~~~~~~~~~~
+
+The Celery task uses the components instantiated in your ``app.py`` file to send a newsletter email to subscribers. 
+
+The ``@celery.task()`` decorator registers the function as a Celery task. Setting ``bind=True`` means the function receives the task instance as the ``self`` argument, which allows it to access Celery task methods and metadata. For more information about tasks, see the `celery.app.task <https://docs.celeryq.dev/en/stable/reference/celery.app.task.html>`__ API documentation.
+
+Since this task runs outside of Flask's HTTP request cycle, you must manually provide application context by wrapping the email logic in a ``with app.app_context()`` block. This gives Flask access to other components like the Flask-Mail ``mail`` instance and the {+driver-short+} connection to your ``newsletter`` MongoDB database.
+
+This method loops through the list of ``subscribers``, creates an email using the Flask-Mail ``Message`` class, and then sends it to each user by using the ``mail`` object. After each email is sent, it logs the delivery by inserting a document into your MongoDB ``deliveries`` collection to record that the message was sent.  Each email operation is wrapped in a ``try`` block to ensure that in the case of an error, the failure is logged and the database is not updated with a false delivery record.
+
+Define your ``send_emails()`` method by adding the following code to your ``tasks.py`` file:
+
+.. code-block:: python
+
+   from flask_mail import Message
+   from app import app, mail, db, celery
+   from datetime import datetime
+
+   @celery.task(bind=True)
+   def send_emails(self, subscribers, title, body):
+      with app.app_context():
+         for subscriber in subscribers:
+               try:
+                  print(f"Sending email to {subscriber['email']}")
+                  msg = Message(title, recipients=[subscriber['email']])
+                  msg.body = body
+                  mail.send(msg)
+                  db.deliveries.insert_one({
+                     'email': subscriber['email'],
+                     'title': title,
+                     'body': body,
+                     'delivered_at': datetime.utcnow()
+                  })
+                  print("Email sent")
+
+               except Exception as e:
+                  print(f"Failed to send email to {subscriber['email']}: {str(e)}")
+
+         return {'result': 'All emails sent'}
+
 
 Define Your Routes
 ~~~~~~~~~~~~~~~~~~
 
-Define the ``root``, ``admin``, ``subscribe``, and ``send-newsletter`` routes by adding the following code to your ``routes.py`` file:
+In Flask, the ``@app.route()`` decorator assigns a URL path to a specific function. In the following code, it is used to define the root (``/``), ``/admin``, ``/subscribe``, and ``/send-newsletter`` routes. The optional ``methods`` parameter is used in some cases to define a list of allowable HTTP methods.
+
+The ``@app.before_request()`` method sets a function to run before every request. In this case, the function provides some basic security by limiting access to the ``admin`` page to IP addresses listed in the ``ALLOWED_IPS`` parameter defined in the ``config.py`` file. Specifically, access is only allowed for the ``localhost``.
+
+The root and ``/admin`` routes render pages using the ``render_template()`` method. The ``/subscribe`` and ``/send-newsletter`` routes access request parameters in ``request.form[]`` to execute commands, and then return HTTP responses.
+
+Define your routes by adding the following code to your ``routes.py`` file:
 
 .. code-block:: python
 
@@ -275,14 +311,12 @@ application in this file.
 Create Your Pages 
 ~~~~~~~~~~~~~~~~~
 
-You can build your user interface in the ``templates`` directory.
+The HTML files in the ``templates`` directory define the user interface, and are written using standard HTML. Since this application uses asynchronous HTTP requests, the scripts in these files use :wikipedia:`Fetch API calls <XMLHttpRequest#Fetch_alternative>`. These scripts also handle timeouts and errors.  
 
-Because this application uses asynchronous messages, the scripts in the
-following files use :wikipedia:`Fetch API calls <XMLHttpRequest#Fetch_alternative>`. They also
-handle timeouts and errors.  
+Subscribe Pages
+```````````````
 
-Copy the following code into your ``subscribe.html`` file to create your
-:guilabel:`Subscribe to Newsletter` page.
+Copy the following code into your ``subscribe.html`` file to create your :guilabel:`Subscribe to Newsletter` page.
 
 .. code-block:: html 
 
@@ -340,6 +374,9 @@ Copy the following code into your ``subscribe.html`` file to create your
    </body>
    </html>
 
+Admin Page
+```````````
+
 The script for the admin page displays an alert to the user that depends on the
 success of the ``send_newsletter`` call. 
 
@@ -399,8 +436,7 @@ Copy the following code into your ``admin.html`` file to create your
 Format Your Pages
 ~~~~~~~~~~~~~~~~~
 
-You can apply a style sheet to your templates by adding the following code to
-the ``styles.css`` file:
+You can apply a style sheet to your templates by adding the following code to the ``styles.css`` file:
 
 .. code-block:: css 
 
@@ -480,14 +516,10 @@ the ``styles.css`` file:
       color: #666;
    }
 
-You can modify this style sheet or create your own to customize your
-application. 
-
 Testing the Platform
 ~~~~~~~~~~~~~~~~~~~~
 
-After you complete the previous steps, you have a working application that
-uses MongoDB, Flask, and Celery to manage a newsletter platform.
+After you complete the previous steps, you have a working application that uses MongoDB, Flask, and Celery to manage a newsletter platform.
 
 You can use the following steps to test your application: