prog¶

به‌طور پیش‌فرض، ArgumentParser نام برنامه را برای نمایش در پیام‌های راهنما، بسته به شیوه‌ای که مفسر پایتون اجرا شده است، محاسبه می‌کند:

• نام پایه برای sys.argv[0]، اگر پرونده‌ای به‌عنوان آرگومان داده شده باشد.

• نام مفسر پایتون که پس از آن sys.argv[0] می‌آید، در صورتی که یک پوشه یا یک پرونده زیپ به‌عنوان آرگومان داده شده باشد.

• نام مفسر پایتون، به‌دنبالِ -m و سپس نام ماژول یا بسته، در صورتی که گزینه‌ی -m استفاده شده باشد.

این پیش‌فرض تقریباً همیشه مطلوب است، زیرا باعث می‌شود پیام‌های راهنما با رشته‌ای که برنامه با آن در خط فرمان فراخوانی شده است مطابقت داشته باشند. با این حال، برای تغییر این رفتار پیش‌فرض، می‌توان مقدار دیگری را با استفاده از آرگومان prog= برای ArgumentParser:: ارائه کرد:

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

استفاده¶

به‌طور پیش‌فرض، 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 برای جایگذاری نام برنامه در پیام‌های کاربرد شما در دسترس است.

هنگامی که پیام کاربرد سفارشی برای پارسر اصلی تعیین می‌شود، ممکن است بخواهید برای اطمینان از سازگاری پیشوندهای فرمان و اطلاعات کاربرد در میان پارسرهای فرعی، ارسال آرگومان prog به add_subparsers() یا آرگومان‌های prog و usage به add_parser() را نیز در نظر بگیرید.

توضیحات¶

در بیشتر فراخوانی‌های سازنده‌ی 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= فهرستی از اشیاء ArgumentParser را می‌پذیرد، همه‌ی کنش‌های جایگاهی و اختیاری (actions) را از آن‌ها جمع‌آوری می‌کند و این کنش‌ها را به شیء 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 (یکی در والد و دیگری در فرزند) را می‌بیند و خطایی پرتاب می‌کند.

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

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 از نام آرگومان type برای هر آرگومان به‌عنوان نام نمایشی برای مقدارهای آن استفاده می‌کند (به‌جای استفاده از dest آن‌گونه که قالب‌بند معمولی انجام می‌دهد):

>>> 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، می‌توانند آن‌ها را با استفاده از آرگومان prefix_chars= در سازنده‌ی ArgumentParser مشخص کنند:

>>> 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¶

گاهی، هنگام کار با یک فهرست آرگومان بسیار طولانی، ممکن است منطقی باشد که فهرست آرگومان‌ها را در یک پرونده نگه دارید، به‌جای آن‌که آن را در خط فرمان تایپ کنید. اگر آرگومان fromfile_prefix_chars= به سازنده‌ی ArgumentParser داده شود، آرگومان‌هایی که با هر یک از نویسه‌های مشخص‌شده آغاز می‌شوند، به‌عنوان پرونده در نظر گرفته می‌شوند و با آرگومان‌هایی که در بر دارند جایگزین می‌شوند. برای مثال:

>>> 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 از filesystem encoding and error handler برای خواندن پرونده حاوی آرگومان‌ها استفاده می‌کند.

مقدار پیش‌فرض آرگومان fromfile_prefix_chars= برابر None است، به این معنا که آرگومان‌ها هرگز به‌عنوان ارجاع به پرونده در نظر گرفته نمی‌شوند.

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¶

به‌طور معمول، هنگامی که یک فهرست آرگومان را به متد parse_args() از یک ArgumentParser ارسال می‌کنید، این متد برای گزینه‌های بلند مخفف‌ها را می‌شناسد.

این قابلیت را می‌توان با تنظیم 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

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) ممکن است مفید باشد که هر آرگومان قدیمی‌تری با همان رشته‌ی گزینه به‌سادگی بازنویسی شود. برای دستیابی به این رفتار، می‌توان مقدار 'resolve' را به آرگومان conflict_handler= در ArgumentParser داد:

