PostgreSQL has excellent support for geographical data thanks to the PostGIS extension, and Django allows you to take full advantage of it thanks to GeoDjango. In this tutorial, I'll show you how to use GeoDjango to build a web app that allows users to search for gigs and events near them.

Requirements

I've made the jump to Python 3, and if you haven't done so yet, I highly recommend it - it's not hard, and there's very few modules left that haven't been ported across. As such, this tutorial assumes you're using Python 3. You'll also need to have Git, PostgreSQL and PostGIS installed - I'll leave the details of doing so up to you as it varies by platform, but you can generally do so easily with a package manager on most Linux distros. On Mac OS X I recommend using Homebrew. If you're on Windows I think your best bet is probably to use a Vagrant VM.

We'll be using Django 1.9 - if by the time you read this a newer version of Django is out, it's quite possible that some things may have changed and you'll need to work around any problems caused. Generally search engines are the best place to look for this, and I'll endeavour to keep the resulting Github repository as up to date as I can, so try those if you get stuck.

Getting started

First of all, let's create our database. Make sure you're running as a user that has the required privileges to create users and databases for PostgreSQL and run the following command:

$ createdb gigfinder

This creates the database. Next, we create the user:

$ createuser -s giguser -P

You'll be prompted to enter a password for the new user. Next, we want to use the psql command-line client to interact with our new database:

$ psql gigfinder

This connects to the database. Run these commands to set up access to the database and install the PostGIS extension:

1# GRANT ALL PRIVILEGES ON DATABASE gigfinder TO giguser;
2# CREATE EXTENSION postgis;
3# \q

With our database set up, it's time to start work on our project. Let's create our virtualenv in a new folder:

$ pyvenv venv

Then activate it:

$ source venv/bin/activate

Then we install Django, along with a few other production dependencies:

$ pip install django-toolbelt

And record our dependencies:

$ pip freeze > requirements.txt

Next, we create our application skeleton:

$ django-admin.py startproject gigfinder .

We'll also create a .gitignore file:

1venv/
2.DS_Store
3*.swp
4node_modules/
5*.pyc

Let's commit our changes:

1$ git init
2$ git add .gitignore requirements.txt manage.py gigfinder
3$ git commit -m 'Initial commit'

Next, let's create our first app, which we will call gigs:

$ python manage.py startapp gigs

We need to add our new app to the INSTALLED_APPS setting. While we're there we'll also add GIS support and set up the database connection. First, add the required apps to INSTALLED_APPS:

1INSTALLED_APPS = [
2    ...
3    'django.contrib.gis',
4    'gigs',
5]

Next, configure the database:

1DATABASES = {
2    'default': {
3         'ENGINE': 'django.contrib.gis.db.backends.postgis',
4         'NAME': 'gigfinder',
5         'USER': 'giguser',
6         'PASSWORD': 'password',
7    },
8}

Let's run the migrations:

1$ python manage.py migrate
2Operations to perform:
3  Apply all migrations: sessions, contenttypes, admin, auth
4Running migrations:
5  Rendering model states... DONE
6  Applying contenttypes.0001_initial... OK
7  Applying auth.0001_initial... OK
8  Applying admin.0001_initial... OK
9  Applying admin.0002_logentry_remove_auto_add... OK
10  Applying contenttypes.0002_remove_content_type_name... OK
11  Applying auth.0002_alter_permission_name_max_length... OK
12  Applying auth.0003_alter_user_email_max_length... OK
13  Applying auth.0004_alter_user_username_opts... OK
14  Applying auth.0005_alter_user_last_login_null... OK
15  Applying auth.0006_require_contenttypes_0002... OK
16  Applying auth.0007_alter_validators_add_error_messages... OK
17  Applying sessions.0001_initial... OK

And create our superuser account:

$ python manage.py createsuperuser

Now, we'll commit our changes:

1$ git add gigfinder/ gigs/
2$ git commit -m 'Created gigs app'
3[master e72a846] Created gigs app
4 8 files changed, 24 insertions(+), 3 deletions(-)
5 create mode 100644 gigs/__init__.py
6 create mode 100644 gigs/admin.py
7 create mode 100644 gigs/apps.py
8 create mode 100644 gigs/migrations/__init__.py
9 create mode 100644 gigs/models.py
10 create mode 100644 gigs/tests.py
11 create mode 100644 gigs/views.py

Our first model

At this point, it's worth thinking about the models we plan for our app to have. First we'll have a Venue model that contains details of an individual venue, which will include a name and a geographical location. We'll also have an Event model that will represent an individual gig or event at a venue, and will include a name, date/time and a venue as a foreign key.

Before we start writing our first model, we need to write a test for it, but we also need to be able to create objects easily in our tests. We also want to be able to easily examine our objects, so we'll install iPDB and Factory Boy:

1$ pip install ipdb factory-boy
2$ pip freeze > requirements.txt

Next, we write a test for the Venue model:

1from django.test import TestCase
2from gigs.models import Venue
3from factory.fuzzy import BaseFuzzyAttribute
4from django.contrib.gis.geos import Point
5import factory.django, random
6
7class FuzzyPoint(BaseFuzzyAttribute):
8    def fuzz(self):
9        return Point(random.uniform(-180.0, 180.0),
10                     random.uniform(-90.0, 90.0))
11
12# Factories for tests
13class VenueFactory(factory.django.DjangoModelFactory):
14    class Meta:
15        model = Venue
16        django_get_or_create = (
17            'name',
18            'location'
19        )
20
21    name = 'Wembley Arena'
22    location = FuzzyPoint()
23
24class VenueTest(TestCase):
25    def test_create_venue(self):
26        # Create the venue
27        venue = VenueFactory()
28
29        # Check we can find it
30        all_venues = Venue.objects.all()
31        self.assertEqual(len(all_venues), 1)
32        only_venue = all_venues[0]
33        self.assertEqual(only_venue, venue)
34
35        # Check attributes
36        self.assertEqual(only_venue.name, 'Wembley Arena')

Note that we randomly generate our location - this is done as suggested in this Stack Overflow post.

Now, running our tests brings up an expected error:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3E
4======================================================================
5ERROR: gigs.tests (unittest.loader._FailedTest)
6----------------------------------------------------------------------
7ImportError: Failed to import test module: gigs.tests
8Traceback (most recent call last):
9  File "/usr/local/Cellar/python3/3.5.1/Frameworks/Python.framework/Versions/3.5/lib/python3.5/unittest/loader.py", line 428, in _find_test_path
10    module = self._get_module_from_name(name)
11  File "/usr/local/Cellar/python3/3.5.1/Frameworks/Python.framework/Versions/3.5/lib/python3.5/unittest/loader.py", line 369, in _get_module_from_name
12    __import__(name)
13  File "/Users/matthewdaly/Projects/gigfinder/gigs/tests.py", line 2, in <module>
14    from gigs.models import Venue
15ImportError: cannot import name 'Venue'
16
17
18----------------------------------------------------------------------
19Ran 1 test in 0.001s
20
21FAILED (errors=1)
22Destroying test database for alias 'default'...

Let's create our Venue model in gigs/models.py:

1from django.contrib.gis.db import models
2
3class Venue(models.Model):
4    """
5    Model for a venue
6    """
7    pass

For now, we're just creating a simple dummy model. Note that we import models from django.contrib.gis.db instead of the usual place - this gives us access to the additional geographical fields.

If we run our tests again we get an error:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3Traceback (most recent call last):
4  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/utils.py", line 64, in execute
5    return self.cursor.execute(sql, params)
6psycopg2.ProgrammingError: relation "gigs_venue" does not exist
7LINE 1: SELECT "gigs_venue"."id" FROM "gigs_venue" ORDER BY "gigs_ve...
8                                      ^
9
10
11The above exception was the direct cause of the following exception:
12
13Traceback (most recent call last):
14  File "manage.py", line 10, in <module>
15    execute_from_command_line(sys.argv)
16  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/__init__.py", line 353, in execute_from_command_line
17    utility.execute()
18  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/__init__.py", line 345, in execute
19    self.fetch_command(subcommand).run_from_argv(self.argv)
20  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/commands/test.py", line 30, in run_from_argv
21    super(Command, self).run_from_argv(argv)
22  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/base.py", line 348, in run_from_argv
23    self.execute(*args, **cmd_options)
24  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/commands/test.py", line 74, in execute
25    super(Command, self).execute(*args, **options)
26  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/base.py", line 399, in execute
27    output = self.handle(*args, **options)
28  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/commands/test.py", line 90, in handle
29    failures = test_runner.run_tests(test_labels)
30  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/test/runner.py", line 532, in run_tests
31    old_config = self.setup_databases()
32  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/test/runner.py", line 482, in setup_databases
33    self.parallel, **kwargs
34  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/test/runner.py", line 726, in setup_databases
35    serialize=connection.settings_dict.get("TEST", {}).get("SERIALIZE", True),
36  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/base/creation.py", line 78, in create_test_db
37    self.connection._test_serialized_contents = self.serialize_db_to_string()
38  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/base/creation.py", line 122, in serialize_db_to_string
39    serializers.serialize("json", get_objects(), indent=None, stream=out)
40  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/serializers/__init__.py", line 129, in serialize
41    s.serialize(queryset, **options)
42  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/serializers/base.py", line 79, in serialize
43    for count, obj in enumerate(queryset, start=1):
44  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/base/creation.py", line 118, in get_objects
45    for obj in queryset.iterator():
46  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/models/query.py", line 52, in __iter__
47    results = compiler.execute_sql()
48  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/models/sql/compiler.py", line 848, in execute_sql
49    cursor.execute(sql, params)
50  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/utils.py", line 64, in execute
51    return self.cursor.execute(sql, params)
52  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/utils.py", line 95, in __exit__
53    six.reraise(dj_exc_type, dj_exc_value, traceback)
54  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/utils/six.py", line 685, in reraise
55    raise value.with_traceback(tb)
56  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/utils.py", line 64, in execute
57    return self.cursor.execute(sql, params)
58django.db.utils.ProgrammingError: relation "gigs_venue" does not exist
59LINE 1: SELECT "gigs_venue"."id" FROM "gigs_venue" ORDER BY "gigs_ve...

Let's update our model:

