Documentation for the discountbot project

Discountbot automatically finds who need a discount, create the discounts and send emails with the discount code in it. Discountbot needs a SQL request to get the emails, a SQL request to create the discounts and an email template to send the emails.

You’ll find below anything you need to install, configure or run discountbot.

Guide

How to install discountbot

From PyPI

You need to define what the SQL database backend you will use, then use the following command:

  • for MySQL
    $ pip3 install discountbot[mysql]
  • for PostgreSQL
    $ pip3 install discountbot[postgresql]

From sources

  • You need at least Python 3.4.

  • Untar the tarball and go to the source directory with the following commands:

    $ tar zxvf discountbot-0.1.tar.gz
    $ cd discountbot
    
  • Next, to install discountbot on your computer, type the following command with the root user:

    $ python3 setup.py install
    $ # or
    $ python3 setup.py install --install-scripts=/usr/bin
    

Configure discountbot

Discountbot Configuration

In order to configure discountbot, you need to create a discountbot.ini file (or any name you prefer, finishing with the extension .ini) with the following parameters:

[discount]
code=MYBIGCOMPANY-WELCOME
; duration of the discount in days
duration=2

[database]
; use the following for MySQL - you need mysql_connector_python
db_connector=mysql+mysqlconnector
; use the following for PostgreSQL - you need psycopg2 python library
; dbconnector=postgresql+psycopg2
db_host=localhost
db_name=customers
db_user=customers_app
db_pass=V3rYS3cR3tP4sSw0rd,
; we use a SQL request to get the customers having an account but not using it
sql_get_users=select custome.email from customerinfos where customerinfos.id not in (select customer_id from payments)
; we us a SQL request to create a discount
; {code} will be replaced by the discount code (see the [discount] section)
; {start} will be replaced by the current date
; {end} will be replaced by the current date + duration (see the [discount] section) days
; {created} will be replaced by the the current datetime while creating the discount
sql_create_discount=insert into discounts (code,percentage,start,end,status,created) values ('{code}',20.00,'{start}','{end}',1,'{created}')

[email]
email_template_path=/usr/share/discountbot/templates/mybigcompany.discount.template.txt
email_host=localhost
email_subject=Your Incredible Discount!
email_from=sales@mybigcompany.com
; email_user=user124@mybigcompany.com => only useful if you use authentication with SMTP
; email_pass=T0pS3cR4tP4s5w0rD => only useful if you use authentication with SMTP

[sqlite]
sqlite_path=/home/chaica/progra/python/discountbot/discountbot.db

For the [discount] section:

  • code: a string prefixing the discount code. ‘-%Y%m%d%H%S{indice}’ where indice is an incremental number of the customer while generating the discount will be added
  • duration: duration of the validity of the discount in days

For the [database] section:

  • db_connector: the Sqlalchemy connector to use to access your database (see examples). Defaults to mysql+mysqlconnector
  • db_host: the host where the database runs. Defaults to 127.0.0.1
  • db_name: the name of the database
  • db_user: the user name to access the database
  • db_pass: the password to access the database
  • sql_get_users: the SQL request to get the list of the emails of the people needing a discount
  • sql_create_discount: the SQL request to create the discounts. Available placeholders are {code} will be replaced by the discount code (see the [discount] section), {start} will be replaced by the current date, {end} will be replaced by the current date + duration (see the [discount] section) days, {created} will be replaced by the the current datetime while creating the discount

For the [email] section:

  • email_template_path: the path to the template of the email. Defaults to /usr/share/discountbot/discountbot.template.txt
  • email_host: the host to send the email to. Defaults to localhost
  • email_subject: the subject of the email
  • email_from: the email addresse of the sender
  • email_user: login for SMTP authentication
  • email_pass: password for SMTP authentication

For the [sqlite] section:

  • sqlite_path: the path to the sqlite database file to store emails of people who already got the discount. Defaults to /var/lib/discountbot/discountbot.db

Email Template

The email template is a html file with some placeholders. These placeholders will be replaced by the discount code:

  • {code}: replaced by the discount code generated by DiscountBot
  • {duration}: the value duration from the configuration file

Here is an example of the content of the email template:

<html>

<head> </head> <body>

<p>Hi,</p> <p>As we are really happy to have you as a potential customer, we are offering you a 20% discount, available for {duration} days!</p> <p>Here is your discount code: {code}</p> <p>Cheers,</p>

</body>

</html>

Initial launch of discountbot

After you defined the configuration of discountbot, while launching discountbot for the first time, you could be interested in NOT sending discounts to all of the identified customers, because maybe you already sent them discounts manually. For that, just use the -p or –populate option:

$ discountbot -p

While launching discountbot this way, the configuration file should be located at /etc/discountbot/discountbot.ini

Change the default location of the discountbot configuration

Or you can change the default location of the configuration file (/etc/discountbot/discountbot.ini) with the -c option:

$ discountbot -c /opt/discountbot/discountbot.ini

Dry run mode

The dry run mode allows for simulating the creations of discounts and sending them to the users. It does not perform any definitive actions, like storing the users or sending them real emails:

$ discount --dry-run

Debug mode

Using the -d or –debug option, you activate the debug mode, increasing verbosity about what’s going on:

$ discountbot -d

License

This software comes under the terms of the GPLv3+. See the LICENSE file for the complete text of the license.

Authors

Carl Chenet <chaica@ohmytux.com>

Indices and tables