`argparse` — 명령줄 옵션, 인자 및 하위 명령어용 파서¶

Added in version 3.2.

참고

argparse 가 기본적인 명령줄 애플리케이션을 구현하기 위한 기본 권장 표준 라이브러리 모듈이지만, 명령줄 애플리케이션이 정확히 어떻게 동작해야 하는지에 대해 더 까다로운 요구사항을 가진 작성자는 필요한 통제 수준을 제공하지 않는 것을 발견할 수 있습니다. argparse 가 응용 프로그램이 요구하는 동작(예: 간헐적으로 끼워 넣는 옵션 및 위치 인자 지원 완전히 비활성화, 또는 다른 정의된 옵션에 해당하는 경우에도 - 로 시작하는 옵션 매개변수 값 허용)을 지원하지 않을 때 고려할 대안은 인자 구문 분석 라이브러리 선택하기 를 참조하십시오.

argparse 모듈은 사용자 친화적인 명령줄 인터페이스를 작성하기 쉽도록 만듭니다. 프로그램을 정의할 때 필요한 인자를 지정하고, argparse`는 그것들을 :data:`sys.argv`에서 파싱하는 방법을 알아냅니다. 또한, :mod:!argparse` 모듈은 도움말과 사용법 메시지를 자동으로 생성합니다. 이 모듈은 사용자에게 유효하지 않은 인자가 주어질 때 오류를 발생시키기도 합니다.

argparse 모듈의 명령줄 인터페이스 지원은 argparse.ArgumentParser 인스턴스를 중심으로 구축됩니다. 이는 인자 사양을 담는 컨테이너이며 파서 전체에 적용되는 옵션을 가지고 있습니다.

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

ArgumentParser.add_argument() 메서드는 개별적인 인자 사양을 파서에 부착합니다. 이 메서드는 위치 기반 인자, 값을 받아들이는 옵션, 그리고 켜기/끄기 플래그를 지원합니다.

parser.add_argument('filename')           # 위치 인자
parser.add_argument('-c', '--count')      # 값을 받는 옵션
parser.add_argument('-v', '--verbose',
                    action='store_true')  # 켜기/끄기 플래그

ArgumentParser.parse_args() 메서드는 파서를 실행하고 추출된 데이터를 argparse.Namespace 객체에 저장합니다.

args = parser.parse_args()
print(args.filename, args.count, args.verbose)

참고

optparse 코드를 :mod:`!argparse`로 업그레이드하는 방법에 대한 가이드는 :ref:`Upgrading Optparse Code <upgrading-optparse-code>`를 참조하십시오.

ArgumentParser 객체¶

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True, *, suggest_on_error=True, color=True)¶

새로운 ArgumentParser 객체를 만듭니다. 모든 매개 변수는 키워드 인자로 전달되어야 합니다. 매개 변수마다 아래에서 더 자세히 설명되지만, 요약하면 다음과 같습니다:

prog - 프로그램의 이름 (기본값: __main__ 모듈 속성과 sys.argv[0] 에서 생성됩니다.)
usage - 프로그램 사용법을 설명하는 문자열 (기본값: 파서에 추가된 인자로부터 만들어지는 값)
description - 인자 도움말 이전에 표시할 텍스트입니다 (기본적으로, 텍스트 없음)
epilog - 인자 도움말 이후에 표시할 텍스트입니다 (기본적으로, 텍스트 없음)
parents - ArgumentParser 객체들의 리스트이고, 이 들의 인자들도 포함된다
formatter_class - 도움말 출력을 사용자 정의하기 위한 클래스
prefix_chars - 선택 인자 앞에 붙는 문자 집합 (기본값: ‘-‘).
fromfile_prefix_chars - 추가 인자를 읽어야 하는 파일 앞에 붙는 문자 집합 (기본값: None).
argument_default - 인자의 전역 기본값 (기본값: None)
conflict_handler - 충돌하는 선택 사항을 해결하기 위한 전략 (일반적으로 불필요함)
add_help - 파서에 -h/--help 옵션을 추가합니다 (기본값: True)
allow_abbrev - 축약어가 모호하지 않은 경우 긴 옵션을 축약할 수 있도록 허용합니다 (기본값: True)
exit_on_error - 오류가 발생했을 때 ArgumentParser`가 오류 정보를 포함하여 종료할지 여부를 결정합니다. (기본값: ``True`)
suggest_on_error - 잘못 입력된 인자 선택지 및 하위 파서 이름에 대한 제안을 활성화합니다 (기본값: True).
color - 색상 출력을 허용합니다 (기본값: True).

버전 3.5에서 변경: allow_abbrev 매개 변수가 추가되었습니다.

버전 3.8에서 변경: 이전 버전에서는, allow_abbrev는 -vv가 -v -v를 뜻하는 것과 같은 짧은 플래그의 그룹화도 비활성화했습니다.

버전 3.9에서 변경: exit_on_error 매개 변수가 추가되었습니다.

버전 3.14에서 변경: suggest_on_error 및 color 매개변수가 추가되었습니다.

버전 3.15에서 변경: suggest_on_error 의 기본값이 True 로 변경되었습니다.

다음 절에서는 이들 각각의 사용 방법에 관해 설명합니다.

prog¶

기본적으로, :class:`ArgumentParser`는 파이썬 해석기가 실행된 방식에 따라 도움말 메시지에 표시할 프로그램 이름을 계산합니다:

파일로 인자가 전달된 경우 sys.argv[0] 의 base name 입니다.
디렉토리나 zip 파일을 인자로 전달한 경우 파이썬 해석기 이름과 sys.argv[0] 입니다.
The Python interpreter name followed by -m followed by the module or package name if the -m option was used.

이 기본값은 일반적으로 매우 바람직합니다. 왜냐하면 도움말 메시지에 프로그램 호출 시 사용된 문자열과 일치시키기 때문입니다. 그러나 이 기본 동작을 변경하려면, ArgumentParser`에 ``prog=` 인자를 사용하여 다른 값을 제공할 수 있습니다:

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]

options:
 -h, --help  show this help message and exit

프로그램의 이름은 sys.argv[0]``에서 결정되든, ``__main__ 모듈 속성을 통해 결정되든, 또는 prog= 인자를 통해 제공되든 상관없이, 도움말 메시지에서는 %(prog)s 형식 지정자를 사용하여 사용할 수 있습니다.

>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]

options:
 -h, --help  show this help message and exit
 --foo FOO   foo of the myprogram program

버전 3.14에서 변경: 기본 prog 값은 이제 항상 os.path.basename(sys.argv[0]) 이 아니라, __main__ 가 실제로 실행된 방식을 반영합니다.

usage¶

기본적으로 ArgumentParser`는 포함된 인자들로부터 사용법 메시지를 계산합니다. 기본 메시지는 ``usage=` 키워드 인자를 통해 재정의할 수 있습니다:

>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]

positional arguments:
 bar          bar help

options:
 -h, --help   show this help message and exit
 --foo [FOO]  foo help

%(prog)s 포맷 지정자는 사용법 메시지에서 프로그램 이름을 채울 때 사용할 수 있습니다.

주 파서에 사용자 정의 사용법 메시지가 지정된 경우, 일관된 명령 접두사 및 사용 정보를 보장하기 위해 add_subparsers`에 ``prog`() 인자를 전달하거나 add_parser`에 ``prog``와 ``usage`() 인자를 전달하는 것도 고려할 수 있습니다.

description¶

ArgumentParser 생성자의 대부분의 호출은 description= 키워드 인자를 사용할 것입니다. 이 인자는 프로그램이 무엇을 하고 어떻게 작동하는지에 대한 간략한 설명을 제공합니다. 도움말 메시지에서 설명은 명령줄 사용법 문자열과 다양한 인자에 대한 도움말 메시지 사이에 표시됩니다.

기본적으로, 설명은 주어진 공간에 맞도록 줄 바꿈 됩니다. 이 동작을 변경하려면 formatter_class 인자를 참조하십시오.

epilog¶

일부 프로그램은 인자에 대한 설명 뒤에 프로그램에 대한 추가 설명을 표시하려고 합니다. 이러한 텍스트는 epilog= 에 대한 인자를 ArgumentParser 에 사용하여 지정할 수 있습니다:

>>> parser = argparse.ArgumentParser(
...     description='A foo that bars',
...     epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]

A foo that bars

options:
 -h, --help  show this help message and exit

And that's how you'd foo a bar

description 인자와 마찬가지로, epilog= 텍스트가 기본적으로 줄 바꿈 됩니다만, 이 동작은 formatter_class 인자를 ArgumentParser 에 제공해서 조정할 수 있습니다.

parents¶

때로는 여러 파서가 공통 인자 집합을 공유하는 경우가 있습니다. 이러한 인자의 정의를 반복하는 대신, 모든 공유 인자를 갖는 파서를 ArgumentParser 에 parents= 인자로 전달할 수 있습니다. parents= 인자는 ArgumentParser 객체의 리스트를 취하여, 그것들로부터 모든 위치와 선택 액션을 수집해서 새로 만들어지는 ArgumentParser 객체에 추가합니다:

>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)

>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)

대부분의 부모 파서는 add_help=False 를 지정합니다. 그렇지 않으면, ArgumentParser 는 (하나는 부모에, 하나는 자식에 있는) 두 개의 -h/--help 옵션을 보게 될 것이고, 에러를 발생시킵니다.