1from django.contrib.gis.db import models
2
3class Venue(models.Model):
4    """
5    Model for a venue
6    """
7    name = models.CharField(max_length=200)
8    location = models.PointField()

Then create our migration:

1$ python manage.py makemigrations
2Migrations for 'gigs':
3  0001_initial.py:
4    - Create model Venue

And run it:

1$ python manage.py migrate
2Operations to perform:
3  Apply all migrations: gigs, sessions, contenttypes, auth, admin
4Running migrations:
5  Rendering model states... DONE
6  Applying gigs.0001_initial... OK

Then if we run our tests:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3.
4----------------------------------------------------------------------
5Ran 1 test in 0.362s
6
7OK
8Destroying test database for alias 'default'...

They should pass. Note that Django may complain about needing to delete the test database before running the tests, but this should not cause any problems. Let's commit our changes:

1$ git add requirements.txt gigs/
2$ git commit -m 'Venue model in place'

With our venue done, let's turn to our Event model. Amend gigs/tests.py as follows:

1from django.test import TestCase
2from gigs.models import Venue, Event
3from factory.fuzzy import BaseFuzzyAttribute
4from django.contrib.gis.geos import Point
5import factory.django, random
6from django.utils import timezone
7
8class FuzzyPoint(BaseFuzzyAttribute):
9    def fuzz(self):
10        return Point(random.uniform(-180.0, 180.0),
11                     random.uniform(-90.0, 90.0))
12
13# Factories for tests
14class VenueFactory(factory.django.DjangoModelFactory):
15    class Meta:
16        model = Venue
17        django_get_or_create = (
18            'name',
19            'location'
20        )
21
22    name = 'Wembley Arena'
23    location = FuzzyPoint()
24
25class EventFactory(factory.django.DjangoModelFactory):
26    class Meta:
27        model = Event
28        django_get_or_create = (
29            'name',
30            'venue',
31            'datetime'
32        )
33
34    name = 'Queens of the Stone Age'
35    datetime = timezone.now()
36
37class VenueTest(TestCase):
38    def test_create_venue(self):
39        # Create the venue
40        venue = VenueFactory()
41
42        # Check we can find it
43        all_venues = Venue.objects.all()
44        self.assertEqual(len(all_venues), 1)
45        only_venue = all_venues[0]
46        self.assertEqual(only_venue, venue)
47
48        # Check attributes
49        self.assertEqual(only_venue.name, 'Wembley Arena')
50
51
52class EventTest(TestCase):
53    def test_create_event(self):
54        # Create the venue
55        venue = VenueFactory()
56
57        # Create the event
58        event = EventFactory(venue=venue)
59
60        # Check we can find it
61        all_events = Event.objects.all()
62        self.assertEqual(len(all_events), 1)
63        only_event = all_events[0]
64        self.assertEqual(only_event, event)
65
66        # Check attributes
67        self.assertEqual(only_event.name, 'Queens of the Stone Age')
68        self.assertEqual(only_event.venue.name, 'Wembley Arena')

Then we run our tests:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3E
4======================================================================
5ERROR: gigs.tests (unittest.loader._FailedTest)
6----------------------------------------------------------------------
7ImportError: Failed to import test module: gigs.tests
8Traceback (most recent call last):
9  File "/usr/local/Cellar/python3/3.5.1/Frameworks/Python.framework/Versions/3.5/lib/python3.5/unittest/loader.py", line 428, in _find_test_path
10    module = self._get_module_from_name(name)
11  File "/usr/local/Cellar/python3/3.5.1/Frameworks/Python.framework/Versions/3.5/lib/python3.5/unittest/loader.py", line 369, in _get_module_from_name
12    __import__(name)
13  File "/Users/matthewdaly/Projects/gigfinder/gigs/tests.py", line 2, in <module>
14    from gigs.models import Venue, Event
15ImportError: cannot import name 'Event'
16
17
18----------------------------------------------------------------------
19Ran 1 test in 0.001s
20
21FAILED (errors=1)
22Destroying test database for alias 'default'...

As expected, this fails, so create an empty Event model in gigs/models.py:

1class Event(models.Model):
2    """
3    Model for an event
4    """
5    pass

