0
# Flask-AppBuilder
1

2
A rapid application development framework built on top of Flask that provides a comprehensive set of tools for building database-driven web applications with authentication, authorization, forms, charts, and REST APIs. Flask-AppBuilder enables developers to quickly create sophisticated web applications with minimal code by providing pre-built components for common web application patterns.
3

4
## Package Information
5

6
- **Package Name**: flask-appbuilder
7
- **Version**: 4.8.1
8
- **Language**: Python
9
- **Installation**: `pip install Flask-AppBuilder`
10
- **Dependencies**: Flask, SQLAlchemy, WTForms, Marshmallow, PyJWT
11

12
## Core Imports
13

14
```python
15
from flask_appbuilder import AppBuilder
16
```
17

18
Common imports for building applications:
19

20
```python
21
from flask_appbuilder import (
22
    AppBuilder, BaseView, ModelView, IndexView,
23
    Model, SQLA, expose, has_access, action
24
)
25
```
26

27
API-focused imports:
28

29
```python
30
from flask_appbuilder.api import ModelRestApi, expose as api_expose
31
from flask_appbuilder.security.decorators import protect
32
```
33

34
## Basic Usage
35

36
### Simple Application Setup
37

38
```python
39
from flask import Flask
40
from flask_appbuilder import AppBuilder, SQLA
41
from flask_appbuilder.models.sqla import Model
42
from sqlalchemy import Column, Integer, String
43

44
# Initialize Flask app and database
45
app = Flask(__name__)
46
app.config['SECRET_KEY'] = 'your-secret-key'
47
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db'
48

49
db = SQLA(app)
50

51
# Create a simple model
52
class Person(Model):
53
    id = Column(Integer, primary_key=True)
54
    name = Column(String(150), unique=True, nullable=False)
55
    email = Column(String(120), unique=True, nullable=False)
56
    
57
    def __repr__(self):
58
        return self.name
59

60
# Initialize AppBuilder
61
appbuilder = AppBuilder(app, db.session)
62

63
# Create database tables
64
db.create_all()
65

66
if __name__ == '__main__':
67
    app.run(debug=True)
68
```
69

70
### Adding CRUD Views
71

72
```python
73
from flask_appbuilder import ModelView
74
from flask_appbuilder.models.sqla.interface import SQLAInterface
75

76
class PersonModelView(ModelView):
77
    datamodel = SQLAInterface(Person)
78
    list_columns = ['name', 'email']
79

80
# Register view with AppBuilder
81
appbuilder.add_view(
82
    PersonModelView,
83
    "List Persons",
84
    icon="fa-address-book-o",
85
    category="Contacts",
86
)
87
```
88

89
### Creating REST APIs
90

91
```python
92
from flask_appbuilder.api import ModelRestApi
93

94
class PersonApi(ModelRestApi):
95
    datamodel = SQLAInterface(Person)
96
    list_columns = ['id', 'name', 'email']
97
    show_columns = ['id', 'name', 'email']
98
    add_columns = ['name', 'email']
99
    edit_columns = ['name', 'email']
100

101
# Register API
102
appbuilder.add_api(PersonApi)
103
```
104

105
## Architecture
106

107
Flask-AppBuilder follows a layered architecture that promotes separation of concerns and extensibility:
108

109
### Core Layer
110
- **AppBuilder**: Central application manager that coordinates all components
111
- **BaseView**: Foundation for all views providing routing, templating, and security integration
112
- **Security Manager**: Handles authentication, authorization, and user management
113

114
### Data Layer  
115
- **Model**: SQLAlchemy base model with Flask-AppBuilder enhancements
116
- **SQLA**: Enhanced SQLAlchemy integration with application factory support
117
- **DataModel Interface**: Abstraction layer for different data backends
118

119
### View Layer
120
- **ModelView**: CRUD operations with automatic form generation and validation
121
- **BaseFormView**: Form handling with validation and processing
122
- **Chart Views**: Data visualization with multiple chart types
123

124
### API Layer
125
- **ModelRestApi**: Full REST API with OpenAPI documentation
126
- **BaseApi**: Foundation for custom API endpoints with security integration
127
- **Schema Conversion**: Automatic Marshmallow schema generation from models
128

129
### Security Layer
130
- **Authentication**: Multiple authentication backends (DB, LDAP, OAuth, OpenID)
131
- **Authorization**: Role-based permissions with fine-grained access control  
132
- **Decorators**: Security enforcement for views and API endpoints
133

134
This architecture enables rapid development while maintaining flexibility for customization and extension.
135

136
## Capabilities
137

138
### Core Framework
139