참고

parents= 를 통해 전달하기 전에 파서를 완전히 초기화해야 합니다. 자식 파서 다음에 부모 파서를 변경하면 자식에 반영되지 않습니다.

formatter_class¶

ArgumentParser 객체는 대체 포매팅 클래스를 지정함으로써 도움말 포매팅을 사용자 정의 할 수 있도록 합니다. 현재 네 가지 클래스가 있습니다:

class argparse.RawDescriptionHelpFormatter¶
class argparse.RawTextHelpFormatter¶
class argparse.ArgumentDefaultsHelpFormatter¶
class argparse.MetavarTypeHelpFormatter¶

RawDescriptionHelpFormatter 와 RawTextHelpFormatter 는 텍스트 설명이 표시되는 방법을 더 제어할 수 있도록 합니다. 기본적으로, ArgumentParser 객체는 명령행 도움말 메시지에서 description 및 epilog 텍스트를 줄 바꿈 합니다.:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     description='''this description
...         was indented weird
...             but that is okay''',
...     epilog='''
...             likewise for this epilog whose whitespace will
...         be cleaned up and whose words will be wrapped
...         across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]

this description was indented weird but that is okay

options:
 -h, --help  show this help message and exit

likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines

RawDescriptionHelpFormatter 를 formatter_class= 로 전달하는 것은 description 과 epilog 가 이미 올바르게 포맷되어 있어서 줄 바꿈 되어서는 안 된다는 것을 가리킵니다:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description=textwrap.dedent('''\
...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I want it
...         '''))
>>> parser.print_help()
usage: PROG [-h]

Please do not mess up this text!
--------------------------------
   I have indented it
   exactly the way
   I want it

options:
 -h, --help  show this help message and exit

:class:`RawTextHelpFormatter`는 인자 설명을 포함한 모든 종류의 도움말 텍스트에 공백을 유지합니다. 하지만 여러 개의 새 줄은 하나로 대체됩니다. 여러 개의 빈 줄을 보존하려면, 새 줄 사이에 공백을 추가해야 합니다.:

ArgumentDefaultsHelpFormatter 는 기본값에 대한 정보를 각각의 인자 도움말 메시지에 자동으로 추가합니다:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar ...]

positional arguments:
 bar         BAR! (default: [1, 2, 3])

options:
 -h, --help  show this help message and exit
 --foo FOO   FOO! (default: 42)

MetavarTypeHelpFormatter 는 각 인자 값의 표시 이름으로 (일반 포매터처럼 dest 를 사용하는 대신에) type 인자의 이름을 사용합니다:

>>> parser = argparse.ArgumentParser(
...     prog='PROG',
...     formatter_class=argparse.MetavarTypeHelpFormatter)
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', type=float)
>>> parser.print_help()
usage: PROG [-h] [--foo int] float

positional arguments:
  float

options:
  -h, --help  show this help message and exit
  --foo int

prefix_chars¶

대부분의 명령줄 옵션은 -``를 접두사로 사용합니다. 예: ``-f/--foo. +f``나 ``/foo 같은 옵션을 위해 다르거나 추가적인 접두사 문자를 지원해야 하는 파서는 ArgumentParser 생성자의 prefix_chars= 인자를 사용하여 이를 지정할 수 있습니다:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')

prefix_chars= 인자의 기본값은 '-' 입니다. - 를 포함하지 않는 문자 집합을 제공하면 -f/--foo 옵션이 허용되지 않게 됩니다.

fromfile_prefix_chars¶

때로는 특히 긴 인자 목록을 다룰 때, 명령줄에 입력하는 것보다 파일에 인자 목록을 유지하는 것이 좋을 수 있습니다. 만약 ArgumentParser 생성자에 fromfile_prefix_chars= 인자가 주어지면, 지정된 문자 중 어느 것으로 시작하는 인자는 파일을 검색한 것으로 간주되어 그 파일이 포함하는 인자로 대체됩니다. 예를 들면:

>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:
...     fp.write('-f\nbar')
...
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')

파일에서 읽은 인자는 기본적으로 한 줄에 하나여야 합니다 (하지만 convert_arg_line_to_args() 도 참조하세요) 그리고 명령줄의 원본 파일을 참조하는 인자와 동일한 위치에 있는 것처럼 처리됩니다. 따라서 위의 예시에서, ['-f', 'foo', '@args.txt'] 는 표현식 ['-f', 'foo', '-f', 'bar'] 와 동등하다고 간주됩니다:

참고

각 줄은 단일 인자로 처리되므로, 빈 줄도 빈 문자열('')로 읽힙니다.:

ArgumentParser uses filesystem encoding and error handler to read the file containing arguments.

fromfile_prefix_chars= 인자의 기본값은 None 입니다. 이것은 인자가 절대로 파일 참조로 취급되지 않는다는 것을 의미합니다.

버전 3.12에서 변경: ArgumentParser changed encoding and errors to read arguments files from default (e.g. locale.getpreferredencoding(False) and "strict") to the filesystem encoding and error handler. Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows.

argument_default¶

일반적으로 인자의 기본값은 add_argument() 에 기본값을 전달하거나 특정 이름-값 쌍 집합을 사용하여 set_defaults() 메서드를 호출하여 지정됩니다. 그러나 때로는, 파서 전체에 적용되는 단일 기본값을 지정하는 것이 유용 할 수 있습니다. 이것은 argument_default= 키워드 인자를 ArgumentParser 에 전달함으로써 이루어질 수 있습니다. 예를 들어, parse_args() 호출에서 어트리뷰트 생성을 전역적으로 억제하려면, argument_default=SUPPRESS 를 제공합니다:

>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()

allow_abbrev¶

일반적으로 ArgumentParser 의 parse_args() 메서드에 인자 리스트를 건네주면 긴 옵션의 약어를 인식합니다.

allow_abbrev 를 False 로 설정하면 이 기능을 비활성화 할 수 있습니다:

>>> parser = argparse.ArgumentParser(prog='PROG', allow_abbrev=False)
>>> parser.add_argument('--foobar', action='store_true')
>>> parser.add_argument('--foonley', action='store_false')
>>> parser.parse_args(['--foon'])
usage: PROG [-h] [--foobar] [--foonley]
PROG: error: unrecognized arguments: --foon

Added in version 3.5.

conflict_handler¶

ArgumentParser 객체는 같은 옵션 문자열을 가진 두 개의 액션을 허용하지 않습니다. 기본적으로 ArgumentParser 객체는 이미 사용 중인 옵션 문자열로 인자를 만들려고 시도하면 예외를 발생시킵니다

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
 ..
ArgumentError: argument --foo: conflicting option string(s): --foo

때로는 (예를 들어 parents 를 사용하는 경우) 같은 옵션 문자열을 갖는 예전의 인자들을 간단히 대체하는 것이 유용 할 수 있습니다. 이 동작을 얻으려면, ArgumentParser 의 conflict_handler= 인자에 'resolve' 값을 제공합니다:

>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]

options:
 -h, --help  show this help message and exit
 -f FOO      old foo help
 --foo FOO   new foo help

ArgumentParser 객체는 모든 옵션 문자열이 재정의된 경우에만 액션을 제거합니다. 위의 예에서, 이전의 -f/--foo 액션은 --foo 옵션 문자열만 재정의되었기 때문에 -f 액션으로 유지됩니다.

add_help¶

기본적으로, ArgumentParser 객체는 파서의 도움말 메시지를 표시하는 옵션을 추가합니다. 명령줄에서 -h 또는 --help 가 제공되면, ArgumentParser 도움이 출력됩니다:

때에 따라, 이 도움말 옵션을 추가하지 않도록 설정하는 것이 유용 할 수 있습니다. add_help= 인자를 False 로 ArgumentParser 에 전달하면 됩니다:

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]

options:
 --foo FOO  foo help

도움말 옵션은 일반적으로 -h/--help 입니다. 예외는 prefix_chars= 가 지정되고 - 을 포함하지 않는 경우입니다. 이 경우 -h 와 --help 는 유효한 옵션이 아닙니다. 이 경우, prefix_chars 의 첫 번째 문자가 도움말 옵션 접두어로 사용됩니다:

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]

options:
  +h, ++help  show this help message and exit

exit_on_error¶

일반적으로, ArgumentParser 의 parse_args() 메소드에 잘못된 인자 목록을 전달하면, sys.stderr 로 메시지 를 출력하고 상태 코드 2와 함께 종료됩니다:

사용자가 수동으로 오류를 처리하려면, exit_on_error 를 False 로 설정하여 이 기능을 활성화할 수 있습니다:

>>> parser = argparse.ArgumentParser(exit_on_error=False)
>>> parser.add_argument('--integers', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, choices=None, help=None, metavar=None)
>>> try:
...     parser.parse_args('--integers a'.split())
... except argparse.ArgumentError:
...     print('Catching an argumentError')
...
Catching an argumentError

Added in version 3.9.

suggest_on_error¶

기본적으로, 사용자가 유효하지 않은 인자 선택지나 서브파서 이름을 전달하면 :class:`ArgumentParser`는 오류 정보와 오타가 있는 인자에 대한 제안을 제공하며 종료됩니다. 에러 메시지는 허용되는 인자 선택지 (지정된 경우) 또는 서브파서 이름과, 근접하게 일치하는 항목이 발견되면 “혹시 다음을 의도하셨나요”라는 제안 목록을 함께 보여줄 것입니다. 참고로 이는 지정된 선택지가 문자열인 인자에만 적용됩니다:

>>> parser = argparse.ArgumentParser(suggest_on_error=True)
>>> parser.add_argument('--action', choices=['debug', 'dryrun'])
>>> parser.parse_args(['--action', 'debugg'])
usage: tester.py [-h] [--action {debug,dryrun}]
tester.py: error: argument --action: invalid choice: 'debugg', maybe you meant 'debug'? (choose from debug, dryrun)

suggest_on_error 를 False 로 설정하여 제안 기능을 비활성화할 수 있습니다:

Added in version 3.14.

버전 3.15에서 변경: suggest_on_error 의 기본값이 False 에서 True 로 변경되었습니다:

색상¶

기본적으로 도움말 메시지는 ANSI escape sequences <https://en.wikipedia.org/wiki/ANSI_escape_code> 를 사용하여 색상으로 출력됩니다. 만약 일반 텍스트 도움말 메시지를 원한다면, 로컬 환경에서 에서 이를 비활성화하거나 아규먼트 파서 자체에서 color``를 ``False `로 설정할 수 있습니다:

>>> parser = argparse.ArgumentParser(description='Process some integers.',
...                                  color=False)
>>> parser.add_argument('--action', choices=['sum', 'max'])
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
...                     help='an integer for the accumulator')
>>> parser.parse_args(['--help'])

참고로, color=True 일 때 색상 출력은 환경 변수와 터미널 기능 모두에 따라 달라집니다. 하지만 color=False 이면, FORCE_COLOR 같은 환경 변수가 설정되어 있더라도 색상 출력은 항상 비활성화됩니다:

Added in version 3.14.

설명, 에필로그 또는 인자 help 텍스트의 인라인 코드를 강조하려면, 백틱을 사용하거나 쌍따옴표 백틱을 사용할 수 있습니다:

>>> parser = argparse.ArgumentParser(
...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description='Run ``python -m myapp`` to start.',
...     epilog='''Examples:
...   `python -m myapp --verbose`
...   ``python -m myapp --config settings.json``
... ''')
>>> parser.add_argument('--foo', help='set the `foo` value')

색상이 활성화될 때, 백틱 내부의 텍스트는 예시가 눈에 잘 띄도록 구분된 색상으로 표시됩니다. 색상이 비활성화되면 백틱은 그대로 유지되며, 일반 텍스트에서도 읽을 수 있습니다:

Added in version 3.15.

add_argument() 메서드¶

ArgumentParser.add_argument(name or flags..., *[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest][, deprecated])¶

단일 명령행 인자를 구문 분석하는 방법을 정의합니다. 매개 변수마다 아래에서 더 자세히 설명되지만, 요약하면 다음과 같습니다:

name or flags - 이름 또는 옵션 문자열 목록입니다. 예: 'foo' 또는 '-f', '--foo' 입니다:
action - 명령행에서 이 인자가 발견될 때 수행 할 액션의 기본형.
nargs - 소비되어야 하는 명령행 인자의 수.
const - 일부 action 및 nargs 를 선택할 때 필요한 상숫값.
default - 인자가 명령행에 없고 namespace 객체에 없으면 생성되는 값.
type - 명령행 인자가 변환되어야 할 형.
choices - 인자 허용 값의 시퀀스입니다:
required - 명령행 옵션을 생략 할 수 있는지 아닌지 (선택적일 때만).
help - 인자가 하는 일에 대한 간단한 설명.
metavar - 사용 메시지에 사용되는 인자의 이름.
dest - parse_args() 가 반환하는 객체에 추가될 어트리뷰트의 이름.
deprecated - 해당 인자의 사용이 더 이상 권장되지 않는지 여부입니다:

이 메서드는 인자를 나타내는 Action 객체를 반환합니다.

다음 절에서는 이들 각각의 사용 방법에 관해 설명합니다.

name or flags¶

add_argument() 메서드는 `-f`나 `–foo`와 같은 선택 인자, 또는 파일명 리스트와 같은 위치 인자가 예상되는지 알아야 합니다. 따라서 :meth:`~ArgumentParser.add_argument`에 전달하는 첫 번째 인자는 일련의 플래그이거나 단순한 인자 이름이어야 합니다.

예를 들어, 선택 인자를 다음과 같이 생성할 수 있습니다:

>>> parser.add_argument('-f', '--foo')

반면에 위치 인자는 이렇게 만들어집니다:

>>> parser.add_argument('bar')

parse_args() 가 호출되면, 선택 인자는 - 접두사로 식별되고, 그 밖의 인자는 위치 인자로 간주합니다:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar

By default, argparse automatically handles the internal naming and display names of arguments, simplifying the process without requiring additional configuration. As such, you do not need to specify the dest and metavar parameters. For optional arguments, the dest parameter defaults to the argument name, with underscores _ replacing hyphens -. The metavar parameter defaults to the upper-cased name. For example:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo-bar')
>>> parser.parse_args(['--foo-bar', 'FOO-BAR'])
Namespace(foo_bar='FOO-BAR')
>>> parser.print_help()
usage:  [-h] [--foo-bar FOO-BAR]

optional arguments:
 -h, --help  show this help message and exit
 --foo-bar FOO-BAR

action¶

ArgumentParser 객체는 명령행 인자를 액션과 연관시킵니다. 대부분의 액션은 단순히 parse_args() 에 의해 반환된 객체에 어트리뷰트를 추가하기만 하지만, 액션은 관련된 명령행 인자로 무엇이든 할 수 있습니다. action 키워드 인자는 명령행 인자의 처리 방법을 지정합니다. 제공되는 액션은 다음과 같습니다:

'store' - 이는 인자의 값만 저장합니다. 이것이 기본 액션입니다.
'store_const' - This stores the value specified by the const keyword argument; note that the const keyword argument defaults to None. The 'store_const' action is most commonly used with optional arguments that specify some sort of flag. For example:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)
```

'store_true' 와 'store_false' - 이들은 각각 기본값이 False 및 True 인 값을 저장하는 ‘’store_const’’ 의 특수한 경우입니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(foo=True, bar=False, baz=True)

'append' - 이것은 각 인자 값을 리스트에 추가합니다. 옵션이 여러 번 지정될 수 있도록 하는 데 유용합니다. 기본값이 비어 있지 않은 리스트인 경우, 구문 분석된 값은 기본 리스트의 요소로 시작하며, 명령줄의 모든 값은 이 기본값 뒤에 추가됩니다. 사용 예는 다음과 같습니다:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append', default=['0'])
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['0', '1', '2'])
```

'append_const' - This appends the value specified by the const keyword argument to a list; note that the const keyword argument defaults to None. The 'append_const' action is typically useful when multiple arguments need to store constants to the same list. For example:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--str', dest='types', action='append_const', const=str)
>>> parser.add_argument('--int', dest='types', action='append_const', const=int)
>>> parser.parse_args('--str --int'.split())
Namespace(types=[<class 'str'>, <class 'int'>])

'extend' - This appends each item from a multi-value argument to a list. The 'extend' action is typically used with the nargs keyword argument value '+' or '*'. Note that when nargs is None (the default) or '?', each character of the argument string will be appended to the list. Example usage:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
>>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
Namespace(foo=['f1', 'f2', 'f3', 'f4'])
```
Added in version 3.8.
'count' - 이것은 인자가 발생하는 횟수를 계산합니다. 예를 들어, 상세도를 높이는 데 유용합니다:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count', default=0)
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
```
참고, 명시적으로 0으로 설정되지 않으면 default는 None이 됩니다.
'help' - 현재 파서의 모든 옵션에 대한 완전한 도움말 메시지를 출력하고 종료합니다. 기본적으로 help 액션은 자동으로 파서에 추가됩니다. 출력이 만들어지는 방법에 대한 자세한 내용은 ArgumentParser 를 보세요.

'version' - add_argument() 호출에서 version= 키워드 인자를 기대하고, 호출되면 버전 정보를 출력하고 종료합니다:

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
>>> parser.parse_args(['--version'])
PROG 2.0

Action 서브 클래스를 전달하거나 동일한 인터페이스를 구현하는 다른 객체를 전달하여 임의의 액션을 지정할 수도 있습니다 (예:, BooleanOptionalAction). 명령행 인자를 소비하는 액션(예:, 'store', 'append', 'extend' 또는 0이 아닌 `nargs`를 가진 사용자 정의 액션)만이 위치 인자와 함께 사용될 수 있습니다.

The recommended way to create a custom action is to extend Action, overriding the __call__() method and optionally the __init__() and format_usage() methods. You can also register custom actions using the register() method and reference them by their registered name.

사용자 정의 액션의 예:

>>> class FooAction(argparse.Action):
...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
...         if nargs is not None:
...             raise ValueError("nargs not allowed")
...         super().__init__(option_strings, dest, **kwargs)
...     def __call__(self, parser, namespace, values, option_string=None):
...         print('%r %r %r' % (namespace, values, option_string))
...         setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')

자세한 내용은 Action 을 참조하십시오.

nargs¶

ArgumentParser 객체는 일반적으로 단일 명령행 인자를 처리할 단일 액션과 연결합니다. nargs 키워드 인자는 서로 다른 수의 명령행 인자를 단일 액션에 연결합니다. 또한 모호한 인자 지정 을 참조하십시오. 지원되는 값은 다음과 같습니다:

N (정수). 명령행에서 N 개의 인자를 함께 모아서 리스트에 넣습니다. 예를 들면:
```
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
>>> parser.add_argument('bar', nargs=1)
>>> parser.parse_args('c --foo a b'.split())
Namespace(bar=['c'], foo=['a', 'b'])
```
nargs=1 은 하나의 항목을 갖는 리스트를 생성합니다. 이는 항목 그대로 생성되는 기본값과 다릅니다.

'?'. 가능하다면 한 인자가 명령행에서 소비되고 단일 항목으로 생성됩니다. 명령행 인자가 없으면 default 의 값이 생성됩니다. 선택 인자의 경우 추가적인 경우가 있습니다 - 옵션 문자열은 있지만, 명령행 인자가 따라붙지 않는 경우입니다. 이 경우 const 의 값이 생성됩니다. 이것을 보여주기 위해 몇 가지 예를 듭니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d')
>>> parser.parse_args(['XX', '--foo', 'YY'])
Namespace(bar='XX', foo='YY')
>>> parser.parse_args(['XX', '--foo'])
Namespace(bar='XX', foo='c')
>>> parser.parse_args([])
Namespace(bar='d', foo='d')

nargs='?' 의 흔한 사용법 중 하나는 선택적 입출력 파일을 허용하는 것입니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?')
>>> parser.add_argument('outfile', nargs='?')
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile='input.txt', outfile='output.txt')
>>> parser.parse_args(['input.txt'])
Namespace(infile='input.txt', outfile=None)
>>> parser.parse_args([])
Namespace(infile=None, outfile=None)

'*'. 모든 명령행 인자를 리스트로 수집합니다. 일반적으로 두 개 이상의 위치 인자에 대해 nargs='*' 를 사용하는 것은 별로 의미가 없지만, nargs='*' 를 갖는 여러 개의 선택 인자는 가능합니다. 예를 들면:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='*')
>>> parser.add_argument('--bar', nargs='*')
>>> parser.add_argument('baz', nargs='*')
>>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

'+'. '*' 와 마찬가지로, 존재하는 모든 명령행 인자는 리스트로 수집됩니다. 또한, 적어도 하나의 명령행 인자가 존재하지 않을 경우 오류 메시지가 생성됩니다. 예를 들면 다음과 같습니다:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args(['a', 'b'])
Namespace(foo=['a', 'b'])
>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]
PROG: error: the following arguments are required: foo

If the nargs keyword argument is not provided, the number of arguments consumed is determined by the action. Generally this means a single command-line argument will be consumed and a single item (not a list) will be produced. Actions that do not consume command-line arguments (e.g. 'store_const') set nargs=0.

const¶

add_argument() 의 const 인자는 명령행에서 읽지는 않지만 다양한 ArgumentParser 액션에 필요한 상숫값을 저장하는 데 사용됩니다. 가장 흔한 두 가지 용도는 다음과 같습니다:

When add_argument() is called with action='store_const' or action='append_const'. These actions add the const value to one of the attributes of the object returned by parse_args(). See the action description for examples. If const is not provided to add_argument(), it will receive a default value of None.
When add_argument() is called with option strings (like -f or --foo) and nargs='?'. This creates an optional argument that can be followed by zero or one command-line arguments. When parsing the command line, if the option string is encountered with no command-line argument following it, the value from const will be used. See the nargs description for examples.

버전 3.11에서 변경: 기본적으로 const=None 이며, 이는 action='append_const' 또는 action='store_const' 일 때도 마찬가지입니다.

default¶

모든 선택 인자와 일부 위치 인자는 명령행에서 생략될 수 있습니다. add_argument() 의 default 키워드 인자는, 기본값은 None 입니다, 명령행 인자가 없을 때 어떤 값을 사용해야 하는지를 지정합니다. 선택 인자의 경우, 옵션 문자열이 명령행에 없을 때 default 값이 사용됩니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)

대상 이름 공간에 이미 어트리뷰트가 설정되어 있다면, action *default* 는 이를 덮어쓰지 않습니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)

default 값이 문자열이면, 파서는 마치 명령행 인자인 것처럼 파싱합니다. 특히, 파서는 Namespace 반환 값에 어트리뷰트를 설정하기 전에, 제공된 모든 type 변환 인자를 적용합니다. 그렇지 않은 경우, 파서는 값을 있는 그대로 사용합니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)

nargs 가 ? 또는 * 인 위치 인자의 경우, 명령행 인자가 없을 때 default 값이 사용됩니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)

nargs='*' 는 공급된 모든 값을 리스트로 모으기 때문에, 누락된 위치 인자는 빈 리스트([])를 반환합니다. 오직 비-None default 만 이를 재정의합니다 (따라서 default=None 은 여전히 [] 을 반환합니다).

For required arguments, the default value is ignored. For example, this applies to positional arguments with nargs values other than ? or *, or optional arguments marked as required=True.

default=argparse.SUPPRESS 를 지정하면 명령행 인자가 없는 경우 어트리뷰트가 추가되지 않습니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')

type¶

기본적으로, 파서는 명령행 인자를 간단한 문자열로 읽습니다. 그러나 꽤 자주 명령행 문자열은 float나 int와 같은 다른 형으로 해석되어야 합니다. add_argument() 의 type 키워드는 필요한 형 검사와 형 변환이 수행되도록 합니다.

type 키워드가 default 키워드와 함께 사용되면, 형 변환기는 기본값이 문자열일 때만 적용됩니다.

The argument to type can be a callable that accepts a single string or the name of a registered type (see register()) If the function raises ArgumentTypeError, TypeError, or ValueError, the exception is caught and a nicely formatted error message is displayed. Other exception types are not handled.

일반적인 내장형과 함수는 형 변환기로 사용될 수 있습니다:

import argparse
import pathlib

parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('datapath', type=pathlib.Path)

사용자 정의 함수도 사용할 수 있습니다:

>>> def hyphenated(string):
...     return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')

bool() 함수는 타입 변환기로 권장되지 않습니다. 이것은 빈 문자열을 False 로, 비어 있지 않은 문자열을 True 로 변환할 뿐입니다. 일반적으로 원하는 바가 아닙니다:

>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('--verbose', type=bool)
>>> parser.parse_args(['--verbose', 'False'])
Namespace(verbose=True)

일반적인 대안으로는 BooleanOptionalAction 또는 action='store_true' 를 사용하십시오.

일반적으로, type 키워드는 지원되는 세 가지 예외 중 하나만 발생할 수 있는 간단한 변환에만 사용해야 하는 편의 기능입니다. 더 흥미로운 에러 처리나 리소스 관리가 필요한 모든 작업은 인자가 구문 분석된 후에 수행되어야 합니다.

예를 들어, JSON 또는 YAML 변환은 type 키워드가 제공할 수 있는 것보다 더 나은 보고가 필요한 복잡한 오류 사례들이 있습니다. JSONDecodeError`는 잘 포맷되지 않을 것이며, :exc:`FileNotFoundError 예외는 전혀 처리되지 않습니다.

심지어 FileType``도 ``type` 키워드와 함께 사용할 때 한계가 있습니다. 만약 한 인자가 이런 경우에는 파서 실행 이후에 기다렸다가 then :keyword:`with-문을 사용하여 파일을 관리하는 것이 더 좋습니다.

고정된 값 집합에 대해 단순히 확인하는 형 검사기의 경우, 대신 choices 키워드를 사용하는 것을 고려하십시오.

choices¶

일부 명령행 인자는 제한된 값의 집합에서 선택되어야 합니다. 이는 :meth:`~ArgumentParser.add_argument``에 시퀀스 객체를 choices 키워드 인자로 전달하여 처리할 수 있습니다. 명령줄이 구문 분석되면, 인자 값들이 검사되고 해당 인자가 허용 가능한 값이 아니면 오류 메시지가 표시됩니다:

>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')

choices 값으로는 모든 시퀀스를 전달할 수 있으므로 list 객체, tuple 객체 및 사용자 정의 시퀀스 모두 지원됩니다.

enum.Enum은 사용법, 도움말 및 에러 메시지에서 나타나는 방식을 제어하기 어렵기 때문에 사용하지 않는 것이 좋습니다.

choices 는 type 변환이 수행된 후에 확인된다는 점에 유의하십시오. 따라서 choices 내의 객체는 지정된 type 과 일치해야 합니다. 이로 인해 choices 가 사용법, 도움말 또는 오류 메시지에서 생소하게 보일 수 있습니다.

choices 를 사용자 친화적으로 유지하려면 값을 변환하고 포맷하는 사용자 정의 타입 래퍼를 고려하거나, type 를 생략하고 애플리케이션 코드에서 변환을 처리하십시오.

포맷된 choices 는 일반적으로 dest 에서 파생되는 기본 metavar_ 를 재정의합니다. 이는 사용자가 dest 매개변수를 결코 보지 않기 때문에 보통 원하는 방식입니다. 만약 이 표시가 바람직하지 않다면 (예: 선택지가 너무 많은 경우), 명시적인 metavar 만 지정하십시오.

required¶

일반적으로, argparse 모듈은 -f``나 ``--bar``와 같은 플래그가 명령어에서 항상 생략 가능한 *선택적* 인자를 나타낸다고 가정합니다. 옵션을 *필수*로 만들려면 :meth:`~ArgumentParser.add_argument`에 이진 필드 `required=\True`를 지정할 수 있습니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: [-h] --foo FOO
: error: the following arguments are required: --foo

예에서 보듯이, 옵션이 required 로 표시되면, parse_args() 는 그 옵션이 명령행에 없을 때 에러를 보고합니다.

참고

필수 옵션은 사용자가 옵션 이 선택적 일 것으로 기대하기 때문에 일반적으로 나쁜 형식으로 간주하므로 가능하면 피해야 합니다.

help¶

"help" 값은 인자에 대한 간략한 설명을 담고 있는 문자열입니다. 사용자가 도움말을 요청할 때 (일반적으로 명령어에서 -h 또는 --help``를 사용하여), 이들 ``help 설명이 각 인자와 함께 표시됩니다:

help 문자열은 프로그램 이름이나 인자 default 와 같은 것들의 반복을 피하고자 다양한 포맷 지정자를 포함 할 수 있습니다. 사용할 수 있는 지정자는 프로그램 이름, %(prog)s 와 add_argument() 의 대부분의 키워드 인자, %(default)s, %(type)s 등을 포함합니다.:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
...                     help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]

positional arguments:
 bar     the bar to frobble (default: 42)

options:
 -h, --help  show this help message and exit

도움말 문자열이 %-포매팅을 지원하기 때문에, 도움말 문자열에 리터럴 % 을 표시하려면, %% 로 이스케이프 처리해야 합니다.

argparse 는 help 값을 argparse.SUPPRESS 로 설정하여 특정 옵션의 도움말 항목을 비활성화하는 것을 지원합니다:

>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]

options:
  -h, --help  show this help message and exit

metavar¶

When ArgumentParser generates help messages, it needs some way to refer to each expected argument. By default, ArgumentParser objects use the dest value as the “name” of each object. By default, for positional argument actions, the dest value is used directly, and for optional argument actions, the dest value is uppercased. So, a single positional argument with dest='bar' will be referred to as bar. A single optional argument --foo that should be followed by a single command-line argument will be referred to as FOO. An example:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo FOO] bar

positional arguments:
 bar

options:
 -h, --help  show this help message and exit
 --foo FOO

다른 이름은 metavar 로 지정할 수 있습니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage:  [-h] [--foo YYY] XXX

positional arguments:
 XXX

options:
 -h, --help  show this help message and exit
 --foo YYY

metavar 는 표시되는 이름 만 변경합니다 - parse_args() 객체의 어트리뷰트 이름은 여전히 dest 값에 의해 결정됩니다.

nargs 값이 다르면 metavar 가 여러 번 사용될 수 있습니다. metavar 에 튜플을 제공하면 인자마다 다른 디스플레이가 지정됩니다:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]

options:
 -h, --help     show this help message and exit
 -x X X
 --foo bar baz

dest¶

대부분 ArgumentParser 액션은 parse_args() 에 의해 반환된 객체의 어트리뷰트로 어떤 값을 추가합니다. 이 어트리뷰트의 이름은 add_argument() 의 dest 키워드 인자에 의해 결정됩니다. 위치 인자 액션의 경우, dest 는 일반적으로 add_argument() 에 첫 번째 인자로 제공됩니다.:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')

선택적 인자 액션의 경우, dest 값은 일반적으로 옵션 문자열에서 추론됩니다. ArgumentParser`는 첫 번째 이중 대시 긴 옵션 문자열을 가져와 초기 `-`` 문자를 제거하여 dest 값을 생성합니다. 이중 대시 긴 옵션 문자열이 제공되지 않은 경우, dest`는 초기 `-`` 문자를 제거한 첫 번째 단일 대시 긴 옵션 문자열에서 파생됩니다. 긴 옵션 문자열이 제공되지 않은 경우, dest`는 초기 `-`` 문자를 제거한 첫 번째 짧은 옵션 문자열에서 파생됩니다. 내부의 모든 - 문자는 문자열이 유효한 속성 이름임을 확실히 하기 위해 _ 문자로 변환됩니다. 아래 예제가 이 동작을 보여줍니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-q', '-quz')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -q 2 -x 3'.split())
Namespace(foo_bar='1', quz='2', x='3')
>>> parser.parse_args('--foo 1 -quz 2 -y 3'.split())
Namespace(foo_bar='1', quz='2', x='2')

dest 는 사용자 정의 어트리뷰트 이름을 지정할 수 있게 합니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')

Multiple arguments may share the same dest. By default, the value from the last such argument given on the command line wins. Use action='append' to collect values from all of them into a list instead. For conflicting option strings rather than dest names, see conflict_handler.

버전 3.15에서 변경: 단일 대시 긴 옵션이 이제 짧은 옵션보다 우선합니다:

폐지됨¶

프로젝트 수명 주기 동안, 일부 인자는 명령줄에서 제거되어야 할 수 있습니다. 제거하기 전에, 사용자가 해당 인자가 더 이상 사용되지 않으며 미래에 제거될 것임을 알려야 합니다. 기본값이 False 인 add_argument() 의 deprecated 키워드 인자는 해당 인자가 폐지되었고 향후 제거될지 여부를 명시합니다. 인자의 경우, deprecated 가 True 이면, 해당 인자를 사용할 때 sys.stderr 에 경고가 출력됩니다:

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='snake.py')
>>> parser.add_argument('--legs', default=0, type=int, deprecated=True)
>>> parser.parse_args([])
Namespace(legs=0)
>>> parser.parse_args(['--legs', '4'])
snake.py: warning: option '--legs' is deprecated
Namespace(legs=4)

Added in version 3.13.

Action 클래스¶

Action 클래스는 Action API를 구현하며, 이는 명령행에서 인수들을 처리하고 반환하는 콜러블(callable)입니다. 이 API를 따르는 모든 객체는 add_argument`의 `action() 매개변수로 전달될 수 있습니다:

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)¶

Action 객체는 ArgumentParser`에 의해 명령줄 문자열 하나 이상으로부터 단일 인자를 구문 분석하는 데 필요한 정보를 나타내는 데 사용됩니다. :class:!Action` 클래스는 위치 인수 두 개의 인자 및 ArgumentParser.add_argument`에 전달된 모든 키워드 인자(`action() 자체 제외)를 받아야 합니다:

Action 인스턴스는 dest, option_strings, default, type, required, help 등의 속성들을 정의해야 합니다. 이러한 속성들이 정의되도록 보장하는 가장 쉬운 방법은 :meth:`!Action.__init__`를 호출하는 것입니다:

__call__(parser, namespace, values, option_string=None)¶

Action 인스턴스는 콜러블이어야 하므로, 서브클래스는 네 개의 매개변수를 받아야 하는 __call__() 메서드를 오버라이드해야 합니다:

parser - 이 액션을 포함하고 있는 ArgumentParser 객체입니다:
네임스페이스 - parse_args() 메서드에 의해 반환되는 Namespace 객체입니다. 대부분의 액션은 :func:`setattr`을 사용하여 이 객체에 속성을 추가합니다.
values - The associated command-line arguments, with any type conversions applied. Type conversions are specified with the type keyword argument to add_argument().
옵션 문자열 - 이 액션을 호출하는 데 사용된 옵션 문자열입니다. option_string 인자는 선택 사항이며, 액션이 위치 인자와 관련된 경우 누락됩니다.

__call__() 메서드는 임의의 액션을 수행할 수 있지만, 일반적으로 namespace 에서 dest 와 values 를 기반으로 속성을 설정합니다.

format_usage()¶: Action 서브 클래스는 인수를 받지 않고 프로그램을 사용할 때 표시되는 문자열을 반환하는 format_usage() 메서드를 정의할 수 있습니다. 이러한 메서드가 제공되지 않은 경우, 적절한 기본값이 사용됩니다.

class argparse.BooleanOptionalAction¶

양수 및 음수 옵션을 처리하기 위한 Action`의 서브 클래스입니다. `–foo``와 같은 단일 인자를 추가하면 자동으로 --foo``와 ``--no-foo 옵션이 모두 생성되며, 각각 `True`와 `False`를 저장합니다:

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)

단일 대시 긴 옵션도 지원됩니다. 예를 들어, 음수 옵션 -nofoo 는 양수 옵션 -foo 에 대해 자동으로 추가됩니다. 하지만 -f 와 같은 짧은 옵션에는 추가 옵션이 추가되지 않습니다.

Added in version 3.9.

버전 3.15에서 변경: 단일 대시 옵션에 대한 지원이 추가되었습니다.

Added support for alternate prefix_chars.

parse_args() 메서드¶

ArgumentParser.parse_args(args=None, namespace=None)¶

인자 문자열을 객체로 변환하고 namespace의 어트리뷰트로 설정합니다. 값들이 설정된 namespace를 돌려줍니다.

add_argument`에 대한 이전 호출이 정확히 어떤 객체가 생성되고 어떻게 할당되는지를 결정합니다. 자세한 내용은 :meth:()!add_argument` 문서를 참조하십시오.

args - 구문 분석할 문자열 리스트. 기본값은 sys.argv 에서 취합니다.
namespace - 어트리뷰트가 대입될 객체. 기본값은 새로 만들어지는 빈 Namespace 객체입니다.

옵션값 문법¶

parse_args() 메서드는 (취할 것이 있다면) 옵션의 값을 지정하는 몇 가지 방법을 지원합니다. 가장 단순한 경우, 옵션과 그 값은 두 개의 독립적인 인자로 전달됩니다:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)

긴 옵션(단일 문자보다 긴 이름을 가진 옵션)의 경우, 옵션과 값을 = 로 구분하여 단일 명령행 인자로 전달할 수도 있습니다:

>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)

짧은 옵션(한 문자 길이의 옵션)의 경우, 옵션과 해당 값을 이어붙일 수 있습니다:

>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')

여러 개의 짧은 옵션은 마지막 옵션만 값을 요구하는 한 (또는 그들 중 아무것도 값을 요구하지 않거나), 하나의 - 접두어를 사용하여 함께 결합 할 수 있습니다:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')

잘못된 인자¶

명령행을 파싱할 때, parse_args() 는 모호한 옵션, 유효하지 않은 형, 유효하지 않은 옵션, 잘못된 위치 인자의 수 등을 포함한 다양한 에러를 검사합니다. 이런 에러가 발생하면, 사용 메시지와 함께 에러를 인쇄합니다:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')

>>> # 유효하지 않은 형식
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # 존재하지 않는 옵션
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

>>> # 인자 개수 오류
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger

`-` 를 포함하는 인자들¶

parse_args() 메서드는 사용자가 분명히 실수했을 때마다 에러를 주려고 하지만, 어떤 상황은 본질에서 모호합니다. 예를 들어, 명령행 인자 -1 은 옵션을 지정하려는 시도이거나 위치 인자를 제공하려는 시도일 수 있습니다. parse_args() 메서드는 이럴 때 신중합니다: 위치 인자는 음수처럼 보이고 파서에 음수처럼 보이는 옵션이 없을 때만 - 로 시작할 수 있습니다:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')

>>> # 음수 개수 옵션이 없으므로, -1은 위치 인자입니다
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # 음수 개수 옵션이 없으므로, -1 및 -5는 위치 인자입니다
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')

>>> # 음수 개수 옵션이 존재하므로, -1은 옵션입니다
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # 음수 개수 옵션이 존재하므로, -2도 옵션입니다
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

>>> # 음수 개수 옵션이 존재하므로, 둘 다 -1은 옵션입니다
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument

- 로 시작해야 하고, 음수처럼 보이지 않는 위치 인자가 있는 경우, parse_args() 에 다음과 같은 의사 인자 '--' 를 삽입 할 수 있습니다. 그 이후의 모든 것은 위치 인자입니다:

>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)

자세한 내용은 :ref:`모호한 인자 처리 방법 on argparse <specifying-ambiguous-arguments>`를 참조하십시오.

인자 약어 (접두사 일치)¶

parse_args() 메서드는 기본적으로 약어가 모호하지 않으면 (접두사가 오직 하나의 옵션과 일치합니다) 긴 옵션을 접두사로 축약 할 수 있도록 합니다:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon

둘 이상의 옵션과 일치하는 인자는 에러를 일으킵니다. 이 기능은 allow_abbrev를 False 로 설정함으로써 비활성화시킬 수 있습니다.

`sys.argv` 너머¶

Sometimes it may be useful to have an ArgumentParser parse arguments other than those of sys.argv. This can be accomplished by passing a list of strings to parse_args(). This is useful for testing at the interactive prompt:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
...     'integers', metavar='int', type=int, choices=range(10),
...     nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
...     '--sum', dest='accumulate', action='store_const', const=sum,
...     default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])

Namespace 객체¶

class argparse.Namespace¶

parse_args() 가 어트리뷰트를 저장하고 반환할 객체를 만드는 데 기본적으로 사용하는 간단한 클래스.

이 클래스는 의도적으로 단순한데, 단지 가독성 있는 문자열 표현을 갖는 object 의 서브 클래스입니다. 어트리뷰트를 딕셔너리처럼 보기 원한다면, 표준 파이썬 관용구를 사용할 수 있습니다, vars():

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}

ArgumentParser 가 새 Namespace 객체가 아니라 이미 존재하는 객체에 어트리뷰트를 대입하는 것이 유용 할 수 있습니다. namespace= 키워드 인자를 지정하면 됩니다:

>>> class C:
...     pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'

기타 유틸리티¶

부속 명령¶

ArgumentParser.add_subparsers(*[, title][, description][, prog][, parser_class][, action][, dest][, required][, help][, metavar])¶

여러 프로그램은 자체 기능을 여러 하위 명령어로 분리합니다. 예를 들어, svn 프로그램은 svn checkout, svn update, 그리고 svn commit 과 같은 하위 명령어를 호출할 수 있습니다. 이처럼 기능을 분리하는 것은 프로그램이 서로 다른 종류의 명령행 인자를 필요로 하는 몇 가지 다른 기능을 수행할 때 특히 좋은 아이디어일 수 있습니다. ArgumentParser 는 add_subparsers() 메서드를 사용하여 이러한 하위 명령어를 생성할 수 있도록 지원합니다. 이 add_subparsers() 메서드는 일반적으로 아무런 인자 없이 호출되며 특수한 액션 객체를 반환합니다. 이 객체는 단일 메서드인 add_parser() 를 가지고 있으며, 이는 명령 이름을 그리고 모든 ArgumentParser 생성자 인자를 받아들이고 평소처럼 수정할 수 있는 ArgumentParser 객체를 반환합니다.

매개 변수 설명:

title - 도움말 출력에서 하위 파서 그룹의 제목입니다. 기본적으로 설명이 제공되면 “하위 명령어”를 사용하며, 그렇지 않으면 위치 인자의 제목을 사용합니다.
description - 도움말 출력에서 하위 파서 그룹에 대한 설명을 지정합니다. 기본값은 None 입니다.
prog - 서브 커맨드 도움말과 함께 표시될 사용법 정보입니다. 기본적으로 프로그램 이름과 서브파서 인자 이전의 모든 위치 인자를 사용합니다.
parser_class - 하위 파서 인스턴스를 생성하는 데 사용될 클래스입니다. 기본적으로 현재 파서의 클래스(예: ArgumentParser)를 사용합니다.
action - 이 인자를 명령행에서 만날 때 수행 할 액션의 기본형
dest - 서브 명령 이름이 저장되는 어트리뷰트의 이름입니다. 기본값은 None 이며 값은 저장되지 않습니다.
required - 부속 명령이 꼭 제공되어야 하는지 아닌지, 기본값은 False (3.7에서 추가)
help - 도움말 출력의 부속 파서 그룹 도움말, 기본적으로 None
metavar - 도움말에서 사용 가능한 하위 명령어를 표시하는 문자열입니다. 기본값이 None 이며, 서브 명령어를 {cmd1, cmd2, ..} 형식으로 표시합니다.

몇 가지 사용 예:

>>> # 최상위 파서 생성
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo 도움말')
>>> subparsers = parser.add_subparsers(help='하위 명령어 도움말')
>>>
>>> # "a" 명령에 대한 파서 생성
>>> parser_a = subparsers.add_parser('a', help='a 도움말')
>>> parser_a.add_argument('bar', type=int, help='bar 도움말')
>>>
>>> # "b" 명령에 대한 파서 생성
>>> parser_b = subparsers.add_parser('b', help='b 도움말')
>>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz 도움말')
>>>
>>> # 일부 인자 목록을 파싱합니다
>>> parser.parse\_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse\_args(['--foo', 'b', '--baz', 'Z'])
Namespace(baz='Z', foo=True)

따라서 위에 제시된 예에서, ``a`() 명령이 지정되면 foo 및 bar 어트리뷰트만 존재하며, b 명령이 지정되면 foo 및 baz 어트리뷰트만 존재합니다.

하위 파서가 부모 파서와 동일한 dest``로 인자를 정의하는 경우, 두 가지는 단일 네임스페이스 어트리뷰트를 공유하므로 부모의 값이 유지되지 않습니다. 사용자는 둘 다를 유지하기 위해 구별되는 ``dest 값을 제공해야 합니다.

마찬가지로, 하위 파서에서 도움말 메시지를 요청하는 경우 해당 특정 파서에 대한 도움말만 출력됩니다. 도움말 메시지에는 부모 파서나 형제 파서의 메시지가 포함되지 않습니다. (다만, 각 하위 파서 명령어에 대한 도움말 메시지는 위 예와 같이 add_parser`에 ``help=`() 인자를 제공하여 줄 수 있습니다.)

>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...

positional arguments:
  {a,b}   subcommand help
    a     a help
    b     b help

options:
  -h, --help  show this help message and exit
  --foo   foo help

>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar

positional arguments:
  bar     bar help

options:
  -h, --help  show this help message and exit

>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]

options:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

add_subparsers() 메서드는 또한 title``과 ``description 키워드 인자를 지원합니다. 둘 중 하나가 존재하면, 하위 파서의 명령어는 도움말 출력에서 자체 그룹으로 나타납니다. 예를 들면:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
...                                    description='valid subcommands',
...                                    help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage:  [-h] {foo,bar} ...

options:
  -h, --help  show this help message and exit

subcommands:
  valid subcommands

  {foo,bar}   additional help

하위 명령어를 처리하는 한 가지 특히 효과적인 방법은 add_subparsers() 메서드의 사용과 set_defaults() 호출을 결합하여 각 하위 파서가 어떤 Python 함수를 실행해야 하는지 알도록 하는 것입니다. 예를 들면:

>>> # 하위 명령어 함수
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # 최상위 파서 생성
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(required=True)
>>>
>>> # "foo" 명령을 위한 파서 생성
>>> parser_foo = subparsers.add_parser('foo')
>>> parser_foo.add_argument('-x', type=int, default=1)
>>> parser_foo.add_argument('y', type=float)
>>> parser_foo.set_defaults(func=foo)
>>>
>>> # "bar" 명령을 위한 파서 생성
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # 인자를 파싱하고 선택된 함수 호출
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # 인자를 파싱하고 선택된 함수 호출
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))

이렇게 하면 parse_args() 가 인자 파싱이 완료된 후 적절한 함수를 호출하도록 할 수 있습니다. 이처럼 액션과 함수를 연결하는 것이 일반적으로 각 하위 파서별로 다른 액션을 처리하기 위한 가장 쉬운 방법입니다. 그러나 호출된 하위 파서의 이름을 확인할 필요가 있다면, add_subparsers() 호출에 dest 키워드 인자를 사용할 수 있습니다:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name')
>>> subparser1 = subparsers.add_parser('1')
>>> subparser1.add_argument('-x')
>>> subparser2 = subparsers.add_parser('2')
>>> subparser2.add_argument('y')
>>> parser.parse_args(['2', 'frobble'])
Namespace(subparser_name='2', y='frobble')

버전 3.7에서 변경: 새로운 필수 키워드 전용 매개 변수입니다.

버전 3.14에서 변경: 하위 파서의 prog 는 더 이상 메인 파서에서 사용자 정의 사용법 메시지에 영향을 받지 않습니다.

_SubParsersAction.add_parser(name, *, help=None, aliases=None, deprecated=False, **kwargs)¶

하위 명령어 name 에 대한 새로운 ArgumentParser 객체를 생성하고 반환합니다.

name 인자는 하위 명령어의 이름을 나타냅니다.

help 인자는 이 하위 명령에 대한 간략한 설명을 제공합니다.

aliases 인자는 이 하위 명령어의 대안적 이름을 제공할 수 있게 합니다. 예를 들어:

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>> checkout = subparsers.add_parser('checkout', aliases=['co'])
>>> checkout.add_argument('foo')
>>> parser.parse_args(['co', 'bar'])
Namespace(foo='bar')

deprecated 인자는 True 인 경우, 해당 하위 명령을 폐지된 것으로 표시하고 사용할 때 경고를 발생시킵니다. 예를 들어:

>>> parser = argparse.ArgumentParser(prog='chicken.py')
>>> subparsers = parser.add_subparsers()
>>> fly = subparsers.add_parser('fly', deprecated=True)
>>> args = parser.parse_args(['fly'])
chicken.py: warning: command 'fly' is deprecated
Namespace()

나머지 모든 키워드 인자는 ArgumentParser 생성자에 직접 전달됩니다.

Added in version 3.13: deprecated 매개 변수가 추가되었습니다.

FileType 객체¶

class argparse.FileType(mode='r', bufsize=-1, encoding=None, errors=None)¶

FileType 팩토리는 ArgumentParser.add_argument() 의 type 인자로 전달될 수 있는 객체를 만듭니다. type으로 FileType 객체를 사용하는 인자는 명령행 인자를 요청된 모드, 버퍼 크기, 인코딩 및 오류 처리의 파일로 엽니다 (자세한 내용은 open() 함수를 참조하세요):

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--raw', type=argparse.FileType('wb', 0))
>>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'))
>>> parser.parse_args(['--raw', 'raw.dat', 'file.txt'])
Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

FileType 객체는 의사 인자 '-' 를 인식하며, 이를 읽을 수 있는 FileType 객체의 경우 자동으로 sys.stdin 으로, 기록 가능한 FileType 객체의 경우 자동으로 sys.stdout 으로 변환합니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<_io.TextIOWrapper name='<stdin>' encoding='UTF-8'>)

참고

인자 중 하나가 FileType 을 사용하고 후속 인자가 실패하는 경우, 오류가 보고되지만 파일은 자동으로 닫히지 않습니다. 이는 출력 파일을 손상시킬 수도 있습니다. 이런 경우에는 파서가 실행된 후에 with-문을 사용하여 파일을 관리하는 것이 더 좋습니다.

버전 3.4에서 변경: encoding 및 errors 매개 변수가 추가되었습니다.

버전 3.14부터 폐지됨.

인자 그룹¶

ArgumentParser.add_argument_group(title=None, description=None, *[, argument_default][, conflict_handler])¶

기본적으로 ArgumentParser`는 도움말 메시지를 표시할 때 명령줄 인자를 "위치 인수"와 "옵션"으로 그룹화합니다. 이 기본값보다 더 나은 개념적 인자 그룹화가 있는 경우, 적절한 그룹을 :meth:!add_argument_group` 메서드를 사용하여 생성할 수 있습니다:

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group')
>>> group.add_argument('--foo', help='foo help')
>>> group.add_argument('bar', help='bar help')
>>> parser.print_help()
usage: PROG [--foo FOO] bar

group:
  bar    bar help
  --foo FOO  foo help

add_argument_group() 메서드는 인자 그룹 객체를 반환하며, 이 객체는 일반적인 ArgumentParser`와 마찬가지로 :meth:`~ArgumentParser.add_argument 메서드를 가지고 있습니다. 그룹에 인자가 추가되면 파서는 이를 정상적인 인자처럼 취급하지만, 도움말 메시지에서는 별도의 그룹으로 표시합니다. add_argument_group() 메서드는 이 표시를 사용자 정의하는 데 사용될 수 있는 title 및 description 인자를 받습니다:

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group1 = parser.add_argument_group('group1', 'group1 description')
>>> group1.add_argument('foo', help='foo help')
>>> group2 = parser.add_argument_group('group2', 'group2 description')
>>> group2.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [--bar BAR] foo

group1:
  group1 description

  foo    foo help

group2:
  group2 description

  --bar BAR  bar help

The optional, keyword-only parameters argument_default and conflict_handler allow for finer-grained control of the behavior of the argument group. These parameters have the same meaning as in the ArgumentParser constructor, but apply specifically to the argument group rather than the entire parser.

사용자 정의 그룹에 없는 인자는 일반적인 “positional arguments” 및 “optional arguments” 섹션으로 들어갑니다.

각 인자 그룹 내에서 인자는 추가되는 순서대로 도움말 출력에 표시됩니다.

버전 3.11에서 폐지되었고, 버전 3.14에서 제거됩니다: 인자 그룹에 :meth:`add_argument_group`을 호출하면 이제 예외가 발생합니다. 이 중첩은 지원된 적이 없으며, 올바르게 작동하지 않는 경우가 많았고, 상속을 통해 의도치 않게 노출되었습니다.

버전 3.14부터 폐지됨: add_argument_group() 에 prefix_chars 를 전달하는 방식은 이제 더 이상 지원되지 않습니다.

상호 배제¶

ArgumentParser.add_mutually_exclusive_group(required=False)¶

:mod:`!argparse`에서 상호 배타적 그룹 만들기. 이 모듈은 명령어 줄에 상호 배타적 그룹의 인자 중 하나만 존재하도록 보장합니다:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group()
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args(['--foo'])
Namespace(bar=True, foo=True)
>>> parser.parse_args(['--bar'])
Namespace(bar=False, foo=False)
>>> parser.parse_args(['--foo', '--bar'])
usage: PROG [-h] [--foo | --bar]
PROG: error: argument --bar: not allowed with argument --foo

add_mutually_exclusive_group() 메서드는 상호 배타적 인자 중 적어도 하나가 필요하다는 것을 나타내기 위한 required 인자도 받아들입니다:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required

현재 상호 배타적 인자 그룹은 :meth:`~ArgumentParser.add_argument_group`의 title 및 description 인자를 지원하지 않는다는 점에 유의하십시오. 그러나 타이틀과 설명이 있는 인자 그룹에 상호 배타적 그룹을 추가할 수 있습니다. 예를 들면:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_argument_group('Group title', 'Group description')
>>> exclusive_group = group.add_mutually_exclusive_group(required=True)
>>> exclusive_group.add_argument('--foo', help='foo help')
>>> exclusive_group.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [-h] (--foo FOO | --bar BAR)

options:
  -h, --help  show this help message and exit

Group title:
  Group description

  --foo FOO   foo help
  --bar BAR   bar help

버전 3.11에서 폐지되었고, 버전 3.14에서 제거됩니다: 상호 배타적 그룹에 add_argument_group() 또는 :meth:`add_mutually_exclusive_group`을 호출하는 경우 이제 예외가 발생합니다. 이러한 중첩은 이전에 지원되지 않았으며, 자주 올바르게 작동하지 않았고 상속을 통해 실수로 노출되었습니다.

파서 기본값¶

ArgumentParser.set_defaults(**kwargs)¶

대부분은, parse_args() 에 의해 반환된 객체의 어트리뷰트는 명령행 인자와 인자 액션을 검사하여 완전히 결정됩니다. set_defaults() 는 명령행을 검사하지 않고 결정되는 몇 가지 추가적인 어트리뷰트를 추가할 수 있도록 합니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.set_defaults(bar=42, baz='badger')
>>> parser.parse_args(['736'])
Namespace(bar=42, baz='badger', foo=736)

기본값은 :meth:`set_defaults`를 사용한 파서 레벨과 :meth:`add_argument`를 사용한 인자 레벨 모두에서 설정할 수 있습니다. 만약 동일한 인자에 대해 둘 다 호출되면, 마지막으로 설정된 기본값이 사용됩니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')

파서 수준의 기본값은 여러 파서로 작업 할 때 특히 유용 할 수 있습니다. 이 유형의 예제는 add_subparsers() 메서드를 참조하십시오.

ArgumentParser.get_default(dest)¶

add_argument() 또는 set_defaults() 에 의해 설정된 이름 공간 어트리뷰트의 기본값을 가져옵니다:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'

도움말 인쇄¶

대부분의 일반적인 응용 프로그램에서 parse_args() 가 사용법이나 오류 메시지를 포매팅하고 인쇄하는 것을 담당합니다. 그러나 여러 가지 포매팅 방법이 제공됩니다:

ArgumentParser.print_usage(file=None)¶: ArgumentParser 가 어떻게 명령행에서 호출되어야 하는지에 대한 간단한 설명을 인쇄합니다. file 이 None 이면, sys.stdout 이 가정됩니다.

ArgumentParser.print_help(file=None)¶: 프로그램 사용법과 ArgumentParser 에 등록된 인자에 대한 정보를 포함하는 도움말 메시지를 출력합니다. file 이 None 이면, sys.stdout 이 가정됩니다.

인쇄하는 대신 단순히 문자열을 반환하는, 이러한 메서드의 변형도 있습니다:

ArgumentParser.format_usage()¶: ArgumentParser 가 어떻게 명령행에서 호출되어야 하는지에 대한 간단한 설명을 담은 문자열을 반환합니다.

ArgumentParser.format_help()¶: 프로그램 사용법과 ArgumentParser 에 등록된 인자에 대한 정보를 포함하는 도움말 메시지를 담은 문자열을 반환합니다.

부분 파싱¶

ArgumentParser.parse_known_args(args=None, namespace=None)¶

때로는 스크립트가 특정 명령어 줄 인자 세트만 처리해야 하고, 나머지 인식되지 않은 인자는 다른 스크립트나 프로그램에 남겨지기도 합니다. 이런 경우 parse_known_args() 메서드가 유용할 수 있습니다.

이 메서드는 :meth:`~ArgumentParser.parse_args`와 유사하게 작동하지만, 추가적인 인식되지 않은 인자에 대해 오류를 발생시키지 않습니다. 대신, 알려진 인자를 분석하고 채워진 이름 공간과 인식되지 않은 인자 목록을 포함하는 두 항목 튜플을 반환합니다.

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

경고

Prefix matching 규칙은 :meth:`~ArgumentParser.parse_known_args`에 적용됩니다. 파서는 알려진 옵션의 접두사일 뿐임에도 불구하고, 남은 인자 목록에 포함하기보다는 해당 옵션을 소비할 수 있습니다.

파일 파싱 사용자 정의¶

ArgumentParser.convert_arg_line_to_args(arg_line)¶

파일에서 읽은 인자는 (ArgumentParser 생성자의 fromfile_prefix_chars 키워드 인자를 참조하세요) 한 줄에 하나의 인자로 읽습니다. 이 동작을 변경하려면 convert_arg_line_to_args() 를 재정의합니다.

이 메서드는 하나의 인자 arg_line 를 받아들이는데, 인자 파일에서 읽어 들인 문자열입니다. 이 문자열에서 파싱된 인자 리스트를 반환합니다. 메서드는 인자 파일에서 읽어 들이는 대로 한 줄에 한 번씩 순서대로 호출됩니다.

이 메서드의 재정의하는 유용한 경우는 스페이스로 분리된 각 단어를 인자로 처리하는 것입니다. 다음 예제는 이렇게 하는 방법을 보여줍니다:

class MyArgumentParser(argparse.ArgumentParser):
    def convert_arg_line_to_args(self, arg_line):
        return arg_line.split()

이 오버라이드를 사용하면 이제 어떤 인자도 공백을 포함할 수 없습니다. 왜냐하면 각 공백으로 구분된 단어가 별도의 인자가 되기 때문입니다:

종료 메서드¶

ArgumentParser.exit(status=0, message=None)¶

이 메서드는 지정된 status 로 프로그램을 종료하고, 주어진 경우 그 전에 sys.stderr 에 message 를 출력합니다. 사용자는 이 메서드를 오버라이드하여 이러한 단계를 다르게 처리할 수 있습니다:

class ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        if status:
            raise Exception(f'Exiting because of an error: {message}')
        exit(status)

ArgumentParser.error(message)¶: 이 메서드는 message 를 포함한 사용법 메시지를 sys.stderr 에 출력하고 상태 코드 2로 프로그램을 종료합니다.

혼합 파싱¶

ArgumentParser.parse_intermixed_args(args=None, namespace=None)¶

ArgumentParser.parse_known_intermixed_args(args=None, namespace=None)¶

많은 유닉스 명령은 사용자가 선택 인자와 위치 인자를 섞을 수 있도록 합니다. parse_intermixed_args() 와 parse_known_intermixed_args() 메서드는 이런 파싱 스타일을 지원합니다.

이 파서들은 모든 argparse 기능을 지원하지 않으며, 지원되지 않는 기능이 사용되면 예외를 발생시킵니다. 특히 부분 파서(subparsers)와 옵션형과 위치 인자를 모두 포함하는 상호 배타적 그룹은 지원되지 않습니다.

다음 예제는 parse_known_args() 와 parse_intermixed_args() 의 차이점을 보여줍니다: 전자는 여분의 인자로 ['2', '3'] 을 반환하는 반면, 후자는 모든 위치 인자를 rest 로 모읍니다.

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('cmd')
>>> parser.add_argument('rest', nargs='*', type=int)
>>> parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Namespace(cmd='doit', foo='bar', rest=[1]), ['2', '3'])
>>> parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Namespace(cmd='doit', foo='bar', rest=[1, 2, 3])

parse_known_intermixed_args() 는 채워진 이름 공간과 잔여 인자 문자열의 리스트를 포함하는 두 항목 튜플을 반환합니다. parse_intermixed_args() 는 파싱되지 않은 인자 문자열이 남아 있으면 에러를 발생시킵니다.

Added in version 3.7.

커스텀 유형 또는 액션 등록하기¶

ArgumentParser.register(registry_name, value, object)¶

때로는 오류 메시지에 사용자가 더 친화적인 출력을 제공하도록 커스텀 문자열을 사용하는 것이 바람직합니다. 이런 경우, :meth:`!register`를 사용하여 파서에 사용자 정의 액션 또는 유형을 등록하고, 해당 호출 가능 이름 대신 등록된 이름을 통해 유형을 참조할 수 있습니다.

register() 메서드는 세 가지 인자를 받습니다. 객체가 저장될 내부 레지스트리를 지정하는 registry_name (예: action, type), 객체가 등록되는 키인 value, 그리고 등록할 호출 가능한 객체인 object입니다.

다음 예제는 파서에 커스텀 유형을 등록하는 방법을 보여줍니다:

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.register('type', 'hexadecimal integer', lambda s: int(s, 16))
>>> parser.add_argument('--foo', type='hexadecimal integer')
_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='hexadecimal integer', choices=None, required=False, help=None, metavar=None, deprecated=False)
>>> parser.parse_args(['--foo', '0xFA'])
Namespace(foo=250)
>>> parser.parse_args(['--foo', '1.2'])
usage: PROG [-h] [--foo FOO]
PROG: error: argument --foo: invalid 'hexadecimal integer' value: '1.2'

예외¶

exception argparse.ArgumentError¶

인자를 생성하거나 사용하는 중 발생하는 오류 (선택형 또는 위치성).

이 예외의 문자열 값은 해당 인자로 인해 발생한 문제에 대한 정보를 추가한 메시지입니다.

exception argparse.ArgumentTypeError¶: 명령줄 문자열을 유형으로 변환하는 과정에서 문제가 생길 때 발생합니다.

가이드 및 튜토리얼

argparse — 명령줄 옵션, 인자 및 하위 명령어용 파서¶

ArgumentParser 객체¶

prog¶

usage¶

description¶

epilog¶

parents¶

formatter_class¶

prefix_chars¶

fromfile_prefix_chars¶

argument_default¶

allow_abbrev¶

conflict_handler¶

add_help¶

exit_on_error¶

suggest_on_error¶

색상¶

add_argument() 메서드¶

name or flags¶

action¶

nargs¶

const¶

default¶

type¶

choices¶

required¶

help¶

metavar¶

dest¶

폐지됨¶

Action 클래스¶

parse_args() 메서드¶

옵션값 문법¶

잘못된 인자¶

- 를 포함하는 인자들¶

인자 약어 (접두사 일치)¶

sys.argv 너머¶

Namespace 객체¶

기타 유틸리티¶

부속 명령¶

FileType 객체¶

인자 그룹¶

상호 배제¶

파서 기본값¶

도움말 인쇄¶

부분 파싱¶

파일 파싱 사용자 정의¶

종료 메서드¶

혼합 파싱¶

커스텀 유형 또는 액션 등록하기¶

예외¶

`argparse` — 명령줄 옵션, 인자 및 하위 명령어용 파서¶

`-` 를 포함하는 인자들¶

`sys.argv` 너머¶