Running the tests now will raise an error due to the table not existing:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3Traceback (most recent call last):
4  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/utils.py", line 64, in execute
5    return self.cursor.execute(sql, params)
6psycopg2.ProgrammingError: relation "gigs_event" does not exist
7LINE 1: SELECT "gigs_event"."id" FROM "gigs_event" ORDER BY "gigs_ev...
8                                      ^
9
10
11The above exception was the direct cause of the following exception:
12
13Traceback (most recent call last):
14  File "manage.py", line 10, in <module>
15    execute_from_command_line(sys.argv)
16  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/__init__.py", line 353, in execute_from_command_line
17    utility.execute()
18  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/__init__.py", line 345, in execute
19    self.fetch_command(subcommand).run_from_argv(self.argv)
20  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/commands/test.py", line 30, in run_from_argv
21    super(Command, self).run_from_argv(argv)
22  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/base.py", line 348, in run_from_argv
23    self.execute(*args, **cmd_options)
24  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/commands/test.py", line 74, in execute
25    super(Command, self).execute(*args, **options)
26  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/base.py", line 399, in execute
27    output = self.handle(*args, **options)
28  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/management/commands/test.py", line 90, in handle
29    failures = test_runner.run_tests(test_labels)
30  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/test/runner.py", line 532, in run_tests
31    old_config = self.setup_databases()
32  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/test/runner.py", line 482, in setup_databases
33    self.parallel, **kwargs
34  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/test/runner.py", line 726, in setup_databases
35    serialize=connection.settings_dict.get("TEST", {}).get("SERIALIZE", True),
36  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/base/creation.py", line 78, in create_test_db
37    self.connection._test_serialized_contents = self.serialize_db_to_string()
38  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/base/creation.py", line 122, in serialize_db_to_string
39    serializers.serialize("json", get_objects(), indent=None, stream=out)
40  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/serializers/__init__.py", line 129, in serialize
41    s.serialize(queryset, **options)
42  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/serializers/base.py", line 79, in serialize
43    for count, obj in enumerate(queryset, start=1):
44  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/base/creation.py", line 118, in get_objects
45    for obj in queryset.iterator():
46  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/models/query.py", line 52, in __iter__
47    results = compiler.execute_sql()
48  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/models/sql/compiler.py", line 848, in execute_sql
49    cursor.execute(sql, params)
50  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/utils.py", line 64, in execute
51    return self.cursor.execute(sql, params)
52  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/utils.py", line 95, in __exit__
53    six.reraise(dj_exc_type, dj_exc_value, traceback)
54  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/utils/six.py", line 685, in reraise
55    raise value.with_traceback(tb)
56  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/db/backends/utils.py", line 64, in execute
57    return self.cursor.execute(sql, params)
58django.db.utils.ProgrammingError: relation "gigs_event" does not exist
59LINE 1: SELECT "gigs_event"."id" FROM "gigs_event" ORDER BY "gigs_ev...

So let's populate our model:

1class Event(models.Model):
2    """
3    Model for an event
4    """
5    name = models.CharField(max_length=200)
6    datetime = models.DateTimeField()
7    venue = models.ForeignKey(Venue)

And create our migration:

1$ python manage.py makemigrations
2Migrations for 'gigs':
3  0002_event.py:
4    - Create model Event

And run it:

1$ python manage.py migrate
2Operations to perform:
3  Apply all migrations: auth, admin, sessions, contenttypes, gigs
4Running migrations:
5  Rendering model states... DONE
6  Applying gigs.0002_event... OK

And run our tests:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3..
4----------------------------------------------------------------------
5Ran 2 tests in 0.033s
6
7OK
8Destroying test database for alias 'default'...

Again, you may be prompted to delete the test database, but this should not be an issue.

With this done, let's commit our changes:

1$ git add gigs
2$ git commit -m 'Added Event model'
3[master 47ba686] Added Event model
4 3 files changed, 67 insertions(+), 1 deletion(-)
5 create mode 100644 gigs/migrations/0002_event.py

Setting up the admin

For an application like this, you'd expect the curators of the site to maintain the gigs and venues stored in the database, and that's an obvious use case for the Django admin. So let's set our models up to be available in the admin. Open up gigs/admin.py and amend it as follows:

1from django.contrib import admin
2from gigs.models import Venue, Event
3
4admin.site.register(Venue)
5admin.site.register(Event)

Now, if you start up the dev server as usual with python manage.py runserver and visit http://127.0.0.1:8000/admin/, you can see that our Event and Venue models are now available. However, the string representations of them are pretty useless. Let's fix that. First, we amend our tests:

1from django.test import TestCase
2from gigs.models import Venue, Event
3from factory.fuzzy import BaseFuzzyAttribute
4from django.contrib.gis.geos import Point
5import factory.django, random
6from django.utils import timezone
7
8class FuzzyPoint(BaseFuzzyAttribute):
9    def fuzz(self):
10        return Point(random.uniform(-180.0, 180.0),
11                     random.uniform(-90.0, 90.0))
12
13# Factories for tests
14class VenueFactory(factory.django.DjangoModelFactory):
15    class Meta:
16        model = Venue
17        django_get_or_create = (
18            'name',
19            'location'
20        )
21
22    name = 'Wembley Arena'
23    location = FuzzyPoint()
24
25class EventFactory(factory.django.DjangoModelFactory):
26    class Meta:
27        model = Event
28        django_get_or_create = (
29            'name',
30            'venue',
31            'datetime'
32        )
33
34    name = 'Queens of the Stone Age'
35    datetime = timezone.now()
36
37class VenueTest(TestCase):
38    def test_create_venue(self):
39        # Create the venue
40        venue = VenueFactory()
41
42        # Check we can find it
43        all_venues = Venue.objects.all()
44        self.assertEqual(len(all_venues), 1)
45        only_venue = all_venues[0]
46        self.assertEqual(only_venue, venue)
47
48        # Check attributes
49        self.assertEqual(only_venue.name, 'Wembley Arena')
50
51        # Check string representation
52        self.assertEqual(only_venue.__str__(), 'Wembley Arena')
53
54
55class EventTest(TestCase):
56    def test_create_event(self):
57        # Create the venue
58        venue = VenueFactory()
59
60        # Create the event
61        event = EventFactory(venue=venue)
62
63        # Check we can find it
64        all_events = Event.objects.all()
65        self.assertEqual(len(all_events), 1)
66        only_event = all_events[0]
67        self.assertEqual(only_event, event)
68
69        # Check attributes
70        self.assertEqual(only_event.name, 'Queens of the Stone Age')
71        self.assertEqual(only_event.venue.name, 'Wembley Arena')
72
73        # Check string representation
74        self.assertEqual(only_event.__str__(), 'Queens of the Stone Age - Wembley Arena')

