original link

Author: rachel-mack

source/integrations/flask-celery-integration.txt

@@ -0,0 +1,280 @@
+.. _pymongo-fastapi:
+.. original URL: https://www.mongodb.com/developer/products/mongodb/python-flask-celery-newsletter/
+
+======================================
+Tutorial: Flask and Celery Integration
+======================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: tutorial
+ 
+.. meta::
+   :keywords: flask, celery, integration, code example
+
+Overview
+--------
+
+In this tutorial, you can build a newsletter platform using Flask, MongoDB, and
+Celery. This application allows users to subscribe to newsletters, and
+administrators to manage and send batch emails asynchronously.
+
+Tutorial
+--------
+
+You can find the completed sample app for this tutorial in the :github:`Newsletter Platform with JavaScript, Flask, and MongoDB sample project </mercybassey/newsletter-javascript-flask-mongodb>` GitHub repository.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+Ensure you have the following components installed and set up before you start
+this tutorial:
+
+- :ref:`MongoDB <pymongo-get-started-create-deployment>`
+- `RabbitMQ <https://www.rabbitmq.com/docs/download>`__ (message broker for Celery)
+- `Gmail <www.gmail.com>`__ (to use as an SMTP)
+- `Python 3.8 or later <https://www.python.org/downloads/>`__
+
+Set-up
+~~~~~~
+
+.. procedure::
+   :style: connected
+
+   .. step:: Install the required Python packages.
+
+      Your application depends on the following libraries:
+
+      - `Flask <https://flask.palletsprojects.com/en/stable/>`__ for handling the web server and routing
+      - `Flask Mail <https://pypi.org/project/Flask-Mail/>`__ for sending emails from your application
+      - :ref:`{+driver-long+} <pymongo-get-started-download-and-install>`
+      - `Celery <https://docs.celeryq.dev/en/stable/>`__ to manage tasks, such
+        as sending batch emails
+    
+      Run the following ``pip`` command in your terminal to install the dependencies:
+
+      .. code-block:: bash
+
+         pip install Flask Flask-Mail pymongo celery
+
+   .. step:: Create directory structure.
+
+      We recommend structuring your application to separate concerns, which can
+      make the application modular and more maintainable.
+      
+      In your project directory, create the following structure:
+
+      .. code-block:: none
+
+         newsletter/
+         ├── app.py
+         ├── config.py
+         ├── routes.py
+         ├── tasks.py
+         ├── templates/
+         │   ├── admin.html
+         │   └── subscribe.html
+         ├── static/
+         └── styles.css
+
+Configure Your Application
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Define the necessary configurations by adding the following code to your
+``config.py`` file:
+
+.. code-block:: python
+
+   import os
+
+   class Config:
+       CELERY_BROKER_URL = 'amqp://guest:guest@localhost//'
+       RESULT_BACKEND = 'mongodb://localhost:27017/celery_results'
+       MAIL_SERVER = 'smtp.gmail.com'
+       MAIL_PORT = 587
+       MAIL_USE_TLS = True
+       MAIL_USERNAME = os.getenv('MAIL_USERNAME')
+       MAIL_PASSWORD = os.getenv('MAIL_PASSWORD')
+       MAIL_DEFAULT_SENDER = os.getenv('MAIL_DEFAULT_SENDER')
+       ALLOWED_IPS = ['127.0.0.1']
+       MONGO_URI = 'mongodb://localhost:27017/newsletter'
+
+Ensure that your Gmail credentials (``MAIL_USERNAME`` and ``MAIL_PASSWORD``) and
+default sender email (``MAIL_DEFAULT_SENDER``) are set in your environment variables.
+
+Initialize Flask, MongoDB, and Celery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Initialize Flask, MongoDB, and Celery by adding the following code to your
+``app.py`` file:
+
+.. code-block:: python
+
+   from flask import Flask
+   from flask_mail import Mail
+   from pymongo import MongoClient
+   from celery import Celery
+   from config import Config
+
+   app = Flask(__name__)
+   app.config.from_object(Config)
+
+   mail = Mail(app)
+   client = MongoClient(app.config['MONGO_URI'])
+   db = client.get_database()
+
+   celery = Celery(app.name, broker=app.config['CELERY_BROKER_URL'])
+   celery.conf.update(app.config)
+
+   from routes import *
+   from tasks import *
+
+Ensure that your connection string (``MONGOD_URI``) and broker url
+(``CELERY_BROKER_URL``) are set in your environment variables. For more in
+formation see the :ref:`Create a Connection String
+<pymongo-get-started-connection-string>` section of this guide and the `Broker Settings
+<https://docs.celeryq.dev/en/stable/userguide/configuration.html#broker-settings>`__
+section of the Celery documentation.
+
+Define Your Routes
+~~~~~~~~~~~~~~~~~~
+
+Define the necessary routes by adding the following code to your ``routes.py`` file:
+
+.. code-block:: python
+
+   from flask import render_template, request, jsonify, abort
+   from app import app, db
+   from tasks import send_emails
+
+   @app.before_request
+   def limit_remote_addr():
+       if 'X-Forwarded-For' in request.headers:
+           remote_addr = request.headers['X-Forwarded-For'].split(',')[0]
+       else:
+           remote_addr = request.remote_addr
+
+       if request.endpoint == 'admin' and remote_addr not in app.config['ALLOWED_IPS']:
+           abort(403)
+
+   @app.route('/')
+   def home():
+       return render_template('subscribe.html')
+
+   @app.route('/admin')
+   def admin():
+       return render_template('admin.html')
+
+   @app.route('/subscribe', methods=['POST'])
+   def subscribe():
+       email = request.form['email']
+       if db.users.find_one({'email': email}):
+
+After you complete these steps, you will have a working application that
+uses MongoDB, Flask and Celery to manage a newsletter platform.
+
+Testing the Platform
+~~~~~~~~~~~~~~~~~~~~
+
+To test your application, run the following ``flask`` command in the terminal:
+
+.. procedure::
+   :style: connected
+
+   .. step::  Start Your Application
+
+      .. code-block:: bash
+
+         flask --app app run
+
+      In another terminal, start the celery worker:
+
+      .. code-block:: bash
+
+         celery -A app.celery worker --loglevel=info
+
+   .. step::  Create a Subscriber
+
+      Navigate to ``localhost:5000`` in your browser to open the
+      :guilabel:`Subscribe to our Newsletter` page. The following image shows
+      the subscriber webpage: 
+
+      .. image:: /includes/integrations/celery-subscriber-page.png
+         :alt: Screenshot of browser and subscriber page
+
+      Enter the subscriber information and click :guilabel:`Subscribe`.
+
+      To confirm that you created a new subscriber, run the following code in
+      your terminal to open a MongoDB Shell instance and view your collections:
+
+      .. code-block:: shell
+
+         mongosh
+         show dbs
+         use newsletter
+         show collections
+
+   .. step::  Dispatch a Newsletter
+
+      Navigate to ``localhost:5000/admin`` in your browser to open the
+      :guilabel:`Send Newsletter` page. The following image shows the admin
+      webpage:
+
+      .. image:: /includes/integrations/celery-admin-page.png
+         :alt: Screenshot of browser and admin
+
+      Enter the newsletter details and click :guilabel:`Send`.
+
+      Your Celery worker log will display an ``Email sent`` log entry, as
+      shown in the following image:
+
+      .. code-block:: bash
+
+         [2024-06-06 13:34:37,304: WARNING/ForkPoolWorker-4] Email sent
+         [2024-06-06 13:34:37,305: INFO/ForkPoolWorker-4] Task tasks.send_emails[b119bb9e-b2ef-4c85-b048-ca96e0e60ae1] succeeded in 17.155154566993588s: {'result': 'All emails sent'}
+
+      You can also see your newsletter deliverable by running the following
+      command in your MongoDB Shell to review your collections: 
+
+      .. code-block:: shell
+
+         newsletter> show collections
+         deliveries
+         subscribers
+         newsletter> 
+
+   .. step::  Review Your Sent Newsletter
+
+      Run the following commands in your MongoDB Shell to your previously sent
+      newsletters, also called ``deliveries``:
+
+      .. code-block:: shell
+
+         db.deliveries.find().pretty()
+
+Next Steps
+~~~~~~~~~~
+
+This application demonstrates how to handle asynchronous tasks efficiently,
+manage subscriber data, and send batch emails. You can further enhance this
+platform by integrating analytics, customizing email templates, and implementing
+automated responses.
+
+More Resources
+--------------
+
+For more information about to components used in this tutorial, see the following
+resources:
+
+- `Flask <https://flask.palletsprojects.com>`__
+- `Flask Mail <https://pypi.org/project/Flask-Mail/#files>`__
+- `Celery <https://docs.celeryq.dev/en/stable/>`__
+- :mdb-shell:`MongoDB Shell <>`
+
+For support or to contribute to the MongoDB Community, see the `MongoDB Developer Community <https://www.mongodb.com/community/>`__.