>>> 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 یک اکشنرا فقط در صورتی حذف می‌کنند که همه رشته‌های گزینه (option strings) آن بازنویسی‌شده باشند. بنابراین، در مثال بالا، اکشن قدیمی -f/--foo به‌عنوان اکشن -f حفظ می‌شود، زیرا فقط رشته گزینه --foo بازنویسی‌شده است.

add_help¶

به‌طور پیش‌فرض، اشیای ArgumentParser گزینه‌ای اضافه می‌کنند که صرفاً پیام راهنمای پارسر را نمایش می‌دهد. اگر -h یا --help در خط فرمان ارائه شود، راهنمای ArgumentParser چاپ خواهد شد.

گاهی اوقات، ممکن است غیرفعال کردن افزودن این گزینه راهنما مفید باشد. این کار را می‌توان با ارسال False به‌عنوان آرگومان add_help= به 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¶

به‌طور معمول، هنگامی که یک فهرست آرگومان‌های نامعتبر را به متد parse_args() از یک ArgumentParser ارسال می‌کنید، پیامی را در sys.stderr چاپ می‌کند و با کد وضعیت ۲ خارج می‌شود.

اگر کاربر بخواهد خطاها را به‌صورت دستی بگیرد، می‌توان این قابلیت را با تنظیم 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

suggest_on_error¶

به طور پیش‌فرض، هنگامی که کاربری یک انتخاب آرگومان یا نام زیرپارسر نامعتبر را ارسال کند، کلاس 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 پیشنهادها را غیرفعال کنید.

رنگ¶

به‌طور پیش‌فرض، پیام راهنما با استفاده از ANSI escape sequences به‌صورت رنگی چاپ می‌شود. اگر پیام‌های راهنما را به‌صورت متن ساده می‌خواهید، می‌توانید آن را در محیط محلی خود یا در خود پارسر آرگومان با تنظیم 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 تنظیم شده باشند.

برای برجسته‌سازی کد درون‌خطی در توضیحات، epilog، یا متن 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')

هنگامی که رنگ‌ها فعال هستند، متن داخل نقل‌قول‌های معکوس با رنگ متمایزی نمایش داده می‌شود تا به برجسته شدن مثال‌ها کمک کند. هنگامی که رنگ‌ها غیرفعال هستند، نقل‌قول‌های معکوس دقیقاً به همان شکل حفظ می‌شوند که در متن ساده خوانا است.

نام یا پرچم‌ها¶

متد add_argument() باید بداند که آیا یک آرگومان اختیاری، مانند -f یا --foo، یا یک آرگومان جایگاهی، مانند فهرستی از نام پرونده‌ها، انتظار می‌رود. بنابراین اولین آرگومان‌های ارسال‌شده به 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

به‌طور پیش‌فرض، argparse نام‌گذاری داخلی و نام‌های نمایشی آرگومان‌ها را به‌طور خودکار مدیریت می‌کند و فرآیند را بدون نیاز به پیکربندی اضافی ساده می‌سازد. بنابراین، نیازی به مشخص کردن پارامترهای dest و metavar ندارید. برای آرگومان‌های اختیاری، پارامتر dest به‌طور پیش‌فرض برابر با نام آرگومان است، با جایگزینی زیرخط _ به‌جای خط‌تیره -. پارامتر metavar به‌طور پیش‌فرض برابر با نام با حروف بزرگ است. برای مثال:

>>> 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' - این مقدار مشخص‌شده با آرگومان کلیدواژه‌ای const را ذخیره می‌کند؛ توجه داشته باشید که مقدار پیش‌فرض آرگومان کلیدواژه‌ای const برابر None است. اکشن 'store_const' بیشتر با آرگومان‌های اختیاری استفاده می‌شود که نوعی پرچم را مشخص می‌کنند. برای مثال:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--foo', action='store_const', const=42)
  >>> parser.parse_args(['--foo'])
  Namespace(foo=42)
  

• 'store_true' و 'store_false' - این‌ها موارد خاصی از 'store_const' هستند که به‌ترتیب مقادیر True و False را با مقادیر پیش‌فرض False و True ذخیره می‌کنند:

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

  این مقادیر پیش‌فرض زمانی اعمال می‌شوند که گزینه‌ها وجود نداشته باشند. آن‌ها را می‌توان توسط default یا argument_default بازنویسی کرد.

