DRY Foundation

Tools and components for building customized and consistent small-scale Flask applications.

Why DRY?

Don't Repeat Yourself. Why write and maintain multiple copies of application infrastructure if it's going to be used and reused?

This package is designed to be a lightweight foundation a Flask application: it performs some of the database setup operations, coordinates database management for robust test suites, and also provides some utilities for enforcing authorization criteria for database access, among other things.

Here are some of the features explained in greater detail.

Application Factories and Command Line Interfaces

The Flask command line interface (CLI) provides a lot of functionality via its Click backend. However, users (e.g., me) may wish to launch an application from the command line depending on a certain configuration. The Flask documentation shows an example of how to structure an application to leverage multiple configurations via objects, but leaves it up to a user to implement the mechanics of passing this configuration to the application via environment variable or some other script.

This package takes a different approach, and provides tools to customize the CLI so that configurations can be loaded dynamically at runtime. Configurations are predefined (for production, development, and testing), and can be loaded by specifying a launch mode:

• Production Mode: Launch an app for production use, drawing from a production-style configuration.
• Local Mode: Launch an app for local use, using the Flask development server but still relying on a production-style configuration.
• Development Mode: Launch an app for development, with default debugging features and using a development style configuration.

A testing configuration is also built-in to provide test-specific configuration settings.

Database Setup

One element of an application foundation is the testing infrastructure. Flask gives some guidance in the current edition of their documentation, and it suggests creating a temporary SQLite database for each test. This is perfectly fine for simple applications, but adds substantial overhead (and test time) to applications with many tests, especially for those where the database contains some preloaded information. Instead, it would be preferable to create and use one temporary database instance for the majority of tests that only require read-access to the database, and then only create additional test databases for the tests that modify the state of the database (e.g., SQLAlchemy transactions).¹

DRY Foundation provides the infrastructure to create databases in both of these cases: a "persistent" database for read-only tests, and "ephemeral" databases for each transaction). The persistent test database is used by default, but a transaction_lifetime decorator can be used to indicate that a given test should use an ephemeral copy.

Repositories and Authorization

The common operations are easy to do using SQLAlchemy, but rather than rolling new functions for each new query in every application, this tool provides a set of repositories that are designed to abstract away a bunch of the tedious details. Also, my experience is that enforcing authorization constraints when manipulating sophisticated table relationships can be tricky, and so this tool and its repositories provide an interface for managing those authorizations consistently.

Installation

DRY Foundation is registered on the Python Package Index (PyPI) for easy installation. To install the package, simply run

pip install dry-foundation

The package requires a recent version of Python (3.10+).

Development dependencies include uv and just.

Usage

The app has lots of tools, but the basics can be used just as drop-in replacements for the standard Flask object and application factory.

# DRY Application:  `dry_application/__init__.py`

from dry_foundation import DryFlask, Factory

@Factory
def create_app(config=None):
    app = DryFlask(__name__, app_name="DRY Application")
    app.configure(config)
    # Anything else performed by the application factory...
    return app

For a more complete, up-to-date API reference, build and read the docs:

# Using `just`: https://just.systems/
just docs
# open `docs/build/html/index.html` in your browser

License

This project is licensed under the GNU General Public License, Version 3. It is fully open-source, and while you are more than welcome to fork, add, modify, etc. it is required that you keep any distributed changes and additions open-source.

Changes

Changes between versions are tracked in the changelog.