The Collected Works of jjmojojjmojo

First, Lets Branch

In repository a, create a new branch called qotd:

$ cd a
$ git checkout -b qotd
Switched to a new branch 'qotd'

Init

Remember that since this is a fresh clone, we'll need to initialize the virtual environment.

$ python -m venv .
$ source bin/activate
(a) $ pip install -r requirements.txt
(a) $ pip install -e .

Next, copy the database file from your other clone:

(a) $ cp ../random_quote/test.db .

Or initialize a new one:

(random_quote) $ python scripts/generate_quotes.py
(random_quote) $ python
>>> from random_quote import util
>>> util.init("test.db")
util.ingest("quotes.csv", "test.db")

Design: Daily Quotes

Off hand, a few possibilities exist for handling this. 🤔

We could:

1. Define a process, that, at midnight each night, uses the RandomQuoteManager to select a random quote. This would happen outside of the application or people using it. It could be a manual process, or automated as a scheduled job or task.
2. Write a function that will pre-generate random quotes for each day of a given time period. This could also be run by a human, or automated to happen on a given interval (once a year, once a month, etc).
3. Wait until a quote of the day is requested, generate it on demand and return it, or return the current quote of the day if it's already been generated.

The first two possibilities have advantages when the historical listing of previous quotes of the day is important. There will be a quote for every day, and if users need that, those approaches are more useful. In either case, there will never be a day (unless the process or function doesn't run or cover a particular day) where a quote isn't generated.

On the other hand, generating quotes on demand means that we'll only ever have quotes for days when at least one user requested a quote of the day. The advantage to this is that we never store more data than we need to. The down-side is that we can't count on any given day to have a quote. If our API has a lot of use, it may never be an issue, but there will likely always be holes in the data. As before, it really depends on how the historical quotes are used.

There are other considerations as well. Generating the quote on demand means that the quote generation happens at most once per day (but also at least once per day), whereas the other two options can batch the load of generating quotes. In option 2, we could generate thousands of days of quotes if we wanted to, all at once. In this way, pre-populating the quotes moves the burden of generating a quote away from the process of a user requesting a quote of the day. This keeps the API from becoming less responsive.

Our app is doing simple things, and generating a random quote is a pretty quick process. So the impact on users, even if a special quote of the day was generated for every single one, every day, would be minimal. In other applications, pre-loading is preferred, because the cost of generating the data that's being provided to the user can be higher and can impact their ability to effectively use the application. You don't want the fact that you're generating data on the fly to make your API less responsive.

All that considered, our use case is simple, and our process for making a quote of the day will be lightweight, so we'll opt to generate our quote of the day on the fly, as needed. We'll build the functionality such that it's easy to automate this process later if generating a quote becomes more expensive, thus getting the best of both worlds.

Design: Past Quotes Of The Day

The other aspect of this feature is keeping old quotes around after the day they're generated.

Since we're already using a relational database, it's a good candidate for storing quotes of the day.

We can add a new table, called quote_of_the_day to store each generated quote. We'll query that database table and use SQL to return the right quote for the current day.

Here's our updated ER diagram:

The new quote_of_the_day table consists of four columns:

• quote_id, an integer, the ID of the quote that was selected. We'll put a foreign key constraint on the id column in the quotes table

The other three columns will encode the day, month and year:

• day, integer, the day of the month (1-31)
• month, integer, the month (1-12)
• year, integer, the year (e.g. 2019)

We'll put a unique constraint on these three columns - this prevents anyone from inserting a second quote of the day for any given month/day/year.

By using three columns, we have a few benefits:

• Integers are (usually) stored in a form that takes up less space/memory.

• We can easily get all the quotes for a given month, or year by just using a WHERE clause

  1 2	-- Get all quote id's from March of 2025 SELECT quote_id FROM qote_of_the_day WHERE month=3, year=2025

• There's no need to worry about the time portion of the typical date-time storage format (ISO8601, Julian, Unix). This means we don't have to be concerned with timezones, or what happens when a locale difference makes a given time occur on a different calendar day.

The SQL needed to generate the new table looks like this:

1
2
3
4
5
6
7
8

CREATE TABLE IF NOT EXISTS quote_of_the_day (
    quote_id INTEGER NOT NULL,
    day INTEGER NOT NULL,
    month INTEGER NOT NULL,
    year INTEGER NOT NULL,
    FOREIGN KEY(quote_id) REFERENCES quotes(id)
    UNIQUE(day, month, year)
);

Design: API Endpoints

Our new feature will require two new endpoints:

• a GET request to / will show the quote of the day (and create it if it's not present), as a single JSON object.
• a GET request to /qotd will return a JSON list of quote objects that were previously generated.

Implementation: Quote Of The Day API

We'll opt to create a new psuedo-manager class, called QuoteOfTheDay. It will be responsible for retrieving a quote for a given day. It will retrieve an existing quote if one is present, generate a new one and save it if not. The default will be the current day, but it will be possible to create or retrieve a quote for any day in the same manner.

For convenience, we'll add an instance of QuoteOfTheDay to RandomQuoteManager, as the qotd property.

Before we start, we need to add the new table to our test.db file. First, add the following to src/random_quote/schema.sql:

11
12
13
14
15
16
17
18

CREATE TABLE IF NOT EXISTS quote_of_the_day (
    quote_id INTEGER NOT NULL,
    day INTEGER NOT NULL,
    month INTEGER NOT NULL,
    year INTEGER NOT NULL,
    FOREIGN KEY(quote_id) REFERENCES quotes(id)
    UNIQUE(day, month, year)
);

Next we'll use our util.init() function, as we did when originally setting up the database:

(a) $ python
>>> from random_quote.util import init
>>> init("test.db")
>>> quit()

Now we can add the code for our QuoteOfTheDay class. We'll place this in a new src/random_quote/qotd.py module.

Here's the code you need to add.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

"""
Generate a random quote of the day.
"""
import sqlite3
import datetime

from . import util

class QuoteOfTheDay:
    def __init__(self, db_filename, manager=None):
        if manager is None:
            from .manager import RandomQuoteManager
            self.manager  = RandomQuoteManager(db_filename)
        else:
            self.manager = manager

        self.conn = util.connection(db_filename)

    def _date_parts(self, date=None):
        """
        Helper method to convert a date to the day/month/year that is
        stored in the database.
        """
        if date is None:
            date = datetime.datetime.now()

        return (date.day, date.month, date.year)

    def get(self, date=None):
        """
        Return the quote of the day for a given date, or the current date
        if one isn't specified.

        If no quote exists for that date, one is generated and saved.
        """
        day, month, year = self._date_parts(date)

        c = self.conn.cursor()

        c.execute("""
                  SELECT quotes.quote,
                         quotes.created,
                         qotd.quote_id,
                         qotd.day,
                         qotd.month,
                         qotd.year
                    FROM quotes, quote_of_the_day as qotd
                   WHERE quotes.id = qotd.quote_id
                     AND day=?
                     AND month=?
                     AND year=?
                  """,
                  (day, month, year))

        result = c.fetchone()

        if result is None:
            return self.add(date)
        else:
            return dict(result)

    def add(self, date=None):
        """
        Add a quote of the day for a given date, or the current date
        if one isn't specified.
        """
        day, month, year = self._date_parts(date)

        quote = self.manager.random()

        c = self.conn.cursor()

        c.execute("""
            INSERT INTO quote_of_the_day
                        (quote_id, day, month, year)
                 VALUES (?, ?, ?, ?)
           """,
           (quote["id"], day, month, year))

        self.conn.commit()

        return {
            'quote_id': quote['id'],
            'quote': quote['quote'],
            'created': quote['created'],
            'day': day,
            'month': month,
            'year': year
        }

    def all(self):
        """
        Retrieve all existing quotes of the day.
        """
        c = self.conn.cursor()

        c.execute("""
                  SELECT quotes.quote,
                         quotes.created,
                         qotd.quote_id,
                         qotd.day,
                         qotd.month,
                         qotd.year
                    FROM quotes, quote_of_the_day as qotd
                   WHERE quotes.id = qotd.quote_id
                ORDER BY qotd.year, qotd.month, qotd.day
                  """)

        result = []

        for row in c.fetchall():
            result.append(dict(row))

        return result

We'll also need to add an import to src/random_quote/__init__.py, so we can access QuoteOfTheDay from the random_quote.qotd module:

1
2
3
4

from . import manager
from . import wsgi
from . import util
from . import qotd

Next we'll add the qotd property to RandomQuoteManager via it's constructor, in src/random_quote/manager.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

"""
API code for dealing with the quote database.
"""

import datetime
import random
from . import util
from .qotd import QuoteOfTheDay

RAND_MIN = -9223372036854775808
RAND_MAX = 9223372036854775807

class RandomQuoteManager:
    def __init__(self, db_filename, qotd=None):
        self.conn = util.connection(db_filename)
        if qotd is None:
            self.qotd = QuoteOfTheDay(db_filename, self)
        else:
            self.qotd = qotd

...

It's a good idea to make a commit after this work is done. This should be second nature by now, but lets walk through the steps, since we're doing something new: adding an untracked file.

(a) $ git status
On branch qotd
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   src/random_quote/__init__.py
    modified:   src/random_quote/schema.sql
    modified:   src/random_quote/manager.py

Untracked files:
  (use "git add <file>..." to include in what will be committed)

    src/random_quote/qotd.py
    test.db

no changes added to commit (use "git add" and/or "git commit -a")

Note that we now have a file we care about in the Untracked files section, src/random_quote/qotd.py.

We have to git add it in order to get it into our commit:

(a) $ git add src/random_quote/qotd.py

Now, git status shows src/random_quote/qotd.py as a new file:

(a) $ git status
On branch qotd
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

    new file:   src/random_quote/qotd.py

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   src/random_quote/__init__.py
    modified:   src/random_quote/manager.py
    modified:   src/random_quote/schema.sql

Untracked files:
  (use "git add <file>..." to include in what will be committed)

    test.db

Now git commit:

(a) $ git commit -a -m"Added first-pass of quote of the day functionality"
[qotd 53ae911] Added first-pass of quote of the day functionality
 4 files changed, 132 insertions(+), 3 deletions(-)
 create mode 100644 src/random_quote/qotd.py

Back-End API Tests

We'll put the main quote of the day tests in src/random_quote/tests/test_qotd.py.

We'll make use of the preconfigured_manager() fixture. This will use fix_random(), and populate the database with some quotes for us.

Then add the tests to src/random_quote/tests/test_qotd.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

"""
Test the "Quote of the day" functionality.
"""

import pytest
import sqlite3
import datetime

def get_quote_id(conn, day, month, year):
    """
    Helper function to get a quote id for the given day/month/year
    """
    c = conn.cursor()

    c.execute("SELECT quote_id FROM quote_of_the_day WHERE day = ? AND month = ? AND year = ?", (day, month, year))

    result = c.fetchone()

    return result[0]

def test_add_qotd(preconfigured_manager):
    """
    Add a new quote of the day, for the current day.
    """
    today = datetime.datetime.now()

    quote = preconfigured_manager.qotd.add()

    check = get_quote_id(preconfigured_manager.conn, today.day, today.month, today.year)

    assert check == quote["quote_id"]

def test_add_qotd_with_date(preconfigured_manager):
    """
    Add a new quote of the day, for a given day.
    """
    date = datetime.datetime(day=1, year=2025, month=3)

    quote = preconfigured_manager.qotd.add(date)

    check = get_quote_id(preconfigured_manager.conn, 1, 3, 2025)

    assert check == quote["quote_id"]

def test_add_duplicate(preconfigured_manager):
    """
    Try to add an additional quote of the day.
    """
    date = datetime.datetime(day=1, year=2025, month=3)

    preconfigured_manager.qotd.add(date)

    with pytest.raises(sqlite3.IntegrityError):
        preconfigured_manager.qotd.add(date)

def test_get_without_date(preconfigured_manager):
    """
    Get a quote of the day, no date specified. Should create a new QOTD.
    """
    today = datetime.datetime.now()

    quote = preconfigured_manager.qotd.get()

    check = get_quote_id(preconfigured_manager.conn, today.day, today.month, today.year)

    assert check == quote["quote_id"]

def test_get_with_date(preconfigured_manager):
    """
    Get a quote of the day, for a specified date. Should create a new QOTD.
    """
    date = datetime.datetime(day=1, year=2025, month=3)

    quote = preconfigured_manager.qotd.get(date)

    check = get_quote_id(preconfigured_manager.conn, 1, 3, 2025)

    assert check == quote["quote_id"]

def test_all(preconfigured_manager):
    """
    Add and retrieve several quotes of the day.
    """
    date1 = datetime.datetime(day=1, year=2025, month=3)
    date2 = datetime.timedelta(days=1) + date1
    date3 = datetime.timedelta(days=1) + date2

    quote1 = preconfigured_manager.qotd.add(date1)
    quote2 = preconfigured_manager.qotd.add(date2)
    quote3 = preconfigured_manager.qotd.add(date3)

    result = preconfigured_manager.qotd.all()

    assert result[0] == quote1
    assert result[1] == quote2
    assert result[2] == quote3

Lets also add a new test case to src/random_quote/tests/test_manager.py to make sure that the qotd property exists:

75
76
77
78
79
80
81

def test_qotd(preconfigured_manager):
    """
    Ensure the qotd property exists.
    """
    from random_quote.qotd import QuoteOfTheDay

    assert isinstance(preconfigured_manager.qotd, QuoteOfTheDay)

Run the tests:

(a) $ pytest src
============================== test session starts ==============================
platform darwin -- Python 3.7.3, pytest-4.6.2, py-1.8.0, pluggy-0.12.0
rootdir: [...]/a
collected 17 items

src/random_quote/tests/test_manager.py .......                            [ 41%]
src/random_quote/tests/test_qotd.py ......                                [ 76%]
src/random_quote/tests/test_wsgi.py ....                                  [100%]

=========================== 17 passed in 0.20 seconds ===========================

Now, git add the src/random_quote/tests/test_qotd.py file, and commit.

Implementation: Web API Endpoints

Here's the updated path map:

To implement the quote of the day functionality in RandomQuoteApp, we'll add the methods qotd() and qotd_listing() which will return the current quote of the day, or all quotes of the day, respectively:

 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

    def qotd(self, request):
        """
        Return today's quote of the day.
        """
        response = Response()

        response.json = self.manager.qotd.get()
        response.content_type = "application/json"

        return response

    def qotd_listing(self, request):
        """
        List all existing quotes of the day.
        """
        response = Response()

        response.json = self.manager.qotd.all()
        response.content_type = "application/json"

        return response

Then we need to update the routing, in __call__():

25
26
27
28
29
30
31
32
33
34
35
36
37

        try:
            if request.path == "/":
                response = self.qotd(request)
            elif request.path == "/qotd":
                response = self.qotd_listing(request)
            elif request.path == "/quotes":
                response = self.listing(request)
            elif request.path.startswith("/quote"):
                response = self.get(request)
            elif request.path == "/random":
                response = self.random(request)
            else:
                raise HTTPNotFound()

We can run the http server again and try it out in our browser:

(a) $ gunicorn -b 127.0.0.1:8080 -t 9999999 -w 1 --reload wsgi:app

If you look at http://127.0.0.1:8080, you'll notice a quote of the day is returned, instead of a 404:

And loading http://127.0.0.1:8080/qotd returns a list, showing the quote that was just generated:

Tests For The Web API

Now we need to add tests to src/random_quote/tests/test_wsgi.py. First we need to add a necessary import, since we're going to be using some functions from datetime:

1
2
3
4
5
6

"""
Functional tests of the WSGI application.
"""

import pytest
import datetime

Then add three new tests to the bottom of the file:

 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105

def test_get_root(preconfigured_wsgi_app):
    """
    Make a GET request for /
    """
    response = preconfigured_wsgi_app.get("/")

    json_quote = response.json

    today = datetime.datetime.now()
    quote = preconfigured_wsgi_app.app.manager.qotd.get(today)

    assert json_quote == quote

def test_qotd_empty(preconfigured_wsgi_app):
    """
    Request the list of quotes of the day at /qotd - no existing quotes
    """
    response = preconfigured_wsgi_app.get("/qotd")

    quotes = response.json

    assert quotes == []

def test_qotd(preconfigured_wsgi_app):
    """
    Request the list of quotes of the day at /qotd
    """
    today = datetime.datetime.now()
    quote1 = preconfigured_wsgi_app.app.manager.qotd.get(today)
    quote2 = preconfigured_wsgi_app.app.manager.qotd.get(datetime.datetime(year=2048, month=2, day=26))

    response = preconfigured_wsgi_app.get("/qotd")

    quotes = response.json

    assert len(quotes) == 2
    assert quotes[0] == quote1
    assert quotes[1] == quote2

Running the tests, we see the new ones have been picked up:

(a) pytest -v src
============================== test session starts ==============================
platform darwin -- Python 3.7.3, pytest-4.6.2, py-1.8.0, pluggy-0.12.0 -- [...]/a/bin/python
cachedir: .pytest_cache
rootdir: [...]/a
collected 20 items

src/random_quote/tests/test_manager.py::test_add_quote PASSED             [  5%]
src/random_quote/tests/test_manager.py::test_get_quote PASSED             [ 10%]
src/random_quote/tests/test_manager.py::test_remove_quote PASSED          [ 15%]
src/random_quote/tests/test_manager.py::test_all PASSED                   [ 20%]
src/random_quote/tests/test_manager.py::test_random_quote PASSED          [ 25%]
src/random_quote/tests/test_manager.py::test_unknown_id PASSED            [ 30%]
src/random_quote/tests/test_manager.py::test_qotd PASSED                  [ 35%]
src/random_quote/tests/test_qotd.py::test_add_qotd PASSED                 [ 40%]
src/random_quote/tests/test_qotd.py::test_add_qotd_with_date PASSED       [ 45%]
src/random_quote/tests/test_qotd.py::test_add_duplicate PASSED            [ 50%]
src/random_quote/tests/test_qotd.py::test_get_without_date PASSED         [ 55%]
src/random_quote/tests/test_qotd.py::test_get_with_date PASSED            [ 60%]
src/random_quote/tests/test_qotd.py::test_all PASSED                      [ 65%]
src/random_quote/tests/test_wsgi.py::test_get_quote PASSED                [ 70%]
src/random_quote/tests/test_wsgi.py::test_all_quotes PASSED               [ 75%]
src/random_quote/tests/test_wsgi.py::test_random_quote PASSED             [ 80%]
src/random_quote/tests/test_wsgi.py::test_get_quote_unknown_id PASSED     [ 85%]
src/random_quote/tests/test_wsgi.py::test_root PASSED                     [ 90%]
src/random_quote/tests/test_wsgi.py::test_qotd_empty PASSED               [ 95%]
src/random_quote/tests/test_wsgi.py::test_qotd PASSED                     [100%]

=========================== 20 passed in 0.52 seconds ===========================

Commit your changes.

Version Bump

As we did in part 2, change the version in setup.py. This time, set the version to 0.2.0, since we have a new feature that is backwards-compatible with the 0.1.0 version.

Don't forget to re-install (pip install -e .), re-run the tests (pytest src), and git commit your changes.

Rebase To master

Since we've only done this process once, lets walk through it again.

First we need to git fetch any outstanding remote changes:

(a) $ git fetch origin master

Next, interactive git rebase:

(a) $ git rebase -i master

Be sure to pick the oldest (first) commit, and squash the rest. Don't forget to write a nice log entry when git rebase gives you the chance.

You can try preserving the old commit messages and adding a summary on the first line:

1
2
3
4
5
6

FEATURE: Quote Of The Day

Added first-pass of quote of the day functionality
Added tests for Quote Of The Day feature
Added HTTP API support for the quote of the day
Set version to 0.2.0

Re-run the tests to make sure nothing went wrong (there should be 20 passing tests):

(a) $ pytest src
============================== test session starts ==============================
platform darwin -- Python 3.7.3, pytest-4.6.2, py-1.8.0, pluggy-0.12.0
rootdir: [...]/a
collected 20 items

src/random_quote/tests/test_manager.py .......                            [ 35%]
src/random_quote/tests/test_qotd.py ......                                [ 65%]
src/random_quote/tests/test_wsgi.py .......                               [100%]

=========================== 20 passed in 0.61 seconds ===========================

Checkout And Merge master

First, git checkout the master branch:

(a) $ git checkout master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.

Then git merge to your qotd feature branch:

(a) $ git merge qotd
Updating c2a655e..150ba38
Fast-forward
 src/random_quote/__init__.py           |   3 +-
 src/random_quote/manager.py            |   9 ++-
 src/random_quote/qotd.py               | 114 ++++++++++++++++++++++++++++++++++
 src/random_quote/schema.sql            |  11 +++-
 src/random_quote/tests/conftest.py     |  26 +++++++-
 src/random_quote/tests/test_manager.py |  10 ++-
 src/random_quote/tests/test_qotd.py    |  96 ++++++++++++++++++++++++++++
 src/random_quote/tests/test_wsgi.py    |  42 ++++++++++++-
 src/random_quote/wsgi.py               |  29 ++++++++-
 9 files changed, 332 insertions(+), 8 deletions(-)
 create mode 100644 src/random_quote/qotd.py
 create mode 100644 src/random_quote/tests/test_qotd.py

Run the tests again (pytest src)

Push

Finally, publish the changes using git push:

(a) $ git push origin master
Enumerating objects: 25, done.
Counting objects: 100% (25/25), done.
Delta compression using up to 8 threads
Compressing objects: 100% (13/13), done.
Writing objects: 100% (14/14), 3.44 KiB | 3.44 MiB/s, done.
Total 14 (delta 6), reused 0 (delta 0)
To [...]/random_quote_remote
   c2a655e..150ba38  master -> master

Design

This bug fix is simply just returning something when an HTTP client makes a GET request for /.

We'll add a static HTML file to the source that will provide links to, and useful info about, each of the API endpoints. It will be served when a GET request is made for /.

We'll use the webob.static.FileApp class to serve the file. This handles buffering and streaming properly for us.

Make The Branch

Lets check out and create our branch. We'll call this one index-info:

(b) $ git checkout -b index-info
Switched to a new branch 'index-info'

Fix The Bug

Lets construct a simple HTML5 file that has the information about the API within it. The links will be relative. This allows for flexibility in how we host the API. We'll put it in a special directory within the source.

First, create the new src/random_quote/static directory:

(b) $ mkdir src/random_quote/static

We're using this name because it indicates there are files that need to be served without being processed. We're setting up an entire directory to give us some flexibility in the future. We may want to add some additional static assets (such as images or CSS files) to our API documentation, or build some sort of front-end for the browser. We can switch to using the webob.static.DirectoryApp class and serve the entire directory at once.

Add the following to src/random_quote/static/index.html:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

<!DOCTYPE html>
<html>
<head>
    <title>Random Quote API</title>
</head>
<meta charset="UTF-8">
<body>
<h1>Random Quote API</h1>
<p>Welcome to the Random Quote API. This API provides random quote functionality via HTTP.</p>

<h2>API Endpoints</h2>
<p><em>All endpoints only work with GET requests. All responses are JSON</em></p>
<dl>
    <dt><a href="quote/1">/quote/1</a></dt>
    <dd>Retrieve a specific quote by its ID. In this example, we are retrieving quote #1.</dd>
    <dt><a href="quotes">/quotes</a></dt>
    <dd>Retrieve all quotes.</dd>
    <dt><a href="random">/random</a></dt>
    <dd>Retrieve a random quote</dd>
</dl>
</body>
</html>

Naming this file index.html is a signal to other developers that this file is intended to be the default file served up when the / (or root path) is requested. This is a convention that goes back to the early days of HTTP servers, and is still in use today.

We need a way to figure out where src/random_quote/static lives. When this application is deployed as a python egg, it could be installed anywhere, and gunicorn (or whatever WSGI server we use) could be running, again, anywhere. We need to find an absolute path to the src/random_quote/static directory.

We have an example of how to do this already, in src/random_quote/util.py, in the schema() function:

14
15
16
17
18

def schema():
    """
    Return the location of the SQL schema.
    """
    return os.path.join(os.path.dirname(__file__), "schema.sql")

Here we use Python's built-in special __file__ variable that returns the path to the currently executing module (more detail). We then use a couple of functions from the os.path module to construct a path in a system-agnostic way.

We can do the same thing with our new static directory. But since we may be using it to serve multiple files, we'll add a little extra functionality to request a more specific path if needed. We'll call the function static(). Add the following to the end of src/random_quote/util.py:

58
59
60
61
62
63
64
65
66
67

def static(path=None):
    """
    Return the full path to a file the static directory.
    """
    static = os.path.join(os.path.dirname(__file__), "static")

    if path:
        return os.path.join(static, path)
    else:
        return static

If we don't pass a path argument, we get the path to just the static directory, otherwise, the path is added to the end.

Next, we need to add an import for webob.static.FileApp, and our new util.static() function, to src/random_quote/wsgi.py:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

"""
WSGI Applications
"""
from . import manager
from . import util
from webob import Request, Response
from webob.exc import HTTPError, HTTPNotFound, HTTPMethodNotAllowed, HTTPBadRequest
from webob.static import FileApp
import re

class RandomQuoteApp:
...

And alter the routing:

27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

        try:
            if request.path == "/":
                response = FileApp(util.static("index.html"))
            elif request.path == "/quotes":
                response = self.listing(request)
            elif request.path.startswith("/quote"):
                response = self.get(request)
            elif request.path == "/random":
                response = self.random(request)
            else:
                raise HTTPNotFound()

            return response(environ, start_response)
        except HTTPError as error_response:
            return error_response(environ, start_response)

Lets start up the web server, and take a quick look:

(b) $ gunicorn -b 127.0.0.1:8080 -t 9999999 -w 1 --reload wsgi:app

If we visit http://127.0.0.1:8080 in a browser, we will see the new landing page. We can click the links and they should work.

Committing our changes is just like we've done before. Be sure to git add the src/random_quote/static/index.html file.

Test For The New Index Page

The test for this fix is pretty simplistic. We just need to make sure there isn't a 404 status returned when making a GET request for /. We can use TestApp to do this, via the preconfigured_wsgi_app() fixture established in src/random_quote/tests/conftest.py.

We should also make sure we're getting the right kind of content, by checking the Content-Type header. A JSON response (application/json), instead of an HTML one (text/html) would indicate something went wrong.

Add this test to the end of src/random_quote/tests/test_wsgi.py:

67
68
69
70
71
72

def test_get_root(preconfigured_wsgi_app):
    """
    Make a GET request for the root path.
    """
    response = preconfigured_wsgi_app.get("/")
    assert response.content_type == 'text/html'

We run the tests again to make sure our new case was picked up, and that we didn't break anything else:

(b) $ pytest -v src

============================== test session starts ==============================
platform darwin -- Python 3.7.3, pytest-4.6.2, py-1.8.0, pluggy-0.12.0 -- [...]/b/bin/python
cachedir: .pytest_cache
rootdir: [...]/b
collected 11 items

src/random_quote/tests/test_manager.py::test_add_quote PASSED             [  9%]
src/random_quote/tests/test_manager.py::test_get_quote PASSED             [ 18%]
src/random_quote/tests/test_manager.py::test_remove_quote PASSED          [ 27%]
src/random_quote/tests/test_manager.py::test_all PASSED                   [ 36%]
src/random_quote/tests/test_manager.py::test_random_quote PASSED          [ 45%]
src/random_quote/tests/test_manager.py::test_unknown_id PASSED            [ 54%]
src/random_quote/tests/test_wsgi.py::test_get_quote PASSED                [ 63%]
src/random_quote/tests/test_wsgi.py::test_all_quotes PASSED               [ 72%]
src/random_quote/tests/test_wsgi.py::test_random_quote PASSED             [ 81%]
src/random_quote/tests/test_wsgi.py::test_get_quote_unknown_id PASSED     [ 90%]
src/random_quote/tests/test_wsgi.py::test_get_root PASSED                 [100%]

=========================== 11 passed in 0.20 seconds ===========================

Commit the tests.

Version Bump

We've fixed a bug, and so we need to change the version number in setup.py again. This time, it will be 0.1.2:

1
2
3
4
5
6
7
8
9

from setuptools import setup, find_packages
setup(
    name="random_quote",
    version="0.1.2",
    packages=['random_quote'],
    package_dir={'':'src'},
    install_requires=['webob'],
    include_package_data=True
)

Be sure to pip install -e . again and re-run the tests before committing your changes.

Rebase

Lets proceed to do the rebase as usual.

First, we need to git fetch any remote changes we haven't seen yet:

(b) $ git fetch
remote: Enumerating objects: 29, done.
remote: Counting objects: 100% (29/29), done.
remote: Compressing objects: 100% (16/16), done.
remote: Total 17 (delta 8), reused 0 (delta 0)
Unpacking objects: 100% (17/17), done.
From [...]/random_quote_remote
   c2a655e..9057fd0  master     -> origin/master

Unlike the last couple of times we called git fetch, we actually have changes to download. This is evidenced by the output above.

When we run git rebase -i master, it works as usual. Be sure to run the tests again (there should still only be 11 tests).

Documentation Update

Add the following links to src/random_quote/static/index.html:

20
21
22
23

    <dt><a href="qotd">/qotd</a></dt>
    <dd>Retrieve today's "Quote of the day."</dd>
    <dt><a href="qotd-history">/qotd-history</a></dt>
    <dd>Retrieve all previous "Quote of the day." entries.</dd>

Start up gunicorn again:

(b) $ gunicorn -b 127.0.0.1:8080 -t 9999999 -w 1 --reload wsgi:app

If we open http://127.0.0.1:8080 in a browser, the new page is shown, and the links do what they're supposed to.

Complete the merge

Now that we've untangled this mess, we need to finish up the merge.

git status reminds us that we're in the middle of merging:

(b) $ git status
On branch master
Your branch is up to date with 'origin/master'.

You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Changes to be committed:

    new file:   src/random_quote/static/index.html
    modified:   src/random_quote/util.py

Unmerged paths:
  (use "git add <file>..." to mark resolution)

    both modified:   setup.py
    both modified:   src/random_quote/tests/test_wsgi.py
    both modified:   src/random_quote/wsgi.py

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   src/random_quote/static/index.html

Untracked files:
  (use "git add <file>..." to include in what will be committed)

    test.db

To finish the merge, we first need to let git know the conflicted files are fixed. We do this by using git add:

(b) $ git add src/random_quote/tests/test_wsgi.py
(b) $ git add src/random_quote/wsgi.py
(b) $ git add setup.py

Now git status tells us what we need to do next:

(b) $ git status
On branch master
Your branch is up to date with 'origin/master'.

All conflicts fixed but you are still merging.
  (use "git commit" to conclude merge)

Changes to be committed:

    modified:   setup.py
    new file:   src/random_quote/static/index.html
    modified:   src/random_quote/tests/test_wsgi.py
    modified:   src/random_quote/util.py
    modified:   src/random_quote/wsgi.py

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   src/random_quote/static/index.html

Untracked files:
  (use "git add <file>..." to include in what will be committed)

    test.db

To complete the merge, we just need to do what git status is telling us: git commit:

(b) $ git commit -a -m"Resolved API endpoint conflicts"
[master 36c0796] Resolved API endpoint conflicts

Now we can git push our changes to the remote:

(b) $ git push origin master
Enumerating objects: 37, done.
Counting objects: 100% (36/36), done.
Delta compression using up to 8 threads
Compressing objects: 100% (18/18), done.
Writing objects: 100% (23/23), 2.59 KiB | 2.59 MiB/s, done.
Total 23 (delta 12), reused 0 (delta 0)
To [...]/random_quote_remote
   9057fd0..5ccabd1  master -> master