Flask에서 스크립트 기반 명령어 관리: Flask-Script와 Flask-CLI 활용

Flask-Script를 사용한 애플리케이션 제어

일반적으로 Flask 앱은 app.run()을 호출하여 직접 실행할 수 있지만, 프로젝트 규모가 커지면 명령어 기반으로 서버를 제어하는 것이 더 효율적입니다. 이때 Flask-Script는 개발자가 터미널에서 다양한 커스텀 명령어를 통해 애플리케이션을 관리할 수 있도록 도와줍니다.

Flask-Script는 외부 라이브러리이므로 버전 호환성을 반드시 확인해야 합니다. 예를 들어 다음과 같은 조합이 일반적입니다:

Flask==2.2.2
Flask-Script==2.0.3

기본 서버 실행 설정

주로 manage.py 파일에 Manager 인스턴스를 생성하여 CLI 기능을 추가합니다.

from flask import Flask
from flask_script import Manager

app = Flask(__name__)
manager = Manager(app)

@manager.command
def run():
    app.run(debug=True)

if __name__ == '__main__':
    manager.run()

터미널에서 아래와 같이 서버를 구동할 수 있습니다:

python manage.py run
# 또는 기본 제공 명령어 사용
python manage.py runserver

사용자 정의 간단 명령어

특정 작업을 자동화하기 위해 파라미터를 받는 커스텀 명령어를 정의할 수 있습니다.

@manager.command
def init_data(path):
    print(f"데이터 초기화 중: {path}")
    # 실제 로직 (예: JSON 파일 로드, DB 삽입 등)

실행 예시:

python manage.py init_data ./data/sample.json

이러한 명령어는 Celery 워커나 비동기 스케줄러(BEAT) 시작과 같은 부팅 전처리 작업에 유용합니다. 내부적으로 subprocess를 사용해 별도 프로세스를 실행할 수 있습니다.

복잡한 옵션 기반 명령어

여러 옵션을 처리해야 할 경우 @manager.option 데코레이터를 활용합니다.

@manager.option('-n', '--name', dest='username')
@manager.option('-e', '--email', dest='email')
def create_user(username, email):
    print(f"새 사용자 생성: {username}, 이메일: {email}")
    # DB 저장 로직 삽입 가능

실행 방법:

python manage.py create_user -n john -e john@example.com
python manage.py create_user --name alice --email alice@domain.com

각 옵션은 단축형(-n), 장축형(--name) 모두 지원하며, dest는 함수 매개변수 이름과 일치해야 합니다.

Flask-CLI: 공식 명령줄 인터페이스

최근 Flask는 내장 CLI 시스템(Flask-CLI)을 제공하며, 더 이상 Flask-Script에 의존하지 않아도 됩니다. 이는 Click 라이브러리를 기반으로 하며, 확장성과 표준화 측면에서 우수합니다.

주요 사용 사례

사전 준비 작업: 서버 구동 전 데이터베이스 마이그레이션이나 테이블 생성 등 환경 설정이 필요할 때.
커스텀 관리 명령: 배치 데이터 처리, 로그 정리, 테스트 데이터 삽입 등 반복 작업 자동화.
컨테이너 배포: Docker 환경에서 FLASK_APP로 진입점을 명시하면 명령어 실행이 용이함.
환경 분리: 개발/운영 환경별로 다른 명령어를 실행하여 충돌 없이 관리 가능.

Flask-CLI 사용법

자동 인식 모드

파일명을 app.py로 하고 최상위에 app = Flask(__name__)을 선언하면 자동 인식됩니다.

python -m flask run
python -m flask custom-command

스크립트 직접 실행

다른 이름의 파일에서도 CLI 명령어를 정의할 수 있습니다.

# server.py 예시
from flask import Flask
import click

app = Flask(__name__)

@app.cli.command()
def deploy():
    click.echo("배포 절차 시작")

# 터미널
python server.py deploy

환경 변수로 지정 (FLASK_APP)

특히 컨테이너나 가상 환경에서는 아래처럼 진입점을 명확히 지정합니다.

export FLASK_APP=src.application:create_app()
export FLASK_ENV=development
python -m flask run

여기서 create_app()은 팩토리 패턴으로 생성된 인스턴스를 반환해야 하며, 이렇게 하면 복잡한 구조에서도 CLI를 안정적으로 사용할 수 있습니다.

태그: Flask-Script Flask-CLI python Click cli

6월 1일 07:24에 게시됨

괴물 클럽