• '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' - این کنش مقدار مشخص‌شده توسط آرگومان کلیدواژه‌ای const را به یک فهرست الحاق می‌کند؛ توجه داشته باشید که مقدار پیش‌فرض آرگومان کلیدواژه‌ای const برابر None است. کنش 'append_const' معمولاً زمانی مفید است که چند آرگومان نیاز دارند ثابت‌ها را در یک فهرست مشترک ذخیره کنند. برای مثال:

  >>> 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' - این هر یک از آیتم‌های یک آرگومان چندمقداری را به یک فهرست اضافه می‌کند. اکشن 'extend' معمولاً همراه با مقدار '+' یا '*' برای آرگومان کلیدواژه‌ای nargs استفاده می‌شود. توجه داشته باشید که وقتی nargs برابر با None (پیش‌فرض) یا '?' باشد، هر نویسه‌ی رشته‌ی آرگومان به فهرست اضافه خواهد شد. نمونه کاربرد:

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

  اضافه شده در نسخه‌ی 3.8.

• 'count' - این تعداد دفعاتی را که یک آرگومان رخ می‌دهد می‌شمارد. برای مثال، این برای افزایش سطوح پرگویی مفید است:

  >>> parser = argparse.ArgumentParser()
  >>> parser.add_argument('--verbose', '-v', action='count', default=0)
  >>> parser.parse_args(['-vvv'])
  Namespace(verbose=3)
  

  مگر اینکه به صراحت تنظیم شده باشد، default برابر با None خواهد بود. اگر مقدار پیش‌فرض عددی غیرصفر باشد، شمارش از آن عدد آغاز می‌شود نه از صفر.

• 'help' - این یک پیام راهنمای کامل برای همه گزینه‌های پارسر فعلی را چاپ می‌کند و سپس خارج می‌شود. به‌طور پیش‌فرض، یک اکشن راهنما به‌صورت خودکار به پارسر اضافه می‌شود. برای جزئیات چگونگی ایجاد خروجی، ArgumentParser را ببینید.

• 'version' - این گزینه به یک آرگومان کلیدواژه‌ای version= در فراخوانی add_argument() نیاز دارد و هنگام فراخوانی، اطلاعات نسخه را چاپ کرده و خارج می‌شود:

  >>> 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' یا کنش‌های سفارشی با nargs غیرصفر) می‌توانند با آرگومان‌های جایگاهی استفاده شوند.

روش توصیه‌شده برای ایجاد یک کنش سفارشی، گسترش Action با بازنویسی متد __call__() و به‌اختیار متدهای __init__() و format_usage() است. همچنین می‌توانید کنش‌های سفارشی را با استفاده از متد register() ثبت کنید و با نام ثبت‌شده‌ی آن‌ها به آن‌ها ارجاع دهید.

مثالی از یک اکشن سفارشی:

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

اگر آرگومان کلیدواژه‌ای nargs ارائه نشده باشد، تعداد آرگومان‌های مصرف‌شده توسط action تعیین می‌شود. به‌طور معمول، این بدان معناست که یک آرگومان خط فرمان مصرف می‌شود و یک آیتم (نه یک فهرست) تولید می‌شود. کنش‌هایی که آرگومان‌های خط فرمان را مصرف نمی‌کنند (مانند 'store_const')، nargs=0 را تنظیم می‌کنند.

const¶

آرگومان const در add_argument() برای نگهداری مقادیر ثابتی استفاده می‌شود که از خط فرمان خوانده نمی‌شوند، اما برای کنش‌های مختلف ArgumentParser مورد نیاز هستند. دو مورد از رایج‌ترین کاربردهای آن عبارت‌اند از:

• هنگامی که add_argument() با action='store_const' یا action='append_const' فراخوانی می‌شود. این اکشن‌ها مقدار const را به یکی از ویژگی‌های شیء برگردانده‌شده توسط parse_args() اضافه می‌کنند. برای مثال‌ها، شرح action را ببینید. اگر const به add_argument() ارائه نشود، مقدار پیش‌فرض None را دریافت خواهد کرد.

