Layout

Where can I find what I'm looking for?

Overview

Path	Description
hknweb/	The root application (hknweb)
keyrings/live/	GPG keyring, for authorizing access to encrypted secrets (Production Server Only)

Config files

File	Description
.gitattributes	Git config for line endings (Windows \r\n -> Mac / Linux \n)
.gitignore	Git config for files to ignore
.pre-commit-config.yaml	pre-commit style enforcement (optional)
LICENSE	Legal license: open source, enforced by law
Makefile	Task running
README.md	General introduction file
Vagrantfile	Vagrant virtual machine config
bbtest.txt.gpg	blackbox test file
manage.py	Django task runner
pytest.ini	pytest test config
tox.ini	tox test config (on multiple Python versions)

Other Tool Files

File	Description
.travis.yml	Travis script for Travis CI build testing
fabfile.py	Fabric deployment scripts

Python modules

Django is a web framework, structured using the Python module system. What does this mean?

It means that the following:

from hknweb import settings

Implies:

• The hknweb module exists
• hknweb has some object named settings

In the simplest case, this might mean hknweb is the file hknweb.py, and settings is an object is in that file:

# hknweb.py

settings = {
    ...
}

In our case, hknweb is the folder hknweb/. Python recognizes it as a package because it has an __init__.py file, allowing .py files to be imported:

hknweb/
    __init__.py
    models.py
    settings.py
    urls.py
    views.py

Then from hknweb import settings means to import the settings module from hknweb.

Django apps

A Django project is structured with the following:

• Settings: global settings, like what database to use, HTTPS options, what port to serve on, etc.
• WSGI: the Python web server gateway interface, allowing Django to work with any other web server (apache, nginx, gunicorn)
• Apps: self-contained units of logic

And each app has the following files:

• templates/: HTML templates, with spaces for data to be filled in
• apps.py: describes the application (usually just a name + minor config)
• models.py: data models, classes representing database tables
• views.py: views, functions that return HTTP responses (usually a page).
• urls.py: url routing, directing routes to their views

Those of you experienced with other web frameworks might recognize this pattern as MVC (Model-View-Controller), where we split logic into the model (data), view (page), and controller (logic). Django labels them differently, splitting them into the model (data), template (page), and view (logic), but the idea is the same.

You may also encounter the following files:

• admin.py: usually used to register classes, so instances can be created from the admin web interface
• forms.py: form classes
• tests.py: automated testing of database consistency