tobi-de/falco

Enhance your Django developer experience: CLI and Guides for the Modern Django Developer.

Falco

An opinionated toolkit for a modern Django development experience

Warning

The falco CLI isn't stable at the moment; stability is expected with the 1.0.0 release. I'm still making numerous changes quite frequently. If you're currently using it, remember to run pip install --upgrade falco-cli from time to time.

Falco is a Django-centric toolkit designed to enhance the development experience. The CLI offers commands for initiating new projects, generating simple CRUD views for rapid prototyping, and more. Additionally, it provides a collection of guides to address common issues in web development specifically tailored to Django.

The CLI

This is a set of commands to help you throughout the lifecycle of your django project development, from bootstrapping a new project using modern tools like htmx, hatch, tailwindcss, to generating CRUD views for your models and a few utilities that might help during deployment.

For a brief introduction to the user experience of the CLI, visit this page.

pip install falco-cli

• start-project: Initialize a new django project the falco way.
• start-app: Initialize a new django app the falco way.
• crud: Generate CRUD (Create, Read, Update, Delete) views for a model.
• install-crud-utils: Install utils necessary for CRUD views.
• work: Run all the services required to run your django project in parallel with a single command. (development only)
• htmx: Download a local copy of the latest version of htmx.
• htmx-ext: Download one of htmx extensions.
• sync-dotenv: Synchronize the .env file with the .env.template file.
• rm-migrations: Remove all migrations for the specified applications directory. (development only)
• reset-migrations: Delete and recreate all migrations. (development only)

Templates

• tailwind (default)
• bootstrap
• pico

The guides

Note

These are currently a work in progress. Most of them are half-written or not written at all. I hope to get them in a usable state by the end of january 2024 as soon as I can. To receive updates subscribe to this discussion or follow me on x or mastodon

If you don't find any use of the CLI, I hope you will in these guides. This is a collection of guides that address common issues in web development, specifically tailored to Django. Each guide provides solutions, patterns, and approaches that are relevant to Django projects. It is similar to the Django topic guides, but instead of focusing on components of the framework like forms, models, views, etc., it focuses on more general topics like task queues, deployment, realtime, etc.

• Interactive user interfaces
• Task Queues and Schedulers
• Writing documentation
• Writing tests
• Logging and monitoring
• The ultimate deployment guide
• Optimizing Database Access
• Business logic in django
• Dynamic Model Schema
• Realtime in Django: Websockets, SSE, Polling
• Permissions and authorizations
• Database Tips: Backup, Scaling, Triggers, and More
• Managing Multi-tenancy in Django
• Async Coding in Django
• Use Sqlite in production
• Running your project in a single container
• Tips and extra

Acknowledgements

Falco is inspired by (and borrows elements from) some excellent open source projects:

• cookiecutter-django
• fuzzy-couscous (predecessor of falco)
• django-hatch-startproject
• django-unicorn (Inspiration for the logo)
• neapolitan
• django-base-site
• django-twc-project

Contributors

Thanks to the following wonderful people emoji key who have helped build falco.

Tobi DEGNON 💻 📖 ⚠️

Muhammad Hammad 🤔

mathiasag7 💻

Richard Shea 📖

Waqar Khan 💻

tissieres 💵

Hsiaoming Yang 🐛

falco's Issues

easy access to the kill command

an option for the work command or a hatch script

lsof -i :8000 -sTCP:LISTEN -t | xargs -t kill

broken ci github workflow for generated project

Originally posted by @786raees in #17 (comment)

Git checks for crud and rm-migrations

these command might have destructive actions on a project, we should probably chech first if a git repo exists and is in a clean state before running these, and there might be a --force option to override this behaviour

crud - use the model verbose name for h1 in the html files

install-crud-utils should make the core folder a package if it does not exists

the start-project template no longer comes with the core app

hatch run lint scripts are painfully slow

proper logging setup for generated projects

media nginx setup

Add this somewhere in docs https://gist.github.com/Tobi-De/7751c394570cbf0d7beb852304394046

automate blueprints from demo

This is just to simplify dev experience, changes would be done only in the demo project, and there would be a command that take the files from the demo project and update the blueprints

Command to generate tests

I was thinkings of somethings similar to crud, that would generate test_views.py, test_models.pyansd test_formsfiles for a specific model

setup docs for starter project

The starter project should comes with a similar docs setup as the falco docs, sphinx + shibuya or maybe this might be a command ?

On a host without git installed falco won't even run

This is happening because falco depends on cruft and cruft depends on gitpython which fails to initialize when git is not installed

delete modal for crud views