• هنگامی که add_argument() با رشته‌های گزینه (مانند -f یا --foo) و nargs='?' فراخوانی می‌شود، این کار یک آرگومان اختیاری ایجاد می‌کند که می‌تواند صفر یا یک آرگومان خط فرمان پس از خود داشته باشد. هنگام تجزیه خط فرمان، اگر رشته گزینه بدون هیچ آرگومان خط فرمانی پس از آن مشاهده شود، مقدار const استفاده خواهد شد. برای نمونه‌ها، توضیحات nargs را ببینید.

پیش‌فرض¶

تمام آرگومان‌های اختیاری و برخی آرگومان‌های جایگاهی را می‌توان در خط فرمان حذف کرد. آرگومان کلیدواژه‌ای default تابع add_argument() مشخص می‌کند که اگر آرگومان خط فرمان وجود نداشته باشد، چه مقداری باید استفاده شود. برای مثال:

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

اگر default حذف شود، add_argument() از مقداری که قبلاً برای dest با set_defaults() تنظیم شده است، یا در غیر این صورت از یک argument_default غیر-None استفاده می‌کند. اگر هیچ‌کدام تنظیم نشده باشند، از پیش‌فرض خودِ اکشن استفاده می‌شود.

اگر فضای نام هدف از قبل ویژگی تنظیم‌شده‌ای داشته باشد، پیش‌فرضِ اکشن آن را بازنویسی نمی‌کند:

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

اگر مقدار default یک رشته باشد، پارسر مقدار را طوری تجزیه می‌کند که گویی یک آرگومان خط فرمان باشد. به‌طور خاص، پارسر هر آرگومان تبدیل type را، در صورت ارائه، پیش از تنظیم ویژگی روی مقدار بازگشتی Namespace اعمال می‌کند. در غیر این صورت، پارسر از مقدار همان‌طور که هست استفاده می‌کند:

>>> 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=None همچنان [] برمی‌گرداند).

برای آرگومان‌های required، مقدار default نادیده گرفته می‌شود. برای مثال، این موضوع به آرگومان‌های جایگاهی با مقادیر nargs غیر از ? یا *، یا آرگومان‌های اختیاری که با 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')

نوع¶

به‌طور پیش‌فرض، پارسر آرگومان‌های خط فرمان را به‌صورت رشته‌های ساده می‌خواند. با این حال، اغلب رشته‌ی خط فرمان باید به‌جای آن به‌عنوان نوع دیگری تفسیر شود، مانند float یا int. کلیدواژه‌ی type برای add_argument() امکان انجام هرگونه بررسی نوع و تبدیل نوع ضروری را فراهم می‌کند.

اگر از کلیدواژه‌ی type همراه با کلیدواژه‌ی default استفاده شود، مبدل نوع فقط زمانی اعمال می‌شود که مقدار پیش‌فرض یک رشته باشد.

آرگومان type می‌تواند یک شیء فراخوانی‌پذیر باشد که یک رشته واحد را می‌پذیرد، یا نام یک نوع ثبت‌شده (به register() مراجعه کنید). اگر تابع ArgumentTypeError، TypeError یا ValueError را پرتاب کند، استثنا گرفته می‌شود و یک پیام خطای به‌خوبی قالب‌بندی‌شده نمایش داده می‌شود. سایر انواع استثنا مدیریت نمی‌شوند.

می‌توان از انواع و توابع توکار رایج به‌عنوان مبدل‌های نوع استفاده کرد:

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 به‌درستی قالب‌بندی نمی‌شد و استثنای FileNotFoundError به‌هیچ‌وجه مدیریت نمی‌شد.

حتی FileType برای استفاده با کلیدواژه‌ی type محدودیت‌هایی دارد. اگر یک آرگومان از FileType استفاده کند و سپس آرگومان بعدی با شکست مواجه شود، خطایی گزارش می‌شود اما پرونده به‌طور خودکار بسته نمی‌شود. در این صورت، بهتر است تا پایان اجرای پارسر صبر کنید و سپس از دستور with برای مدیریت پرونده‌ها استفاده کنید.

برای ابزارهای بررسی نوع که صرفاً در برابر مجموعه ثابتی از مقادیر بررسی می‌کنند، استفاده از کلیدواژه choices را به‌جای آن در نظر بگیرید.

گزینه‌ها¶

