Skip to content

Flask 치트시트

가벼운 Python 웹 프레임워크(마이크로프레임워크)입니다.

01

시작하기

첫 애플리케이션

Flask는 마이크로프레임워크입니다 — 필수만 제공하고 필요한 것은 직접 더합니다. debug=True는 자동 리로드와 상세 에러 페이지를 활성화합니다.

flask
# 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을 쓰세요.

flask
# 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로 환경을 재현할 수 있습니다.

flask
# 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/ 폴더는 버전 관리에 넣지 말아야 할 배포 전용 시크릿을 담습니다.

flask
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 옵션은 앱을 반환하는 콜러블을 받습니다.

flask
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가 정적 파일과 템플릿 위치를 찾습니다. 레이아웃이 기본값과 다르면 생성자 인수로 폴더 위치를 덮어쓸 수 있습니다.

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!"
02

라우팅

변수 규칙

<converter:varname>으로 표시된 부분이 URL 세그먼트를 캡처합니다. 내장 컨버터: string(기본값), int, float, path(슬래시 허용), uuid. 값은 함수 인수로 전달됩니다.

flask
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에 등록하세요.

flask
@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를 반환합니다. 라우트마다 하나의 규칙을 정해 일관되게 유지하세요.

flask
@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 Found

HTTP 메서드

methods 인수로 여러 동사를 받거나, 단일 메서드 라우트에는 @app.get / @app.post 축약(Flask 2.0+)을 쓰세요. GET이 기본값입니다.

flask
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을 만듭니다.

flask
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 형태를 서빙합니다.

flask
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.
03

요청과 응답

Request 객체

request는 현재 요청 컨텍스트에 묶인 스레드 로컬 프록시입니다. 명시적으로 전달되지 않고도 URL, 메서드, 헤더, 본문, 클라이언트 정보를 노출합니다.

flask
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) 튜플을 반환하면 됩니다.

flask
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로 두면 브라우저가 다운로드로 처리합니다.

flask
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 상태 코드를 쓰세요.

flask
@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을 설정하세요.

flask
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를 설정하세요. 쿠키는 응답의 일부이지 요청 본문이 아닙니다.

flask
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 resp
04

Request 객체 (form/args/files)

쿼리 파라미터 (args)

request.args는 쿼리 문자열 값의 MultiDict입니다. 기본값과 타입 변환이 있는 get을 쓰고, 반복 키에는 getlist를 쓰세요. 직접 인덱싱하지 마세요 — 없는 키는 400을 냅니다.

flask
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은 비어 있습니다.

flask
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으로 처리해 경로 구분자와 위험한 문자를 제거하세요.

flask
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는 파싱 오류를 숨깁니다.

flask
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는 클라이언트가 보낸 들어온 쿠키를 담습니다. 둘 다 읽기 전용입니다 — 응답 헤더/쿠키는 응답에 설정하세요.

flask
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은 '?' 뒤의 원본 바이트입니다.

flask
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(),
    }
05

Jinja2 템플릿

템플릿 렌더링

render_template은 templates/ 폴더에서 Jinja2 파일을 불러와 키워드 인수를 변수로 주입합니다. {{ }} 문법이 표현식을 출력하며, Flask는 안전을 위해 HTML을 자동 이스케이프합니다.

flask
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 필터는 문자열을 신뢰됨으로 표시해 이스케이프하지 않습니다 — 완전히 통제하는 콘텐츠에만 쓰세요.

flask
# 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는 이터러블이 비었을 때 실행됩니다.

