Armin Ronacher Style Guide⁠‍⁠​‌​‌​​‌‌‍​‌​​‌​‌‌‍​​‌‌​​​‌‍​‌​​‌‌​​‍​​​​​​​‌‍‌​​‌‌​‌​‍‌​​​​​​​‍‌‌​​‌‌‌‌‍‌‌​​​‌​​‍‌‌‌‌‌‌​‌‍‌‌​‌​​​​‍​‌​‌‌‌‌‌‍​‌​​‌​‌‌‍​‌‌​‌​​‌‍‌​‌​‌‌‌​‍​​‌​‌​​​‍‌‌‌​‌​‌‌‍​​​‌‌​​​‍​‌​‌‌​‌‌‍​‌​‌​​‌​‍‌‌​​​‌​‌‍​​​​‌​​‌‍‌‌‌‌​‌​​⁠‍⁠

Overview

Armin Ronacher created Flask, Jinja2, Click, Werkzeug, and many other foundational Python libraries. His approach: pragmatic minimalism, explicit behavior, and composable design. Flask's success proves that "micro" can be mighty.

Core Philosophy

"Explicit is better than implicit."

"Simple things should be simple, complex things should be possible."

"We're all consenting adults here."

Ronacher believes in trusting developers with power and flexibility, while providing sensible defaults and clear documentation.

Design Principles

Explicit Over Implicit: Never do magic behind the scenes. Make behavior visible.

Composable Over Monolithic: Small, focused components that work together.

Configuration Over Convention: Don't hide configuration in naming conventions.

Extension Points: Design for extensibility from day one.

When Writing Code

Always

• Use explicit imports, never implicit * imports

• Make dependencies obvious and injectable

• Provide hooks for customization

• Document extension points clearly

• Use context locals sparingly and explicitly

• Prefer composition over inheritance

Never

• Modify global state silently

• Use metaclass magic without clear benefit

• Hide functionality in init.py imports

• Create deep inheritance hierarchies

• Make assumptions about the user's environment

Prefer

• Factory functions over global instances

• Dependency injection over singletons

• Decorators for cross-cutting concerns

• Context managers for resource management

• Plain functions over classes when state isn't needed

Code Patterns

The Application Factory Pattern

BAD: Global application state

from flask import Flask app = Flask(name) app.config['DEBUG'] = True

Impossible to test, configure differently, or run multiple instances

GOOD: Application factory (Flask pattern)

def create_app(config=None): app = Flask(name)

# Default configuration
app.config.from_object('myapp.default_config')

# Override with instance config
app.config.from_pyfile('config.py', silent=True)

# Override with passed config
if config:
    app.config.update(config)

# Register blueprints
from myapp.views import main_bp
app.register_blueprint(main_bp)

# Initialize extensions
db.init_app(app)

return app

Testing is now easy

def test_something(): app = create_app({'TESTING': True}) with app.test_client() as client: response = client.get('/') assert response.status_code == 200

Explicit Extension Pattern

Flask extension pattern: explicit initialization

class Database: def init(self, app=None): self._app = app if app is not None: self.init_app(app)

def init_app(self, app):
    # Store config, set up teardown, etc.
    app.config.setdefault('DATABASE_URI', 'sqlite:///:memory:')
    app.teardown_appcontext(self._teardown)
    
    # Store self on app for retrieval
    if not hasattr(app, 'extensions'):
        app.extensions = {}
    app.extensions['database'] = self

def _teardown(self, exception):
    # Clean up resources
    pass

def get_connection(self):
    # Get connection for current app context
    return self._get_connection_for_app(current_app._get_current_object())

Usage:

db = Database()

def create_app(): app = Flask(name) db.init_app(app) # Explicit initialization return app

Decorator-Based Configuration

Click-style command decoration

import click

@click.command() @click.option('--name', default='World', help='Name to greet') @click.option('--count', default=1, type=int, help='Number of greetings') @click.option('--verbose', '-v', is_flag=True, help='Enable verbose mode') def hello(name, count, verbose): """Simple program that greets NAME for COUNT times.""" for _ in range(count): if verbose: click.echo(f'Verbose: About to greet {name}') click.echo(f'Hello, {name}!')

Benefits:

- Self-documenting

- Type conversion built-in

- Help text from decorators

- Testable without subprocess

Context-Local Pattern (Use Sparingly)

from werkzeug.local import LocalStack, LocalProxy

Context stack for request-like objects

_request_ctx_stack = LocalStack()

def get_current_request(): ctx = _request_ctx_stack.top if ctx is None: raise RuntimeError('No request context') return ctx.request

Proxy that always points to current request

current_request = LocalProxy(get_current_request)

class RequestContext: def init(self, app, request): self.app = app self.request = request

def push(self):
    _request_ctx_stack.push(self)

def pop(self):
    _request_ctx_stack.pop()

def __enter__(self):
    self.push()
    return self

def __exit__(self, *args):
    self.pop()

Explicit context management

with RequestContext(app, request): # current_request is now available print(current_request.method)

Composable Middleware/Decorators

Composable decorators for routes

from functools import wraps

def require_auth(f): @wraps(f) def decorated(*args, **kwargs): if not current_user.is_authenticated: return redirect(url_for('login')) return f(*args, **kwargs) return decorated

def require_role(role): def decorator(f): @wraps(f) def decorated(*args, **kwargs): if role not in current_user.roles: abort(403) return f(*args, **kwargs) return decorated return decorator

def cached(timeout=300): def decorator(f): @wraps(f) def decorated(*args, **kwargs): key = f'{f.name}:{args}:{kwargs}' result = cache.get(key) if result is None: result = f(*args, **kwargs) cache.set(key, result, timeout=timeout) return result return decorated return decorator

Compose them explicitly

@app.route('/admin/users') @require_auth @require_role('admin') @cached(timeout=60) def admin_users(): return get_all_users()

Jinja2-Style Template Inheritance

Explicit template inheritance

base.html

""" <!DOCTYPE html> <html> <head> <title>{% block title %}Default Title{% endblock %}</title> </head> <body> {% block content %}{% endblock %} </body> </html> """

child.html

""" {% extends "base.html" %}

{% block title %}My Page{% endblock %}

{% block content %} <h1>Hello, World!</h1> {% endblock %} """

Benefits:

- Explicit extension declaration

- Clear block boundaries

- No magic filename conventions

Mental Model

Ronacher designs systems by asking:

• What's the minimal core? Start with the smallest useful thing.

• Where are the extension points? Design for customization from the start.

• Is behavior explicit? Can a reader understand what's happening?

• Are components composable? Can pieces be used independently?

The Flask Philosophy

• One way to do configuration: Use app.config

• One way to register routes: Use decorators or add_url_rule

• One way to handle requests: The WSGI interface

• Many ways to extend: Blueprints, extensions, middleware

This isn't limiting—it's clarifying.