Next, we run our tests:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3FF
4======================================================================
5FAIL: test_create_event (gigs.tests.EventTest)
6----------------------------------------------------------------------
7Traceback (most recent call last):
8  File "/Users/matthewdaly/Projects/gigfinder/gigs/tests.py", line 74, in test_create_event
9    self.assertEqual(only_event.__str__(), 'Queens of the Stone Age - Wembley Arena')
10AssertionError: 'Event object' != 'Queens of the Stone Age - Wembley Arena'
11- Event object
12+ Queens of the Stone Age - Wembley Arena
13
14
15======================================================================
16FAIL: test_create_venue (gigs.tests.VenueTest)
17----------------------------------------------------------------------
18Traceback (most recent call last):
19  File "/Users/matthewdaly/Projects/gigfinder/gigs/tests.py", line 52, in test_create_venue
20    self.assertEqual(only_venue.__str__(), 'Wembley Arena')
21AssertionError: 'Venue object' != 'Wembley Arena'
22- Venue object
23+ Wembley Arena
24
25
26----------------------------------------------------------------------
27Ran 2 tests in 0.059s
28
29FAILED (failures=2)
30Destroying test database for alias 'default'...

They fail as expected. So let's update gigs/models.py:

1from django.contrib.gis.db import models
2
3class Venue(models.Model):
4    """
5    Model for a venue
6    """
7    name = models.CharField(max_length=200)
8    location = models.PointField()
9
10    def __str__(self):
11        return self.name
12
13
14class Event(models.Model):
15    """
16    Model for an event
17    """
18    name = models.CharField(max_length=200)
19    datetime = models.DateTimeField()
20    venue = models.ForeignKey(Venue)
21
22    def __str__(self):
23        return "%s - %s" % (self.name, self.venue.name)

For the venue, we just use the name. For the event, we use the event name and the venue name.

Now, we run our tests again:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3..
4----------------------------------------------------------------------
5Ran 2 tests in 0.048s
6
7OK
8Destroying test database for alias 'default'...

Time to commit our changes:

1$ git add gigs
2$ git commit -m 'Added models to admin'
3[master 65d051f] Added models to admin
4 3 files changed, 15 insertions(+), 1 deletion(-)

Our models are now in place, so you may want to log into the admin and create a few venues and events so you can see it in action. Note that the location field for the Venue model creates a map widget that allows you to select a geographical location. It is a bit basic, however, so let's make it better. Let's install django-floppyforms:

$ pip install django-floppyforms

And add it to our requirements:

$ pip freeze -r requirements.txt

Then add it to INSTALLED_APPS in gigfinder/setttings.py:

1INSTALLED_APPS = [
2    ...
3    'django.contrib.gis',
4    'gigs',
5    'floppyforms',
6]

Now we create a custom point widget for our admin, a custom form for the venues, and a custom venue admin:

1from django.contrib import admin
2from gigs.models import Venue, Event
3from django.forms import ModelForm
4from floppyforms.gis import PointWidget, BaseGMapWidget
5
6class CustomPointWidget(PointWidget, BaseGMapWidget):
7    class Media:
8        js = ('/static/floppyforms/js/MapWidget.js',)
9
10class VenueAdminForm(ModelForm):
11    class Meta:
12        model = Venue
13        fields = ['name', 'location']
14        widgets = {
15            'location': CustomPointWidget()
16        }
17
18class VenueAdmin(admin.ModelAdmin):
19    form = VenueAdminForm
20
21admin.site.register(Venue, VenueAdmin)
22admin.site.register(Event)

Note in particular that we define the media for our widget so we can include some required Javascript. If you run the dev server again, you should see that the map widget in the admin is now provided by Google Maps, making it much easier to identify the correct location of the venue.

Time to commit our changes:

1$ git add gigfinder/ gigs/ requirements.txt
2$ git commit -m 'Customised location widget'

With our admin ready, it's time to move on to the user-facing part of the web app.

Creating our views

We will keep the front end for this app as simple as possible for the purposes of this tutorial, but of course you should feel free to expand upon this as you see fit. What we'll do is create a form that uses HTML5 geolocation to get the user's current geographical coordinates. It will then return events in the next week, ordered by how close the venue is. Please note that there are plans afoot in some browsers to prevent HTML5 geolocation from working unless content is server over HTTPS, so that may complicate things.

How do we query the database to get this data? It's not too difficult, as shown in this example:

1$ python manage.py shell
2Python 3.5.1 (default, Mar 25 2016, 00:17:15)
3Type "copyright", "credits" or "license" for more information.
4
5IPython 4.1.2 -- An enhanced Interactive Python.
6?         -> Introduction and overview of IPython's features.
7%quickref -> Quick reference.
8help      -> Python's own help system.
9object?   -> Details about 'object', use 'object??' for extra details.
10
11In [1]: from gigs.models import *
12
13In [2]: from django.contrib.gis.geos import Point
14
15In [3]: from django.contrib.gis.db.models.functions import Distance
16
17In [4]: location = Point(52.3749159, 1.1067473, srid=4326)
18
19In [5]: Venue.objects.all().annotate(distance=Distance('location', location)).order_by('distance')
20Out[5]: [<Venue: Diss Corn Hall>, <Venue: Waterfront Norwich>, <Venue: UEA Norwich>, <Venue: Wembley Arena>]

I've set up a number of venues using the admin, one round the corner, two in Norwich, and one in London. I then imported the models, the Point class, and the Distance function, and created a Point object. Note that the Point is passed three fields - the first and second are the latitude and longitude, respectively, while the srid field takes a value of 4326. This field represents the Spatial Reference System Identifier used for this query - we've gone for WGS 84, which is a common choice and is referred to with the SRID 4326.

Now, we want the user to be able to submit the form and get the 5 nearest events in the next week. We can get the date for this time next week as follows:

In [6]: next_week = timezone.now() + timezone.timedelta(weeks=1)

Then we can get the events we want, sorted by distance, like this:

1In [7]: Event.objects.filter(datetime__gte=timezone.now()).filter(datetime__lte=next_week).annotate(distance=Distance('venue__location', location)).order_by('distance')[0:5]
2Out[7]: [<Event: Primal Scream - UEA Norwich>, <Event: Queens of the Stone Age - Wembley Arena>]

With that in mind, let's write the test for our view. The view should contain a single form that accepts a user's geographical coordinates - for convenience we'll auto-complete this with HTML5 geolocation. On submit, the user should see a list of the five closest events in the next week.

First, let's test the GET request. Amend gigs/tests.py as follows:

1from django.test import TestCase
2from gigs.models import Venue, Event
3from factory.fuzzy import BaseFuzzyAttribute
4from django.contrib.gis.geos import Point
5import factory.django, random
6from django.utils import timezone
7from django.test import RequestFactory
8from django.core.urlresolvers import reverse
9from gigs.views import LookupView
10
11class FuzzyPoint(BaseFuzzyAttribute):
12    def fuzz(self):
13        return Point(random.uniform(-180.0, 180.0),
14                     random.uniform(-90.0, 90.0))
15
16# Factories for tests
17class VenueFactory(factory.django.DjangoModelFactory):
18    class Meta:
19        model = Venue
20        django_get_or_create = (
21            'name',
22            'location'
23        )
24
25    name = 'Wembley Arena'
26    location = FuzzyPoint()
27
28class EventFactory(factory.django.DjangoModelFactory):
29    class Meta:
30        model = Event
31        django_get_or_create = (
32            'name',
33            'venue',
34            'datetime'
35        )
36
37    name = 'Queens of the Stone Age'
38    datetime = timezone.now()
39
40class VenueTest(TestCase):
41    def test_create_venue(self):
42        # Create the venue
43        venue = VenueFactory()
44
45        # Check we can find it
46        all_venues = Venue.objects.all()
47        self.assertEqual(len(all_venues), 1)
48        only_venue = all_venues[0]
49        self.assertEqual(only_venue, venue)
50
51        # Check attributes
52        self.assertEqual(only_venue.name, 'Wembley Arena')
53
54        # Check string representation
55        self.assertEqual(only_venue.__str__(), 'Wembley Arena')
56
57
58class EventTest(TestCase):
59    def test_create_event(self):
60        # Create the venue
61        venue = VenueFactory()
62
63        # Create the event
64        event = EventFactory(venue=venue)
65
66        # Check we can find it
67        all_events = Event.objects.all()
68        self.assertEqual(len(all_events), 1)
69        only_event = all_events[0]
70        self.assertEqual(only_event, event)
71
72        # Check attributes
73        self.assertEqual(only_event.name, 'Queens of the Stone Age')
74        self.assertEqual(only_event.venue.name, 'Wembley Arena')
75
76        # Check string representation
77        self.assertEqual(only_event.__str__(), 'Queens of the Stone Age - Wembley Arena')
78
79
80class LookupViewTest(TestCase):
81    """
82    Test lookup view
83    """
84    def setUp(self):
85        self.factory = RequestFactory()
86
87    def test_get(self):
88        request = self.factory.get(reverse('lookup'))
89        response = LookupView.as_view()(request)
90        self.assertEqual(response.status_code, 200)
91        self.assertTemplateUsed('gigs/lookup.html')

Let's run our tests:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3E
4======================================================================
5ERROR: gigs.tests (unittest.loader._FailedTest)
6----------------------------------------------------------------------
7ImportError: Failed to import test module: gigs.tests
8Traceback (most recent call last):
9  File "/usr/local/Cellar/python3/3.5.1/Frameworks/Python.framework/Versions/3.5/lib/python3.5/unittest/loader.py", line 428, in _find_test_path
10    module = self._get_module_from_name(name)
11  File "/usr/local/Cellar/python3/3.5.1/Frameworks/Python.framework/Versions/3.5/lib/python3.5/unittest/loader.py", line 369, in _get_module_from_name
12    __import__(name)
13  File "/Users/matthewdaly/Projects/gigfinder/gigs/tests.py", line 9, in <module>
14    from gigs.views import LookupView
15ImportError: cannot import name 'LookupView'
16
17
18----------------------------------------------------------------------
19Ran 1 test in 0.000s
20
21FAILED (errors=1)
22Destroying test database for alias 'default'...

