시작하기
첫 애플리케이션
Flask는 마이크로프레임워크입니다 — 필수만 제공하고 필요한 것은 직접 더합니다. debug=True는 자동 리로드와 상세 에러 페이지를 활성화합니다.
# install Flask
pip install flask
# app.py
from flask import Flask, render_template
app = Flask(__name__)
@app.route("/")
def home():
return render_template("index.html")
if __name__ == "__main__":
app.run(debug=True)개발 서버 실행
내장 서버를 프로덕션에서 절대 쓰지 마세요. FLASK_APP은 앱 인스턴스가 있는 모듈을 가리킵니다. 네트워크에서 접근 가능하게 하려면 --host=0.0.0.0을 쓰세요.
# Set the entry point and enable debug mode
export FLASK_APP=app.py
export FLASK_ENV=development
flask run
# Override host and port
flask run --host=0.0.0.0 --port=5000
# Or run the module directly
python app.py가상 환경
가상 환경은 프로젝트 의존성을 시스템 Python으로부터 격리합니다. requirements.txt에 정확한 버전을 기록해 두면 다른 사람이 pip install -r requirements.txt로 환경을 재현할 수 있습니다.
# Create an isolated environment
python -m venv venv
# Activate (Linux/macOS)
source venv/bin/activate
# Activate (Windows PowerShell)
venv\Scripts\Activate.ps1
# Install dependencies
pip install flask
pip freeze > requirements.txt프로젝트 구조
Flask는 레이아웃을 강제하지 않지만, 정적 파일·템플릿·설정을 분리하는 것이 관례입니다. instance/ 폴더는 버전 관리에 넣지 말아야 할 배포 전용 시크릿을 담습니다.
myapp/
app.py # application factory or instance
config.py # configuration classes
requirements.txt # pinned dependencies
instance/
config.py # secret instance config (not in VCS)
static/ # CSS, JS, images
css/style.css
templates/ # Jinja2 templates
base.html
index.html
models.py # database models
views.py # route handlers애플리케이션 팩토리 패턴
팩토리 패턴은 함수가 호출될 때까지 앱 생성을 미룹니다 — 다중 인스턴스, 테스트, 확장에 필수입니다. Flask의 --app 옵션은 앱을 반환하는 콜러블을 받습니다.
from flask import Flask
def create_app(config_name="default"):
app = Flask(__name__)
app.config.from_object(f"config.{config_name.title()}Config")
from .views import bp as views_bp
app.register_blueprint(views_bp)
@app.route("/health")
def health():
return {"status": "ok"}
return app
# Run with: flask --app myapp create_app run
# or export FLASK_APP=myapp:create_app최소 애플리케이션 해부
__name__을 전달하면 Flask가 정적 파일과 템플릿 위치를 찾습니다. 레이아웃이 기본값과 다르면 생성자 인수로 폴더 위치를 덮어쓸 수 있습니다.
from flask import Flask
app = Flask(
__name__,
static_folder="static",
template_folder="templates",
static_url_path="/static",
)
# __name__ lets Flask locate resources relative to the module.
# Route decorators map URL patterns to view functions.
@app.route("/")
def index():
return "Hello, Flask!"라우팅
변수 규칙
<converter:varname>으로 표시된 부분이 URL 세그먼트를 캡처합니다. 내장 컨버터: string(기본값), int, float, path(슬래시 허용), uuid. 값은 함수 인수로 전달됩니다.
from flask import Flask
app = Flask(__name__)
@app.route("/user/<username>")
def show_user(username):
return f"User: {username}"
@app.route("/post/<int:post_id>")
def show_post(post_id):
return f"Post #{post_id}"
@app.route("/path/<path:subpath>")
def show_path(subpath):
return f"Path: {subpath}"URL 컨버터
컨버터는 URL 변수를 검증하고 캐스팅합니다. 정규식 패턴(예: 제품 코드)을 강제하려면 BaseConverter 서브클래스를 app.url_map.converters에 등록하세요.
@app.route("/item/<int:item_id>")
def item_int(item_id):
return f"Integer ID: {item_id}"
@app.route("/weight/<float:kg>")
def weight(kg):
return f"{kg} kg"
@app.route("/uid/<uuid:token>")
def by_token(token):
return str(token)
# Custom converter
from werkzeug.routing import BaseConverter
class RegexConverter(BaseConverter):
def __init__(self, url_map, *items):
super().__init__(url_map)
self.regex = items[0]
app.url_map.converters["re"] = RegexConverter
@app.route("/code/<re:[a-z]{3}-[0-9]{4}:code>")
def code(code):
return code고유 URL과 리다이렉트
끝 슬래시가 중요합니다. '/'로 끝나는 라우트는 슬래시 없는 형태를 리다이렉트하고, '/' 없는 라우트는 슬래시 붙은 형태에 404를 반환합니다. 라우트마다 하나의 규칙을 정해 일관되게 유지하세요.
@app.route("/projects/")
def projects():
return "Projects page"
# /projects/ -> 200 OK
# /projects -> 301 redirect to /projects/
@app.route("/about")
def about():
return "About page"
# /about -> 200 OK
# /about/ -> 404 Not FoundHTTP 메서드
methods 인수로 여러 동사를 받거나, 단일 메서드 라우트에는 @app.get / @app.post 축약(Flask 2.0+)을 쓰세요. GET이 기본값입니다.
from flask import request, render_template
@app.route("/login", methods=["GET", "POST"])
def login():
if request.method == "POST":
return do_login()
return render_template("login.html")
# Method-specific shortcuts
@app.get("/profile")
def profile_get():
return render_template("profile.html")
@app.post("/profile")
def profile_post():
return update_profile()url_for로 URL 만들기
url_for는 엔드포인트 이름(기본값: 뷰 함수 이름)으로 URL을 생성합니다. URL이 바뀌어도 안전하고, _external=True를 주면 절대 URL을 만듭니다.
from flask import Flask, url_for
app = Flask(__name__)
@app.route("/")
def index():
# builds '/user/alice' instead of hardcoding
return f'<a href="{url_for("show_user", username="alice")}">Alice</a>'
@app.route("/user/<username>")
def show_user(username):
return f"Hello {username}"
with app.test_request_context():
print(url_for("show_user", username="bob")) # /user/bob하나의 뷰에 여러 규칙
add_url_rule은 데코레이터 없이 URL을 등록합니다. 각 규칙에 고유 endpoint를 주고 같은 뷰 함수에 defaults를 쓰면, 하나의 핸들러가 여러 URL 형태를 서빙합니다.
from flask import Flask
app = Flask(__name__)
def show(id=None, name=None):
if id is not None:
return f"By id: {id}"
return f"By name: {name}"
app.add_url_rule("/by-id/<int:id>", "by_id", show, defaults={"name": None})
app.add_url_rule("/by-name/<name>", "by_name", show, defaults={"id": None})
# Two endpoints share one function with different defaults.요청과 응답
Request 객체
request는 현재 요청 컨텍스트에 묶인 스레드 로컬 프록시입니다. 명시적으로 전달되지 않고도 URL, 메서드, 헤더, 본문, 클라이언트 정보를 노출합니다.
from flask import Flask, request
app = Flask(__name__)
@app.route("/info")
def info():
return {
"url": request.url,
"method": request.method,
"remote_addr": request.remote_addr,
"user_agent": str(request.user_agent),
"headers": dict(request.headers),
}응답 만들기
make_response는 상태, 헤더, 본문에 대한 완전한 제어를 제공합니다. 단순한 경우 문자열, dict(JSON), (body, status, headers) 튜플을 반환하면 됩니다.
from flask import Flask, make_response
app = Flask(__name__)
@app.route("/")
def index():
resp = make_response("Hello, World!")
resp.status_code = 201
resp.headers["X-Custom"] = "yes"
resp.set_cookie("visited", "1")
return resp
# Returning a tuple: (body, status, headers)
@app.route("/quick")
def quick():
return "OK", 202, {"X-Quick": "1"}Response 객체
커스텀 mimetype(예: XML, CSV)이나 헤더가 필요하면 Response를 쓰세요. Content-Disposition을 attachment로 두면 브라우저가 다운로드로 처리합니다.
from flask import Response
@app.route("/xml")
def xml():
return Response("<msg>hi</msg>", mimetype="application/xml")
@app.route("/text")
def text():
return Response("plain text", mimetype="text/plain")
@app.route("/csv")
def csv():
body = "a,b,c\n1,2,3\n"
headers = {"Content-Disposition": "attachment; filename=data.csv"}
return Response(body, mimetype="text/csv", headers=headers)커스텀 상태와 헤더
간결한 커스텀 응답에는 (body, status, headers) 튜플을 반환하세요. 본문 없는 성공 응답에는 204 No Content, 의미에는 표준 HTTP 상태 코드를 쓰세요.
@app.route("/created")
def created():
return "done", 201, {"Location": "/resource/1"}
@app.route("/no-content")
def no_content():
return "", 204
@app.route("/teapot")
def teapot():
return "I'm a teapot", 418스트리밍 응답
제너레이터 반환 값은 데이터를 클라이언트로 스트리밍합니다. 큰 파일(전체를 메모리에 올리지 않음)과 Server-Sent Events에 유용합니다. 적절한 mimetype을 설정 하세요.
from flask import Response
def generate():
yield "data: first\n\n"
yield "data: second\n\n"
yield "data: third\n\n"
@app.route("/stream")
def stream():
return Response(generate(), mimetype="text/event-stream")
@app.route("/big-file")
def big_file():
def chunks():
with open("large.log", "rb") as f:
while chunk := f.read(8192):
yield chunk
return Response(chunks(), mimetype="application/octet-stream")응답의 쿠키
set_cookie가 Set-Cookie 헤더를 쓰고, delete_cookie가 만료시킵니다. 보안을 위해 항상 httponly와 samesite를 설정하세요. 쿠키는 응답의 일부이지 요청 본문이 아닙니다.
from flask import make_response
@app.route("/set-theme")
def set_theme():
resp = make_response("theme set")
resp.set_cookie("theme", "dark", max_age=30*86400, httponly=True, samesite="Lax")
return resp
@app.route("/clear-theme")
def clear_theme():
resp = make_response("cleared")
resp.delete_cookie("theme")
return respRequest 객체 (form/args/files)
쿼리 파라미터 (args)
request.args는 쿼리 문자열 값의 MultiDict입니다. 기본값과 타입 변환이 있는 get을 쓰고, 반복 키에는 getlist를 쓰세요. 직접 인덱싱하지 마세요 — 없는 키는 400을 냅니다.
from flask import request
@app.route("/search")
def search():
q = request.args.get("q", "") # default ""
page = request.args.get("page", 1, type=int)
tags = request.args.getlist("tag") # /search?tag=a&tag=b -> ["a","b"]
return {"q": q, "page": page, "tags": tags}폼 데이터
request.form은 POST된 application/x-www-form-urlencoded 또는 multipart 데이터를 담습니다. 선택 필드의 KeyError를 피하려면 .get()을 쓰세요. GET 요청의 form은 비어 있습니다.
from flask import request, render_template
@app.route("/login", methods=["GET", "POST"])
def login():
if request.method == "POST":
username = request.form.get("username")
password = request.form.get("password")
if not username or not password:
return "Missing fields", 400
return f"Welcome {username}"
return render_template("login.html")파일 업로드
request.files는 FileStorage 객체의 MultiDict입니다. 저장 전에 사용자가 올린 파일명을 반드시 secure_filename으로 처리해 경로 구분자와 위험한 문자를 제거하세요.
from flask import request
from werkzeug.utils import secure_filename
import os
@app.route("/upload", methods=["POST"])
def upload():
file = request.files.get("file")
if not file or file.filename == "":
return "No file", 400
name = secure_filename(file.filename)
file.save(os.path.join("uploads", name))
return "saved"JSON 본문
get_json()은 Content-Type이 application/json일 때만 본문을 JSON으로 파싱합니다. force=True는 헤더를 무시합니다(신중히 쓰세요). silent=True는 파싱 오류를 숨깁니다.
from flask import request
@app.route("/api/echo", methods=["POST"])
def echo():
data = request.get_json() # returns None if not JSON
if data is None:
return "Expected JSON", 415
return {"you_sent": data}
# Force parsing even without the right header (risky)
@app.route("/api/force")
def force():
data = request.get_json(force=True)
return data헤더와 쿠키
request.headers는 EnvironHeaders dict류 객체이고, request.cookies는 클라이언트가 보낸 들어온 쿠키를 담습니다. 둘 다 읽기 전용입니다 — 응답 헤더/쿠키는 응답에 설정하세요.
from flask import request
@app.route("/inspect")
def inspect():
auth = request.headers.get("Authorization")
accept = request.headers.get("Accept")
session_id = request.cookies.get("session_id")
return {
"auth": auth,
"accept": accept,
"session_id": session_id,
}요청 메서드와 프로퍼티
request는 연결과 본문에 대한 메타데이터를 노출합니다. is_json은 Content-Type을, is_secure는 HTTPS 여부를 검사하고, query_string은 '?' 뒤의 원본 바이트입니다.
from flask import request
@app.route("/state")
def state():
return {
"method": request.method,
"is_xhr": request.is_json,
"content_type": request.content_type,
"content_length": request.content_length,
"is_secure": request.is_secure,
"scheme": request.scheme,
"host": request.host,
"path": request.path,
"query_string": request.query_string.decode(),
}Jinja2 템플릿
템플릿 렌더링
render_template은 templates/ 폴더에서 Jinja2 파일을 불러와 키워드 인수를 변수로 주입합니다. {{ }} 문법이 표현식을 출력하며, Flask는 안전을 위해 HTML을 자동 이스케이프합니다.
from flask import render_template
@app.route("/<name>")
def hello(name):
return render_template("hello.html", name=name, title="Welcome")
# templates/hello.html
# <!DOCTYPE html>
# <html>
# <head><title>{{ title }}</title></head>
# <body>
# <h1>Hello {{ name }}!</h1>
# </body>
# </html>템플릿 변수
Jinja2는 속성(user.name)과 항목(user['age']) 접근을 지원합니다. safe 필터는 문자열을 신뢰됨으로 표시해 이스케이프하지 않습니다 — 완전히 통제하는 콘텐츠에만 쓰세요.
# View
@app.route("/")
def index():
return render_template(
"index.html",
user={"name": "Alice", "age": 30},
items=["apple", "banana", "cherry"],
html_content="<b>safe?</b>",
)
# Template
# <p>Name: {{ user.name }}</p>
# <p>Age: {{ user["age"] }}</p>
# <p>First: {{ items[0] }}</p>
# <p>Raw HTML: {{ html_content | safe }}</p>제어 구조
Jinja2는 {% if %}, {% for %}, {% block %}을 지원합니다. 루프 안에서는 특수한 loop 변수가 index, index0, first, last, length, revindex를 제공합니다. for-else는 이터러블이 비었을 때 실행됩니다.
{# if / elif / else #}
{% if user.age >= 18 %}
Adult
{% elif user.age >= 13 %}
Teen
{% else %}
Child
{% endif %}
{# for loop #}
<ul>
{% for item in items %}
<li>{{ loop.index }}: {{ item }}</li>
{% else %}
<li>No items</li>
{% endfor %}
</ul>템플릿 상속
extends가 기본 템플릿을 가져오고 자식 템플릿이 이름 붙은 블록을 재정의합니다. 공유 레이아웃(내비게이션, 스크립트)을 한 곳에 유지합니다. super()는 부모 블록의 내용을 렌더링합니다.
{# templates/base.html #}
<!DOCTYPE html>
<html>
<head>
<title>{% block title %}Default{% endblock %}</title>
</head>
<body>
{% block content %}{% endblock %}
</body>
</html>
{# templates/child.html #}
{% extends "base.html" %}
{% block title %}Home{% endblock %}
{% block content %}
<h1>Welcome home</h1>
{% endblock %}필터
필터는 파이프(|) 문법으로 값을 변형하며 인수를 받습니다. 템플릿 전반에서 로직을 재사용하려면 app.jinja_env.filters에 커스텀 필터를 등록하세요.
{{ name | capitalize }} {# alice -> Alice #}
{{ price | round(2) }} {# 3.14159 -> 3.14 #}
{{ items | length }} {# count #}
{{ text | truncate(20) }} {# shorten #}
{{ tags | join(", ") }} {# ["a","b"] -> "a, b" #}
{{ value | default("n/a") }} {# fallback #}
{{ html | striptags }} {# remove HTML tags #}
{# Custom filter #}
def reverse_filter(s):
return s[::-1]
app.jinja_env.filters["reverse"] = reverse_filter
{{ "hello" | reverse }} {# olleh #}매크로
매크로는 함수처럼 재사용 가능한 템플릿 조각입니다. {% from %}이나 {% import %}로 가져옵니다. 반복되는 HTML(폼 필드, 카드)을 DRY하게 유지합니다.
{# templates/macros.html #}
{% macro input(name, value="", type="text") %}
<input type="{{ type }}" name="{{ name }}" value="{{ value }}">
{% endmacro %}
{% macro label(text, for_id) %}
<label for="{{ for_id }}">{{ text }}</label>
{% endmacro %}
{# In another template #}
{% from "macros.html" import input, label %}
<form>
{{ label("Username", "u") }}
{{ input("username") }}
{{ label("Password", "p") }}
{{ input("password", type="password") }}
</form>정적 파일
정적 파일 서빙
Flask는 static 폴더에 /static/<path:filename> 라우트를 자동 등록합니다. static_url_path가 바뀌어도 경로가 올바르게 유지되도록 URL은 항상 url_for로 만드세요.
# Files in the static/ folder are served at /static/<filename>
# static/css/style.css -> http://localhost:5000/static/css/style.css
# Reference them in templates
# <link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
# <script src="{{ url_for('static', filename='js/app.js') }}"></script>
# <img src="{{ url_for('static', filename='img/logo.png') }}">정적 자산용 url_for
url_for('static', filename=...)이 정적 파일 경로를 해석합니다. 절대 URL(이메일이나 피드에 유용)에는 _external=True를, 캐시 무력화에는 쿼리 인수를 전달하세요.
from flask import Flask, url_for
app = Flask(__name__)
with app.test_request_context():
print(url_for("static", filename="css/style.css"))
# /static/css/style.css
print(url_for("static", filename="js/app.js", _external=True))
# http://localhost/static/js/app.js커스텀 정적 폴더
static_folder(디스크 위치)와 static_url_path(URL 접두사)를 프로젝트 관례에 맞게 덮어쓰세요. 기본값은 폴더 'static'이 /static에 매핑되는 것입니다.
from flask import Flask
app = Flask(
__name__,
static_folder="assets", # folder on disk
static_url_path="/public", # URL prefix
)
# Now files in assets/ are served at /public/<filename>
# Template: url_for('static', filename='css/style.css') -> /public/css/style.css파비콘
브라우저는 기본적으로 루트의 /favicon.ico를 요청합니다. 명시적 라우트를 추가하거나 <link> 태그로 아이콘을 연결하세요. send_from_directory는 디렉터리에서 파일을 안전하게 서빙합니다.
from flask import send_from_directory
import os
@app.route("/favicon.ico")
def favicon():
return send_from_directory(
os.path.join(app.root_path, "static"),
"favicon.ico",
mimetype="image/vnd.microsoft.icon",
)
# Or place favicon.ico in static/ and link it:
# <link rel="icon" href="{{ url_for('static', filename='favicon.ico') }}">캐시 무력화
브라우저는 URL 기준으로 정적 자산을 캐시합니다. 버전 해시를 붙이면 파일이 바뀐 뒤 클라이언트가 새 사본을 가져옵니다. 큰 프로젝트에서는 빌드 도구(Vite, Flask-Assets)가 이를 자동화합니다.
# Append a version query param to force reloads
# <link href="{{ url_for('static', filename='css/app.css', v='1.2') }}">
# Or compute a hash at startup
import hashlib, os
def asset_version(filename):
path = os.path.join(app.static_folder, filename)
with open(path, "rb") as f:
return hashlib.md5(f.read()).hexdigest()[:8]
@app.template_filter("bust")
def bust(filename):
v = asset_version(filename)
return url_for("static", filename=filename) + f"?v={v}"
# Template: <link href="{{ 'css/app.css' | bust }}">블루프린트
블루프린트 생성
블루프린트는 관련 라우트, 템플릿, 정적 파일을 모듈로 묶습니다. 첫 인수가 블루프린트 이름이고, url_prefix는 정의하는 모든 라우트에 경로를 앞에 붙입니다.
# auth.py
from flask import Blueprint, render_template
bp = Blueprint("auth", __name__, url_prefix="/auth")
@bp.route("/login")
def login():
return render_template("auth/login.html")
@bp.route("/register")
def register():
return render_template("auth/register.html")블루프린트 등록
register_blueprint가 블루프린트를 앱에 붙입니다. 등록 시점에 url_prefix를 덮어쓸 수 있어, 같은 블루프린트를 앱마다 다른 경로 아래 장착할 수 있습니다.
from flask import Flask
from auth import bp as auth_bp
from blog import bp as blog_bp
app = Flask(__name__)
app.register_blueprint(auth_bp) # /auth/*
app.register_blueprint(blog_bp, url_prefix="/blog") # /blog/*
# Register later, or with a name override
app.register_blueprint(auth_bp, name="alt_auth")URL 접두사가 있는 블루프린트
url_prefix는 블루프린트에 정의하거나 등록 시 지정합니다. API 경로를 버저닝하면(/api/v1) 파괴적 변경 시 /api/v2를 나중에 도입하면서 기존 클라이언트를 지킬 수 있습니다.
# api/__init__.py
from flask import Blueprint
bp = Blueprint("api", __name__, url_prefix="/api/v1")
@bp.route("/users")
def list_users():
return {"users": []}
@bp.route("/users/<int:uid>")
def get_user(uid):
return {"id": uid}
# All routes become /api/v1/users...블루프린트 리소스
블루프린트는 자체 templates와 static 폴더를 가질 수 있습니다. 템플릿 해석은 블루프린트를 먼저, 그다음 앱을 검사하므로, 같은 이름의 블루프린트 로컬 파일이 앱 전역 파일을 이깁니다.
bp = Blueprint(
"admin",
__name__,
url_prefix="/admin",
template_folder="templates", # blueprint-local templates
static_folder="static", # blueprint-local static
)
# Templates: blueprint lookups first, then app templates
# render_template("admin/dashboard.html")
# Static: url_for('admin.static', filename='css/admin.css')블루프린트 에러 핸들러
블루프린트 수준 에러 핸들러는 그 블루프린트의 라우트가 발생시킨 오류만 잡습니다 — 섹션별 에러 페이지를 만들 수 있습니다. 앱 수준 핸들러는 잡히지 않은 모든 것을 처리합니다.
from flask import Blueprint, render_template
bp = Blueprint("blog", __name__)
@bp.errorhandler(404)
def blog_not_found(e):
return render_template("blog/404.html"), 404
@bp.errorhandler(403)
def blog_forbidden(e):
return render_template("blog/403.html"), 403중첩 블루프린트
Flask 2.0+는 블루프린트 중첩을 지원합니다. register_blueprint로 부모에 자식을 등록하면 url_prefix가 이어 붙어, 작은 모듈로 큰 앱을 조립할 수 있습니다.
from flask import Blueprint
parent = Blueprint("parent", __name__, url_prefix="/parent")
child = Blueprint("child", __name__, url_prefix="/child")
@child.route("/info")
def info():
return "nested info"
parent.register_blueprint(child)
app.register_blueprint(parent)
# Final URL: /parent/child/info컨텍스트 (g / session)
애플리케이션 컨텍스트
애플리케이션 컨텍스트는 요청 밖(예: CLI 커맨드나 백그라운드 작업)에서 current_app과 g를 사용 가능하게 합니다. 요청 밖에서 작업할 때는 app.app_context()로 푸시하세요.
from flask import current_app, g
@app.route("/")
def index():
app_name = current_app.name
config_value = current_app.config["SECRET_KEY"]
return f"Running {app_name}"
# Push a context manually (scripts, shell)
with app.app_context():
print(current_app.config["DEBUG"])g 객체
g는 데이터베이스 연결 같은 공유 리소스를 저장하는 요청별 네임스페이스입니다. 요청마다 초기화되며 teardown_appcontext 핸들러에서 정리됩니다.
from flask import g
import sqlite3
def get_db():
if "db" not in g:
g.db = sqlite3.connect("app.db")
g.db.row_factory = sqlite3.Row
return g.db
@app.teardown_appcontext
def close_db(exc):
db = g.pop("db", None)
if db is not None:
db.close()요청 컨텍스트
요청 컨텍스트는 request, session, url_for를 스레드에 바인딩합니다. 테스트와 스크립트에서 test_request_context를 쓰면 HTTP 서버 없이 요청을 흉내 냅니다.
from flask import request
# Flask pushes a request context automatically during dispatch.
# Push one manually to use request/url_for outside a view:
with app.test_request_context("/?q=flask"):
print(request.args.get("q")) # flask
print(request.path) # /
# request_context for real WSGI environments
from werkzeug.test import EnvironBuilder
env = EnvironBuilder("/post/1").get_environ()
with app.request_context(env):
print(request.path)current_app과 request 프록시
current_app, request, session, g는 활성 컨텍스트로 속성 접근을 전달하는 LocalProxy입니다. 전역 변수에 담지 마세요 — 항상 호출 시점에 접근하세요.
from flask import current_app, request, session, g
# These are LocalProxy objects, not the real thing.
# They resolve to the current context's object at access time.
@app.route("/")
def index():
current_app.logger.info("hit /")
g.request_start = time.time()
session["visited"] = True
return current_app.config["APP_NAME"]
# Avoid storing proxies in module-level variables;
# always access them inside a context.Session 객체
session은 서명된 쿠키 기반 dict입니다. Flask가 서명하려면 app.secret_key가 필요합니다. 값은 클라이언트에 저장되어 사용자가 읽을 수 있습니다(변조는 불가) — 시크릿을 저장하지 마세요.
from flask import session
@app.route("/login")
def login():
session["user_id"] = 42
session["role"] = "admin"
return "logged in"
@app.route("/who")
def who():
uid = session.get("user_id")
return f"user {uid}" if uid else "anonymous"
@app.route("/logout")
def logout():
session.clear()
return "logged out"컨텍스트 라이프사이클
라이프사이클을 이해하는 것이 훅을 올바르게 쓰는 열쇠입니다. teardown_* 핸들러는 오류 시에도 항상 실행되므로 데이터베이스 연결 종료와 리소스 해제의 적합한 자리입니다.
# Per-request lifecycle:
# 1. Application context pushed
# 2. Request context pushed
# 3. before_request handlers run
# 4. View function runs
# 5. after_request handlers run (can modify response)
# 6. Request context popped
# 7. teardown_request handlers run
# 8. teardown_appcontext handlers run (close resources)
@app.before_request
def before():
g.start = time.time()
@app.teardown_request
def teardown(exc):
elapsed = time.time() - getattr(g, "start", time.time())
app.logger.debug("request took %.3fs", elapsed)SQLAlchemy 통합
Flask-SQLAlchemy 설정
Flask-SQLAlchemy는 SQLAlchemy를 감싸 Flask의 앱 컨텍스트와 통합합니다. SQLALCHEMY_DATABASE_URI에 연결 문자열을 두고 메모리 절약을 위해 track modifications를 끄세요.
pip install flask-sqlalchemy
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
db = SQLAlchemy(app)
# In a factory, init with db.init_app(app)모델 정의
모델은 db.Model을 상속하고, 컬럼은 db.Column 인스턴스입니다. 흔한 타입: Integer, String, Text, DateTime, Boolean. 제약에는 unique=True와 nullable=False를 쓰세요.
from datetime import datetime
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80), unique=True, nullable=False)
email = db.Column(db.String(120), unique=True)
created_at = db.Column(db.DateTime, default=datetime.utcnow)
def __repr__(self):
return f"<User {self.username}>"
class Post(db.Model):
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(200), nullable=False)
body = db.Column(db.Text)
user_id = db.Column(db.Integer, db.ForeignKey("user.id"))데이터 조회
Model.query는 편의 조회 인터페이스입니다. filter_by(keyword=value)는 단순하고, filter(expression)는 >, <, like, in_ 같은 연산자를 지원합니다. paginate()는 항목과 페이지 메타데이터를 반환합니다.
# Fetch all
users = User.query.all()
# Primary key lookup
user = User.query.get(1)
# Filter
admins = User.query.filter_by(role="admin").all()
active = User.query.filter(User.email.isnot(None)).first()
# Order, limit, paginate
recent = User.query.order_by(User.created_at.desc()).limit(10).all()
page = User.query.paginate(page=2, per_page=20)
# Count
total = User.query.count()추가와 업데이트
모든 변경은 db.session의 트랜잭션에서 일어납니다. add가 새 객체를 스테이징하고 commit이 기록합니다. 오류 시 db.session.rollback()으로 세션을 계속 쓸 수 있게 하세요.
# Create
u = User(username="alice", email="[email protected]")
db.session.add(u)
db.session.commit()
# Update
u.email = "[email protected]"
db.session.commit()
# Delete
db.session.delete(u)
db.session.commit()
# Bulk insert
db.session.add_all([User(username="b"), User(username="c")])
db.session.commit()관계
db.relationship이 모델 간 링크를 정의합니다. backref가 역방향 속성을 더합니다. lazy='dynamic'은 리스트 대신 쿼리 객체를 반환하며, 추가 필터링하려는 큰 컬렉션에 유용합니다.
class User(db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80))
posts = db.relationship("Post", backref="author", lazy="dynamic")
class Post(db.Model):
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(200))
user_id = db.Column(db.Integer, db.ForeignKey("user.id"))
# Usage
user = User.query.get(1)
user.posts.all() # list of posts
post = Post.query.get(5)
post.author.username # backref to userFlask-Migrate 마이그레이션
Flask-Migrate는 Alembic을 감싸 스키마를 버전 관리합니다. migrate가 모델 변경으로 스크립트를 자동 생성하고, upgrade가 적용합니다. 커밋 전에 자동 생성된 스크립트를 반드시 검토하세요.
pip install flask-migrate
from flask_migrate import Migrate
migrate = Migrate(app, db)
# CLI commands
# flask db init # create migrations folder
# flask db migrate -m "create users"
# flask db upgrade # apply migrations
# flask db downgrade # revert one step
# flask db current # show current revisionWTForms (Flask-WTF)
Flask-WTF 설치
Flask-WTF는 WTForms를 Flask와 통합하고 CSRF 보호를 자동 추가합니다. CSRF 토큰 서명을 위해 SECRET_KEY가 필요합니다. CSRF는 공개 API 엔드포인트에만 끄세요.
pip install flask-wtf
from flask import Flask
from flask_wtf import FlaskForm
app = Flask(__name__)
app.config["SECRET_KEY"] = "change-me-in-production"
app.config["WTF_CSRF_ENABLED"] = True
# CSRF protection is enabled by default
# when SECRET_KEY is set.폼 정의
폼은 FlaskForm을 상속합니다. 각 필드는 라벨과 validate()에서 실행되는 검증기 목록을 받습니다. 검증기가 필수 입력, 길이, 이메일 형식 등을 강제합니다.
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, SubmitField
from wtforms.validators import DataRequired, Email, Length
class LoginForm(FlaskForm):
email = StringField("Email", validators=[DataRequired(), Email()])
password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
submit = SubmitField("Log In")
class RegisterForm(FlaskForm):
username = StringField("Username", validators=[DataRequired(), Length(min=3, max=20)])
email = StringField("Email", validators=[DataRequired(), Email()])
submit = SubmitField("Sign Up")템플릿에서 폼 렌더링
form.hidden_tag()가 CSRF 토큰과 숨김 필드를 렌더링합니다. 각 필드는 라벨, 입력, 오류를 개별 렌더링할 수 있습니다. 빠른 출력에는 {{ form.field() }}가 HTML 입력을 렌더링합니다.
{# templates/login.html #}
<form method="POST">
{{ form.hidden_tag() }} {# CSRF token #}
<p>
{{ form.email.label }}
{{ form.email() }}
{% for err in form.email.errors %}<span class="err">{{ err }}</span>{% endfor %}
</p>
<p>
{{ form.password.label }}
{{ form.password() }}
</p>
{{ form.submit() }}
</form>폼 검증
validate_on_submit()은 모든 검증기를 통과한 POST 요청에서만 True를 반환합니다. 성공 시 form.field.data에서 값을 읽고, 실패 시 오류를 보이도록 템플릿을 다시 렌더링하세요.
from flask import render_template, redirect, url_for, flash
@app.route("/login", methods=["GET", "POST"])
def login():
form = LoginForm()
if form.validate_on_submit(): # POST + valid
email = form.email.data
flash(f"Logged in as {email}")
return redirect(url_for("dashboard"))
return render_template("login.html", form=form)
# validate_on_submit() returns False on GET or invalid POST내장 검증기
검증기는 실패 시 ValidationError를 발생시키는 콜러블입니다. EqualTo는 비밀번호 확인에 흔합니다. 리스트로 체이닝하며 순서대로 실행되어 하나가 실패하면 멈춥니다.
from wtforms.validators import (
DataRequired, # field not empty
Email, # valid email format
Length, # Length(min=3, max=20)
NumberRange, # NumberRange(min=0, max=100)
URL, # valid URL
Regexp, # Regexp(r"^\\w+$")
EqualTo, # EqualTo("password") - match another field
Optional, # skip validation if empty
InputRequired, # field submitted (even if empty string)
NoneOf, # NoneOf(["admin", "root"])
)
password = PasswordField("Password", validators=[DataRequired(), Length(min=8)])
confirm = PasswordField("Confirm", validators=[EqualTo("password")])FileField
flask_wtf.file의 FileField에 FileRequired와 FileAllowed를 붙여 업로드를 검증하세요. 업로드된 파일은 form.field.data에서 FileStorage 객체로 접근합니다. form 태그에 enctype=multipart/form-data가 필요합니다.
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed
class UploadForm(FlaskForm):
image = FileField("Image", validators=[
FileRequired(),
FileAllowed(["jpg", "png", "gif"], "Images only!"),
])
submit = SubmitField("Upload")
@app.route("/upload", methods=["GET", "POST"])
def upload():
form = UploadForm()
if form.validate_on_submit():
f = form.image.data
f.save("uploads/" + f.filename)
return "uploaded"
return render_template("upload.html", form=form)Flask-Login 인증
Flask-Login 설정
Flask-Login은 사용자 세션을 관리합니다: 로그인, 로그아웃, 사용자 기억. login_view를 두면 미인증 사용자가 그곳으로 리다이렉트됩니다. login_message가 리다이렉트에서 플래시됩니다.
pip install flask-login
from flask import Flask
from flask_login import LoginManager
app = Flask(__name__)
app.config["SECRET_KEY"] = "secret"
login_manager = LoginManager()
login_manager.init_app(app)
login_manager.login_view = "login"
login_manager.login_message = "Please log in to access this page."User 모델
사용자 모델은 UserMixin(is_authenticated, is_active, get_id 등을 제공)을 믹스인하고 ID로 사용자를 반환하는 user_loader 콜백을 구현해야 합니다. 평문 비밀번호를 저장하지 마세요 — 해시하세요.
from flask_login import UserMixin
from werkzeug.security import generate_password_hash, check_password_hash
class User(UserMixin, db.Model):
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(80), unique=True)
password_hash = db.Column(db.String(256))
def set_password(self, pw):
self.password_hash = generate_password_hash(pw)
def check_password(self, pw):
return check_password_hash(self.password_hash, pw)
@login_manager.user_loader
def load_user(user_id):
return User.query.get(int(user_id))로그인 뷰
login_user가 세션에 사용자를 싣습니다. 지속 쿠키에는 remember=True를 전달하세요. 로그인 전에 반드시 해시 검증으로 비밀번호를 확인하고, 실패 시 일반적인 오류만 플래시하세요.
from flask import render_template, redirect, url_for, flash
from flask_login import login_user
from forms import LoginForm
@app.route("/login", methods=["GET", "POST"])
def login():
form = LoginForm()
if form.validate_on_submit():
user = User.query.filter_by(username=form.username.data).first()
if user and user.check_password(form.password.data):
login_user(user, remember=form.remember.data)
return redirect(url_for("dashboard"))
flash("Invalid username or password")
return render_template("login.html", form=form)라우트 보호
@login_required 데코레이터는 익명 사용자를 거부해 login_view로 리다이렉트합니다. current_user는 뷰와 템플릿에서 쓰이는 로그인 사용자(또는 AnonymousUserMixin) 프록시입니다.
from flask_login import login_required, current_user
@app.route("/dashboard")
@login_required
def dashboard():
return f"Welcome {current_user.username}"
@app.route("/settings")
@login_required
def settings():
return render_template("settings.html", user=current_user)
# Unauthenticated users redirect to login_view
# @login_required must be the innermost decorator로그아웃
logout_user가 세션에서 사용자를 지웁니다. 로그인한 사용자만 로그아웃하도록 @login_required로 라우트를 보호하세요. 이후 공개 페이지(인덱스나 로그인)로 리다이렉트합니다.
from flask_login import logout_user, login_required
from flask import redirect, url_for, flash
@app.route("/logout")
@login_required
def logout():
logout_user()
flash("You have been logged out.")
return redirect(url_for("index"))
# logout_user() clears the session and cookiesRemember Me와 current_user
remember=True는 별도 쿠키를 설정해 브라우저를 닫은 뒤에도 로그인 상태를 유지합니다. current_user는 뷰와 템플릿 양쪽에서 동작해 인증 상태에 따른 조건부 UI 렌더링이 쉬워집니다.
from flask_login import current_user
# In the login view
login_user(user, remember=True)
# remember=True stores a separate long-lived cookie
# so the session survives a browser restart.
# current_user is available everywhere a context exists
@app.route("/")
def index():
if current_user.is_authenticated:
return f"Hi {current_user.username}"
return "Welcome, guest"
# In templates:
# {% if current_user.is_authenticated %}
# <a href="{{ url_for('logout') }}">Logout</a>
# {% endif %}에러 처리
abort()
abort()는 뷰를 즉시 중단하고 HTTP 오류를 반환합니다. 상태 코드와 선택적 메시지를 전달하세요. Flask가 대응하는 오류 응답으로 변환하는 HTTPException을 발생시킵니다.
from flask import abort
@app.route("/user/<int:id>")
def get_user(id):
user = find_user(id)
if user is None:
abort(404) # Not Found
if not can_access(user):
abort(403, "Forbidden") # Forbidden with description
return render_template("user.html", user=user)
# Common codes: 400 Bad Request, 401 Unauthorized,
# 403 Forbidden, 404 Not Found, 418 Teapot, 500 Server Error커스텀 에러 페이지
@app.errorhandler(code)로 핸들러를 등록합니다. (템플릿, status_code) 튜플을 반환하세요. 이 핸들러는 abort() 호출과 그 상태로 매핑되는 예외를 모두 잡습니다.
from flask import render_template
@app.errorhandler(404)
def not_found(e):
return render_template("errors/404.html"), 404
@app.errorhandler(403)
def forbidden(e):
return render_template("errors/403.html"), 403
@app.errorhandler(500)
def server_error(e):
return render_template("errors/500.html"), 500예외용 에러 핸들러
HTTP 코드뿐 아니라 커스텀 예외 클래스에도 핸들러를 등록할 수 있습니다. 뷰 어디에서든 예외를 발생시키면 핸들러가 트리거되어 도메인 오류의 응답이 중앙화됩니다.
from werkzeug.exceptions import HTTPException
class InvalidUsage(Exception):
status_code = 400
def __init__(self, message, status_code=None, payload=None):
super().__init__()
self.message = message
if status_code is not None:
self.status_code = status_code
self.payload = payload
@app.errorhandler(InvalidUsage)
def handle_invalid_usage(e):
return {"error": e.message}, e.status_code
@app.route("/raise")
def raise_err():
raise InvalidUsage("Bad input", status_code=422)catch-all 404 핸들러
일반 Exception 핸 들러는 500의 최후의 보루입니다. HTTPException은 재발생시켜 내장 페이지가 계속 동작하게 하고, 트레이스백은 로깅하세요. 프로덕션에서 스택 트레이스가 사용자에게 새지 않게 주의하세요.
@app.errorhandler(404)
def page_not_found(e):
# Log the missing URL for analysis
app.logger.info("404: %s", request.path)
return render_template("errors/404.html", path=request.path), 404
@app.errorhandler(Exception)
def unhandled(e):
# Catch any uncaught exception -> 500
if isinstance(e, HTTPException):
return e
app.logger.exception("Unhandled error")
return render_template("errors/500.html"), 500에러 로깅
exc_info=True로 로그하면 전체 트레이스백이 잡힙니다. RotatingFileHandler는 로그 파일이 무한히 커지는 것을 막습니다. 프로덕션에서는 중앙화된 서비스로 로그를 보내세요.
import logging
from logging.handlers import RotatingFileHandler
handler = RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)
handler.setLevel(logging.ERROR)
handler.setFormatter(logging.Formatter(
"%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]"
))
app.logger.addHandler(handler)
@app.errorhandler(500)
def server_error(e):
app.logger.error("Server error: %s", e, exc_info=True)
return "Internal error", 500HTTP 예외 처리
HTTPException은 모든 Werkzeug HTTP 오류의 기반 클래스입니다. HTTPException 핸들러는 한꺼번에 모두를 잡고, 서브클래스 전용 핸들러(NotFound)가 해당 코드에 우선합니다.
from werkzeug.exceptions import HTTPException, NotFound, BadRequest
@app.errorhandler(HTTPException)
def handle_http_exception(e):
# All HTTP exceptions in one handler
return render_template(
"errors/generic.html",
code=e.code,
name=e.name,
description=e.description,
), e.code
# Specific subclasses still work
@app.errorhandler(NotFound)
def specific_404(e):
return "custom 404", 404JSON과 API
jsonify
jsonify는 Python dict/리스트를 올바른 Content-Type과 ASCII 안전 이스케이프가 있는 JSON 응답으로 변환합니다. Flask 2.1+에서는 리스트를 직접 전달할 수 있고, 구버전은 dict가 필요합니다.
from flask import jsonify
@app.route("/api/user")
def api_user():
return jsonify(username="alice", age=30)
@app.route("/api/users")
def api_users():
users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
return jsonify(users)
# jsonify sets Content-Type: application/json
# and dumps with proper escapingJSON 반환
dict나 리스트를 직접 반환하는 것이 JSON을 보내는 가장 단순한 방법입니다. 커스텀 상태 코드나 헤더에는 튜플을 반환하세요. 직렬화를 완전히 제어해야 할 때만 Response + json.dumps를 쓰세요.
# Returning a dict/list is auto-converted to JSON (Flask 1.1+)
@app.route("/api/quick")
def quick():
return {"status": "ok", "count": 42}
# With custom status and headers
@app.route("/api/created", methods=["POST"])
def created():
return {"id": 99}, 201, {"Location": "/api/99"}
# A Response with JSON body
from flask import Response
import json
@app.route("/api/raw")
def raw():
return Response(json.dumps({"k": "v"}), mimetype="application/json")JSON 수신
get_json()은 Content-Type이 application/json일 때 본문을 JSON으로 파싱합니다. 사용 전에 반드시 파싱된 구조를 검증하세요 — 클라이언트 입력을 신뢰하지 마세요. 잘못된 페이로드에는 400/422를 반환하세요.