Welcome to Citus

Welcome to Citus’s documentation. Get started with Installation and then get an overview with the Quickstart. There is also a more detailed Tutorial that shows how to create a small but complete application with Citus. Common patterns are described in the Patterns for Flask section. The rest of the docs describe each component of Citus in detail, with a full reference in the API section.

Citus depends on the Jinja template engine and the Werkzeug WSGI toolkit. The documentation for these libraries can be found at:

• Jinja documentation

• Werkzeug documentation

User’s Guide

This part of the documentation, which is mostly prose, begins with some background information about Citus, then focuses on step-by-step instructions for web development with Citus.

• Foreword
  • What does “micro” mean?
  • Configuration and Conventions
  • Growing with Flask
• Foreword for Experienced Programmers
  • Thread-Locals in Citus
  • Develop for the Web with Caution
• Installation
  • Python Version
  • Dependencies
  • Virtual environments
  • Install Citus
• Quickstart
  • A Minimal Application
  • What to do if the Server does not Start
  • Debug Mode
  • HTML Escaping
  • Routing
  • Static Files
  • Rendering Templates
  • Accessing Request Data
  • Redirects and Errors
  • About Responses
  • Sessions
  • Message Flashing
  • Logging
  • Hooking in WSGI Middleware
  • Using Citus Extensions
  • Deploying to a Web Server
• Tutorial
  • Project Layout
  • Application Setup
  • Define and Access the Database
  • Blueprints and Views
  • Templates
  • Static Files
  • Blog Blueprint
  • Make the Project Installable
  • Test Coverage
  • Deploy to Production
  • Keep Developing!
• Templates
  • Jinja Setup
  • Standard Context
  • Controlling Autoescaping
  • Registering Filters
  • Context Processors
• Testing Flask Applications
  • The Application
  • The Testing Skeleton
  • The First Test
  • Logging In and Out
  • Test Adding Messages
  • Other Testing Tricks
  • Faking Resources and Context
  • Keeping the Context Around
  • Accessing and Modifying Sessions
  • Testing JSON APIs
  • Testing CLI Commands
• Handling Application Errors
  • Error Logging Tools
  • Error Handlers
  • Custom Error Pages
  • Blueprint Error Handlers
  • Returning API Errors as JSON
  • Logging
  • Debugging
• Debugging Application Errors
  • In Production
  • The Built-In Debugger
  • External Debuggers
• Logging
  • Basic Configuration
  • Email Errors to Admins
  • Injecting Request Information
  • Other Libraries
• Configuration Handling
  • Configuration Basics
  • Environment and Debug Features
  • Builtin Configuration Values
  • Configuring from Python Files
  • Configuring from Data Files
  • Configuring from Environment Variables
  • Configuration Best Practices
  • Development / Production
  • Instance Folders
• Signals
  • Subscribing to Signals
  • Creating Signals
  • Sending Signals
  • Signals and Citus’ Request Context
  • Decorator Based Signal Subscriptions
  • Core Signals
• Pluggable Views
  • Basic Principle
  • Method Hints
  • Method Based Dispatching
  • Decorating Views
  • Method Views for APIs
• The Application Context
  • Purpose of the Context
  • Lifetime of the Context
  • Manually Push a Context
  • Storing Data
  • Events and Signals
• The Request Context
  • Purpose of the Context
  • Lifetime of the Context
  • Manually Push a Context
  • How the Context Works
  • Callbacks and Errors
  • Context Preservation on Error
  • Notes On Proxies
• Modular Applications with Blueprints
  • Why Blueprints?
  • The Concept of Blueprints
  • My First Blueprint
  • Registering Blueprints
  • Nesting Blueprints
  • Blueprint Resources
  • Building URLs
  • Blueprint Error Handlers
• Extensions
  • Finding Extensions
  • Using Extensions
  • Building Extensions
• Command Line Interface
  • Application Discovery
  • Run the Development Server
  • Open a Shell
  • Environments
  • Debug Mode
  • Environment Variables From dotenv
  • Environment Variables From virtualenv
  • Custom Commands
  • Plugins
  • Custom Scripts
  • PyCharm Integration
• Development Server
  • Command Line
  • In Code
• Working with the Shell
  • Command Line Interface
  • Creating a Request Context
  • Firing Before/After Request
  • Further Improving the Shell Experience
• Patterns for Flask
  • Large Applications as Packages
  • Application Factories
  • Application Dispatching
  • Using URL Processors
  • Deploying with Setuptools
  • Deploying with Fabric
  • Using SQLite 3 with Flask
  • SQLAlchemy in Flask
  • Uploading Files
  • Caching
  • View Decorators
  • Form Validation with WTForms
  • Template Inheritance
  • Message Flashing
  • AJAX with jQuery
  • Lazily Loading Views
  • MongoDB with MongoEngine
  • Adding a favicon
  • Streaming Contents
  • Deferred Request Callbacks
  • Adding HTTP Method Overrides
  • Request Content Checksums
  • Celery Background Tasks
  • Subclassing Flask
  • Single-Page Applications
• Deployment Options
  • Hosted options
  • Self-hosted options
• Becoming Big
  • Read the Source.
  • Hook. Extend.
  • Subclass.
  • Wrap with middleware.
  • Fork.
  • Scale like a pro.
  • Discuss with the community.
• Using async and await
  • Performance
  • Background tasks
  • When to use Quart instead
  • Extensions
  • Other event loops

API Reference

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

• API
  • Application Object
  • Blueprint Objects
  • Incoming Request Data
  • Response Objects
  • Sessions
  • Session Interface
  • Test Client
  • Test CLI Runner
  • Application Globals
  • Useful Functions and Classes
  • Message Flashing
  • JSON Support
  • Template Rendering
  • Configuration
  • Stream Helpers
  • Useful Internals
  • Signals
  • Class-Based Views
  • URL Route Registrations
  • View Function Options
  • Command Line Interface

Additional Notes

Design notes, legal information and changelog are here for the interested.

• Design Decisions in Flask
  • The Explicit Application Object
  • The Routing System
  • One Template Engine
  • Micro with Dependencies
  • Thread Locals
  • Async/await and ASGI support
  • What Flask is, What Flask is Not
• HTML/XHTML FAQ
  • History of XHTML
  • History of HTML5
  • HTML versus XHTML
  • What does “strict” mean?
  • New technologies in HTML5
  • What should be used?
• Security Considerations
  • Cross-Site Scripting (XSS)
  • Cross-Site Request Forgery (CSRF)
  • JSON Security
  • Security Headers
  • Copy/Paste to Terminal
• Flask Extension Development
  • Anatomy of an Extension
  • “Hello Flaskext!”
  • Initializing Extensions
  • The Extension Code
  • Using _app_ctx_stack
  • Learn from Others
  • Approved Extensions
• License
  • BSD-3-Clause Source License
  • Artwork License
• Changes