Our first issue is that we can't import the view in the test. Let's fix that by amending gigs/views.py:

1from django.shortcuts import render
2from django.views.generic.base import View
3
4class LookupView(View):
5    pass

Running the tests again results in the following:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3.E.
4======================================================================
5ERROR: test_get (gigs.tests.LookupViewTest)
6----------------------------------------------------------------------
7Traceback (most recent call last):
8  File "/Users/matthewdaly/Projects/gigfinder/gigs/tests.py", line 88, in test_get
9    request = self.factory.get(reverse('lookup'))
10  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/urlresolvers.py", line 600, in reverse
11    return force_text(iri_to_uri(resolver._reverse_with_prefix(view, prefix, *args, **kwargs)))
12  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/core/urlresolvers.py", line 508, in _reverse_with_prefix
13    (lookup_view_s, args, kwargs, len(patterns), patterns))
14django.core.urlresolvers.NoReverseMatch: Reverse for 'lookup' with arguments '()' and keyword arguments '{}' not found. 0 pattern(s) tried: []
15
16----------------------------------------------------------------------
17Ran 3 tests in 0.154s
18
19FAILED (errors=1)
20Destroying test database for alias 'default'...

We can't resolve the URL for our new view, so we need to add it to our URLconf. First of all, save this as gigs/urls.py:

1from django.conf.urls import url
2from gigs.views import LookupView
3
4urlpatterns = [
5    # Lookup
6    url(r'', LookupView.as_view(), name='lookup'),
7]

Then amend gigfinder/urls.py as follows:

1from django.conf.urls import url, include
2from django.contrib import admin
3
4urlpatterns = [
5    url(r'^admin/', admin.site.urls),
6
7    # Gig URLs
8    url(r'', include('gigs.urls')),
9]

Then run the tests:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3.F.
4======================================================================
5FAIL: test_get (gigs.tests.LookupViewTest)
6----------------------------------------------------------------------
7Traceback (most recent call last):
8  File "/Users/matthewdaly/Projects/gigfinder/gigs/tests.py", line 90, in test_get
9    self.assertEqual(response.status_code, 200)
10AssertionError: 405 != 200
11
12----------------------------------------------------------------------
13Ran 3 tests in 0.417s
14
15FAILED (failures=1)
16Destroying test database for alias 'default'...

We get a 405 response because the view does not accept GET requests. Let's resolve that:

1from django.shortcuts import render_to_response
2from django.views.generic.base import View
3
4class LookupView(View):
5    def get(self, request):
6        return render_to_response('gigs/lookup.html')

If we run our tests now:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3.E.
4======================================================================
5ERROR: test_get (gigs.tests.LookupViewTest)
6----------------------------------------------------------------------
7Traceback (most recent call last):
8  File "/Users/matthewdaly/Projects/gigfinder/gigs/tests.py", line 89, in test_get
9    response = LookupView.as_view()(request)
10  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/views/generic/base.py", line 68, in view
11    return self.dispatch(request, *args, **kwargs)
12  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/views/generic/base.py", line 88, in dispatch
13    return handler(request, *args, **kwargs)
14  File "/Users/matthewdaly/Projects/gigfinder/gigs/views.py", line 6, in get
15    return render_to_response('gigs/lookup.html')
16  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/shortcuts.py", line 39, in render_to_response
17    content = loader.render_to_string(template_name, context, using=using)
18  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/template/loader.py", line 96, in render_to_string
19    template = get_template(template_name, using=using)
20  File "/Users/matthewdaly/Projects/gigfinder/venv/lib/python3.5/site-packages/django/template/loader.py", line 43, in get_template
21    raise TemplateDoesNotExist(template_name, chain=chain)
22django.template.exceptions.TemplateDoesNotExist: gigs/lookup.html
23
24----------------------------------------------------------------------
25Ran 3 tests in 0.409s
26
27FAILED (errors=1)
28Destroying test database for alias 'default'...

We see that the template is not defined. Save the following as gigs/templates/gigs/includes/base.html:

1<!DOCTYPE html>
2<html>
3    <head>
4        <title>Gig finder</title>
5        <meta charset="utf-8">
6        <meta http-equiv="X-UA-Compatible" content="IE=edge">
7        <meta name="viewport" content="width=device-width, initial-scale=1">
8        <link rel="stylesheet" type="text/css" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css"></link>
9    </head>
10    <body>
11        <h1>Gig Finder</h1>
12        <div class="container">
13            <div class="row">
14                {% block content %}{% endblock %}
15            </div>
16        </div>
17        <script src="https://code.jquery.com/jquery-2.2.2.min.js" integrity="sha256-36cp2Co+/62rEAAYHLmRCPIych47CvdM+uTBJwSzWjI=" crossorigin="anonymous"></script>
18        <script language="javascript" type="text/javascript" src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js"></script>
19    </body>
20</html>