برخی آرگومان‌های خط فرمان باید از میان یک مجموعه محدود از مقدارها انتخاب شوند. این موارد را می‌توان با ارسال یک شیء دنباله به‌عنوان آرگومان کلیدواژه‌ای choices به add_argument() مدیریت کرد. هنگامی که خط فرمان تجزیه می‌شود، مقدارهای آرگومان بررسی خواهند شد و اگر آرگومان یکی از مقدارهای قابل‌قبول نباشد، یک پیام خطا نمایش داده می‌شود:

>>> 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 را حذف کنید و تبدیل را در کد برنامه‌تان مدیریت کنید.

گزینه‌های قالب‌بندی‌شده به‌جای metavar پیش‌فرض، که معمولاً از dest مشتق می‌شود، استفاده می‌شوند. این معمولاً همان چیزی است که شما می‌خواهید، زیرا کاربر هرگز پارامتر dest را نمی‌بیند. اگر این نمایش مطلوب نیست (شاید به این دلیل که گزینه‌های زیادی وجود دارد)، کافی است یک metavar صریح مشخص کنید.

الزامی¶

به‌طور کلی، ماژول argparse فرض می‌کند که پرچم‌هایی مانند -f و --bar نشان‌دهنده‌ی آرگومان‌های اختیاری هستند که همیشه می‌توان در خط فرمان از آن‌ها صرف‌نظر کرد. برای الزامی کردن یک گزینه، می‌توان True را برای آرگومان کلیدواژه‌ای required= در add_argument() مشخص کرد:

>>> 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 یک رشته است که شامل توضیحی مختصر در مورد آرگومان می‌شود. هنگامی که کاربر درخواست راهنما می‌کند (معمولاً با استفاده از -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¶

هنگامی که ArgumentParser پیام‌های راهنما را تولید می‌کند، به روشی برای ارجاع به هر آرگومان مورد انتظار نیاز دارد. به‌طور پیش‌فرض، اشیاء ArgumentParser از مقدار dest به‌عنوان «نام» هر شیء استفاده می‌کنند. به‌طور پیش‌فرض، برای کنش‌های آرگومان‌های جایگاهی، مقدار dest مستقیماً استفاده می‌شود، و برای کنش‌های آرگومان‌های اختیاری، مقدار dest به حروف بزرگ تبدیل می‌شود. بنابراین، یک آرگومان جایگاهی با dest='bar'، bar نامیده می‌شود. یک آرگومان اختیاری --foo که باید یک آرگومان خط فرمان به دنبال آن بیاید، FOO نامیده می‌شود. یک مثال:

>>> 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() می‌افزایند. نام این ویژگی با آرگومان کلیدواژه‌ای dest در add_argument() تعیین می‌شود. برای کنش‌های آرگومان‌های جایگاهی، 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')

آرگومان‌های متعدد می‌توانند dest یکسانی داشته باشند. به‌صورت پیش‌فرض، مقدار آخرین آرگومان از این نوع که در خط فرمان وارد شود، برنده می‌شود. در عوض، برای جمع‌آوری مقادیر همه‌ی آن‌ها در یک فهرست، از action='append' استفاده کنید. برای رشته‌های گزینه دارای تعارض، نه نام‌های dest، conflict_handler را ببینید.

منسوخ¶

در طول عمر یک پروژه، ممکن است نیاز باشد برخی آرگومان‌ها از خط فرمان حذف شوند. پیش از حذف آن‌ها، باید به کاربران خود اطلاع دهید که آرگومان‌ها منسوخ شده‌اند و حذف خواهند شد. آرگومان کلیدواژه‌ای deprecated در add_argument()، که مقدار پیش‌فرض آن False است، مشخص می‌کند که آیا آرگومان منسوخ است و در آینده حذف خواهد شد یا خیر. برای آرگومان‌ها، اگر 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)

کلاس‌های اکشن¶

کلاس‌های Action، Action API را پیاده‌سازی می‌کنند؛ یک فراخوانی‌پذیر که یک فراخوانی‌پذیر برای پردازش آرگومان‌های خط فرمان بازمی‌گرداند. هر شیء‌ای که از این API پیروی کند، می‌تواند به‌عنوان پارامتر action به add_argument() ارسال شود.

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