140
Foundation classes and application management including AppBuilder initialization, view registration, security setup, and application lifecycle management.
141

142
```python { .api }
143
class AppBuilder:
144
    def __init__(app, session, menu=None, indexview=None): ...
145
    def add_view(baseview, name, href="", icon="", label="", category=""): ...
146
    def add_api(baseview): ...
147
    def init_app(app, session): ...
148

149
class BaseView:
150
    def render_template(template, **kwargs): ...
151
    def create_blueprint(appbuilder, endpoint=None, static_folder=None): ...
152
```
153

154
[Core Framework](./core-framework.md)
155

156
### Security System
157

158
Authentication, authorization, and security decorators providing user management, role-based permissions, and access control for views and APIs.
159

160
```python { .api }
161
@has_access
162
def secure_method(self): ...
163

164
@protect(allow_browser_login=False) 
165
def api_method(self): ...
166

167
@permission_name("custom_permission")
168
def method_with_custom_permission(self): ...
169
```
170

171
[Security System](./security.md)
172

173
### REST API System
174

175
Complete REST API framework with automatic CRUD operations, OpenAPI documentation, schema generation, and JSON serialization.
176

177
```python { .api }
178
class ModelRestApi(BaseModelApi):
179
    def get_list(**kwargs): ...
180
    def get(pk, **kwargs): ...  
181
    def post(): ...
182
    def put(pk): ...
183
    def delete(pk): ...
184
    def info(**kwargs): ...
185
```
186

187
[REST API System](./rest-api.md)
188

189
### Database Models and Interfaces
190

191
SQLAlchemy integration with enhanced models, database interfaces, and application factory support for flexible database management.
192

193
```python { .api }
194
class Model:
195
    def to_json(): ...
196
    
197
class SQLA(SQLAlchemy):
198
    def create_session(options): ...
199
    def make_declarative_base(model, metadata): ...
200
```
201

202
[Database Models](./database-models.md)
203

204
### Views and CRUD Operations  
205

206
Model views with automatic CRUD operations, form generation, validation, pagination, searching, and filtering capabilities.
207

208
```python { .api }
209
class ModelView(BaseCRUDView):
210
    datamodel = SQLAInterface(Model)
211
    list_columns = ['field1', 'field2']
212
    show_columns = ['field1', 'field2', 'field3'] 
213
    add_columns = ['field1', 'field2']
214
    edit_columns = ['field1', 'field2']
215
```
216

217
[Views and CRUD](./views-crud.md)
218

219
### Forms and Field Widgets
220

221
Custom form fields, widgets, and form handling including AJAX select fields, query fields, and specialized input widgets.
222

223
```python { .api }
224
class AJAXSelectField(Field): ...
225
class QuerySelectField(SelectFieldBase): ...
226
class FormWidget(RenderTemplateWidget): ...
227
```
228

229
[Forms and Fields](./forms-fields.md)
230

231
### Charts and Visualizations
232

233
Data visualization with chart views supporting pie charts, bar charts, line charts, and custom aggregation functions.
234

235
```python { .api }
236
class GroupByChartView(BaseChartView):
237
    chart_type = "ColumnChart"
238
    group_bys = ['field']
239
    
240
@aggregate(label="Total")
241
def aggregate_sum(items, col): ...
242
```
243

244
[Charts and Visualizations](./charts.md)
245

246
### CLI Tools and Commands
247

248
Command-line interface for user management, database operations, security management, and application maintenance.
249

250
```python { .api }
251
# Flask CLI commands
252
flask fab create-admin
253
flask fab create-user  
254
flask fab reset-password
255
flask fab create-db
256
flask fab list-users
257
```
258

259
[CLI Tools](./cli-tools.md)
260

261
### Actions and Lifecycle Hooks
262

263
Action decorators for bulk operations and lifecycle hooks for customizing create, update, and delete operations.
264

265
```python { .api }
266
@action("approve", "Approve", "Approve selected items?", "fa-check")
267
def approve_action(self, items): ...
268

269
def pre_add(self, item): ...
270
def post_update(self, item): ...
271
```
272

273
[Actions and Hooks](./actions-hooks.md)
274

275
### Constants and Exception Handling
276

277
Framework constants, authentication types, API configuration, and comprehensive exception classes for error handling.
278

279
```python { .api }
280
# Authentication constants
281
AUTH_DB = 1
282
AUTH_LDAP = 2  
283
AUTH_OAUTH = 4
284

285
# Exception classes
286
class FABException(Exception): ...
287
class InvalidLoginAttempt(FABException): ...
288
```
289

290
[Constants and Exceptions](./constants-exceptions.md)