Contributing to Open Source: An overview of the Django-Drip-Campaigns Project

Open Source software (OSS) is a key initiative for developers at Rootstrap to stay sharp and engage with the developer community. In this blog post, I’m going to talk about a particular project named Django Drip Campaigns and the process of publishing it as a PyPI package.

Pypi (Python Package Index) is a repository of software for the Python programming language that helps us find and install software developed by the Python community. One of our contributions to the OSS community is to publish and maintain the mentioned project and I want to share that experience in this article.

The Django Drip Campaigns Project

Django Drip Campaigns Project is an open-source app to create drip campaigns for email using Django’s admin interface and a User queryset. This means that using this app, you are able to easily schedule and send emails to the registered users, creating querysets in a friendly interface.

For example, you can very quickly configure your app to send a periodic email to the users that haven’t logged in in a day or more, send a custom email to the users that registered more than a week ago, etc. To do this, you only need to define one or more querysets in the admin page. If you want to install it and work with it, you can follow the simple steps documented in the github page of Django Drip Campaigns.

We didn’t create this project, we just made a fork of the one written by Zapier that is no longer maintained. After this, we worked on fixing some bugs, doing a couple of enhancements, creating more documentation, and publishing the app as a PyPI package.

Since it’s published, any programmer that wants to use this project in his Django app is able to quickly download it with a simple command described in the mentioned docs.

Features

After a successful installation and configuration, you are able to easily create drip campaigns for email using the admin interface of Django. If you don’t have an admin user, create one with the Django createsuperuser command. After this, login into Django’s admin page and click on Manage Them. There you are able to:

  • View created and sent drips.
  • Create a new drip.
  • Select and delete drips.

Creating a New Drip

Click on the ADD DRIP + button to create a new drip. You will see a page like this:

New drip django form

In the next section, I will talk about the queryset rules that you can build in an easy way to create very useful drips.

Queryset Rules

When you create a drip, you need at least one queryset so the users in it will be the ones that receive the defined email. In the METHOD TYPE menu you are able to choose to filter or to exclude the users in the defined queryset.

On the other hand, when you click in the FIELD NAME OF USER input, you will see the fields of your User model and the fields of your user model in the models related to it:

In the previous image, for example, last_login is the field in the User model, and groups__user__id is the user id from the Groups model that is related to it. So you can enter the name of the field or select it from the list that you see when you click on the input.

After the selection of the field name, you have to choose the type of lookup that you want to do over the field. The possibilities are exactlyexactly (case insensitive)containscontains (case insensitive)greater thangreater than or equal toless than, etc. This lookup type will be done over the user field and the FIELD VALUE that you enter.

The FIELD VALUE input can be a string, a number, or a regular expression. The correctness of the queryset rule will depend on the type of the user field, the lookup type, and the field value.

When you enter a user field that has a date type, Django Drip Campaigns allows you to enter a date value in natural language combining the current time and some operation with seconds, hours, days, etc. For example, if you have selected the field last_login that has a date type, and you want to create a drip to send emails to the users who logged in exactly one week ago; you can enter:

now-1 week

or

now- 1 w

Possible operations and values:

  • Add (+) or subtract (-) dates.
  • On the left side of the operation, write the current DateTime value: now.
  • On the right side of the operation:
    • seconds or s.
    • minutes or m.
    • hours or h.
    • days or d.
    • weeks or w.
    • If you enter the number 1, you can write secondminute, etc.
    • Don’t enter a space between now and the operation symbol. Optionally you can add (or not) a space around the number value.

Let’s see some examples of the date values that you can enter:

  • now-1 day
  • now+ 8days
  • now+ 1 h
  • now-4hours
  • now- 3 weeks
  • now-1 weeks

To finalize this subsection, I would like to show you two examples to clarify the queryset rules creation:

  • Send a recordatory email to the users that haven’t logged in for a week or more:
    • method type: filter
    • user field: last_login
    • lookup type: less than or equal to
    • field value: now- 1 week
  • Send an email to the users that have a Gmail account, excluding the ones that registered yesterday:
    • Rule 1:
      • method type: filter
      • user field: email
      • lookup type: contains
      • field value: gmail
    • Rule 2:
      • method type: exclude
      • user field: date_joined
      • lookup type: exactly
      • field value: now- 1 d

As you can see, the queryset rules creation is very powerful and for each drip, you can add as many as you want.

View the timeline of a Drip