اشیای Action توسط یک ArgumentParser برای نشان دادن اطلاعات مورد نیاز برای تجزیه‌ی یک آرگومان از یک یا چند رشته از خط فرمان به کار می‌روند. کلاس Action باید دو آرگومان جایگاهی به‌همراه هر آرگومان کلیدواژه‌ای که به ArgumentParser.add_argument() ارسال می‌شود، به‌جز خود action، بپذیرد.

در نمونه‌های Action (یا مقدار بازگشتی هر فراخوانی‌پذیر که به پارامتر action داده شود) باید ویژگی‌های dest، option_strings، default، type، required، help و غیره تعریف‌شده باشند. ساده‌ترین راه برای اطمینان از تعریف این ویژگی‌ها، فراخوانی Action.__init__() است.

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

نمونه‌های Action باید فراخوانی‌پذیر باشند، بنابراین زیرکلاس‌ها باید متد __call__() را بازنویسی کنند، که باید چهار پارامتر بپذیرد:

• parser - شیء ArgumentParser که شامل این اکشناست.

• namespace - شیء Namespace که توسط parse_args() بازگردانده می‌شود. بیشتر اکشن‌ها با استفاده از setattr() یک ویژگی به این شیء اضافه می‌کنند.

• values - آرگومان‌های مرتبط با خط فرمان، با هرگونه تبدیل نوع اعمال‌شده. تبدیل‌های نوع با آرگومان کلیدواژه‌ای type در add_argument() مشخص می‌شوند.

• option_string - رشته‌ی گزینه‌ای که برای فراخوانی این عمل استفاده شده است. آرگومان 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 اضافه نمی‌شود.

اضافه شده در نسخه‌ی 3.9.

تغییر یافته در نسخه‌ی 3.15: پشتیبانی از گزینه‌های تک‌خط‌تیره اضافه شد.

پشتیبانی از prefix_chars جایگزین اضافه شد.

سینتکس مقدار گزینه¶

متد 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='?')

>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'

>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: unrecognized arguments: --bar

>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: unrecognized arguments: badger

آرگومان‌های شامل -¶

متد parse_args() تلاش می‌کند هرگاه کاربر به‌وضوح اشتباهی مرتکب شده باشد، خطا گزارش کند، اما برخی موقعیت‌ها ذاتاً مبهم هستند. برای مثال، آرگومان خط فرمان -1 می‌تواند تلاشی برای مشخص کردن یک گزینه یا تلاشی برای ارائه یک آرگومان جایگاهی باشد. متد parse_args() در اینجا محتاط است: آرگومان‌های جایگاهی تنها در صورتی می‌توانند با - شروع شوند که شبیه اعداد منفی باشند و هیچ گزینه‌ای در پارسر وجود نداشته باشد که شبیه اعداد منفی باشد:

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

>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')

>>> # no negative number options, so -1 and -5 are positional arguments
>>> 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='?')

>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')

>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: unrecognized arguments: -2

>>> # negative number options present, so both -1s are options
>>> 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)

برای جزئیات بیشتر، راهنمای argparse درباره آرگومان‌های مبهم را نیز ببینید.

مخفف‌های آرگومان (تطبیق پیشوند)¶

متد 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¶

گاهی ممکن است مفید باشد که یک ArgumentParser آرگومان‌هایی غیر از آرگومان‌های sys.argv را تجزیه کند. این کار را می‌توان با گذراندن فهرستی از رشته‌ها به parse_args() انجام داد. این برای آزمون در خط فرمان تعاملی مفید است:

>>> 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])

شیء فضای نام¶

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 - عنوان برای گروه زیرپارسر (sub-parser) در خروجی راهنما؛ به‌طور پیش‌فرض اگر توضیحات ارائه شده باشد، "subcommands" خواهد بود، در غیر این صورت، از عنوان آرگومان‌های جایگاهی استفاده می‌شود

• description - توضیح برای گروه زیرپارسرها در خروجی راهنما، به‌طور پیش‌فرض None

• prog - اطلاعات استفاده‌ای که همراه با راهنمای زیردستور نمایش داده می‌شود، به‌طور پیش‌فرض نام برنامه و هر آرگومان جایگاهی پیش از آرگومان زیرپارسر (subparser)