The current delete button generated with crud command use the default browser confirm, but it might be a good idea to use the native modal for a custom UI

• https://htmx.org/examples/confirm/
• https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog

missing comma after running start-app

when start-app is launched at least twice, the INSTALLED_APPS becomes non-functional due to a missing comma between registered applications.

crud - better list objects variable name

use the app_name for the list objects variable name when the entry-point value is set, for example if the app_name is categories, and crud is generated using the entry-point option, use the app_name categories instead of doing categorys for the list object variables

on that note, plural for words ending with y should be easy to guess, implement that.

interactive mode for crud

Reading this mastodon thread https://fosstodon.org/@paulox/111783847246554164 gave me an idea
An interactive --interactive mode for the crud command, the current idea is to have the crud command able to generate an application when it doesn't exist and add a model from the CLI, but adding all these options to the command directly could result in too many options, so they could all be available in the experimental interactive mode.
basic workflow idea:

1. falco crud books.model --interactive
2. create the books app and add it to INSTALLED_APPS if it does not exists
3. ask for the Book model fields in CLI and add to model the the models.py file
4. Generate migrations
5. generate crud views for the model
6. register the urls in the root url config

crud default exclude list

Add a crud config for excluded_fields, by default generated project with the modified field excluded

crud: add colored checkedbox for boolean fields in table

hatch2venv

python -m venv --prompt . --upgrade-deps .venv
.venv/bin/python -m pip install pip-tools poethepoet

remove everything hatch related
replace hatch scripts with poethepoet tasks

run reorder-python-imports as a python formatter

This will help having crud generated files passing pre-commit hooks

work command should open the browser by default, can be disabled

crud: add clickable links for image or file fields in table

for htmx decorator

something similar to https://github.com/spookylukey/django-htmx-patterns/blob/master/code/htmx_patterns/utils.py#L27

Add an options to use django-tables

https://github.com/jieter/django-tables2

Add via crud configuration an option to use django_tables2

[tool.falco.crud]
use-django-tables2 = true

Proposal: Integrating Command Aliases for Ease of Use

Hello,

I hope you are doing well. This project is really cool and I appreciate your work. I'm looking forward to it being stable. I wanted to ask if you could consider adding aliases for the commands?

Thank you in advance.

crud option --filter to generate django-filter filters

On every start-project check for new a version of falco

better html templates

decent html templates with styling, override and improve django-allauth pages, similar to what cookiecutter django does

• home page : similar to landing pages, very basic with project name, login, logout buttons
• login
• logout
• password reset flow
• email verification flow
• basic profile page ?

better default for sync-dotenv

export DJANGO_DEBUG=True && falco sync-dotenv

or

falco sync-dotenv --prod

The idea to have better default based on if local or prod setup

try to download the latest version of htmx during startproject

The starter project comes with an htmx js file already. The idea is, after initializing the project, try to download and install the latest version using falco htmx. This way, in case there is a new version, the user always starts with the latest htmx version. This step is optional, so it should fails silently in case of a network error, for example.

some commands to help with deployment ?

I was thinking of something that would forexample, update nginx configuration, maybe get certificates ? do some basic env setup for production, but would that be even necessary ? there is so much potential points of failure with this process, and there is other tools that aleady to this better than anything I could come up with, docker, ansible, etc..

crud: better table ux

• https://www.uxpin.com/studio/blog/table-ux/
• https://uxplanet.org/tables-that-arent-boring-a-guide-to-creating-visually-appealing-and-informative-data-tables-e20e885dd3cf
• https://pencilandpaper.io/articles/ux-pattern-analysis-enterprise-data-tables/

the first columns should also serve as a link to details
toolbars overs the table for seach add button, filtering
center paginations numbers and put next and previous at each extreme
backgrount color when hovering over a row
background color to distinguish header from rows

Left align numbers (IntegerField and all its variable)

Better DX for CRUD html templates

The CRUD html templates are currently painful to write, I think I'll have to move to something like cookiecutter or copier to make things simpler.

media s3 config

https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html

# django-storages[s3]

STORAGES = {
    "default": {
        "BACKEND": "storages.backends.s3.S3Storage",
        "OPTIONS": {
            "location": "media",
            "file_overwrite": False,
        },
    },
 }
aws_s3_domain = AWS_S3_CUSTOM_DOMAIN or f"{AWS_STORAGE_BUCKET_NAME}.s3.amazonaws.com"
MEDIA_URL = f"https://{aws_s3_domain}/media/"

Guides ideas

• Charting with django
• Social auth
• Guides

track if crud utils are installed via the tool.falco section

