house-backend

The shared backend of the house projects: the Python every service of them used to carry its own copy of - reading the environment, the logging setup, the PostgreSQL pool and the worker connection with its retry, the schema sync against db/init.sql - plus what the projects to come will need: registration, login and sessions, more than one language, and the kit their smoke tests are built on. A project carries it as a git submodule pinned to one commit; it is plain Python with no build step and no package index.

Its partner is house-frontend, which holds the other half of every page: the markup, the scripts, and what the endpoints answer them with.

Documentation

File	Covers
docs/getting-started.md	adding the library to a project: the submodule, the images, the tests, the Makefile
docs/configuration.md	env - reading .env - and log, the one logging setup
docs/postgres.md	the web pool, the worker connection, and how both ride out a database restart
docs/schema.md	the sync of a live database against db/init.sql, and what it never does alone
docs/auth.md	accounts: registration, login, logout, the user store, the CLI
docs/visitors.md	telling a person from a program, for what a site counts
docs/i18n.md	a site in more than one language: translations, _(), the scripts' words
docs/testing.md	the smoke-test fixtures and the checks every house site passes
docs/development.md	changing the library: rules, tests, rolling a change out

The why behind the rules - the factory, --preload, configuration in .env - is in the house conventions, code.md; these pages describe what the library contains and how to use it.

At a glance

# flask/app/__init__.py
from flask import Flask

from house_backend.log import setup_logger
from house_backend.postgres import configure_pool


def create_app() -> Flask:
    setup_logger()
    app = Flask(__name__)
    configure_pool(max_connections=3, statement_timeout='15s')

    from .house import init_app as init_house       # house-frontend
    init_house(app, error_template='error.html')

    from .routes import main
    app.register_blueprint(main)
    return app

# worker/run_task.py
from house_backend.log import setup_logger
from house_backend.postgres import DatabaseFatalError, create_connection, with_retry
from database import fetch_rows

conn_ref = create_connection()
rows = with_retry(conn_ref, fetch_rows)

Layout

house_backend/
├── env.py               env(), required(), env_int(), env_bool()
├── log.py               setup_logger()
├── postgres.py          configure_pool(), get_db_connection(); create_connection(), with_retry()
├── schema.py            the sync behind every run_db_init.py
├── visitors.py          is_likely_human()
├── i18n.py              I18n, _(): translations, the reader's language, /translations.js
├── auth/                Auth, the user stores, `flask users`
├── sql/auth.sql         the accounts table, for a project with auth
└── testing/             the pytest plugin and invariants.py
tests/                   make test: against a throwaway PostgreSQL
docs/                    these pages