• parser_class - کلاسی که برای ایجاد نمونه‌های زیرپارسر استفاده خواهد شد، به‌طور پیش‌فرض کلاس پارسر فعلی (مثلاً ArgumentParser)

• action - نوع پایه‌ای اکشنی که باید هنگام مواجهه با این آرگومان در خط فرمان انجام شود

• dest - نام ویژگی‌ای که نام زیردستور در آن ذخیره می‌شود؛ به‌طور پیش‌فرض None است و هیچ مقداری ذخیره نمی‌شود

• required - اینکه آیا یک زیردستور باید ارائه شود یا خیر، به‌طور پیش‌فرض False (در 3.7 افزوده شده است)

• help - راهنمای گروه زیرپارسرها در خروجی راهنما، به‌طور پیش‌فرض None

• metavar - رشته‌ای که زیردستورهای در دسترس را در راهنما نمایش می‌دهد؛ به‌طور پیش‌فرض None است و زیردستورها را در قالب {cmd1, cmd2, ..} نمایش می‌دهد

چند نمونه کاربرد:

>>> # create the top-level parser
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='subcommand help')
>>>
>>> # create the parser for the "a" command
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # create the parser for the "b" command
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help')
>>>
>>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
Namespace(baz='Z', foo=True)

توجه داشته باشید که شیء بازگردانده‌شده توسط parse_args() تنها شامل ویژگی‌های مربوط به پارسر اصلی و زیرپارسری خواهد بود که توسط خط فرمان انتخاب شده است (و شامل سایر زیرپارسرها نمی‌شود). بنابراین در مثال بالا، هنگامی که دستور a مشخص می‌شود، تنها ویژگی‌های foo و bar حضور دارند، و هنگامی که دستور b مشخص می‌شود، تنها ویژگی‌های foo و baz حضور دارند.

اگر یک زیرپارسر آرگومانی با همان dest پارسر والد تعریف کند، این دو یک ویژگی فضای نام واحد را به اشتراک می‌گذارند، بنابراین مقدار پارسر والد حفظ نخواهد شد. کاربران باید برای آن‌ها مقادیر dest متمایزی تعیین کنند تا هر دو حفظ شوند.

به‌طور مشابه، هنگامی که یک پیام راهنما از یک زیرپارسر درخواست شود، فقط راهنمای همان پارسر خاص چاپ خواهد شد. پیام راهنما شامل پیام‌های پارسر والد یا پارسرهای هم‌سطح نخواهد شد. (با این حال، می‌توان با ارائه آرگومان help= به add_parser() مانند بالا، یک پیام راهنما برای هر دستور زیرپارسر ارائه داد.)

>>> 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() است تا هر زیرپارسر بداند که کدام تابع پایتون را باید اجرا کند. برای مثال:

>>> # subcommand functions
>>> def foo(args):
...     print(args.x * args.y)
...
>>> def bar(args):
...     print('((%s))' % args.z)
...
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(required=True)
>>>
>>> # create the parser for the "foo" command
>>> 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)
>>>
>>> # create the parser for the "bar" command
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))

به این ترتیب، می‌توانید به parse_args() اجازه دهید کار فراخوانی تابع مناسب را پس از اتمام تجزیه آرگومان انجام دهد. مرتبط کردن توابع با کنش‌ها به این شکل، معمولاً آسان‌ترین راه برای مدیریت کنش‌های مختلف برای هر یک از زیرپارسرهای شما است. با این حال، اگر بررسی نام زیرپارسری که فراخوانی شده است ضروری باشد، آرگومان کلیدواژه‌ای dest در فراخوانی add_subparsers() کارساز خواهد بود:

>>> 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)¶

یک شیء جدید ArgumentParser برای name (نام) زیردستور ایجاد کرده و برمی‌گرداند.

آرگومان 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 منتقل می‌شوند.

اضافه شده در نسخه‌ی 3.13: پارامتر deprecated اضافه شد.

اشیای FileType¶

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

کارخانه‌ی FileType اشیایی را ایجاد می‌کند که می‌توان آن‌ها را به آرگومان type در ArgumentParser.add_argument() ارسال کرد. آرگومان‌هایی که اشیای 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 آرگومان‌های خط فرمان را هنگام نمایش پیام‌های راهنمایی به «آرگومان‌های جایگاهی» و «گزینه‌ها» گروه‌بندی می‌کند. هرگاه گروه‌بندی مفهومی بهتری نسبت به این حالت پیش‌فرض برای آرگومان‌ها وجود داشته باشد، می‌توان گروه‌های مناسب را با استفاده از متد 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 معمولی، متد 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

