argparse — 커맨드라인 옵션·인자·서브커맨드 파서

(3.2 추가, 소스: Lib/argparse.py)

참고: argparse가 기본적인 커맨드라인 애플리케이션 구현을 위한 표준 라이브러리 모듈로 권장되지만, 커맨드라인 애플리케이션의 정확한 동작에 대해 더 엄격한 요구사항이 있는 작성자는 필요한 수준의 제어를 제공하지 못한다는 걸 알 수 있어요. argparse가 요구하는 동작을 지원하지 않을 때(예: 옵션과 위치 인자가 섞이는 걸 완전히 비활성화하거나, 다른 정의된 옵션에 해당하더라도 -로 시작하는 옵션 매개변수 값을 받는 것) 고려할 대안은 "Choosing an argument parsing library"를 참고하세요.

이 페이지는 API 레퍼런스 정보예요. 파이썬 커맨드라인 파싱에 대한 더 부드러운 입문은 argparse 튜토리얼을 보세요.

argparse 모듈은 사용자 친화적인 커맨드라인 인터페이스를 쉽게 작성하게 해 줘요. 프로그램이 필요한 인자를 정의하면 argparse가 그걸 sys.argv에서 어떻게 파싱할지 알아내요. argparse 모듈은 도움말과 사용법(usage) 메시지를 자동으로 생성하고, 사용자가 유효하지 않은 인자를 주면 오류도 발생시켜요.

argparse의 커맨드라인 인터페이스 지원은 argparse.ArgumentParser 인스턴스를 중심으로 구축돼요. 그것은 인자 사양의 컨테이너이고 파서 전체에 적용되는 옵션이 있어요.

parser = argparse.ArgumentParser(
                    prog='ProgramName',
                    description='What the program does',
                    epilog='Text at the bottom of help')

ArgumentParser.add_argument() 메서드가 개별 인자 사양을 파서에 붙여요. 위치 인자, 값을 받는 옵션, on/off 플래그를 지원해요.

parser.add_argument('filename')           # positional argument
parser.add_argument('-c', '--count')      # option that takes a value
parser.add_argument('-v', '--verbose',
                    action='store_true')  # on/off flag

ArgumentParser.parse_args() 메서드는 파서를 실행하고 추출된 데이터를 argparse.Namespace 객체에 넣어요.

출처: Python documentation

본문

`ArgumentParser` 객체

ArgumentParser 생성자는 여러 옵션을 받아요.

prog: 프로그램 이름 (기본 sys.argv[0]의 basename).
usage: 사용법 메시지. 기본은 자동 생성.
description: 도움말에서 인자 도움말 앞에 표시되는 텍스트.
epilog: 도움말에서 인자 도움말 뒤에 표시되는 텍스트.
parents: 다른 ArgumentParser 객체 리스트로, 그들의 인자를 이 파서로 가져와요.
formatter_class: 도움말 포맷팅 커스터마이즈. RawDescriptionHelpFormatter, RawTextHelpFormatter, ArgumentDefaultsHelpFormatter, MetavarTypeHelpFormatter.
prefix_chars: 옵션이 시작하는 문자 집합 (기본 '-'). 예: -f/--foo 대신 +f/++foo를 쓰려면 prefix_chars='+'.
fromfile_prefix_chars: 추가 인자를 담은 파일을 읽도록 하는 문자 집합 (기본 None).
argument_default: 인자의 전역 기본값 (기본 None).
allow_abbrev: 접두사 매칭으로 옵션 축약 허용 여부 (기본 True).
conflict_handler: 충돌하는 옵션 문자열을 해결하는 전략 ('error' 또는 'resolve', 기본 'error').
add_help: -h/--help 옵션 추가 여부 (기본 True).
exit_on_error: parse_args()가 오류 시 2의 상태 코드로 프로그램을 종료할지 (기본 True). False면 ArgumentError를 발생.
suggest_on_error: 오류가 나면 유사한 옵션 제안 표시 여부 (기본 False).
color: 오류와 도움말 출력에 색상을 사용할지 ('auto', 'always', 'never', 기본 'auto').

`add_argument()` 메서드

name or flags: 'foo' 같은 위치 인자 이름 또는 '-f', '--foo' 같은 옵션 문자열.
action: 커맨드라인 인자를 만났을 때 할 일. 'store'(기본), 'store_const', 'store_true', 'store_false', 'append', 'append_const', 'count', 'help', 'version', 'extend', 사용자 정의 Action 클래스나 함수.
nargs: 소비할 커맨드라인 인자 수. 정수, '?'(0 또는 1), '*' (0 이상), '+' (1 이상), 'REMAINDER'.
const: action과 nargs에 쓰는 상수.
default: 인자가 없을 때 쓰는 값.
type: 커맨드라인 인자를 변환할 타입 (기본 str). open, int, float 등.
choices: 허용되는 값의 컨테이너.
required: 옵션 인자를 필수로 할지 (기본 False).
help: 이 인자에 대한 간단한 설명.
metavar: 도움말에서 사용되는 인자 이름.
dest: parse_args()의 반환 Namespace에서 이 인자가 저장될 속성 이름.
deprecated: 해당 인자가 deprecated임을 표시.

기본 액션 클래스 외에도 Action 클래스를 서브클래스화해 커스텀 동작을 만들 수 있어요.

`parse_args()` 메서드

parse_args(args=None, namespace=None): args(기본 sys.argv[1:])를 파싱해 Namespace를 반환.
옵션 값 문법: -f value, -fvalue, --foo=value 등 다양한 형태를 지원.
잘못된 인자: 사용자가 잘못된 옵션을 주면 오류가 나고 도움말이 표시돼요.
-를 포함한 인자: - 단독은 위치 인자로, --는 그 뒤를 모두 위치 인자로 취급.
인자 축약(접두사 매칭): --verb 같은 긴 옵션의 유일한 접두사가 있으면 축약 허용.
parse_known_args(args=None, namespace=None): 알려지지 않은 인자는 무시하고 (남은 인자, Namespace) 튜플 반환.
parse_intermixed_args(args=None, namespace=None): 옵션과 위치 인자가 섞인 것을 다룸.

Namespace 객체

parse_args()는 argparse.Namespace 객체를 반환해요. 속성에 인자 값이 저장되고, vars()로 사전으로 변환하거나 Namespace(**kwargs)로 직접 만들 수 있어요.

기타 유틸리티

서브커맨드 (Subcommands): add_subparsers()로 하위 파서를 만들어 git commit 같은 서브커맨드 구조를 지원해요.
class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None): 파일을 여는 커스텀 타입 팩토리.
인자 그룹 (Argument groups): add_argument_group()로 도움말을 논리 그룹으로 나누기.
상호 배제 (Mutual exclusion): add_mutually_exclusive_group()으로 하나만 허용되는 인자 그룹 만들기.
파서 기본값 (Parser defaults): set_defaults()로 파서 수준 기본값 설정.
도움말 인쇄: print_help(), print_usage(), format_help(), format_usage().
부분 파싱: parse_known_args().
종료 메서드: exit(), error().
사용자 정의 타입/액션 등록: register().
예외: ArgumentError, ArgumentTypeError. exit_on_error=False일 때 parse_args()는 ArgumentError를 발생시켜요.

더 알아보기 (Learn more)

Python 공식 문서

argparse — 커맨드라인 옵션·인자·서브커맨드 파서