flask + htmx + bulma

sample app which provides:

• backend
  • backend via apiflask
  • db via sqlalchemy
  • config management via dotenv
  • security via flask-security-too
  • admin views via flask-admin
  • package management via pipenv
  • cli via click and rich
• ui
  • frontend via htmx and jinja
  • styling via bulma and bulma-extensions
  • charting via chartjs
  • tables via tabulator
• test
  • runner via pytest
  • code styles via flake8 and biome
  • system testing via playwright
  • ci via gitub actions

setup

• install system requirements
  • debian/ubuntu - sudo apt install libpq-dev postgresql pipenv
• install python reqs - pipenv install
• configure db
  • sudo -u postgres psql
  • create database <dbname>;
  • create user <user> with encrypted password '<pw>';
  • grant all privileges on database <dbname> to <user>;
  • create schema <schema>;
  • grant all on schema <schema> to <user>;

configuring

config options can be found at app/config.py. at a minimum, the following options need to be set:

• SQLALCHEMY_DATABASE_URI
• SECRET_KEY (run secrets.token_urlsafe() if not sure)
• SECURITY_PASSWORD_SALT (run secrets.SystemRandom().getrandbits(128) if not sure)

you will need to create and assign a superuser role to the user to see model views in Admin

auth providers

todo how to set up external providers

managing

migrations

autogen migrations

• ENV=local pipenv run flask --app app.app db migrate -m '' --directory app/storage/migrations

apply

• ENV=local pipenv run flask --app app.app db upgrade --directory app/storage/migrations

init (if starting from scratch or you want to compress migrations)

• ENV=local pipenv run flask --app app.app db init --directory app/storage/migrations

permissions

init

• ENV=local pipenv run flask --app app.app roles create superuser
• ENV=local pipenv run flask --app app.app users create -a

details

• ENV=local pipenv run flask --app app.app show roles

running

server (locally)

• ENV=local pipenv run flask --app app.app run --debug

server (container - locally)

• podman build -f Dockerfile
• podman run --network host -p 5000:5000 --env-file=.env flask --app app.app run --debug

client

import requests
sess = requests.Session()
sess.post('http://127.0.0.1:5000/api/login',
          data={'email':'<email>','password':'<pw>', 'remember': 'false'},
          headers={"Content-Type": "application/x-www-form-urlencoded"})
# session should have cookie
sess.cookies

running tests

• pipenv install --dev

styling

• pipenv run flake8
• ./biome check app/static

unit

• SQLALCHEMY_DATABASE_URI=<postgres_uri> pipenv run pytest tests/unit
• see github actions workflow for sample

system

setup

• pipenv run playwright install

run

• ENV=local pipenv run flask --app app.app run
• TEST_USER= TEST_PW= pipenv run pytest tests/system

debug

• TEST_USER= TEST_PW= pipenv run pytest tests/system -k <test_case> --headed --slowmo 1000

resources

• flask-security:
  • pallets-eco/flask-security-3.0#769
  • oauth configuration:
    • https://blog.miguelgrinberg.com/post/oauth-authentication-with-flask-in-2023
    • https://flask-security-too.readthedocs.io/en/stable/features.html#social-oauth-authentication
• flask deep dives (tbh, i didn't read/watch these but so i clear bookmarks):
  • https://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-xxiii-application-programming-interfaces-apis
  • https://hackersandslackers.com/flask-user-sessions-and-redis/
  • https://www.youtube.com/watch?v=MwZwr5Tvyxo&list=PL-osiE80TeTs4UjLw5MM6OjgkjFeUxCYH
• bulma
  • templates - https://github.com/BulmaTemplates/bulma-templates
  • buttons - https://github.com/aldi/bulma-social
• chart options - https://www.monterail.com/blog/javascript-libraries-data-visualization
• alt reactive tables
  • grid.js - seems to mildly inactive, simpler functionality
  • tanstack - docs are not helpful if not using framework
  • glide - requires react
  • ag-grid - requires money
• htmx
  • https://blog.ohheybrian.com/2023/06/smarter-templating-with-htmx-and-flask/
  • https://www.advantch.com/blog/how-to-build-interactive-charts-in-python-using-htmx-and-echarts/
  • https://github.com/Konfuzian/htmx-examples-with-flask
• js
  • https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules

todo

• more frontend via htmx https://htmx.org/docs/
• customise bulma via https://bulma.io/documentation/customize/
• worker processes? via ?
• optimised ci via mergify
• https://unsuckjs.com/
• plugin lines disappear (probably because afterevent is drawn before rendering);