پارامترهای اختیاری و فقط کلیدواژه‌ای argument_default و conflict_handler امکان کنترل دقیق‌تر رفتار گروه آرگومان را فراهم می‌کنند. این پارامترها همان معنایی را دارند که در سازنده‌ی ArgumentParser دارند، اما به‌طور خاص بر گروه آرگومان اعمال می‌شوند، نه بر کل پارسر.

توجه داشته باشید که هر آرگومانی که در گروه‌های تعریف‌شده توسط شما نباشد، در نهایت به بخش‌های معمول «آرگومان‌های جایگاهی» و «آرگومان‌های اختیاری» بازمی‌گردد.

در هر گروه آرگومان، آرگومان‌ها در خروجی راهنما به همان ترتیبی که افزوده شده‌اند نمایش داده می‌شوند.

منسوخ شده از نسخه‌ی 3.11، در نسخه‌ی 3.14 حذف شده است: فراخوانی add_argument_group() بر روی یک گروه آرگومان اکنون استثنا پرتاب می‌کند. این تودرتوسازی هرگز پشتیبانی نمی‌شد، اغلب به‌درستی کار نمی‌کرد و به‌طور غیرعمد از طریق ارث‌بری در دسترس قرار گرفته بود.

منسوخ شده از نسخه‌ی 3.14: ارسال prefix_chars به add_argument_group() اکنون منسوخ شده است.

انحصار متقابل¶

ArgumentParser.add_mutually_exclusive_group(required=False)¶

یک گروه با انحصار متقابل ایجاد کنید. 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

توجه کنید که در حال حاضر گروه‌های آرگومان انحصاریِ متقابل از آرگومان‌های title و description متد add_argument_group() پشتیبانی نمی‌کنند. بااین‌حال، یک گروه انحصاریِ متقابل را می‌توان به یک گروه آرگومان که دارای عنوان و توضیحات است اضافه کرد. برای مثال:

>>> 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() یا 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)

توجه داشته باشید که پیش‌فرض‌ها را می‌توان هم در سطح پارسر با استفاده از set_defaults() و هم در سطح آرگومان با استفاده از 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() می‌تواند مفید باشد.

این متد مشابه 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'])

سفارشی‌سازی تجزیه پرونده¶

ArgumentParser.convert_arg_line_to_args(arg_line)¶

آرگومان‌هایی که از یک پرونده خوانده می‌شوند (آرگومان کلیدواژه‌ای fromfile_prefix_chars در سازنده‌ی ArgumentParser را ببینید)، به‌صورت یک آرگومان در هر خط خوانده می‌شوند. می‌توان 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 مشخص خاتمه می‌دهد و در صورت ارائه شدن، پیش از آن یک message را در sys.stderr چاپ می‌کند. کاربر می‌تواند این متد را بازنویسی کند تا این مراحل به شکل متفاوتی مدیریت شوند:

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 چاپ می‌کند و برنامه را با کد وضعیت ۲ پایان می‌دهد.

تجزیه درهم‌آمخته¶

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 پشتیبانی نمی‌کنند و در صورت استفاده از قابلیت‌های پشتیبانی‌نشده، استثنا پرتاب می‌کنند. به‌طور خاص، زیرپارسرها و گروه‌های متقابلاً انحصاری که شامل هر دو آرگومان اختیاری و جایگاهی هستند، پشتیبانی نمی‌شوند.

مثال زیر تفاوت میان 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() اگر رشته‌های آرگومان تجزیه‌نشده‌ی باقی‌مانده‌ای وجود داشته باشد، خطایی پرتاب می‌کند.

اضافه شده در نسخه‌ی 3.7.

ثبت انواع سفارشی یا کنش‌های سفارشی¶

ArgumentParser.register(registry_name, value, object)¶

گاهی اوقات مطلوب است که در پیام‌های خطا از یک رشته سفارشی استفاده شود تا خروجی کاربر پسندتری ارائه شود. در این موارد، 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'