In the django admin, you can select a drip and then click on the VIEW TIMELINE button to view the emails expected to be sent with the corresponding receivers:

Message Class

By default, Django Drip creates and sends messages that are instances of Django’s EmailMultiAlternatives class. If you want to customize in any way the message that is created and sent, you can do that by creating a subclass of EmailMessage and overriding any method that you want to behave differently. For example:

In that example, PlainDripEmail overrides the message property of the base DripMessage class to create a simple EmailMessage instance instead of an EmailMultiAlternatives instance.

In order to be able to specify that your custom message class should be used for a drip, you need to configure it in the DRIP_MESSAGE_CLASSES setting:


This will allow you to choose in the admin, for each drip, whether the default (DripMessage) or plain message class should be used for generating and sending the messages to users.

Send Drips

To send the created and enabled drips, run the command:

python manage.py send_drips

You can use cron to schedule the drips.

What we have been doing in the project

Publish a PyPi Package

Despite Django Drip Campaigns is still a work in progress, we already published the package in PyPI. It’s nothing fancy, but it’s a must to know a few things before starting, so in this section, I’ll be talking about the main steps for publishing an app.

  • Project structure: Your project needs a couple of files in a determined place to be published correctly. An appropriate structure could be:
root_project_folder/
  |
  |__ docs/    # Documentation files
  |__ project_folder/  # Code of the app
  |__ AUTHORS.md
  |__ LICENSE.txt
  |__ MANIFEST.in
  |__ README.md
  |__ setup.py
  • AUTHORS: Specify the author’s information of your project in this file.
  • LICENSE: You have to specify the license of the project. That is a document that provides legally binding guidelines for the use and distribution of software. In OSS the most known are BSD and MIT. We used an MIT license in this case.
  • MANIFEST: Here you can specify the files that aren’t programming files but you want to include anyway in the build of your project. For example the author’s file, the docs, etc.
  • README.md: A file where you introduce and explain your project. It’s very important because otherwise, you can have a very good and useful project but if new people see it and don’t understand what it does nor how it works, then it won’t be used.
  • setup.py: This is a fundamental file. It contains a global setup function that is in charge of the building and configuration of your project at the moment of installation.
  • docs folder: Here is where the files of the documentation are.

  1. Install setuptools and wheel. They are used to generate the distribution package: a group of files needed to upload your app.
python3 -m pip install --user --upgrade setuptools wheel

2. Generate the distribution package. The next command will create all the necessary files under a dist/ folder:

python3 setup.py sdist bdist_wheel

3. Install twine, that a allows you to upload your app as a package:

python3 -m pip install --user --upgrade twine

4. Once installed, run twine to upload the archives under dist/. This will ask for a user and a password, that are the ones you used on the registration at PyPI:

python3 -m twine upload --repository pypi dist/*

If everything went well, you have published your project as a PyPI package. Now you anyone is able to download it with:

pip3 install <project-name>

Summary

In this blog post I talked about the Django Drip Campaigns project, its main features and what we did with it at Rootstrap. We love to make contributions to OSS because it’s a wonderful way of learning, of sharing knowledge, and creating useful programs to be used by other programmers.

Besides I talked about the experience and how to publish a project as a pypi package so anyone who wants to give it a try can download it with a simple command.

OSS gives a great opportunity not only to see how some other group of people solves a problem addressed by the program, but also to purpose and contribute with fixes and improvements. Finally, I hope you have enjoyed this blog and feel motivated to use and work with Django Drip Campaigns and to contribute with OSS.

Want to work with Bruno Michetti?
We are hiring :)

Thanks to the creation of blockchain technology in 2008, a lot of developments have occurred since. For example, the creation […]
June 15
5 min read
One of the most important western philosophers of all time, Aristotle once said – “Man is by nature a social […]
December 7
5 min read
Month-over-month growth is a key metric for measuring the growth of your business.
June 18
5 min read
Quality assurance teams can use various tools to improve a company’s software. For example, a QA engineer may use a stress […]
October 2
5 min read
Startup leaders are always about making contingency plans for when things go wrong. Preparing for the worst is great. But […]
September 28
5 min read
Behind every mobile application, a UI framework determines how developers create the application and how well it performs. Today, UI […]
September 23
5 min read
Handling data is a big part of developing applications with Django. To do that, we use Django’s ORM, from retrieving […]
September 21
5 min read
DevOps has grown to be the top software development methodology worldwide. DevOps prioritizes the company and the customer by improving […]
September 21
5 min read