Running the crud command before the install-crud-utils can lead to some issues, e.g the admin code failing to be generated.
Maybe it's a good idea to track is the crud utils are installed and then suggest to auto install them whenever crud is run

base project should pass the pyright tests

A fresh project generated with start-project should pass all pyright tests

Exclude fields option for crud

The reasonning is simple, by default all fields are showed in the table and include in the form, but that rarely the case for real word model, so an option to exclude a set of fields make sense

rm-migrations try to guess the apps_dir

got a free vps to play with

sync-dotenv remove comments and spacing in the file

Add functionality to specify a custom directory for project creation

Feature Request

Is your feature request related to a problem? Please describe.
Currently, the falco CLI tool for Django project management does not allow users to specify a custom directory when creating a new project. This limitation requires users to manually move the project or rearrange their workspace after creation, which can be cumbersome.

Describe the solution you'd like
I propose adding a new option to the project creation command, --directory (or -d for short), which allows users to define a custom directory path where the new project will be initialized. This feature would enhance usability and flexibility, aligning with common practices in other project management tools.

For example:

falco start-project myproject --directory /path/to/custom/directory

Describe alternatives you've considered
An alternative is to manually move the project files after creation, but this approach is not as seamless and can introduce unnecessary steps for the user.

Additional context
Allowing users to specify the project's directory makes it easier to integrate with various development workflows and project structures. It also adds convenience for users who prefer to organize their projects in specific ways from the outset.

I believe this feature would be a valuable addition to the falco, and I am willing to contribute to its implementation.

Thank you for considering this enhancement.

better settings organization

orders settings alphabetically grouping them

django core settings
third party settings
user custom settings

add comments with links to associated documentation, I previously removed this, that was a dumb idea

option for sync-dotenv to print the content of the .env file

something like

falco sync-dotenv  -p

this, will print the content of the .env file so that it can be piped into another program, ex:

falco sync-dotenv -p | clipcopy

use case: easy copy into caprover

the work command need to be in the project virtualenv to run

advance starter - shipfaster

I want another version of the starter project, a more advanced version something similar to:

• https://www.forgepackages.com/pro/
• https://www.saaspegasus.com/
• https://shipfa.st/

The idea is to ship and build faster, for now I've settled on falco shipfaster. I'm not sure if this will be an entirely new project blueprint or it will just update an existing project created with falco start-project.

But for now this is what I"m planning to include:

• payment ( lemon squeezy)
• caching with redis
• sqlite for production using litestream for backup
• everything in one container (s6 overlay)
• a landing page with pricing section
• a basic admin like interface for logged in users (profile, login, logout, change, password, change email, dashbaord etc..)
• templates for login (with google enabled ? , github ???) and signup page
• email setup (I often use AWS SES but maybe a simpler alternative, sendgrid, mailgun?)
• background tasks with django-q2
• django storages setup with AWS S3 for Media files

additional ideas:

• optional postgres setup with pghoard for backup
• daphne for async and realtime
• Internationalization (french and english by default)
• wagtail integration for CMS
• features flags
• something with user impersonation
• a basic ecommerce store (maybe with https://github.com/dinoperovic/django-salesman)
• a basic blog

add instructions on the docs for each components and how to swap them

Shipfaster will have it owns section on the docs and gallery

move the makemigrations commands to falco-cli

less code in the project blueprint

New command reset-migrations

I think I've come across a potential addition: a new command, falco reset-migrations.

1. Firstly, it run falco rm-migrations.

2. Then, it clears your Django migrations table:

   from django.db import connection
   
   with connection.cursor() as cursor:
       cursor.execute("DELETE FROM django_migrations")

3. and python manage.py makemigrations

4. Lastly, it executes python manage.py migrate --fake to ensure the new migrations are added to the migrations table as if they were already applied

This approach allows you to retain your data while achieving a clean slate for migrations. What are your thoughts on this @hammadarshad1 ?

Originally posted by @Tobi-De in #12 (comment)

update command to keep generated project in sync with falco

more flexible crud via configuration

I will make some options of crud configurable via the pyproject.toml file

crud_login: it is quite common to have most of the views decorated with the login_required decorated, so this could be configure via the pyproject.toml file to be always true without having the specify the --login option

crud_blueprint: for the html blueprint if the user has some custom one or is using https://github.com/falco-blueprints/falco_blueprint_basic_bootstrap, he won't have to type the path every time

migrate: I'm not sure how to call this yet, but basically tell the crud command will always run makemigrations and migrate first, only configurable via pyproject

skip-git-check: for people who like to live dangerously

filters: always generate filters code, see #54