flask
{# 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()는 부모 블록의 내용을 렌더링합니다.

flask
{# 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에 커스텀 필터를 등록하세요.

flask
{{ 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하게 유지합니다.

flask
{# 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>
06

정적 파일

정적 파일 서빙

Flask는 static 폴더에 /static/<path:filename> 라우트를 자동 등록합니다. static_url_path가 바뀌어도 경로가 올바르게 유지되도록 URL은 항상 url_for로 만드세요.

flask
# 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를, 캐시 무력화에는 쿼리 인수를 전달하세요.

flask
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에 매핑되는 것입니다.

flask
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는 디렉터리에서 파일을 안전하게 서빙합니다.

flask
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)가 이를 자동화합니다.

flask
# 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 }}">
07

블루프린트

블루프린트 생성

블루프린트는 관련 라우트, 템플릿, 정적 파일을 모듈로 묶습니다. 첫 인수가 블루프린트 이름이고, url_prefix는 정의하는 모든 라우트에 경로를 앞에 붙입니다.

flask
# 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를 덮어쓸 수 있어, 같은 블루프린트를 앱마다 다른 경로 아래 장착할 수 있습니다.

flask
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를 나중에 도입하면서 기존 클라이언트를 지킬 수 있습니다.

flask
# 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 폴더를 가질 수 있습니다. 템플릿 해석은 블루프린트를 먼저, 그다음 앱을 검사하므로, 같은 이름의 블루프린트 로컬 파일이 앱 전역 파일을 이깁니다.

flask
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')

블루프린트 에러 핸들러

블루프린트 수준 에러 핸들러는 그 블루프린트의 라우트가 발생시킨 오류만 잡습니다 — 섹션별 에러 페이지를 만들 수 있습니다. 앱 수준 핸들러는 잡히지 않은 모든 것을 처리합니다.

flask
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가 이어 붙어, 작은 모듈로 큰 앱을 조립할 수 있습니다.

flask
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
08

컨텍스트 (g / session)

애플리케이션 컨텍스트

애플리케이션 컨텍스트는 요청 밖(예: CLI 커맨드나 백그라운드 작업)에서 current_app과 g를 사용 가능하게 합니다. 요청 밖에서 작업할 때는 app.app_context()로 푸시하세요.

flask
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 핸들러에서 정리됩니다.

flask
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 서버 없이 요청을 흉내 냅니다.

flask
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입니다. 전역 변수에 담지 마세요 — 항상 호출 시점에 접근하세요.

flask
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가 필요합니다. 값은 클라이언트에 저장되어 사용자가 읽을 수 있습니다(변조는 불가) — 시크릿을 저장하지 마세요.

flask
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_* 핸들러는 오류 시에도 항상 실행되므로 데이터베이스 연결 종료와 리소스 해제의 적합한 자리입니다.

flask
# 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)
09

SQLAlchemy 통합

Flask-SQLAlchemy 설정

Flask-SQLAlchemy는 SQLAlchemy를 감싸 Flask의 앱 컨텍스트와 통합합니다. SQLALCHEMY_DATABASE_URI에 연결 문자열을 두고 메모리 절약을 위해 track modifications를 끄세요.

flask
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를 쓰세요.

flask
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()는 항목과 페이지 메타데이터를 반환합니다.

flask
# 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()으로 세션을 계속 쓸 수 있게 하세요.

flask
# 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'은 리스트 대신 쿼리 객체를 반환하며, 추가 필터링하려는 큰 컬렉션에 유용합니다.

flask
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 user

Flask-Migrate 마이그레이션

Flask-Migrate는 Alembic을 감싸 스키마를 버전 관리합니다. migrate가 모델 변경으로 스크립트를 자동 생성하고, upgrade가 적용합니다. 커밋 전에 자동 생성된 스크립트를 반드시 검토하세요.

flask
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 revision
10

WTForms (Flask-WTF)

Flask-WTF 설치

Flask-WTF는 WTForms를 Flask와 통합하고 CSRF 보호를 자동 추가합니다. CSRF 토큰 서명을 위해 SECRET_KEY가 필요합니다. CSRF는 공개 API 엔드포인트에만 끄세요.

flask
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()에서 실행되는 검증기 목록을 받습니다. 검증기가 필수 입력, 길이, 이메일 형식 등을 강제합니다.

flask
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 입력을 렌더링합니다.

flask
{# 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에서 값을 읽고, 실패 시 오류를 보이도록 템플릿을 다시 렌더링하세요.

flask
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는 비밀번호 확인에 흔합니다. 리스트로 체이닝하며 순서대로 실행되어 하나가 실패하면 멈춥니다.

flask
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가 필요합니다.

flask
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)
11

Flask-Login 인증

Flask-Login 설정

Flask-Login은 사용자 세션을 관리합니다: 로그인, 로그아웃, 사용자 기억. login_view를 두면 미인증 사용자가 그곳으로 리다이렉트됩니다. login_message가 리다이렉트에서 플래시됩니다.

flask
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 콜백을 구현해야 합니다. 평문 비밀번호를 저장하지 마세요 — 해시하세요.

flask
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를 전달하세요. 로그인 전에 반드시 해시 검증으로 비밀번호를 확인하고, 실패 시 일반적인 오류만 플래시하세요.

flask
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) 프록시입니다.

flask
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로 라우트를 보호하세요. 이후 공개 페이지(인덱스나 로그인)로 리다이렉트합니다.

flask
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 cookies

Remember Me와 current_user

remember=True는 별도 쿠키를 설정해 브라우저를 닫은 뒤에도 로그인 상태를 유지합니다. current_user는 뷰와 템플릿 양쪽에서 동작해 인증 상태에 따른 조건부 UI 렌더링이 쉬워집니다.

flask
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 %}
12

에러 처리

abort()

abort()는 뷰를 즉시 중단하고 HTTP 오류를 반환합니다. 상태 코드와 선택적 메시지를 전달하세요. Flask가 대응하는 오류 응답으로 변환하는 HTTPException을 발생시킵니다.

flask
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() 호출과 그 상태로 매핑되는 예외를 모두 잡습니다.

flask
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 코드뿐 아니라 커스텀 예외 클래스에도 핸들러를 등록할 수 있습니다. 뷰 어디에서든 예외를 발생시키면 핸들러가 트리거되어 도메인 오류의 응답이 중앙화됩니다.

flask
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은 재발생시켜 내장 페이지가 계속 동작하게 하고, 트레이스백은 로깅하세요. 프로덕션에서 스택 트레이스가 사용자에게 새지 않게 주의하세요.

flask
@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는 로그 파일이 무한히 커지는 것을 막습니다. 프로덕션에서는 중앙화된 서비스로 로그를 보내세요.

flask
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", 500

HTTP 예외 처리

HTTPException은 모든 Werkzeug HTTP 오류의 기반 클래스입니다. HTTPException 핸들러는 한꺼번에 모두를 잡고, 서브클래스 전용 핸들러(NotFound)가 해당 코드에 우선합니다.

flask
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", 404
13

JSON과 API

jsonify

jsonify는 Python dict/리스트를 올바른 Content-Type과 ASCII 안전 이스케이프가 있는 JSON 응답으로 변환합니다. Flask 2.1+에서는 리스트를 직접 전달할 수 있고, 구버전은 dict가 필요합니다.

flask
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 escaping

JSON 반환

dict나 리스트를 직접 반환하는 것이 JSON을 보내는 가장 단순한 방법입니다. 커스텀 상태 코드나 헤더에는 튜플을 반환하세요. 직렬화를 완전히 제어해야 할 때만 Response + json.dumps를 쓰세요.

flask
# 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를 반환하세요.

flask
from flask import request, jsonify

@app.route("/api/echo", methods=["POST"])
def echo():
    data = request.get_json()
    if not data:
        return jsonify({"error": "Invalid JSON"}), 400
    return jsonify({"received": data})

# Validate the structure
@app.route("/api/signup", methods=["POST"])
def signup():
    data = request.get_json()
    if not data or "email" not in data:
        return jsonify({"error": "email required"}), 422
    return jsonify({"email": data["email"]}), 201

API 블루프린트

API 라우트를 버저닝된 url_prefix(/api/v1)를 가진 블루프린트로 묶으세요. API 로직이 페이지 라우트와 분리되고 버저닝이 명시적이 됩니다 — 파괴적 변경이 생기면 /api/v2로 올리세요.

flask
from flask import Blueprint, jsonify, request

api = Blueprint("api", __name__, url_prefix="/api/v1")

@api.route("/health")
def health():
    return jsonify(status="ok")

@api.route("/items", methods=["GET", "POST"])
def items():
    if request.method == "POST":
        return jsonify(created=True), 201
    return jsonify(items=[])

# Register: app.register_blueprint(api)

CORS

flask-cors가 Access-Control-Allow-Origin 헤더를 추가해 브라우저가 교차 출처 요청을 허용하게 합니다. 프로덕션에서는 와일드카드 '*' 대신 신뢰된 도메인으로 출처를 제한하세요.

flask
pip install flask-cors

from flask import Flask
from flask_cors import CORS

app = Flask(__name__)

# Enable for all routes
CORS(app)

# Or restrict to specific origins
CORS(app, resources={r"/api/*": {"origins": ["https://example.com", "http://localhost:3000"]}})

# Per-route
@app.route("/api/public")
@cross_origin(origins="*")
def public():
    return {"data": "open"}

API 에러 응답

헬퍼 함수가 엔드포인트 전반에서 오류 응답을 일관되게 유지합니다 — 같은 모양, 같은 키 이름. 일관된 오류 본문은 클라이언트 측 오류 처리를 훨씬 쉽게 만듭니다. 시크릿을 새지 않으면서 디버깅에 도움되는 세부를 포함하세요.

flask
from flask import jsonify, abort

def api_error(message, status=400, **extra):
    body = {"error": message}
    body.update(extra)
    return jsonify(body), status

@app.route("/api/users/<int:id>")
def get_user(id):
    user = find_user(id)
    if not user:
        return api_error("User not found", 404, user_id=id)
    return jsonify(user.serialize())

# Consistent error shape across the API:
# {"error": "User not found", "user_id": 1}
14

파일 업로드

기본 업로드

파일 업로드에는 form 태그에 enctype=multipart/form-data가 필요합니다. MAX_CONTENT_LENGTH를 설정하면 본문이 온전히 읽히기 전에 과대 업로드를 413으로 거부합니다 — 서버를 보호합니다.

flask
from flask import request
import os

app.config["UPLOAD_FOLDER"] = "uploads"
app.config["MAX_CONTENT_LENGTH"] = 16 * 1024 * 1024  # 16 MB

@app.route("/upload", methods=["POST"])
def upload():
    file = request.files["file"]
    file.save(os.path.join(app.config["UPLOAD_FOLDER"], file.filename))
    return "uploaded"

# HTML form must include enctype:
# <form method="POST" enctype="multipart/form-data">
#   <input type="file" name="file">
#   <button>Upload</button>
# </form>

안전한 파일명

secure_filename은 사용자가 올린 파일명에서 디렉터리 트래버설과 안전하지 않은 문자를 제거합니다. 고유성을 보장하지 않으므로 덮어쓰기 위험이 있으면 UUID를 붙이거나 충돌을 확인하세요.

flask
from werkzeug.utils import secure_filename
import os

@app.route("/upload", methods=["POST"])
def upload():
    f = request.files.get("file")
    if not f:
        return "no file", 400

    safe = secure_filename(f.filename)  # "my file!!/x.txt" -> "my_file__x.txt"
    if not safe:
        return "invalid filename", 400

    f.save(os.path.join("uploads", safe))
    return f"saved as {safe}"

여러 파일

multiple 속성을 가진 input과 함께 request.files.getlist('files')를 쓰면 여러 파일을 한 번에 받습니다. 저장 전에 각 파일의 확장자와 크기를 검증하세요.

flask
from flask import request

@app.route("/upload-many", methods=["POST"])
def upload_many():
    files = request.files.getlist("files")
    saved = []
    for f in files:
        if f and f.filename:
            name = secure_filename(f.filename)
            f.save(os.path.join("uploads", name))
            saved.append(name)
    return {"saved": saved}

# <form method="POST" enctype="multipart/form-data">
#   <input type="file" name="files" multiple>
# </form>

WTForms 업로드

Flask-WTF의 FileField가 업로드의 확장자와 존재 여부를 검증합니다. form 태그에 enctype=multipart/form-data가 필요합니다. 업로드된 파일은 form.photo.data에서 접근합니다.

flask
from flask_wtf import FlaskForm
from flask_wtf.file import FileField, FileRequired, FileAllowed

class PhotoForm(FlaskForm):
    photo = FileField("Photo", validators=[
        FileRequired(),
        FileAllowed(["jpg", "jpeg", "png"], "Images only"),
    ])
    submit = SubmitField("Upload")

@app.route("/photo", methods=["GET", "POST"])
def photo():
    form = PhotoForm()
    if form.validate_on_submit():
        f = form.photo.data
        f.save(os.path.join("uploads", secure_filename(f.filename)))
        return "uploaded"
    return render_template("photo.html", form=form)

파일 타입과 크기 검증

저장 전에 확장자와 콘텐츠 길이를 모두 검증하세요. MAX_CONTENT_LENGTH는 거대한 요청을 일찍 거부하지만, 파일별 검사가 더 세밀한 제어를 줍니다. 더 강한 안전을 위해 확장자만이 아니라 파일의 매직 바이트를 검사하세요.

flask
import os
from flask import request

ALLOWED = {".png", ".jpg", ".jpeg", ".gif", ".pdf"}
MAX_SIZE = 5 * 1024 * 1024  # 5 MB

@app.route("/upload", methods=["POST"])
def upload():
    f = request.files.get("file")
    if not f or not f.filename:
        return "no file", 400

    ext = os.path.splitext(f.filename)[1].lower()
    if ext not in ALLOWED:
        return "file type not allowed", 415

    f.stream.seek(0, 2)        # seek to end
    size = f.stream.tell()
    f.stream.seek(0)
    if size > MAX_SIZE:
        return "file too large", 413

    f.save(os.path.join("uploads", secure_filename(f.filename)))
    return "ok"
15

쿠키와 세션

쿠키 설정

쿠키는 응답 객체에 set_cookie로 설정합니다. httponly=True는 JavaScript가 읽지 못하게 하고(XSS 방어), secure=True는 HTTPS 전용이며, samesite='Lax' 또는 'Strict'는 CSRF 방어입니다.

flask
from flask import make_response

@app.route("/set-cookie")
def set_cookie():
    resp = make_response("cookie set")
    resp.set_cookie("user", "alice", max_age=3600, httponly=True)
    resp.set_cookie("theme", "dark", path="/", secure=True, samesite="Lax")
    return resp

# max_age in seconds; expires sets a datetime
# httponly blocks JS access; secure requires HTTPS
# samesite: "Lax" (default), "Strict", or "None"

쿠키 읽기

request.cookies는 브라우저가 보낸 쿠키의 읽기 전용 ImmutableMultiDict입니다. 쿠키가 없을 수 있으므로 인덱싱 대신 기본값이 있는 .get()을 쓰세요. 쿠키 수정은 응답에서 일어납니다.

flask
from flask import request

@app.route("/show-cookies")
def show_cookies():
    user = request.cookies.get("user", "guest")
    theme = request.cookies.get("theme", "light")
    all_cookies = request.cookies.to_dict()
    return f"user={user}, theme={theme}"

# request.cookies is a read-only dict
# use .get() with a default to avoid KeyError

Session 객체

session은 직렬화된 dict를 저장하는 서명된 쿠키입니다. secret_key로 서명되어 사용자가 변조할 수는 없지만 읽을 수는 있습니다 — 비밀번호나 시크릿을 세션에 저장하지 마세요.

flask
from flask import session

app.secret_key = "a-very-secret-string"

@app.route("/login")
def login():
    session["user_id"] = 1
    session["role"] = "admin"
    return "logged in"

@app.route("/dashboard")
def dashboard():
    if "user_id" not in session:
        return "please log in", 401
    return f"user {session['user_id']}"

@app.route("/logout")
def logout():
    session.pop("user_id", None)
    return "logged out"

Secret Key

secret_key가 세션 쿠키와 CSRF 토큰에 서명합니다. 긴 무작위 값을 쓰고, 소스 관리에 커밋되지 않도록 환경에서 불러오세요. 모든 앱 인스턴스가 같은 키를 공유해야 합니다.

flask
import os
from flask import Flask

app = Flask(__name__)

# Generate a strong random key
app.secret_key = os.urandom(32)

# Or load from environment (recommended for production)
app.secret_key = os.environ.get("SECRET_KEY")

# For multiple workers, all must share the same key
# so sessions survive being routed to different processes.
# A key of at least 32 random bytes is recommended.

플래시 메시지

flash는 리다이렉트를 넘어 살아남아 다음 요청에서 표시되는 메시지를 세션에 저장합니다. 템플릿에서 get_flashed_messages로 꺼내고 지웁니다. with_categories로 타입별 스타일링이 가능합니다.

flask
from flask import flash, redirect, url_for, render_template

app.secret_key = "secret"   # flash uses the session

@app.route("/save", methods=["POST"])
def save():
    flash("Saved successfully!", "success")
    return redirect(url_for("index"))

# In the template:
# {% with messages = get_flashed_messages(with_categories=true) %}
#   {% for category, message in messages %}
#     <div class="alert alert-{{ category }}">{{ message }}</div>
#   {% endfor %}
# {% endwith %}

세션 설정

기본 세션은 쿠키 기반이며 브라우저가 닫히면 만료됩니다. session.permanent=True와 PERMANENT_SESSION_LIFETIME으로 늘리세요. Flask-Session은 더 크거나 안전한 세션을 위해 저장소를 서버 측(Redis, 파일시스템)으로 옮깁니다.

flask
app.config.update(
    SECRET_KEY="secret",
    SESSION_COOKIE_NAME="sid",
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SECURE=True,     # HTTPS only
    SESSION_COOKIE_SAMESITE="Lax",
    PERMANENT_SESSION_LIFETIME=3600,  # seconds
    SESSION_TYPE="redis",            # needs Flask-Session
)

# Mark a session as permanent
from flask import session
from datetime import timedelta

@app.route("/remember")
def remember():
    session.permanent = True
    session["user"] = "alice"
    return "remembered for 1 hour"
16

Before/After 요청 훅

before_request

before_request 핸들러는 각 뷰 전에 실행됩니다. 인증 검사, 유지보수 모드, g에 공유 상태 로딩에 쓰세요. 값을 반환하면 뷰를 건너뛰고 그 응답이 바로 쓰입니다.

flask
from flask import g, request

@app.before_request
def check_maintenance():
    if app.config.get("MAINTENANCE"):
        return "Site under maintenance", 503

@app.before_request
def load_user():
    token = request.headers.get("Authorization")
    if token:
        g.user = verify_token(token)

# Return a value to short-circuit the request

after_request

after_request 핸들러는 뷰 뒤에 실행되며 응답을 받아 반환합니다. 헤더 추가, 로깅, 캐싱에 완벽합니다. 처리되지 않은 예외가 발생하면 after_request는 건너뜁니다.

flask
@app.after_request
def add_security_headers(resp):
    resp.headers["X-Content-Type-Options"] = "nosniff"
    resp.headers["X-Frame-Options"] = "SAMEORIGIN"
    return resp

@app.after_request
def log_response(resp):
    app.logger.info("%s %s -> %s", request.method, request.path, resp.status_code)
    return resp

# Must take and return a Response object

teardown_request

teardown_request는 오류 시에도 모든 요청 끝에서 실행됩니다 — after_request와 다릅니다. 예외(또는 None)를 받으며, DB 연결이나 파일 핸들 같은 리소스 해제의 적합한 자리입니다.

flask
import sqlite3
from flask import g

def get_db():
    if "db" not in g:
        g.db = sqlite3.connect("app.db")
    return g.db

@app.teardown_request
def close_db(exc):
    db = g.pop("db", None)
    if db is not None:
        db.close()

# teardown_request always runs, even if the view raised

before_first_request (폐기됨)

before_first_request는 현대의 비동기 서버와 다중 프로세스 환경과 맞지 않아 Flask 2.3에서 제거되었습니다. 일회성 설정은 임포트 시점의 앱 컨텍스트 안이나 CLI 커맨드에서 실행하세요.

flask
# Flask 2.3+ removed before_first_request.
# Old code:
# @app.before_first_request
# def init():
#     warm_cache()

# Modern alternative: use the app context at startup
with app.app_context():
    warm_cache()

# Or a CLI command run once during deployment
@app.cli.command("init")
def init_cmd():
    warm_cache()

응답 수정

여러 after_request 핸들러는 등록의 역순으로 체이닝됩니다. 각 핸들러는 반드시 응답을 반환해야 합니다. 보안 헤더, 캐시 지시문, 트레이싱 ID에 유용합니다.

flask
@app.after_request
def no_cache(resp):
    resp.headers["Cache-Control"] = "no-store"
    resp.headers["Pragma"] = "no-cache"
    return resp

@app.after_request
def add_request_id(resp):
    rid = getattr(g, "request_id", "n/a")
    resp.headers["X-Request-ID"] = rid
    return resp

# Multiple after_request handlers run in reverse
# registration order; each receives the previous one's output.

데이터베이스 연결 패턴

흔한 패턴: get_db에서 수요 시 연결을 열고(g에 저장) teardown_appcontext에서 닫습니다. 각 요청이 자신의 연결을 갖고 오류 시에도 정리가 보장됩니다.

flask
import sqlite3
from flask import g, current_app

def get_db():
    if "db" not in g:
        g.db = sqlite3.connect(
            current_app.config["DATABASE"],
            detect_types=sqlite3.PARSE_DECLTYPES,
        )
        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()

@app.route("/users")
def users():
    db = get_db()
    rows = db.execute("SELECT * FROM users").fetchall()
    return {"users": [dict(r) for r in rows]}
17

CLI 커맨드

커스텀 커맨드

@app.cli.command로 CLI 커맨드를 등록하고 click 인수/옵션으로 꾸밉니다. 독스트링이 도움말 텍스트가 됩니다. flask --help로 사용 가능한 모든 커맨드를 나열하세요.

flask
import click
from flask import Flask

app = Flask(__name__)

@app.cli.command("create-user")
@click.argument("name")
@click.option("--admin", is_flag=True, default=False)
def create_user(name, admin):
    """Create a new user."""
    role = "admin" if admin else "user"
    click.echo(f"Created {name} as {role}")

# Run: flask create-user alice --admin

flask run

flask run이 Werkzeug 개발 서버를 시작합니다. --debug는 리로더와 인터랙티브 디버거를 켭니다. --app은 모듈이나 팩토리를 가리킵니다. 이 서버는 단일 스레드이고 안전하지 않으니 프로덕션에서 절대 쓰지 마세요.

flask
# Basic
flask run

# Custom host/port
flask run --host=0.0.0.0 --port=8000

# Enable reloader and debugger
flask run --debug

# Specify the app explicitly
flask --app myapp run
flask --app myapp:create_app run

# With SSL (development)
flask run --cert=cert.pem --key=key.pem

셸 컨텍스트

shell_context_processor는 flask shell에 이름을 주입해 임포트 없이 실험하게 합니다. 모델 디버깅이나 앱 대상 애드혹 쿼리에 매우 유용합니다.

flask
from flask import Flask
from models import db, User

app = Flask(__name__)

@app.shell_context_processor
def make_shell_context():
    return {"db": db, "User": User, "app": app}

# flask shell
# >>> User.query.all()
# >>> db.session.add(User(username="x"))

CLI와 애플리케이션 팩토리

팩토리 패턴 사용 시 CLI 커맨드를 create_app 안에 등록하면 설정된 앱에 접근할 수 있습니다. Flask의 --app 옵션은 팩토리를 감지해 대신 호출합니다.

flask
# myapp/__init__.py
from flask import Flask

def create_app():
    app = Flask(__name__)
    app.config.from_object("config.Config")

    @app.cli.command("init-db")
    def init_db():
        """Initialize the database."""
        click.echo("Initialized")

    return app

# Run: flask --app myapp init-db
# The factory is detected automatically.

CLI 그룹

@app.cli.group으로 관련 커맨드를 부모 아래 묶으세요. 서브커맨드는 그룹에 등록되어 CLI가 정리됩니다: flask db init, flask db migrate 등.

flask
import click
from flask import Flask

app = Flask(__name__)

@app.cli.group("db")
def db_group():
    """Database commands."""
    pass

@db_group.command("init")
def db_init():
    click.echo("DB initialized")

@db_group.command("drop")
def db_drop():
    click.echo("DB dropped")

# flask db init
# flask db drop

환경 변수

FLASK_APP과 FLASK_DEBUG가 CLI를 설정합니다. 공유 개발 설정에는 .flaskenv를, 시크릿에는 .env를 쓰세요(python-dotenv가 설치되면 둘 다 자동 로드). .flaskenv는 보통 커밋되므로 시크릿은 넣지 마세요.

flask
# Flask reads these env vars:
# FLASK_APP      -> module/app to run (app.py, myapp, myapp:create_app)
# FLASK_DEBUG    -> 1/0 to toggle debug mode
# FLASK_ENV      -> development/production (deprecated, use FLASK_DEBUG)
# FLASK_RUN_PORT -> default port
# FLASK_RUN_HOST -> default host

# .env or .flaskenv files are auto-loaded by python-dotenv
# .flaskenv (committed): FLASK_APP=app.py
# .env (gitignored): SECRET_KEY=..., DATABASE_URL=...

# Prefer app.config.from_envvar or from_object for app secrets.
18

테스트

테스트 클라이언트 기본

test_client()는 네트워크 없이 요청을 보내는 클라이언트를 반환합니다. TESTING=True는 더 나은 오류 메시지와 오류 캐칭 비활성화를 줍니다. 각 테스트가 새 앱을 얻도록 fixture를 쓰세요.

flask
import pytest
from myapp import create_app

@pytest.fixture()
def client():
    app = create_app()
    app.config["TESTING"] = True
    with app.test_client() as client:
        with app.app_context():
            pass  # init DB here
        yield client

def test_home(client):
    resp = client.get("/")
    assert resp.status_code == 200
    assert b"Hello" in resp.data

테스트에서 요청 보내기

테스트 클라이언트는 브라우저를 흉내 냅니다: data(폼), json, query_string, headers와 함께 get/post/put/delete. JSON 응답 파싱에는 resp.get_json(), 헤더 검사에는 resp.headers를 쓰세요.

flask
def test_get(client):
    resp = client.get("/users/1")
    assert resp.status_code == 200

def test_post_form(client):
    resp = client.post("/login", data={"username": "a", "password": "b"})
    assert resp.status_code == 302  # redirect

def test_post_json(client):
    resp = client.post("/api/echo", json={"key": "value"})
    assert resp.get_json() == {"received": {"key": "value"}}

def test_query(client):
    resp = client.get("/search?q=flask&page=2")
    assert resp.status_code == 200

def test_headers(client):
    resp = client.get("/", headers={"X-Test": "1"})

JSON API 테스트

json=...을 전달하면 올바른 Content-Type으로 JSON 본문을 보냅니다. 상태, 파싱된 JSON 본문, Location 같은 헤더를 단언하세요. 성공과 오류 경로를 모두 테스트하면 API가 일관되게 동작함을 보장합니다.

flask
def test_create_user(client):
    resp = client.post(
        "/api/users",
        json={"username": "alice", "email": "[email protected]"},
    )
    assert resp.status_code == 201
    body = resp.get_json()
    assert body["username"] == "alice"
    assert "id" in body
    assert resp.headers["Location"].endswith(str(body["id"]))

def test_error(client):
    resp = client.post("/api/users", json={})
    assert resp.status_code == 422
    assert "error" in resp.get_json()

pytest 픽스처

픽스처는 재사용 가능한 셋업을 제공합니다: 인메모리 데이터베이스, 테스트 클라이언트, CLI 러너. 리소스를 yield하고 뒤에 정리하세요. test_cli_runner()는 테스트에서 CLI 커맨드를 실행하고 출력과 종료 코드를 검사합니다.

flask
import pytest
from myapp import create_app, db

@pytest.fixture()
def app():
    app = create_app()
    app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
    with app.app_context():
        db.create_all()
        yield app
        db.drop_all()

@pytest.fixture()
def client(app):
    return app.test_client()

@pytest.fixture()
def runner(app):
    return app.test_cli_runner()

def test_cli(runner):
    result = runner.invoke(args=["create-user", "alice"])
    assert result.exit_code == 0

테스트 데이터베이스

빠르고 격리된 테스트를 위해 인메모리 SQLite를 쓰세요. 픽스처 안에서 테이블을 만들고 데이터를 심은 뒤 끝에 전부 drop합니다. 각 테스트는 깨끗한 상태로 시작해 테스트 간 오염을 막습니다.

flask
import pytest
from myapp import create_app, db
from myapp.models import User

@pytest.fixture()
def app():
    app = create_app()
    app.config["TESTING"] = True
    app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///:memory:"
    with app.app_context():
        db.create_all()
        db.session.add(User(username="alice"))
        db.session.commit()
        yield app
        db.session.remove()
        db.drop_all()

def test_user_count(app):
    with app.app_context():
        assert User.query.count() == 1

목킹

patch는 외부 호출(HTTP, 이메일, 큐)을 목으로 대체해 테스트를 빠르고 결정론적으로 유지합니다. 목이 기대한 인수로 호출됐는지 단언하세요. 이름이 정의된 곳이 아니라 조회되는 곳을 patch하세요.

flask
from unittest.mock import patch, MagicMock
import myapp

def test_external_call(client):
    with patch("myapp.requests.get") as mock_get:
        mock_get.return_value = MagicMock(status_code=200, json=lambda: {"ok": True})
        resp = client.get("/proxy")
        assert resp.status_code == 200
        mock_get.assert_called_once()

def test_email(client):
    with patch("myapp.send_email") as mock_send:
        client.post("/register", data={"email": "[email protected]"})
        mock_send.assert_called_once_with("[email protected]", "Welcome!")
19

배포

프로덕션 서버 경고

Werkzeug 개발 서버는 단일 스레드이고 안전하지 않습니다 — 인터넷에 노출하지 마세요. 리버스 프록시 뒤에 프로덕션 WSGI 서버(Gunicorn, uWSGI, Waitress)를 쓰세요. 디버그 디버거는 원격 코드 실행 위험입니다.

flask
# WARNING: Flask's built-in server is for development only!
# app.run() / flask run -> single-threaded, no security, not scalable

# For production use a WSGI server:
# - Gunicorn (Linux/macOS)
# - uWSGI
# - Waitress (Windows-friendly)
# Behind a reverse proxy (Nginx, Apache, Caddy)

# The dev server also enables the interactive debugger
# when debug=True, which allows arbitrary code execution.
# NEVER deploy with debug=True.

Gunicorn

Gunicorn은 리눅스/macOS에서 가장 인기 있는 WSGI 서버입니다. (2 × CPU + 1) 워커 공식이 좋은 출발점입니다. Nginx 뒤에서는 127.0.0.1에 바인딩하고 TLS와 정적 파일은 프록시에 맡기세요.

flask
pip install gunicorn

# Basic
gunicorn "app:app"

# With factory
gunicorn "myapp:create_app()"

# Workers and binding
gunicorn -w 4 -b 0.0.0.0:8000 "app:app"

# With timeout and logging
gunicorn -w 4 -b 0.0.0.0:8000 --timeout 120 --access-logfile - "app:app"

# Recommended workers: (2 * CPU) + 1
# Use --preload to share memory, or -k gevent for async.

uWSGI

uWSGI는 고성능·고설정 WSGI 서버입니다. 마스터 프로세스가 워커를 관리하고, vacuum이 종료 시 정리합니다. 최고 처리량을 위해 Nginx와 uwsgi 프로토콜로 짝지으세요.

flask
pip install uwsgi

# Command line
uwsgi --http 0.0.0.0:8000 --module app:app --processes 4 --threads 2

# INI config (uwsgi.ini)
# [uwsgi]
# module = app:app
# http = 0.0.0.0:8000
# processes = 4
# threads = 2
# master = true
# vacuum = true
# die-on-term = true

# Run: uwsgi uwsgi.ini

리버스 프록시 (Nginx)

Nginx가 Gunicorn 앞에 섭니다: 정적 파일을 직접 서빙하고(더 빠름) TLS를 종료하며 요청을 WSGI 서버로 전달합니다. X-Forwarded-* 헤더로 Flask가 실제 클라이언트 IP와 스킴을 보게 되는데 — 이를 신뢰하도록 ProxyFix를 설정하세요.

flask
# /etc/nginx/sites-available/myapp
server {
    listen 80;
    server_name example.com;

    location /static/ {
        alias /path/to/app/static/;
        expires 30d;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;
    }
}

Docker

슬림 Python 베이스 이미지가 이미지를 작게 유지합니다. Docker의 레이어 캐시를 활용하려면 코드 복사 전에 의존성을 설치하세요. 시크릿은 환경 변수(--env-file)로 전달하고 이미지에 굽지 마세요.

flask
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]

# .dockerignore
# __pycache__/
# venv/
# *.pyc
# .env

# Build and run
# docker build -t myapp .
# docker run -p 8000:8000 --env-file .env myapp

환경 설정

설정을 계층화하세요: 코드의 기본값, 환경별 오버라이드, 환경 변수의 인스턴스 시크릿. 이로써 시크릿이 소스 관리에 새지 않고 하나의 코드베이스가 개발, 스테이징, 프로덕션에서 동작합니다.

flask
import os
from flask import Flask

app = Flask(__name__)
app.config.from_object("config.DefaultConfig")

# Override with environment-specific config
env = os.environ.get("FLASK_ENV", "development")
app.config.from_object(f"config.{env.title()}Config")

# Then instance-specific secrets from env vars
app.config["SECRET_KEY"] = os.environ["SECRET_KEY"]
app.config["SQLALCHEMY_DATABASE_URI"] = os.environ["DATABASE_URL"]

# Use python-dotenv for local .env files
from dotenv import load_dotenv
load_dotenv()
20

설정

Config 객체

설정을 기본 Config를 상속하는 클래스로 정의하세요. 환경마다 바뀌는 것만 오버라이드합니다. from_object는 대문자 속성을 app.config로 복사하므로 소문자 헬퍼는 무시됩니다.

flask
class Config:
    DEBUG = False
    TESTING = False
    SECRET_KEY = "change-me"
    SQLALCHEMY_DATABASE_URI = "sqlite:///app.db"

class DevelopmentConfig(Config):
    DEBUG = True
    SECRET_KEY = "dev-secret"

class ProductionConfig(Config):
    DEBUG = False
    SECRET_KEY = os.environ["SECRET_KEY"]

class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"

app.config.from_object(DevelopmentConfig)

환경 변수

시크릿에는 os.environ을 써 코드에 존재하지 않게 하세요. from_envvar은 환경 변수가 가리키는 Python 파일을 불러옵니다 — 배포별 오버라이드에 유용합니다. python-dotenv는 로컬 개발용 .env 파일을 로드합니다.

flask
import os
from flask import Flask

app = Flask(__name__)

# Read individual values
app.config["SECRET_KEY"] = os.environ.get("SECRET_KEY", "dev")
app.config["DATABASE_URL"] = os.environ.get("DATABASE_URL", "sqlite:///app.db")

# Load a whole config file from an env var path
# export MYAPP_SETTINGS=/etc/myapp/prod.py
app.config.from_envvar("MYAPP_SETTINGS", silent=True)

# python-dotenv loads .env automatically if installed
from dotenv import load_dotenv
load_dotenv()

인스턴스 폴더

인스턴스 폴더는 배포별 파일(시크릿, 설정)을 버전 관리 밖에 둡니다. instance_relative_config=True를 두고 from_pyfile로 불러오세요. 코드와 환경 설정이 깔끔하게 분리됩니다.

flask
# The instance/ folder sits outside the package, not in VCS.
# Flask searches it automatically for config files.

app = Flask(__name__, instance_relative_config=True)

# Load from instance/config.py
app.config.from_pyfile("config.py", silent=True)

# instance/config.py (deployment-specific, gitignored)
# SECRET_KEY = "real-production-key"
# SQLALCHEMY_DATABASE_URI = "postgresql://user:pass@db/app"

# Access the path
print(app.instance_path)  # /abs/path/to/instance

파일에서 설정

from_object는 모듈이나 객체 경로를 임포트하고, from_pyfile은 절대 파일을 로드하며, from_file(Flask 2.0+)은 로더 함수로 JSON, TOML, YAML을 지원합니다. 하나의 형식을 정해 일관되게 유지하세요.

flask
# config.py
DEBUG = True
SECRET_KEY = "dev"
SQLALCHEMY_DATABASE_URI = "sqlite:///dev.db"

# Load a Python file
app.config.from_object("config")

# Load by path
app.config.from_pyfile("/etc/myapp/config.py")

# Load from a JSON file
app.config.from_file("config.json", load=json.load)

# config.json
# { "DEBUG": true, "SECRET_KEY": "dev" }

개발 vs 프로덕션

환경 변수로 설정을 전환하면 같은 코드가 어디서든 실행됩니다. 프로덕션은 반드시 debug를 끄고(디버거가 보안 구멍입니다) 실제 데이터베이스를 쓰세요. 프로덕션에서 debug가 켜져 있으면 경고를 로그하세요.

flask
import os
from flask import Flask

env = os.environ.get("FLASK_ENV", "development")

configs = {
    "development": DevelopmentConfig,
    "production": ProductionConfig,
    "testing": TestingConfig,
}

app = Flask(__name__)
app.config.from_object(configs[env])

# In production, never enable debug:
if app.config["DEBUG"]:
    print("WARNING: running in debug mode!")

로깅 설정

로깅 설정은 debug 모드가 아닐 때만 하세요(Flask는 debug에서 기본적으로 stderr에 로그합니다). RotatingFileHandler는 무한 로그 성장을 막습니다. 프로덕션에서는 집계 서비스를 위해 구조화된 JSON 로깅을 고려하세요.

flask
import logging
from logging.handlers import RotatingFileHandler

if not app.debug:
    handler = RotatingFileHandler("app.log", maxBytes=10*1024*1024, backupCount=5)
    handler.setFormatter(logging.Formatter(
        "%(asctime)s %(levelname)s: %(message)s [in %(pathname)s:%(lineno)d]"
    ))
    handler.setLevel(logging.INFO)
    app.logger.addHandler(handler)
    app.logger.setLevel(logging.INFO)

# In a view
@app.route("/")
def index():
    app.logger.info("Index page accessed")
    return "Hello"

# Flask's logger is a standard logging.Logger

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.