README.md

voterbowl

The code behind https://voterbowl.org/

We use:

• Python 3.12
• Django 5
• Postgres 16

We spend all our hipster tech tokens for this project to help us build a front-end directly in Django-land. In particular, we use:

• HTMX with django-htmx
• htpy for HTML building, rather than Django templates (with a small handful of exceptions).

So far, I'm liking both. For projects like this one, HTMX is a keeper. htpy has its advantages and its frictions; I'm reminded of javascript templating land just before JSX got introduced.

(Other hipster tools under consideration included css-scope-inline and surreal for "locality of behavior", none of which turned out to be particularly desirable in practice; django-slippers, django-template-partials, and django-components, all of which attempt to relieve pain points in Django's built-in templates but none of which seem terribly successful at it; and various bits of wisdom from django-htmx-patterns.)

For code cleanliness, we also use:

• Ruff for linting
• pyright for type checking

Getting a local dev instance running

1. Make sure you have python 3.12 installed
2. Create and enable a python virtualenv with python -m venv .venv; source .venv/bin/activate
3. Install the python dependencies with pip install -r requirements.txt
4. Get postgres set up. If you've got docker installed, ./scripts/dockerpg.sh up
5. Configure your environment variables. (See .env.sample and settings.py)
6. Run the app. ./scripts/runserver.sh and visit http://localhost:8000/