And the following as gigs/templates/gigs/lookup.html:

1{% extends "gigs/includes/base.html" %}
2
3{% block content %}
4    <form role="form" action="/" method="post">{% csrf_token %}
5        <div class="form-group">
6            <label for="latitude">Latitude:</label>
7            <input id="id_latitude" name="latitude" type="text" class="form-control"></input>
8        </div>
9        <div class="form-group">
10            <label for="longitude">Longitude:</label>
11            <input id="id_longitude" name="longitude" type="text" class="form-control"></input>
12        </div>
13        <input class="btn btn-primary" type="submit" value="Submit" />
14    </form>
15    <script language="javascript" type="text/javascript">
16        navigator.geolocation.getCurrentPosition(function (position) {
17            var lat = document.getElementById('id_latitude');
18            var lon = document.getElementById('id_longitude');
19            lat.value = position.coords.latitude;
20            lon.value = position.coords.longitude;
21        });
22    </script>
23{% endblock %}

Note the JavaScript to populate the latitude and longitude. Now, if we run our tests:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3...
4----------------------------------------------------------------------
5Ran 3 tests in 1.814s
6
7OK
8Destroying test database for alias 'default'...

Success! We now render our form as expected. Time to commit:

1$ git add gigs gigfinder
2$ git commit -m 'Implemented GET handler'

Handling POST requests

Now we need to be able to handle POST requests and return the appropriate results. First, let's write a test for it in our existing LookupViewTest class:

1    def test_post(self):
2        # Create venues to return
3        v1 = VenueFactory(name='Venue1')
4        v2 = VenueFactory(name='Venue2')
5        v3 = VenueFactory(name='Venue3')
6        v4 = VenueFactory(name='Venue4')
7        v5 = VenueFactory(name='Venue5')
8        v6 = VenueFactory(name='Venue6')
9        v7 = VenueFactory(name='Venue7')
10        v8 = VenueFactory(name='Venue8')
11        v9 = VenueFactory(name='Venue9')
12        v10 = VenueFactory(name='Venue10')
13
14        # Create events to return
15        e1 = EventFactory(name='Event1', venue=v1)
16        e2 = EventFactory(name='Event2', venue=v2)
17        e3 = EventFactory(name='Event3', venue=v3)
18        e4 = EventFactory(name='Event4', venue=v4)
19        e5 = EventFactory(name='Event5', venue=v5)
20        e6 = EventFactory(name='Event6', venue=v6)
21        e7 = EventFactory(name='Event7', venue=v7)
22        e8 = EventFactory(name='Event8', venue=v8)
23        e9 = EventFactory(name='Event9', venue=v9)
24        e10 = EventFactory(name='Event10', venue=v10)
25
26        # Set parameters
27        lat = 52.3749159
28        lon = 1.1067473
29
30        # Put together request
31        data = {
32            'latitude': lat,
33            'longitude': lon
34        }
35        request = self.factory.post(reverse('lookup'), data)
36        response = LookupView.as_view()(request)
37        self.assertEqual(response.status_code, 200)
38        self.assertTemplateUsed('gigs/lookupresults.html')

If we now run this test:

1$ python manage.py test gigs
2Creating test database for alias 'default'...
3..F.
4======================================================================
5FAIL: test_post (gigs.tests.LookupViewTest)
6----------------------------------------------------------------------
7Traceback (most recent call last):
8  File "/Users/matthewdaly/Projects/gigfinder/gigs/tests.py", line 117, in test_post
9    self.assertEqual(response.status_code, 200)
10AssertionError: 405 != 200
11
12----------------------------------------------------------------------
13Ran 4 tests in 1.281s
14
15FAILED (failures=1)
16Destroying test database for alias 'default'...

We can see that it fails because the POST method is not supported. Now we can start work on implementing it. First, let's create a form in gigs/forms.py:

1from django.forms import Form, FloatField
2
3class LookupForm(Form):
4    latitude = FloatField()
5    longitude = FloatField()

Next, edit gigs/views.py:

1from django.shortcuts import render_to_response
2from django.views.generic.edit import FormView
3from gigs.forms import LookupForm
4from gigs.models import Event
5from django.utils import timezone
6from django.contrib.gis.geos import Point
7from django.contrib.gis.db.models.functions import Distance
8
9class LookupView(FormView):
10    form_class = LookupForm
11
12    def get(self, request):
13        return render_to_response('gigs/lookup.html')
14
15    def form_valid(self, form):
16        # Get data
17        latitude = form.cleaned_data['latitude']
18        longitude = form.cleaned_data['longitude']
19
20        # Get today's date
21        now = timezone.now()
22
23        # Get next week's date
24        next_week = now + timezone.timedelta(weeks=1)
25
26        # Get Point
27        location = Point(longitude, latitude, srid=4326)
28
29        # Look up events
30        events = Event.objects.filter(datetime__gte=now).filter(datetime__lte=next_week).annotate(distance=Distance('venue__location', location)).order_by('distance')[0:5]
31
32        # Render the template
33        return render_to_response('gigs/lookupresults.html', {
34            'events': events
35            })