argparse --- Trình phân tích cú pháp cho các tùy chọn dòng lệnh, đối số và lệnh phụ

Added in version 3.2.

Source code: Lib/argparse.py

Ghi chú

Mặc dù argparse là mô-đun thư viện tiêu chuẩn được đề xuất mặc định để triển khai các ứng dụng dòng lệnh cơ bản, nhưng các tác giả có yêu cầu chính xác hơn về cách ứng dụng dòng lệnh của họ hoạt động chính xác có thể thấy nó không cung cấp mức độ kiểm soát cần thiết. Tham khảo Chọn thư viện phân tích đối số để biết các lựa chọn thay thế cần cân nhắc khi argparse không hỗ trợ các hành vi mà ứng dụng yêu cầu (chẳng hạn như tắt hoàn toàn hỗ trợ cho các tùy chọn xen kẽ và đối số vị trí hoặc chấp nhận các giá trị tham số tùy chọn bắt đầu bằng - ngay cả khi chúng tương ứng với một tùy chọn được xác định khác).

Mô-đun argparse giúp bạn dễ dàng viết giao diện dòng lệnh thân thiện với người dùng. Chương trình xác định những đối số mà nó yêu cầu và argparse sẽ tìm ra cách phân tích những đối số đó ra khỏi sys.argv. Mô-đun argparse cũng tự động tạo thông báo trợ giúp và sử dụng. Mô-đun cũng sẽ báo lỗi khi người dùng đưa ra các đối số không hợp lệ cho chương trình.

Hỗ trợ của mô-đun argparse cho giao diện dòng lệnh được xây dựng dựa trên phiên bản của argparse.ArgumentParser. Nó là nơi chứa các đặc tả đối số và có các tùy chọn áp dụng cho toàn bộ trình phân tích cú pháp

trình phân tích cú pháp = argparse.ArgumentParser(
                    prog='Tên chương trình',
                    description='Chương trình làm gì',
                    epilog='Văn bản ở cuối phần trợ giúp')

Phương thức ArgumentParser.add_argument() đính kèm các đặc tả đối số riêng lẻ vào trình phân tích cú pháp. Nó hỗ trợ các đối số vị trí, các tùy chọn chấp nhận giá trị và cờ bật/tắt

đối số parser.add_argument('filename') # positional
Parser.add_argument('-c', '--count') # option nhận một giá trị
parser.add_argument('-v', '--verbose',
                    action='store_true') cờ # on/tắt

Phương thức ArgumentParser.parse_args() chạy trình phân tích cú pháp và đặt dữ liệu được trích xuất vào đối tượng argparse.Namespace

args = trình phân tích cú pháp.parse_args()
print(args.filename, args.count, args.verbose)

Ghi chú

Nếu bạn đang tìm hướng dẫn về cách nâng cấp mã optparse lên argparse, hãy xem Upgrading Optparse Code.

Đối tượng 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=False, color=True)

Tạo một đối tượng ArgumentParser mới. Tất cả các tham số phải được chuyển dưới dạng đối số từ khóa. Mỗi tham số có mô tả chi tiết hơn bên dưới, nhưng tóm lại là:

  • prog - Tên của chương trình (mặc định: được tạo từ các thuộc tính mô-đun __main__ và sys.argv[0])

  • Cách sử dụng - Chuỗi mô tả cách sử dụng chương trình (mặc định: được tạo từ các đối số được thêm vào trình phân tích cú pháp)

  • description - Văn bản hiển thị trước trợ giúp đối số (theo mặc định, không có văn bản)

  • epilog - Văn bản hiển thị sau trợ giúp đối số (theo mặc định, không có văn bản)

  • parent - Danh sách các đối tượng ArgumentParser có đối số cũng cần được đưa vào

  • formatter_class - Một lớp để tùy chỉnh đầu ra trợ giúp

  • prefix_chars - Tập hợp các ký tự có tiền tố đối số tùy chọn (mặc định: '-')

  • fromfile_prefix_chars - Tập hợp các ký tự tiền tố của tệp mà từ đó các đối số bổ sung sẽ được đọc (mặc định: None)

  • đối số_default - Giá trị mặc định chung cho đối số (mặc định: None)

  • xung đột_handler - Chiến lược giải quyết các tùy chọn xung đột (thường không cần thiết)

  • add_help - Thêm tùy chọn -h/--help vào trình phân tích cú pháp (mặc định: True)

  • allow_abbrev - Cho phép viết tắt các tùy chọn dài nếu chữ viết tắt rõ ràng (mặc định: True)

  • exit_on_error - Xác định xem ArgumentParser có thoát với thông tin lỗi khi xảy ra lỗi hay không. (mặc định: True)

  • gợi ý_on_error - Cho phép đề xuất cho các lựa chọn đối số bị nhập sai và tên trình phân tích cú pháp con (mặc định: False)

  • color - Cho phép xuất màu (mặc định: True)

Thay đổi trong phiên bản 3.5: tham số allow_abbrev đã được thêm vào.

Thay đổi trong phiên bản 3.8: Trong các phiên bản trước, allow_abbrev cũng vô hiệu hóa việc nhóm các cờ ngắn như -vv có nghĩa là -v -v.

Thay đổi trong phiên bản 3.9: tham số exit_on_error đã được thêm vào.

Thay đổi trong phiên bản 3.14: Các thông số suggest_on_error và color đã được thêm vào.

Các phần sau đây mô tả cách sử dụng từng loại này.

buổi lễ

Theo mặc định, ArgumentParser tính toán tên của chương trình để hiển thị trong thông báo trợ giúp tùy thuộc vào cách chạy trình thông dịch Python:

  • base name của sys.argv[0] nếu một tệp được chuyển làm đối số.

  • Tên trình thông dịch Python theo sau là sys.argv[0] nếu một thư mục hoặc tệp zip được chuyển làm đối số.

  • Tên trình thông dịch Python theo sau là -m, theo sau là tên mô-đun hoặc gói nếu tùy chọn -m được sử dụng.

Mặc định này hầu như luôn được mong muốn vì nó sẽ làm cho các thông báo trợ giúp khớp với chuỗi được sử dụng để gọi chương trình trên dòng lệnh. Tuy nhiên, để thay đổi hành vi mặc định này, một giá trị khác có thể được cung cấp bằng đối số prog= cho ArgumentParser:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='myprogram')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: chương trình của tôi [-h]

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát

Lưu ý rằng tên chương trình, cho dù được xác định từ sys.argv[0], từ thuộc tính mô-đun __main__ hoặc từ đối số prog=, đều có sẵn để trợ giúp các thông báo bằng cách sử dụng bộ xác định định dạng %(prog)s.

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='myprogram')
>>> Parser.add_argument('--foo', help='foo của chương trình %(prog)s')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: chương trình của tôi [-h] [--foo FOO]

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát
 --foo FOO foo của chương trình myprogram

Thay đổi trong phiên bản 3.14: Giá trị prog mặc định hiện phản ánh cách __main__ thực sự được thực thi, thay vì luôn là os.path.basename(sys.argv[0]).

cách sử dụng

Theo mặc định, ArgumentParser tính toán thông báo sử dụng từ các đối số chứa trong đó. Thông báo mặc định có thể được ghi đè bằng đối số từ khóa usage=

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG', use='%(prog)s [options]')
>>> Parser.add_argument('--foo', nargs='?', help='foo help')
>>> Parser.add_argument('bar', nargs='+', help='bar help')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [tùy chọn]

lập luận vị trí:
 trợ giúp thanh bar

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát
 --foo [FOO] foo giúp đỡ

Công cụ xác định định dạng %(prog)s có sẵn để điền tên chương trình vào thông báo sử dụng của bạn.

Khi thông báo sử dụng tùy chỉnh được chỉ định cho trình phân tích cú pháp chính, bạn cũng có thể muốn xem xét chuyển đối số prog cho add_subparsers() hoặc prog và các đối số usage cho add_parser(), để đảm bảo tiền tố lệnh và thông tin sử dụng nhất quán trên các phân tích cú pháp phụ.

mô tả

Hầu hết các lệnh gọi tới hàm tạo ArgumentParser sẽ sử dụng đối số từ khóa description=. Đối số này đưa ra một mô tả ngắn gọn về những gì chương trình làm và cách thức hoạt động của nó. Trong thông báo trợ giúp, mô tả được hiển thị giữa chuỗi sử dụng dòng lệnh và thông báo trợ giúp cho các đối số khác nhau.

Theo mặc định, mô tả sẽ được ngắt dòng để vừa với khoảng trống nhất định. Để thay đổi hành vi này, hãy xem đối số formatter_class.

lời kết

Một số chương trình muốn hiển thị mô tả bổ sung về chương trình sau phần mô tả các đối số. Văn bản như vậy có thể được chỉ định bằng cách sử dụng đối số epilog= cho ArgumentParser:

>>> trình phân tích cú pháp = argparse.ArgumentParser(
... description='Một thanh foo đó',
... epilog="Và đó là cách bạn đi bar")
>>> trình phân tích cú pháp.print_help()
cách sử dụng: argparse.py [-h]

Một foo đó thanh

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát

Và đó là cách bạn đánh bại một quán bar

Giống như đối số description, văn bản epilog= theo mặc định được ngắt dòng, nhưng hành vi này có thể được điều chỉnh bằng đối số formatter_class thành ArgumentParser.

bố mẹ

Đôi khi, một số trình phân tích cú pháp có chung một bộ đối số. Thay vì lặp lại định nghĩa của các đối số này, có thể sử dụng một trình phân tích cú pháp duy nhất có tất cả các đối số được chia sẻ và được chuyển tới đối số parents= tới ArgumentParser. Đối số parents= lấy danh sách các đối tượng ArgumentParser, thu thập tất cả các hành động vị trí và tùy chọn từ chúng, đồng thời thêm các hành động này vào đối tượng ArgumentParser đang được xây dựng:

>>> 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'])
Không gian tên(foo='XXX', parent=2)

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Không gian tên(bar='YYY', parent=None)

Lưu ý rằng hầu hết các trình phân tích cú pháp gốc sẽ chỉ định add_help=False. Nếu không, ArgumentParser sẽ thấy hai tùy chọn -h/--help (một ở cha và một ở con) và đưa ra lỗi.

Ghi chú

Bạn phải khởi tạo đầy đủ các trình phân tích cú pháp trước khi chuyển chúng qua parents=. Nếu bạn thay đổi trình phân tích cú pháp gốc sau trình phân tích cú pháp con, những thay đổi đó sẽ không được phản ánh ở trình phân tích cú pháp con.

lớp định dạng

Các đối tượng ArgumentParser cho phép tùy chỉnh định dạng trợ giúp bằng cách chỉ định một lớp định dạng thay thế. Hiện nay có 4 lớp như vậy:

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

RawDescriptionHelpFormatter và RawTextHelpFormatter cung cấp nhiều quyền kiểm soát hơn về cách hiển thị mô tả văn bản. Theo mặc định, các đối tượng ArgumentParser bọc dòng văn bản description và epilog trong thông báo trợ giúp dòng lệnh:

>>> trình phân tích cú pháp = argparse.ArgumentParser(
... prog='PROG',
... description='''mô tả này
... được thụt vào một cách kỳ lạ
...nhưng không sao đâu''',
... phần kết='''
... tương tự như vậy đối với phần kết này có khoảng trắng sẽ
... được dọn dẹp và lời nói của ai sẽ được bọc lại
... qua một vài dòng''')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [-h]

mô tả này thụt vào hơi kỳ lạ nhưng không sao

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát

tương tự như vậy đối với phần kết này, khoảng trắng sẽ được dọn sạch và các từ của nó
sẽ được gói gọn trong vài dòng

Việc chuyển RawDescriptionHelpFormatter thành formatter_class= cho biết rằng description và epilog đã được định dạng chính xác và không được ngắt dòng:

>>> trình phân tích cú pháp = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.RawDescriptionHelpFormatter,
... description=textwrap.dedent('''\
... Xin đừng làm xáo trộn văn bản này!
... --------------------------------
... Tôi đã thụt lề nó
... chính xác là cách
... tôi muốn nó
...''))
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [-h]

Xin đừng làm xáo trộn văn bản này!
--------------------------------
   Tôi đã thụt lề nó
   chính xác là con đường
   tôi muốn nó

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát

RawTextHelpFormatter duy trì khoảng trắng cho tất cả các loại văn bản trợ giúp, bao gồm cả mô tả đối số. Tuy nhiên, nhiều dòng mới được thay thế bằng một dòng. Nếu bạn muốn giữ nhiều dòng trống, hãy thêm dấu cách giữa các dòng mới.

ArgumentDefaultsHelpFormatter tự động thêm thông tin về các giá trị mặc định vào từng thông báo trợ giúp đối số:

>>> trình phân tích cú pháp = 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!')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [-h] [--foo FOO] [bar ...]

lập luận vị trí:
 thanh BAR! (mặc định: [1, 2, 3])

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát
 --foo FOO FOO! (mặc định: 42)

MetavarTypeHelpFormatter sử dụng tên của đối số type cho mỗi đối số làm tên hiển thị cho các giá trị của nó (thay vì sử dụng dest như trình định dạng thông thường):

>>> trình phân tích cú pháp = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.MetavarTypeHelpFormatter)
>>> Parser.add_argument('--foo', type=int)
>>> Parser.add_argument('bar', type=float)
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [-h] [--foo int] float

lập luận vị trí:
  phao

tùy chọn:
  -h, --help hiển thị thông báo trợ giúp này và thoát
  --foo int

tiền tố_chars

Hầu hết các tùy chọn dòng lệnh sẽ sử dụng - làm tiền tố, ví dụ: -f/--foo. Các trình phân tích cú pháp cần hỗ trợ các ký tự tiền tố khác hoặc bổ sung, ví dụ: đối với các tùy chọn như +f hoặc /foo, có thể chỉ định chúng bằng cách sử dụng đối số prefix_chars= cho hàm tạo ArgumentParser:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> trình phân tích cú pháp.add_argument('+f')
>>> Parser.add_argument('++bar')
>>> Parser.parse_args('+f X ++bar Y'.split())
Không gian tên(bar='Y', f='X')

Đối số prefix_chars= mặc định là '-'. Việc cung cấp một bộ ký tự không bao gồm - sẽ khiến các tùy chọn -f/--foo không được phép.

từfile_prefix_chars

Đôi khi, khi xử lý một danh sách đối số đặc biệt dài, có thể sẽ hợp lý hơn nếu giữ danh sách đối số trong một tệp thay vì gõ nó ra dòng lệnh. Nếu đối số fromfile_prefix_chars= được cấp cho hàm tạo ArgumentParser thì các đối số bắt đầu bằng bất kỳ ký tự nào được chỉ định sẽ được coi là tệp và sẽ được thay thế bằng các đối số mà chúng chứa. Ví dụ:

>>> với open('args.txt', 'w',coding=sys.getfilesystemencoding()) là fp:
... fp.write('-f\nbar')
...
>>> trình phân tích cú pháp = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> Parser.add_argument('-f')
>>> Parser.parse_args(['-f', 'foo', '@args.txt'])
Không gian tên(f='bar')

Theo mặc định, các đối số được đọc từ một tệp phải là một đối số trên mỗi dòng (nhưng xem thêm convert_arg_line_to_args()) và được xử lý như thể chúng ở cùng một vị trí với đối số tham chiếu tệp gốc trên dòng lệnh. Vì vậy, trong ví dụ trên, biểu thức ['-f', 'foo', '@args.txt'] được coi là tương đương với biểu thức ['-f', 'foo', '-f', 'bar'].

Ghi chú

Các dòng trống được coi là chuỗi trống (''), được phép làm giá trị nhưng không được phép làm đối số. Các dòng trống được đọc dưới dạng đối số sẽ dẫn đến lỗi "đối số không được nhận dạng".

ArgumentParser sử dụng filesystem encoding and error handler để đọc tệp chứa đối số.

Đối số fromfile_prefix_chars= mặc định là None, nghĩa là các đối số sẽ không bao giờ được coi là tham chiếu tệp.

Thay đổi trong phiên bản 3.12: ArgumentParser đã thay đổi mã hóa và lỗi để đọc tệp đối số từ mặc định (ví dụ: locale.getpreferredencoding(False) và "strict") sang filesystem encoding and error handler. Tệp đối số phải được mã hóa trong UTF-8 thay vì ANSI Codepage trên Windows.

đối số_mặc định

Nói chung, các giá trị mặc định của đối số được chỉ định bằng cách chuyển giá trị mặc định cho add_argument() hoặc bằng cách gọi các phương thức set_defaults() với một tập hợp các cặp tên-giá trị cụ thể. Tuy nhiên, đôi khi, có thể hữu ích khi chỉ định một giá trị mặc định cho toàn bộ trình phân tích cú pháp cho các đối số. Điều này có thể được thực hiện bằng cách chuyển đối số từ khóa argument_default= cho ArgumentParser. Ví dụ: để ngăn chặn việc tạo thuộc tính trên toàn cầu đối với lệnh gọi parse_args(), chúng tôi cung cấp argument_default=SUPPRESS:

>>> trình phân tích cú pháp = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> Parser.add_argument('--foo')
>>> Parser.add_argument('bar', nargs='?')
>>> Parser.parse_args(['--foo', '1', 'BAR'])
Không gian tên(bar='BAR', foo='1')
>>> trình phân tích cú pháp.parse_args([])
Không gian tên()

allow_abbrev

Thông thường, khi bạn chuyển một danh sách đối số sang phương thức parse_args() của ArgumentParser, nó sẽ có recognizes abbreviations các tùy chọn dài.

Tính năng này có thể bị tắt bằng cách đặt allow_abbrev thành False:

>>> trình phân tích cú pháp = 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'])
cách sử dụng: PROG [-h] [--foobar] [--foonley]
PROG: lỗi: đối số không được nhận dạng: --foon

Added in version 3.5.

xung đột_xử lý

Đối tượng ArgumentParser không cho phép hai hành động có cùng chuỗi tùy chọn. Theo mặc định, các đối tượng ArgumentParser đưa ra một ngoại lệ nếu cố gắng tạo một đối số với chuỗi tùy chọn đã được sử dụng

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('-f', '--foo', help='old foo help')
>>> Parser.add_argument('--foo', help='trợ giúp foo mới')
Traceback (cuộc gọi gần đây nhất):
 ..
ArgumentError: đối số --foo: (các) chuỗi tùy chọn xung đột: --foo

Đôi khi (ví dụ: khi sử dụng parent), có thể hữu ích khi ghi đè mọi đối số cũ hơn bằng cùng một chuỗi tùy chọn. Để có được hành vi này, giá trị 'resolve' có thể được cung cấp cho đối số conflict_handler= của ArgumentParser:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG',conflict_handler='resolve')
>>> Parser.add_argument('-f', '--foo', help='old foo help')
>>> Parser.add_argument('--foo', help='trợ giúp foo mới')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [-h] [-f FOO] [--foo FOO]

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát
 -f FOO foo cũ giúp đỡ
 --foo FOO trợ giúp về foo mới

Lưu ý rằng đối tượng ArgumentParser chỉ xóa một hành động nếu tất cả các chuỗi tùy chọn của nó bị ghi đè. Vì vậy, trong ví dụ trên, hành động -f/--foo cũ được giữ lại dưới dạng hành động -f, vì chỉ có chuỗi tùy chọn --foo bị ghi đè.

thêm_trợ giúp

Theo mặc định, các đối tượng ArgumentParser thêm một tùy chọn chỉ hiển thị thông báo trợ giúp của trình phân tích cú pháp. Nếu -h hoặc --help được cung cấp ở dòng lệnh, trợ giúp ArgumentParser sẽ được in.

Đôi khi, việc tắt tính năng bổ sung tùy chọn trợ giúp này có thể hữu ích. Điều này có thể đạt được bằng cách chuyển False làm đối số add_help= cho ArgumentParser:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> Parser.add_argument('--foo', help='foo help')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [--foo FOO]

tùy chọn:
 --foo FOO foo trợ giúp

Tùy chọn trợ giúp thường là -h/--help. Ngoại lệ cho trường hợp này là nếu prefix_chars= được chỉ định và không bao gồm -, trong trường hợp đó -h và --help không phải là các tùy chọn hợp lệ. Trong trường hợp này, ký tự đầu tiên trong prefix_chars được sử dụng làm tiền tố cho các tùy chọn trợ giúp:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [+h]

tùy chọn:
  +h, ++help hiển thị thông báo trợ giúp này và thoát

exit_on_error

Thông thường, khi bạn chuyển danh sách đối số không hợp lệ sang phương thức parse_args() của ArgumentParser, nó sẽ in message thành sys.stderr và thoát với mã trạng thái là 2.

Nếu người dùng muốn phát hiện lỗi theo cách thủ công, tính năng này có thể được bật bằng cách đặt exit_on_error thành False:

>>> trình phân tích cú pháp = argparse.ArgumentParser(exit_on_error=False)
>>> Parser.add_argument('--integer', type=int)
_StoreAction(option_strings=['--integers'], dest='integers', nargs=None, const=None, default=None, type=<class 'int'>, Choices=None, help=None, metavar=None)
>>> thử:
... Parser.parse_args('--số nguyên a'.split())
... ngoại trừ argparse.ArgumentError:
... print('Bắt được một đối sốError')
...
Bắt một đối sốLỗi

Added in version 3.9.

đề xuất_on_error

Theo mặc định, khi người dùng chuyển một lựa chọn đối số hoặc tên trình phân tích con không hợp lệ, ArgumentParser sẽ thoát ra với thông tin lỗi và liệt kê các lựa chọn đối số được phép (nếu được chỉ định) hoặc tên trình phân tích con như một phần của thông báo lỗi.

Nếu người dùng muốn bật đề xuất cho các lựa chọn đối số bị nhập sai và tên trình phân tích cú pháp con, tính năng này có thể được bật bằng cách đặt suggest_on_error thành True. Lưu ý rằng điều này chỉ áp dụng cho các đối số khi các lựa chọn được chỉ định là chuỗi

>>> trình phân tích cú pháp = argparse.ArgumentParser(suggest_on_error=True)
>>> Parser.add_argument('--action', Choices=['debug', 'dryrun'])
>>> Parser.parse_args(['--action', 'debugg'])
cách sử dụng: test.py [-h] [--action {debug,dryrun}]
thử nghiệm.py: lỗi: đối số --action: lựa chọn không hợp lệ: 'gỡ lỗi', có thể ý bạn là 'gỡ lỗi'? (chọn từ gỡ lỗi, chạy khô)

Nếu bạn đang viết mã cần tương thích với các phiên bản Python cũ hơn và muốn tận dụng cơ hội sử dụng suggest_on_error khi có sẵn, bạn có thể đặt mã đó làm thuộc tính sau khi khởi tạo trình phân tích cú pháp thay vì sử dụng đối số từ khóa:

>>> trình phân tích cú pháp = argparse.ArgumentParser(description='Xử lý một số số nguyên.')
>>> trình phân tích cú pháp.suggest_on_error = Đúng

Added in version 3.14.

màu sắc

Theo mặc định, thông báo trợ giúp được in màu bằng ANSI escape sequences. Nếu bạn muốn có thông báo trợ giúp bằng văn bản thuần túy, bạn có thể tắt in your local environment này hoặc trong chính trình phân tích cú pháp đối số bằng cách đặt color thành False:

>>> trình phân tích cú pháp = argparse.ArgumentParser(description='Xử lý một số số nguyên.',
... màu=Sai)
>>> Parser.add_argument('--action', Choices=['sum', 'max'])
>>> Parser.add_argument('số nguyên', metavar='N', type=int, nargs='+',
... help='một số nguyên cho bộ tích lũy')
>>> Parser.parse_args(['--help'])

Lưu ý rằng khi color=True, đầu ra có màu phụ thuộc vào cả biến môi trường và khả năng của thiết bị đầu cuối. Tuy nhiên, nếu color=False, đầu ra màu luôn bị tắt, ngay cả khi các biến môi trường như FORCE_COLOR được đặt.

Ghi chú

Thông báo lỗi sẽ bao gồm mã màu khi chuyển hướng stderr sang một tệp. Để tránh điều này, hãy đặt biến môi trường NO_COLOR hoặc PYTHON_COLORS (ví dụ: NO_COLOR=1 python script.py 2> errors.txt).

Added in version 3.14.

Phương thức add_argument()

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

Xác định cách phân tích cú pháp một đối số dòng lệnh. Mỗi tham số có mô tả chi tiết hơn bên dưới, nhưng tóm lại là:

  • name or flags - Tên hoặc danh sách các chuỗi tùy chọn, ví dụ: 'foo' hoặc '-f', '--foo'.

  • action - Loại hành động cơ bản được thực hiện khi gặp đối số này ở dòng lệnh.

  • nargs - Số lượng đối số dòng lệnh sẽ được sử dụng.

  • const - Một giá trị không đổi được yêu cầu bởi một số lựa chọn action và nargs.

  • default - Giá trị được tạo ra nếu đối số không có trong dòng lệnh và nếu nó không có trong đối tượng không gian tên.

  • type - Loại mà đối số dòng lệnh sẽ được chuyển đổi.

  • lựa chọn - Một chuỗi các giá trị được phép cho đối số.

  • bắt buộc - Có thể bỏ qua tùy chọn dòng lệnh hay không (chỉ tùy chọn).

  • help - Mô tả ngắn gọn về chức năng của đối số.

  • metavar - Tên cho đối số trong thông báo sử dụng.

  • dest - Tên thuộc tính cần thêm vào đối tượng được trả về bởi parse_args().

  • deprecated - Việc sử dụng đối số có bị phản đối hay không.

Phương thức này trả về một đối tượng Action đại diện cho đối số.

Các phần sau đây mô tả cách sử dụng từng loại này.

tên hoặc cờ

Phương thức add_argument() phải biết liệu một đối số tùy chọn, như -f hoặc --foo hay một đối số vị trí, như danh sách tên tệp, có được mong đợi hay không. Do đó, các đối số đầu tiên được truyền cho add_argument() phải là một chuỗi cờ hoặc một tên đối số đơn giản.

Ví dụ: một đối số tùy chọn có thể được tạo như sau

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

trong khi một đối số vị trí có thể được tạo như

>>> Parser.add_argument('bar')

Khi parse_args() được gọi, các đối số tùy chọn sẽ được xác định bằng tiền tố - và các đối số còn lại sẽ được coi là vị trí

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('-f', '--foo')
>>> Parser.add_argument('bar')
>>> trình phân tích cú pháp.parse_args(['BAR'])
Không gian tên(bar='BAR', foo=None)
>>> Parser.parse_args(['BAR', '--foo', 'FOO'])
Không gian tên(bar='BAR', foo='FOO')
>>> Parser.parse_args(['--foo', 'FOO'])
cách sử dụng: thanh PROG [-h] [-f FOO]
PROG: lỗi: bắt buộc phải có các đối số sau: bar

Theo mặc định, argparse tự động xử lý việc đặt tên nội bộ và tên hiển thị của các đối số, đơn giản hóa quy trình mà không yêu cầu cấu hình bổ sung. Như vậy, bạn không cần chỉ định tham số dest và metavar. Đối với các đối số tùy chọn, tham số dest mặc định là tên đối số, với dấu gạch dưới _ thay thế dấu gạch ngang -. Tham số metavar mặc định là tên viết hoa. Ví dụ:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('--foo-bar')
>>> Parser.parse_args(['--foo-bar', 'FOO-BAR'])
Không gian tên(foo_bar='FOO-BAR')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: [-h] [--foo-bar FOO-BAR]

đối số tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát
 --foo-bar FOO-BAR

hành động

Đối tượng ArgumentParser liên kết các đối số dòng lệnh với hành động. Những hành động này có thể thực hiện bất cứ điều gì với các đối số dòng lệnh được liên kết với chúng, mặc dù hầu hết các hành động chỉ đơn giản là thêm một thuộc tính vào đối tượng được trả về bởi parse_args(). Đối số từ khóa action chỉ định cách xử lý các đối số dòng lệnh. Các hành động được cung cấp là:

  • 'store' - Điều này chỉ lưu trữ giá trị của đối số. Đây là hành động mặc định.

  • 'store_const' - Cái này lưu trữ giá trị được chỉ định bởi đối số từ khóa const; lưu ý rằng đối số từ khóa const mặc định là None. Hành động 'store_const' được sử dụng phổ biến nhất với các đối số tùy chọn chỉ định một số loại cờ. Ví dụ:

    >>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', action='store_const', const=42)
>>> Parser.parse_args(['--foo'])
Không gian tên(foo=42)

  • 'store_true' và 'store_false' - Đây là các trường hợp đặc biệt của 'store_const' lưu trữ các giá trị True và False với các giá trị mặc định là False và True:

    >>> trình phân tích cú pháp = 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())
Không gian tên(foo=True, bar=False, baz=True)

  • 'append' - Điều này sẽ thêm từng giá trị đối số vào danh sách. Nó rất hữu ích khi cho phép một tùy chọn được chỉ định nhiều lần. Nếu giá trị mặc định là danh sách không trống thì giá trị được phân tích cú pháp sẽ bắt đầu bằng các thành phần của danh sách mặc định và mọi giá trị từ dòng lệnh sẽ được thêm vào sau các giá trị mặc định đó. Ví dụ sử dụng:

    >>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', action='append', default=['0'])
>>> Parser.parse_args('--foo 1 --foo 2'.split())
Không gian tên(foo=['0', '1', '2'])

  • 'append_const' - Điều này sẽ thêm giá trị được chỉ định bởi đối số từ khóa const vào danh sách; lưu ý rằng đối số từ khóa const mặc định là None. Hành động 'append_const' thường hữu ích khi có nhiều đối số cần lưu trữ các hằng số vào cùng một danh sách. Ví dụ:

    >>> trình phân tích cú pháp = 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())
Không gian tên(types=[<class 'str'>, <class 'int'>])

  • 'extend' - Thao tác này sẽ nối từng mục từ đối số nhiều giá trị vào danh sách. Hành động 'extend' thường được sử dụng với giá trị đối số từ khóa nargs '+' hoặc '*'. Lưu ý rằng khi nargs là None (mặc định) hoặc '?', mỗi ký tự của chuỗi đối số sẽ được thêm vào danh sách. Ví dụ sử dụng:

    >>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument("--foo", action="extend", nargs="+", type=str)
>>> Parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
Không gian tên(foo=['f1', 'f2', 'f3', 'f4'])

    Added in version 3.8.

  • 'count' - Đếm số lần xảy ra đối số. Ví dụ: điều này rất hữu ích để tăng mức độ dài dòng:

    >>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--verbose', '-v', action='count', default=0)
>>> Parser.parse_args(['-vvv'])
Không gian tên(dài=3)

    Lưu ý, default sẽ là None trừ khi được đặt rõ ràng thành 0.

  • 'help' - Thao tác này sẽ in thông báo trợ giúp hoàn chỉnh cho tất cả các tùy chọn trong trình phân tích cú pháp hiện tại rồi thoát. Theo mặc định, một hành động trợ giúp sẽ tự động được thêm vào trình phân tích cú pháp. Xem ArgumentParser để biết chi tiết về cách tạo đầu ra.

  • 'version' - Điều này đòi hỏi một đối số từ khóa version= trong lệnh gọi add_argument(), đồng thời in thông tin phiên bản và thoát khi được gọi:

    >>> nhập argparse
>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('--version', action='version', version='%(prog)s 2.0')
>>> Parser.parse_args(['--version'])
PROG 2.0

Bạn cũng có thể chỉ định một hành động tùy ý bằng cách chuyển một lớp con Action (ví dụ: BooleanOptionalAction) hoặc đối tượng khác triển khai cùng một giao diện. Chỉ những hành động sử dụng đối số dòng lệnh (ví dụ: 'store', 'append', 'extend' hoặc hành động tùy chỉnh với nargs khác 0) mới có thể được sử dụng với các đối số vị trí.

Cách được đề xuất để tạo hành động tùy chỉnh là mở rộng Action, ghi đè phương thức __call__() và tùy chọn các phương thức __init__() và format_usage(). Bạn cũng có thể đăng ký các hành động tùy chỉnh bằng phương pháp register() và tham chiếu chúng theo tên đã đăng ký.

Ví dụ về hành động tùy chỉnh:

>>> lớp FooAction(argparse.Action):
... def __init__(self, option_strings, dest, nargs=None, **kwargs):
... nếu nargs không phải là Không có:
... tăng ValueError("nargs không được phép")
... super().__init__(option_strings, dest, **kwargs)
... def __call__(self, trình phân tích cú pháp, không gian tên, giá trị, option_string=None):
... print('%r %r %r' % (không gian tên, giá trị, option_string))
... setattr(không gian tên, self.dest, giá trị)
...
>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', action=FooAction)
>>> Parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Không gian tên(bar=None, foo=None) '1' Không có
Không gian tên(bar='1', foo=None) '2' '--foo'
>>> lập luận
Không gian tên(bar='1', foo='2')

Để biết thêm chi tiết, xem Action.

lảm nhảm

Các đối tượng ArgumentParser thường liên kết một đối số dòng lệnh với một hành động duy nhất được thực hiện. Đối số từ khóa nargs liên kết một số đối số dòng lệnh khác nhau với một hành động. Xem thêm Chỉ định các đối số mơ hồ. Các giá trị được hỗ trợ là:

  • N (một số nguyên). Các đối số N từ dòng lệnh sẽ được tập hợp lại thành một danh sách. Ví dụ:

    >>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', nargs=2)
>>> Parser.add_argument('bar', nargs=1)
>>> Parser.parse_args('c --foo a b'.split())
Không gian tên(bar=['c'], foo=['a', 'b'])

    Lưu ý rằng nargs=1 tạo ra danh sách một mục. Điều này khác với mặc định, trong đó vật phẩm được sản xuất bởi chính nó.

  • '?'. Một đối số sẽ được sử dụng từ dòng lệnh nếu có thể và được tạo dưới dạng một mục duy nhất. Nếu không có đối số dòng lệnh, giá trị từ default sẽ được tạo. Lưu ý rằng đối với các đối số tùy chọn, có một trường hợp bổ sung - chuỗi tùy chọn có mặt nhưng không có đối số dòng lệnh theo sau. Trong trường hợp này, giá trị từ const sẽ được tạo ra. Một số ví dụ minh họa điều này:

    >>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> Parser.add_argument('bar', nargs='?', default='d')
>>> Parser.parse_args(['XX', '--foo', 'YY'])
Không gian tên(bar='XX', foo='YY')
>>> Parser.parse_args(['XX', '--foo'])
Không gian tên(bar='XX', foo='c')
>>> trình phân tích cú pháp.parse_args([])
Không gian tên(bar='d', foo='d')

    Một trong những cách sử dụng phổ biến hơn của nargs='?' là cho phép các tệp đầu vào và đầu ra tùy chọn

    >>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('infile', nargs='?')
>>> Parser.add_argument('outfile', nargs='?')
>>> Parser.parse_args(['input.txt', 'output.txt'])
Không gian tên(infile='input.txt', outfile='output.txt')
>>> Parser.parse_args(['input.txt'])
Không gian tên(infile='input.txt', outfile=None)
>>> trình phân tích cú pháp.parse_args([])
Không gian tên(infile=Không, outfile=Không)

  • '*'. Tất cả các đối số dòng lệnh hiện tại được tập hợp thành một danh sách. Lưu ý rằng nói chung sẽ không có nhiều ý nghĩa khi có nhiều hơn một đối số vị trí với nargs='*', nhưng có thể có nhiều đối số tùy chọn với nargs='*'. Ví dụ:

    >>> trình phân tích cú pháp = 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())
Không gian tên(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

  • '+'. Giống như '*', tất cả các đối số dòng lệnh hiện có đều được tập hợp thành một danh sách. Ngoài ra, một thông báo lỗi sẽ được tạo nếu không có ít nhất một đối số dòng lệnh. Ví dụ:

    >>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('foo', nargs='+')
>>> Parser.parse_args(['a', 'b'])
Không gian tên(foo=['a', 'b'])
>>> trình phân tích cú pháp.parse_args([])
cách sử dụng: PROG [-h] foo [foo ...]
PROG: error: bắt buộc phải có các đối số sau: foo

Nếu đối số từ khóa nargs không được cung cấp, số lượng đối số được sử dụng sẽ được xác định bởi hành động. Nói chung, điều này có nghĩa là một đối số dòng lệnh sẽ được sử dụng và một mục duy nhất (không phải danh sách) sẽ được tạo ra. Các hành động không sử dụng đối số dòng lệnh (ví dụ: 'store_const') sẽ đặt nargs=0.

const

Đối số const của add_argument() được sử dụng để giữ các giá trị không đổi không được đọc từ dòng lệnh nhưng được yêu cầu cho các hành động ArgumentParser khác nhau. Hai cách sử dụng phổ biến nhất của nó là:

  • Khi add_argument() được gọi bằng action='store_const' hoặc action='append_const'. Những hành động này thêm giá trị const vào một trong các thuộc tính của đối tượng được trả về bởi parse_args(). Xem mô tả action để biết ví dụ. Nếu const không được cung cấp cho add_argument(), nó sẽ nhận giá trị mặc định là None.

  • Khi add_argument() được gọi với các chuỗi tùy chọn (như -f hoặc --foo) và nargs='?'. Điều này tạo ra một đối số tùy chọn có thể theo sau là 0 hoặc một đối số dòng lệnh. Khi phân tích cú pháp dòng lệnh, nếu gặp chuỗi tùy chọn mà không có đối số dòng lệnh nào theo sau nó, giá trị từ const sẽ được sử dụng. Xem mô tả nargs để biết ví dụ.

Thay đổi trong phiên bản 3.11: const=None theo mặc định, kể cả khi action='append_const' hoặc action='store_const'.

mặc định

Tất cả các đối số tùy chọn và một số đối số vị trí có thể được bỏ qua ở dòng lệnh. Đối số từ khóa default của add_argument(), có giá trị mặc định là None, chỉ định giá trị nào sẽ được sử dụng nếu không có đối số dòng lệnh. Đối với các đối số tùy chọn, giá trị default được sử dụng khi chuỗi tùy chọn không có ở dòng lệnh

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', default=42)
>>> Parser.parse_args(['--foo', '2'])
Không gian tên(foo='2')
>>> trình phân tích cú pháp.parse_args([])
Không gian tên(foo=42)

Nếu không gian tên mục tiêu đã có tập thuộc tính, hành động default sẽ không ghi đè lên nó:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', default=42)
>>> Parser.parse_args([], namespace=argparse.Namespace(foo=101))
Không gian tên(foo=101)

Nếu giá trị default là một chuỗi, trình phân tích cú pháp sẽ phân tích giá trị đó như thể nó là một đối số dòng lệnh. Cụ thể, trình phân tích cú pháp áp dụng bất kỳ đối số chuyển đổi type nào, nếu được cung cấp, trước khi đặt thuộc tính trên giá trị trả về Namespace. Ngược lại, trình phân tích cú pháp sẽ sử dụng giá trị như sau:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--length', default='10', type=int)
>>> Parser.add_argument('--width', default=10.5, type=int)
>>> trình phân tích cú pháp.parse_args()
Không gian tên(chiều dài=10, chiều rộng=10,5)

Đối với các đối số vị trí có nargs bằng ? hoặc *, giá trị default được sử dụng khi không có đối số dòng lệnh:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('foo', nargs='?', default=42)
>>> trình phân tích cú pháp.parse_args(['a'])
Không gian tên(foo='a')
>>> trình phân tích cú pháp.parse_args([])
Không gian tên(foo=42)

Đối với các đối số bắt buộc, giá trị default bị bỏ qua. Ví dụ: điều này áp dụng cho các đối số vị trí có giá trị nargs không phải là ? hoặc * hoặc các đối số tùy chọn được đánh dấu là required=True.

Việc cung cấp default=argparse.SUPPRESS sẽ không thêm thuộc tính nào nếu không có đối số dòng lệnh

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> trình phân tích cú pháp.parse_args([])
Không gian tên()
>>> Parser.parse_args(['--foo', '1'])
Không gian tên(foo='1')

loại

Theo mặc định, trình phân tích cú pháp đọc các đối số dòng lệnh dưới dạng các chuỗi đơn giản. Tuy nhiên, thay vào đó, chuỗi dòng lệnh thường được hiểu là một loại khác, chẳng hạn như float hoặc int. Từ khóa type cho add_argument() cho phép thực hiện mọi chuyển đổi loại và kiểm tra loại cần thiết.

Nếu từ khóa type được sử dụng với từ khóa default thì trình chuyển đổi loại chỉ được áp dụng nếu mặc định là một chuỗi.

Đối số cho type có thể là một lệnh gọi chấp nhận một chuỗi đơn hoặc tên của loại đã đăng ký (xem register()) Nếu hàm tăng ArgumentTypeError, TypeError hoặc ValueError, ngoại lệ sẽ bị bắt và thông báo lỗi được định dạng rõ ràng sẽ hiển thị. Các loại ngoại lệ khác không được xử lý.

Các loại và chức năng tích hợp phổ biến có thể được sử dụng làm bộ chuyển đổi loại:

nhập khẩu argparse
nhập đường dẫn

trình phân tích cú pháp = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('khoảng cách', type=float)
parser.add_argument('street', type=ascii)
Parser.add_argument('code_point', type=ord)
Parser.add_argument('datapath', type=pathlib.Path)

Các chức năng do người dùng xác định cũng có thể được sử dụng:

>>> gạch nối chắc chắn (chuỗi):
... return '-'.join([word[:4] cho từ trong string.casefold().split()])
...
>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> _ = Parser.add_argument('short_title', type=gạch nối)
>>> Parser.parse_args(['"Câu chuyện về hai thành phố"'])
Không gian tên(short_title='"the-tale-of-two-citi')

Chức năng bool() không được khuyến nghị làm công cụ chuyển đổi loại. Tất cả những gì nó làm là chuyển đổi các chuỗi trống thành False và các chuỗi không trống thành True. Đây thường không phải là điều mong muốn:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> _ = Parser.add_argument('--verbose', type=bool)
>>> Parser.parse_args(['--verbose', 'False'])
Không gian tên(verbose=True)

Xem BooleanOptionalAction hoặc action='store_true' để biết các lựa chọn thay thế phổ biến.

Nói chung, từ khóa type là một tiện ích chỉ nên sử dụng cho các chuyển đổi đơn giản chỉ có thể đưa ra một trong ba ngoại lệ được hỗ trợ. Bất cứ điều gì có tính năng xử lý lỗi hoặc quản lý tài nguyên thú vị hơn sẽ được thực hiện ở phần cuối sau khi các đối số được phân tích cú pháp.

Ví dụ: chuyển đổi JSON hoặc YAML có các trường hợp lỗi phức tạp yêu cầu báo cáo tốt hơn mức mà từ khóa type có thể đưa ra. Một JSONDecodeError sẽ không được định dạng tốt và một ngoại lệ FileNotFoundError sẽ không được xử lý.

Ngay cả FileType cũng có những hạn chế khi sử dụng với từ khóa type. Nếu một đối số sử dụng FileType và sau đó đối số tiếp theo không thành công thì sẽ có lỗi nhưng tệp không tự động đóng. Trong trường hợp này, tốt hơn là đợi cho đến khi trình phân tích cú pháp chạy xong rồi sử dụng câu lệnh with để quản lý các tệp.

Đối với những trình kiểm tra loại chỉ kiểm tra một tập hợp giá trị cố định, thay vào đó hãy xem xét sử dụng từ khóa Choices.

sự lựa chọn

Một số đối số dòng lệnh phải được chọn từ một tập hợp giá trị bị hạn chế. Chúng có thể được xử lý bằng cách chuyển một đối tượng chuỗi làm đối số từ khóa choices cho add_argument(). Khi dòng lệnh được phân tích cú pháp, các giá trị đối số sẽ được kiểm tra và thông báo lỗi sẽ được hiển thị nếu đối số không phải là một trong các giá trị được chấp nhận:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='game.py')
>>> Parser.add_argument('di chuyển', Choices=['đá', 'giấy', 'kéo'])
>>> Parser.parse_args(['rock'])
Không gian tên(move='rock')
>>> Parser.parse_args(['fire'])
cách sử dụng: game.py [-h] {đá,giấy,kéo}
game.py: error: đối số di chuyển: lựa chọn không hợp lệ: 'fire' (chọn từ 'rock',
'giấy', 'kéo')

Bất kỳ chuỗi nào cũng có thể được chuyển dưới dạng giá trị choices, vì vậy các đối tượng list, đối tượng tuple và chuỗi tùy chỉnh đều được hỗ trợ.

Việc sử dụng enum.Enum không được khuyến khích vì khó kiểm soát sự xuất hiện của nó trong các thông báo sử dụng, trợ giúp và lỗi.

Lưu ý rằng choices được kiểm tra sau khi thực hiện bất kỳ chuyển đổi type nào, vì vậy các đối tượng trong choices phải khớp với type được chỉ định. Điều này có thể làm cho choices có vẻ lạ trong cách sử dụng, trợ giúp hoặc thông báo lỗi.

Để giữ cho choices thân thiện với người dùng, hãy xem xét một trình bao bọc loại tùy chỉnh có thể chuyển đổi và định dạng các giá trị hoặc bỏ qua type và xử lý chuyển đổi trong mã ứng dụng của bạn.

Các lựa chọn được định dạng ghi đè metavar mặc định thường bắt nguồn từ dest. Đây thường là điều bạn muốn vì người dùng không bao giờ nhìn thấy tham số dest. Nếu màn hình này không được mong muốn (có lẽ vì có nhiều lựa chọn), chỉ cần chỉ định một metavar rõ ràng.

bắt buộc

Nói chung, mô-đun argparse giả định rằng các cờ như -f và --bar biểu thị các đối số optional, những đối số này luôn có thể được bỏ qua ở dòng lệnh. Để tạo tùy chọn required, True có thể được chỉ định cho đối số từ khóa required= cho add_argument():

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', require=True)
>>> Parser.parse_args(['--foo', 'BAR'])
Không gian tên(foo='BAR')
>>> trình phân tích cú pháp.parse_args([])
cách sử dụng: [-h] --foo FOO
: error: bắt buộc phải có các đối số sau: --foo

Như ví dụ cho thấy, nếu một tùy chọn được đánh dấu là required, parse_args() sẽ báo lỗi nếu tùy chọn đó không xuất hiện ở dòng lệnh.

Ghi chú

Các tùy chọn bắt buộc thường được coi là dạng xấu vì người dùng mong đợi options là optional và do đó nên tránh chúng khi có thể.

giúp đỡ

Giá trị help là một chuỗi chứa mô tả ngắn gọn về đối số. Khi người dùng yêu cầu trợ giúp (thường bằng cách sử dụng -h hoặc --help ở dòng lệnh), các mô tả help này sẽ được hiển thị với mỗi đối số.

Chuỗi help có thể bao gồm nhiều định dạng định dạng khác nhau để tránh lặp lại những thứ như tên chương trình hoặc đối số default. Các thông số xác định có sẵn bao gồm tên chương trình, %(prog)s và hầu hết các đối số từ khóa cho add_argument(), ví dụ: %(default)s, %(type)s, v.v.:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='frobble')
>>> Parser.add_argument('bar', nargs='?', type=int, default=42,
... help='thanh tới %(prog)s (mặc định: %(default)s)')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: làm mờ [-h] [bar]

lập luận vị trí:
 chặn thanh để hoạt động (mặc định: 42)

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát

Vì chuỗi trợ giúp hỗ trợ định dạng %, nếu bạn muốn % theo nghĩa đen xuất hiện trong chuỗi trợ giúp, bạn phải thoát nó dưới dạng %%.

argparse hỗ trợ tắt tiếng mục trợ giúp cho một số tùy chọn nhất định, bằng cách đặt giá trị help thành argparse.SUPPRESS:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='frobble')
>>> Parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> trình phân tích cú pháp.print_help()
cách sử dụng: bọt [-h]

tùy chọn:
  -h, --help hiển thị thông báo trợ giúp này và thoát

metavar

Khi ArgumentParser tạo thông báo trợ giúp, nó cần một số cách để tham chiếu đến từng đối số dự kiến. Theo mặc định, các đối tượng ArgumentParser sử dụng giá trị dest làm "tên" của từng đối tượng. Theo mặc định, đối với các hành động đối số vị trí, giá trị dest được sử dụng trực tiếp và đối với các hành động đối số tùy chọn, giá trị dest được viết hoa. Vì vậy, một đối số vị trí duy nhất với dest='bar' sẽ được gọi là bar. Một đối số tùy chọn duy nhất --foo phải được theo sau bởi một đối số dòng lệnh duy nhất sẽ được gọi là FOO. Một ví dụ:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo')
>>> Parser.add_argument('bar')
>>> Parser.parse_args('X --foo Y'.split())
Không gian tên(bar='X', foo='Y')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: thanh [-h] [--foo FOO]

lập luận vị trí:
 thanh

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát
 --foo FOO

Một tên thay thế có thể được chỉ định bằng metavar:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', metavar='YYY')
>>> Parser.add_argument('bar', metavar='XXX')
>>> Parser.parse_args('X --foo Y'.split())
Không gian tên(bar='X', foo='Y')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: [-h] [--foo YYY] XXX

lập luận vị trí:
 XXX

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát
 --foo YYY

Lưu ý rằng metavar chỉ thay đổi tên displayed - tên thuộc tính trên đối tượng parse_args() vẫn được xác định bởi giá trị dest.

Các giá trị khác nhau của nargs có thể khiến metavar được sử dụng nhiều lần. Việc cung cấp một bộ dữ liệu cho metavar sẽ chỉ định một cách hiển thị khác nhau cho từng đối số:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('-x', nargs=2)
>>> Parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [-h] [-x X X] [--foo bar baz]

tùy chọn:
 -h, --help hiển thị thông báo trợ giúp này và thoát
 -x X X
 --foo bar baz

số phận

Hầu hết các hành động ArgumentParser đều thêm một số giá trị làm thuộc tính của đối tượng được trả về bởi parse_args(). Tên của thuộc tính này được xác định bởi đối số từ khóa dest của add_argument(). Đối với các hành động đối số vị trí, dest thường được cung cấp làm đối số đầu tiên cho add_argument():

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('bar')
>>> trình phân tích cú pháp.parse_args(['XXX'])
Không gian tên(bar='XXX')

Đối với các hành động đối số tùy chọn, giá trị của dest thường được suy ra từ các chuỗi tùy chọn. ArgumentParser tạo giá trị của dest bằng cách lấy chuỗi tùy chọn dài đầu tiên và loại bỏ chuỗi -- ban đầu. Nếu không cung cấp chuỗi tùy chọn dài, dest sẽ được lấy từ chuỗi tùy chọn ngắn đầu tiên bằng cách loại bỏ ký tự - ban đầu. Mọi ký tự - bên trong sẽ được chuyển đổi thành ký tự _ để đảm bảo chuỗi là tên thuộc tính hợp lệ. Các ví dụ dưới đây minh họa hành vi này:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('-f', '--foo-bar', '--foo')
>>> Parser.add_argument('-x', '-y')
>>> Parser.parse_args('-f 1 -x 2'.split())
Không gian tên(foo_bar='1', x='2')
>>> Parser.parse_args('--foo 1 -y 2'.split())
Không gian tên(foo_bar='1', x='2')

dest cho phép cung cấp tên thuộc tính tùy chỉnh

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', dest='bar')
>>> Parser.parse_args('--foo XXX'.split())
Không gian tên(bar='XXX')

không được dùng nữa

Trong suốt vòng đời của dự án, một số đối số có thể cần phải được loại bỏ khỏi dòng lệnh. Trước khi xóa chúng, bạn nên thông báo cho người dùng của mình rằng các đối số không được dùng nữa và sẽ bị xóa. Đối số từ khóa deprecated của add_argument(), mặc định là False, chỉ định xem đối số có được dùng nữa hay không và sẽ bị xóa trong tương lai. Đối với các đối số, nếu deprecated là True thì cảnh báo sẽ được in thành sys.stderr khi đối số được sử dụng

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

Lớp hành động

Các lớp Action triển khai Action API, một lệnh gọi trả về một lệnh gọi có thể xử lý các đối số từ dòng lệnh. Bất kỳ đối tượng nào theo sau API này đều có thể được chuyển dưới dạng tham số action cho add_argument().

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

Các đối tượng Action được ArgumentParser sử dụng để thể hiện thông tin cần thiết để phân tích một đối số từ một hoặc nhiều chuỗi từ dòng lệnh. Lớp Action phải chấp nhận hai đối số vị trí cộng với bất kỳ đối số từ khóa nào được truyền cho ArgumentParser.add_argument() ngoại trừ chính action.

Các phiên bản của Action (hoặc giá trị trả về của bất kỳ tham số action nào có thể gọi được) phải có các thuộc tính dest, option_strings, default, type, required, help, v.v. được xác định. Cách dễ nhất để đảm bảo các thuộc tính này được xác định là gọi Action.__init__().

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

Các phiên bản Action có thể gọi được, vì vậy các lớp con phải ghi đè phương thức __call__(), phương thức này sẽ chấp nhận bốn tham số:

  • parser - Đối tượng ArgumentParser chứa hành động này.

  • namespace - Đối tượng Namespace sẽ được parse_args() trả về. Hầu hết các hành động đều thêm thuộc tính vào đối tượng này bằng setattr().

  • values - Các đối số dòng lệnh liên quan, áp dụng bất kỳ chuyển đổi loại nào. Chuyển đổi loại được chỉ định bằng đối số từ khóa type thành add_argument().

  • option_string - Chuỗi tùy chọn được sử dụng để gọi hành động này. Đối số option_string là tùy chọn và sẽ không có nếu hành động được liên kết với đối số vị trí.

Phương thức __call__() có thể thực hiện các hành động tùy ý nhưng thường sẽ đặt thuộc tính trên namespace dựa trên dest và values.

format_usage()

Các lớp con Action có thể định nghĩa một phương thức format_usage() không có đối số và trả về một chuỗi sẽ được sử dụng khi in cách sử dụng chương trình. Nếu phương pháp đó không được cung cấp thì một giá trị mặc định hợp lý sẽ được sử dụng.

class argparse.BooleanOptionalAction

Một lớp con của Action để xử lý các cờ boolean với các tùy chọn tích cực và tiêu cực. Việc thêm một đối số duy nhất như --foo sẽ tự động tạo cả hai tùy chọn --foo và --no-foo, lưu trữ True và False tương ứng:

>>> nhập argparse
>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> Parser.parse_args(['--no-foo'])
Không gian tên(foo=False)

Added in version 3.9.

Phương thức pars_args()

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

Chuyển đổi chuỗi đối số thành đối tượng và gán chúng làm thuộc tính của không gian tên. Trả về không gian tên đã được điền.

Các lệnh gọi trước tới add_argument() xác định chính xác đối tượng nào được tạo và cách chúng được chỉ định. Xem tài liệu về add_argument() để biết chi tiết.

  • args - Danh sách các chuỗi cần phân tích. Mặc định được lấy từ sys.argv.

  • namespace - Một đối tượng để lấy các thuộc tính. Mặc định là một đối tượng Namespace trống mới.

Cú pháp giá trị tùy chọn

Phương thức parse_args() hỗ trợ một số cách chỉ định giá trị của một tùy chọn (nếu cần). Trong trường hợp đơn giản nhất, tùy chọn và giá trị của nó được truyền dưới dạng hai đối số riêng biệt:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> trình phân tích cú pháp.add_argument('-x')
>>> Parser.add_argument('--foo')
>>> Parser.parse_args(['-x', 'X'])
Không gian tên(foo=Không có, x='X')
>>> Parser.parse_args(['--foo', 'FOO'])
Không gian tên(foo='FOO', x=None)

Đối với các tùy chọn dài (các tùy chọn có tên dài hơn một ký tự), tùy chọn và giá trị cũng có thể được chuyển dưới dạng một đối số dòng lệnh duy nhất, sử dụng = để phân tách chúng:

>>> Parser.parse_args(['--foo=FOO'])
Không gian tên(foo='FOO', x=None)

Đối với các tùy chọn ngắn (tùy chọn chỉ dài một ký tự), tùy chọn và giá trị của nó có thể được nối

>>> Parser.parse_args(['-xX'])
Không gian tên(foo=Không có, x='X')

Một số tùy chọn ngắn có thể được nối với nhau, chỉ sử dụng một tiền tố - duy nhất, miễn là chỉ có tùy chọn cuối cùng (hoặc không có tùy chọn nào trong số chúng) yêu cầu một giá trị:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('-x', action='store_true')
>>> Parser.add_argument('-y', action='store_true')
>>> trình phân tích cú pháp.add_argument('-z')
>>> Parser.parse_args(['-xyzZ'])
Không gian tên(x=True, y=True, z='Z')

Đối số không hợp lệ

Trong khi phân tích dòng lệnh, parse_args() kiểm tra nhiều loại lỗi, bao gồm các tùy chọn không rõ ràng, loại không hợp lệ, tùy chọn không hợp lệ, số lượng đối số vị trí sai, v.v. Khi gặp lỗi như vậy, nó sẽ thoát và in lỗi cùng với thông báo sử dụng:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('--foo', type=int)
>>> Parser.add_argument('bar', nargs='?')

>>> loại # invalid
>>> Parser.parse_args(['--foo', 'spam'])
cách sử dụng: PROG [-h] [--foo FOO] [bar]
PROG: lỗi: đối số --foo: giá trị int không hợp lệ: 'spam'

>>> tùy chọn # invalid
>>> Parser.parse_args(['--bar'])
cách sử dụng: PROG [-h] [--foo FOO] [bar]
PROG: lỗi: không có tùy chọn như vậy: --bar

>>> # wrong số lượng đối số
>>> Parser.parse_args(['spam', 'badger'])
cách sử dụng: PROG [-h] [--foo FOO] [bar]
PROG: lỗi: tìm thấy đối số bổ sung: lửng

Đối số chứa -

Phương pháp parse_args() cố gắng đưa ra lỗi bất cứ khi nào người dùng rõ ràng đã mắc lỗi, nhưng một số tình huống vốn đã mơ hồ. Ví dụ: đối số dòng lệnh -1 có thể là một nỗ lực để chỉ định một tùy chọn hoặc một nỗ lực để cung cấp một đối số vị trí. Phương pháp parse_args() được thận trọng ở đây: các đối số vị trí chỉ có thể bắt đầu bằng - nếu chúng trông giống như số âm và không có tùy chọn nào trong trình phân tích cú pháp trông giống như số âm:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> trình phân tích cú pháp.add_argument('-x')
>>> Parser.add_argument('foo', nargs='?')

>>> # no tùy chọn số âm, vì vậy -1 là đối số vị trí
>>> Parser.parse_args(['-x', '-1'])
Không gian tên(foo=Không có, x='-1')

>>> # no tùy chọn số âm, vì vậy -1 và -5 là đối số vị trí
>>> Parser.parse_args(['-x', '-1', '-5'])
Không gian tên(foo='-5', x='-1')

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('-1', dest='one')
>>> Parser.add_argument('foo', nargs='?')

>>> Có tùy chọn số # negative, vì vậy -1 là một tùy chọn
>>> Parser.parse_args(['-1', 'X'])
Không gian tên(foo=Không có, one='X')

>>> Có tùy chọn số # negative, vì vậy -2 là một tùy chọn
>>> trình phân tích cú pháp.parse_args(['-2'])
cách sử dụng: PROG [-h] [-1 ONE] [foo]
PROG: lỗi: không có tùy chọn như vậy: -2

>>> Có tùy chọn số # negative nên cả hai -1 đều là tùy chọn
>>> Parser.parse_args(['-1', '-1'])
cách sử dụng: PROG [-h] [-1 ONE] [foo]
PROG: lỗi: đối số -1: mong đợi một đối số

Nếu bạn có đối số vị trí phải bắt đầu bằng - và trông không giống số âm, bạn có thể chèn đối số giả '--' để cho parse_args() biết rằng mọi thứ sau đó đều là đối số vị trí:

>>> Parser.parse_args(['--', '-f'])
Không gian tên(foo='-f', one=None)

Xem thêm the argparse howto on ambiguous arguments để biết thêm chi tiết.

Viết tắt đối số (khớp tiền tố)

Phương thức parse_args() by default cho phép các tùy chọn dài được viết tắt thành tiền tố, nếu từ viết tắt rõ ràng (tiền tố khớp với một tùy chọn duy nhất):

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('-bacon')
>>> Parser.add_argument('-badger')
>>> Parser.parse_args('-bac MMM'.split())
Không gian tên(bacon='MMM', badger=None)
>>> Parser.parse_args('-bad WOOD'.split())
Không gian tên(bacon=Không có, badger='WOOD')
>>> Parser.parse_args('-ba BA'.split())
cách sử dụng: PROG [-h] [-thịt xông khói BACON] [-badger BADGER]
PROG: lỗi: tùy chọn không rõ ràng: -ba có thể khớp với -badger, -bacon

Lỗi được tạo ra đối với các đối số có thể tạo ra nhiều tùy chọn. Tính năng này có thể bị tắt bằng cách đặt allow_abbrev thành False.

Ngoài sys.argv

Đôi khi có thể hữu ích khi có các đối số phân tích cú pháp ArgumentParser khác với các đối số của sys.argv. Điều này có thể được thực hiện bằng cách chuyển danh sách các chuỗi tới parse_args(). Điều này hữu ích cho việc thử nghiệm tại dấu nhắc tương tác:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> trình phân tích cú pháp.add_argument(
... 'số nguyên', metavar='int', type=int, Choices=range(10),
... nargs='+', help='một số nguyên trong phạm vi 0..9')
>>> trình phân tích cú pháp.add_argument(
... '--sum', dest='tích lũy', action='store_const', const=sum,
... default=max, help='tổng các số nguyên (mặc định: tìm giá trị lớn nhất)')
>>> Parser.parse_args(['1', '2', '3', '4'])
Không gian tên(tích lũy=<hàm tích hợp max>, số nguyên=[1, 2, 3, 4])
>>> Parser.parse_args(['1', '2', '3', '4', '--sum'])
Không gian tên(tích lũy=<tổng hàm dựng sẵn>, số nguyên=[1, 2, 3, 4])

Đối tượng không gian tên

class argparse.Namespace

Lớp đơn giản được parse_args() sử dụng theo mặc định để tạo một đối tượng chứa các thuộc tính và trả về nó.

Lớp này rất đơn giản, chỉ là một lớp con object với biểu diễn chuỗi có thể đọc được. Nếu bạn muốn có chế độ xem thuộc tính giống như chính tả, bạn có thể sử dụng thành ngữ Python tiêu chuẩn, vars():

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}

Cũng có thể hữu ích khi gán các thuộc tính ArgumentParser cho một đối tượng đã tồn tại, thay vì một đối tượng Namespace mới. Điều này có thể đạt được bằng cách chỉ định đối số từ khóa namespace=:

>>> lớp C:
... vượt qua
...
>>> c = C()
>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo')
>>> Parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'

Tiện ích khác

Lệnh phụ

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

Nhiều chương trình chia chức năng của chúng thành một số lệnh con, ví dụ: chương trình svn có thể gọi các lệnh con như svn checkout, svn update và svn commit. Việc chia tách chức năng theo cách này có thể là một ý tưởng đặc biệt hay khi một chương trình thực hiện một số chức năng khác nhau yêu cầu các loại đối số dòng lệnh khác nhau. ArgumentParser hỗ trợ tạo các lệnh con như vậy bằng phương thức add_subparsers(). Phương thức add_subparsers() thường được gọi không có đối số và trả về một đối tượng hành động đặc biệt. Đối tượng này có một phương thức duy nhất, add_parser(), lấy tên lệnh và bất kỳ đối số nào của hàm tạo ArgumentParser, rồi trả về một đối tượng ArgumentParser có thể được sửa đổi như bình thường.

Mô tả các thông số:

  • title - tiêu đề cho nhóm phân tích cú pháp phụ trong đầu ra trợ giúp; theo mặc định là "các lệnh phụ" nếu mô tả được cung cấp, nếu không thì sử dụng tiêu đề cho các đối số vị trí

  • description - mô tả cho nhóm phân tích cú pháp phụ trong đầu ra trợ giúp, theo mặc định là None

  • prog - thông tin sử dụng sẽ được hiển thị với trợ giúp lệnh phụ, theo mặc định là tên của chương trình và mọi đối số vị trí trước đối số của trình phân tích cú pháp con

  • parser_class - lớp sẽ được sử dụng để tạo các phiên bản trình phân tích cú pháp phụ, theo mặc định là lớp của trình phân tích cú pháp hiện tại (ví dụ: ArgumentParser)

  • action - loại hành động cơ bản được thực hiện khi gặp đối số này ở dòng lệnh

  • dest - tên của thuộc tính mà tên lệnh phụ sẽ được lưu trữ; theo mặc định None và không có giá trị nào được lưu trữ

  • bắt buộc - Theo mặc định, có phải cung cấp lệnh phụ hay không, False (được thêm vào 3.7)

  • help - trợ giúp cho nhóm phân tích cú pháp phụ trong đầu ra trợ giúp, theo mặc định None

  • metavar - chuỗi trình bày các lệnh phụ có sẵn trong trợ giúp; theo mặc định nó là None và trình bày các lệnh con ở dạng {cmd1, cmd2, ..}

Một số ví dụ sử dụng:

>>> # create trình phân tích cú pháp cấp cao nhất
>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> Parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='subcommand help')
>>>
>>> # create trình phân tích cú pháp cho lệnh "a"
>>> Parser_a = subparsers.add_parser('a', help='a help')
>>> Parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # create trình phân tích cú pháp cho lệnh "b"
>>> Parser_b = subparsers.add_parser('b', help='b help')
>>> Parser_b.add_argument('--baz', Choices=('X', 'Y', 'Z'), help='baz help')
>>>
>>> # parse một số danh sách đối số
>>> Parser.parse_args(['a', '12'])
Không gian tên(bar=12, foo=False)
>>> Parser.parse_args(['--foo', 'b', '--baz', 'Z'])
Không gian tên(baz='Z', foo=True)

Lưu ý rằng đối tượng được trả về bởi parse_args() sẽ chỉ chứa các thuộc tính cho trình phân tích cú pháp chính và trình phân tích cú pháp con đã được chọn bởi dòng lệnh (chứ không phải bất kỳ trình phân tích cú pháp con nào khác). Vì vậy, trong ví dụ trên, khi lệnh a được chỉ định, chỉ có thuộc tính foo và bar và khi lệnh b được chỉ định, chỉ có thuộc tính foo và baz.

Tương tự, khi một thông báo trợ giúp được yêu cầu từ một trình phân tích cú pháp con, chỉ trợ giúp cho trình phân tích cú pháp cụ thể đó mới được in. Thông báo trợ giúp sẽ không bao gồm các thông báo của trình phân tích cú pháp chính hoặc trình phân tích cú pháp anh em. (Tuy nhiên, có thể cung cấp thông báo trợ giúp cho mỗi lệnh của trình phân tích con bằng cách cung cấp đối số help= cho add_parser() như trên.)

>>> Parser.parse_args(['--help'])
cách sử dụng: PROG [-h] [--foo] {a,b} ...

lập luận vị trí:
  Trợ giúp về lệnh con {a,b}
    một sự giúp đỡ
    giúp tôi với

tùy chọn:
  -h, --help hiển thị thông báo trợ giúp này và thoát
  --foo foo giúp đỡ

>>> Parser.parse_args(['a', '--help'])
cách sử dụng: PROG một thanh [-h]

lập luận vị trí:
  trợ giúp thanh bar

tùy chọn:
  -h, --help hiển thị thông báo trợ giúp này và thoát

>>> Parser.parse_args(['b', '--help'])
cách sử dụng: PROG b [-h] [--baz {X,Y,Z}]

tùy chọn:
  -h, --help hiển thị thông báo trợ giúp này và thoát
  --baz {X,Y,Z} trợ giúp

Phương thức add_subparsers() cũng hỗ trợ các đối số từ khóa title và description. Khi có một trong hai, các lệnh của trình phân tích cú pháp con sẽ xuất hiện trong nhóm riêng của chúng trong đầu ra trợ giúp. Ví dụ:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
... description='các lệnh con hợp lệ',
... trợ giúp='trợ giúp bổ sung')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> Parser.parse_args(['-h'])
cách sử dụng: [-h] {foo,bar} ...

tùy chọn:
  -h, --help hiển thị thông báo trợ giúp này và thoát

lệnh phụ:
  lệnh phụ hợp lệ

  {foo,bar} trợ giúp thêm

Hơn nữa, add_parser() hỗ trợ một đối số aliases bổ sung, cho phép nhiều chuỗi tham chiếu đến cùng một trình phân tích cú pháp con. Ví dụ này, giống như svn, bí danh co là viết tắt của checkout:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> phân tích cú pháp phụ = phân tích cú pháp.add_subparsers()
>>> kiểm tra = subparsers.add_parser('checkout', aliases=['co'])
>>> kiểm tra.add_argument('foo')
>>> Parser.parse_args(['co', 'bar'])
Không gian tên(foo='bar')

add_parser() cũng hỗ trợ một đối số deprecated bổ sung, cho phép loại bỏ trình phân tích cú pháp con.

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

Added in version 3.13.

Một cách đặc biệt hiệu quả để xử lý các lệnh con là kết hợp việc sử dụng phương thức add_subparsers() với các lệnh gọi đến set_defaults() để mỗi trình phân tích cú pháp con biết hàm Python nào cần thực thi. Ví dụ:

>>> chức năng # subcommand
>>> def foo(args):
... print(args.x * args.y)
...
>>> thanh def(args):
... print('((%s))' % args.z)
...
>>> # create trình phân tích cú pháp cấp cao nhất
>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(required=True)
>>>
>>> # create trình phân tích cú pháp cho lệnh "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)
>>>
>>> # create trình phân tích cú pháp cho lệnh "bar"
>>> Parser_bar = subparsers.add_parser('bar')
>>> Parser_bar.add_argument('z')
>>> Parser_bar.set_defaults(func=bar)
>>>
>>> # parse các đối số và gọi bất kỳ hàm nào đã được chọn
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # parse các đối số và gọi bất kỳ hàm nào đã được chọn
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))

Bằng cách này, bạn có thể để parse_args() thực hiện công việc gọi hàm thích hợp sau khi quá trình phân tích đối số hoàn tất. Việc liên kết các hàm với các hành động như thế này thường là cách dễ nhất để xử lý các hành động khác nhau cho từng phân tích cú pháp con của bạn. Tuy nhiên, nếu cần kiểm tra tên của trình phân tích con đã được gọi, đối số từ khóa dest cho lệnh gọi add_subparsers() sẽ hoạt động:

>>> trình phân tích cú pháp = 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'])
Không gian tên(subparser_name='2', y='frobble')

Thay đổi trong phiên bản 3.7: Tham số chỉ từ khóa required mới.

Thay đổi trong phiên bản 3.14: prog của trình phân tích cú pháp con không còn bị ảnh hưởng bởi thông báo sử dụng tùy chỉnh trong trình phân tích cú pháp chính.

Đối tượng FileType

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

Nhà máy FileType tạo các đối tượng có thể được chuyển tới đối số kiểu của ArgumentParser.add_argument(). Các đối số có loại đối tượng FileType sẽ mở các đối số dòng lệnh dưới dạng tệp có chế độ được yêu cầu, kích thước bộ đệm, mã hóa và xử lý lỗi (xem hàm open() để biết thêm chi tiết):

>>> trình phân tích cú pháp = 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'])
Không gian tên(out=<_io.TextIOWrapper name='file.txt' mode='w' Encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>)

Các đối tượng FileType hiểu đối số giả '-' và tự động chuyển đổi đối số này thành sys.stdin cho các đối tượng FileType có thể đọc được và sys.stdout cho các đối tượng FileType có thể ghi:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('infile', type=argparse.FileType('r'))
>>> trình phân tích cú pháp.parse_args(['-'])
Không gian tên(infile=<_io.TextIOWrapper name='<stdin>' Encoding='UTF-8'>)

Ghi chú

Nếu một đối số sử dụng FileType và sau đó đối số tiếp theo không thành công thì sẽ có lỗi nhưng tệp không tự động đóng. Điều này cũng có thể ghi đè các tập tin đầu ra. Trong trường hợp này, tốt hơn là đợi cho đến khi trình phân tích cú pháp chạy xong rồi sử dụng câu lệnh with để quản lý các tệp.

Thay đổi trong phiên bản 3.4: Đã thêm thông số encoding và errors.

Sắp loại bỏ từ phiên bản 3.14.

Nhóm đối số

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

Theo mặc định, ArgumentParser nhóm các đối số dòng lệnh thành "đối số vị trí" và "tùy chọn" khi hiển thị thông báo trợ giúp. Khi có một nhóm đối số mang tính khái niệm tốt hơn nhóm đối số mặc định này, các nhóm thích hợp có thể được tạo bằng phương thức add_argument_group()

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> nhóm = parser.add_argument_group('group')
>>> group.add_argument('--foo', help='foo help')
>>> group.add_argument('bar', help='bar help')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: thanh PROG [--foo FOO]

nhóm:
  trợ giúp thanh bar
  --foo FOO foo trợ giúp

Phương thức add_argument_group() trả về một đối tượng nhóm đối số có phương thức add_argument() giống như ArgumentParser thông thường. Khi một đối số được thêm vào nhóm, trình phân tích cú pháp sẽ xử lý nó giống như một đối số thông thường nhưng hiển thị đối số đó trong một nhóm riêng biệt cho các thông báo trợ giúp. Phương thức add_argument_group() chấp nhận các đối số title và description có thể được sử dụng để tùy chỉnh màn hình này:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group1 = parser.add_argument_group('group1', 'mô tả nhóm1')
>>> group1.add_argument('foo', help='foo help')
>>> group2 = parser.add_argument_group('group2', 'mô tả nhóm2')
>>> group2.add_argument('--bar', help='bar help')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [--bar BAR] foo

nhóm1:
  mô tả nhóm1

  foo foo giúp đỡ

nhóm2:
  mô tả nhóm2

  --bar BAR thanh trợ giúp

Các tham số tùy chọn, chỉ dành cho từ khóa, đối số_default và xung đột_handler cho phép kiểm soát chi tiết hơn hành vi của nhóm đối số. Các tham số này có cùng ý nghĩa như trong hàm tạo ArgumentParser, nhưng áp dụng cụ thể cho nhóm đối số thay vì toàn bộ trình phân tích cú pháp.

Lưu ý rằng mọi đối số không nằm trong nhóm do người dùng xác định sẽ quay trở lại phần "đối số vị trí" và "đối số tùy chọn" thông thường.

Trong mỗi nhóm đối số, các đối số được hiển thị trong đầu ra trợ giúp theo thứ tự chúng được thêm vào.

Không được dùng nữa kể từ phiên bản 3.11, đã bị xóa trong phiên bản 3.14: Việc gọi add_argument_group() trên một nhóm đối số hiện gây ra một ngoại lệ. Việc lồng ghép này không bao giờ được hỗ trợ, thường không hoạt động chính xác và vô tình bị lộ thông qua tính kế thừa.

Sắp loại bỏ từ phiên bản 3.14: Việc truyền prefix_chars tới add_argument_group() hiện không còn được dùng nữa.

Loại trừ lẫn nhau

ArgumentParser.add_mutually_exclusive_group(required=False)

Tạo một nhóm loại trừ lẫn nhau. argparse sẽ đảm bảo rằng chỉ một trong các đối số trong nhóm loại trừ lẫn nhau xuất hiện trên dòng lệnh

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> nhóm = trình phân tích cú pháp.add_mutually_exclusive_group()
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> Parser.parse_args(['--foo'])
Không gian tên(bar=True, foo=True)
>>> Parser.parse_args(['--bar'])
Không gian tên(bar=False, foo=False)
>>> Parser.parse_args(['--foo', '--bar'])
cách sử dụng: PROG [-h] [--foo | --thanh]
PROG: error: đối số --bar: không được phép với đối số --foo

Phương thức add_mutually_exclusive_group() cũng chấp nhận đối số required, để chỉ ra rằng cần có ít nhất một trong các đối số loại trừ lẫn nhau:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> nhóm = trình phân tích cú pháp.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> trình phân tích cú pháp.parse_args([])
cách sử dụng: PROG [-h] (--foo | --bar)
PROG: lỗi: bắt buộc phải có một trong các đối số --foo --bar

Lưu ý rằng các nhóm đối số hiện loại trừ lẫn nhau không hỗ trợ các đối số title và description của add_argument_group(). Tuy nhiên, một nhóm loại trừ lẫn nhau có thể được thêm vào nhóm đối số có tiêu đề và mô tả. Ví dụ:

>>> trình phân tích cú pháp = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_argument_group('Tiêu đề nhóm', 'Mô tả nhóm')
>>> độc quyền_group = nhóm.add_mutually_exclusive_group(required=True)
>>> độc quyền_group.add_argument('--foo', help='foo trợ giúp')
>>> Exclusive_group.add_argument('--bar', help='bar help')
>>> trình phân tích cú pháp.print_help()
cách sử dụng: PROG [-h] (--foo FOO | --bar BAR)

tùy chọn:
  -h, --help hiển thị thông báo trợ giúp này và thoát

Tiêu đề nhóm:
  Mô tả nhóm

  --foo FOO foo trợ giúp
  --bar BAR thanh trợ giúp

Không được dùng nữa kể từ phiên bản 3.11, đã bị xóa trong phiên bản 3.14: Việc gọi add_argument_group() hoặc add_mutually_exclusive_group() trên một nhóm loại trừ lẫn nhau giờ đây sẽ đưa ra một ngoại lệ. Việc lồng ghép này không bao giờ được hỗ trợ, thường không hoạt động chính xác và vô tình bị lộ thông qua tính kế thừa.

Mặc định của trình phân tích cú pháp

ArgumentParser.set_defaults(**kwargs)

Hầu hết các thuộc tính của đối tượng được trả về bởi parse_args() sẽ được xác định đầy đủ bằng cách kiểm tra các đối số dòng lệnh và hành động đối số. set_defaults() cho phép thêm một số thuộc tính bổ sung được xác định mà không cần kiểm tra dòng lệnh:

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('foo', type=int)
>>> Parser.set_defaults(bar=42, baz='badger')
>>> trình phân tích cú pháp.parse_args(['736'])
Không gian tên(bar=42, baz='badger', foo=736)

Lưu ý rằng giá trị mặc định có thể được đặt ở cả cấp trình phân tích cú pháp bằng set_defaults() và ở cấp đối số bằng add_argument(). Nếu cả hai đều được gọi cho cùng một đối số, bộ mặc định cuối cùng cho một đối số sẽ được sử dụng

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', default='bar')
>>> Parser.set_defaults(foo='spam')
>>> trình phân tích cú pháp.parse_args([])
Không gian tên(foo='spam')

Giá trị mặc định ở cấp độ trình phân tích cú pháp có thể đặc biệt hữu ích khi làm việc với nhiều trình phân tích cú pháp. Xem phương pháp add_subparsers() để biết ví dụ về loại này.

ArgumentParser.get_default(dest)

Nhận giá trị mặc định cho thuộc tính không gian tên, do add_argument() hoặc set_defaults():

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', default='badger')
>>> trình phân tích cú pháp.get_default('foo')
'lửng'

Trợ giúp in ấn

Trong hầu hết các ứng dụng thông thường, parse_args() sẽ đảm nhiệm việc định dạng và in mọi thông báo lỗi hoặc cách sử dụng. Tuy nhiên, có một số phương pháp định dạng có sẵn:

ArgumentParser.print_usage(file=None)

In mô tả ngắn gọn về cách gọi ArgumentParser trên dòng lệnh. Nếu file là None thì giả sử sys.stdout.

ArgumentParser.print_help(file=None)

In thông báo trợ giúp, bao gồm cách sử dụng chương trình và thông tin về các đối số đã đăng ký với ArgumentParser. Nếu file là None thì giả sử sys.stdout.

Ngoài ra còn có các biến thể của các phương thức này chỉ đơn giản trả về một chuỗi thay vì in nó:

ArgumentParser.format_usage()

Trả về một chuỗi chứa mô tả ngắn gọn về cách gọi ArgumentParser trên dòng lệnh.

ArgumentParser.format_help()

Trả về một chuỗi chứa thông báo trợ giúp, bao gồm cách sử dụng chương trình và thông tin về các đối số đã đăng ký với ArgumentParser.

Phân tích một phần

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

Đôi khi một tập lệnh chỉ cần xử lý một tập hợp đối số dòng lệnh cụ thể, để lại mọi đối số không được nhận dạng cho tập lệnh hoặc chương trình khác. Trong những trường hợp này, phương pháp parse_known_args() có thể hữu ích.

Phương pháp này hoạt động tương tự như parse_args(), nhưng nó không gây ra lỗi cho các đối số bổ sung, không được nhận dạng. Thay vào đó, nó phân tích các đối số đã biết và trả về một bộ gồm hai mục chứa vùng tên được điền và danh sách mọi đối số không được nhận dạng.

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo', action='store_true')
>>> Parser.add_argument('bar')
>>> Parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Không gian tên(bar='BAR', foo=True), ['--badger', 'spam'])

Cảnh báo

quy tắc Prefix matching áp dụng cho parse_known_args(). Trình phân tích cú pháp có thể sử dụng một tùy chọn ngay cả khi nó chỉ là tiền tố của một trong các tùy chọn đã biết, thay vì để nó trong danh sách đối số còn lại.

Tùy chỉnh phân tích tập tin

ArgumentParser.convert_arg_line_to_args(arg_line)

Các đối số được đọc từ một tệp (xem đối số từ khóa fromfile_prefix_chars cho hàm tạo ArgumentParser) được đọc một đối số trên mỗi dòng. convert_arg_line_to_args() có thể được ghi đè để đọc dễ dàng hơn.

Phương thức này lấy một đối số duy nhất arg_line là một chuỗi được đọc từ tệp đối số. Nó trả về một danh sách các đối số được phân tích cú pháp từ chuỗi này. Phương thức này được gọi một lần trên mỗi dòng được đọc từ tệp đối số, theo thứ tự.

Một cách ghi đè hữu ích của phương pháp này là một cách xử lý từng từ được phân tách bằng dấu cách làm đối số. Ví dụ sau đây minh họa cách thực hiện việc này:

lớp MyArgumentParser(argparse.ArgumentParser):
    def Convert_arg_line_to_args(self, arg_line):
        trả về arg_line.split()

Phương thức thoát

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

Phương thức này kết thúc chương trình, thoát với status được chỉ định và nếu được đưa ra, nó sẽ in message thành sys.stderr trước đó. Người dùng có thể ghi đè phương pháp này để xử lý các bước này theo cách khác:

lớp ErrorCatchingArgumentParser(argparse.ArgumentParser):
    def exit(self, status=0, message=None):
        nếu trạng thái:
            raise Exception(f'Thoát vì lỗi: {message}')
        thoát (trạng thái)
ArgumentParser.error(message)

Phương pháp này in một thông báo sử dụng, bao gồm message, tới sys.stderr và kết thúc chương trình với mã trạng thái là 2.

Phân tích hỗn hợp

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

Một số lệnh Unix cho phép người dùng trộn lẫn các đối số tùy chọn với các đối số vị trí. Các phương thức parse_intermixed_args() và parse_known_intermixed_args() hỗ trợ kiểu phân tích cú pháp này.

Các trình phân tích cú pháp này không hỗ trợ tất cả các tính năng của argparse và sẽ đưa ra các ngoại lệ nếu sử dụng các tính năng không được hỗ trợ. Đặc biệt, các phân tích cú pháp con và các nhóm loại trừ lẫn nhau bao gồm cả tùy chọn và vị trí không được hỗ trợ.

Ví dụ sau đây cho thấy sự khác biệt giữa parse_known_args() và parse_intermixed_args(): ví dụ trước trả về ['2', '3'] dưới dạng đối số chưa được phân tích cú pháp, trong khi ví dụ sau thu thập tất cả các vị trí vào rest.

>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.add_argument('--foo')
>>> trình phân tích cú pháp.add_argument('cmd')
>>> Parser.add_argument('rest', nargs='*', type=int)
>>> Parser.parse_known_args('doit 1 --foo bar 2 3'.split())
(Không gian tên(cmd='doit', foo='bar', Rest=[1]), ['2', '3'])
>>> Parser.parse_intermixed_args('doit 1 --foo bar 2 3'.split())
Không gian tên(cmd='doit', foo='bar', Rest=[1, 2, 3])

parse_known_intermixed_args() trả về một bộ gồm hai mục chứa không gian tên được điền và danh sách các chuỗi đối số còn lại. parse_intermixed_args() sẽ báo lỗi nếu còn lại bất kỳ chuỗi đối số nào chưa được phân tích cú pháp.

Added in version 3.7.

Đăng ký các loại hoặc hành động tùy chỉnh

ArgumentParser.register(registry_name, value, object)

Đôi khi, bạn nên sử dụng một chuỗi tùy chỉnh trong các thông báo lỗi để cung cấp kết quả thân thiện hơn với người dùng. Trong những trường hợp này, register() có thể được sử dụng để đăng ký các hành động hoặc loại tùy chỉnh bằng trình phân tích cú pháp và cho phép bạn tham chiếu loại theo tên đã đăng ký thay vì tên có thể gọi được của chúng.

Phương thức register() chấp nhận ba đối số - registry_name, chỉ định sổ đăng ký nội bộ nơi đối tượng sẽ được lưu trữ (ví dụ: action, type), value, là khóa mà đối tượng sẽ được đăng ký và đối tượng, có thể gọi được để đăng ký.

Ví dụ sau đây cho thấy cách đăng ký loại tùy chỉnh với trình phân tích cú pháp:

>>> nhập argparse
>>> trình phân tích cú pháp = argparse.ArgumentParser()
>>> Parser.register('type', 'số nguyên thập lục phân', lambda s: int(s, 16))
>>> Parser.add_argument('--foo', type='số nguyên thập lục phân')
_StoreAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default=None, type='số nguyên thập lục phân', Choices=None, bắt buộc=False, help=None, metavar=None, deprecated=False)
>>> Parser.parse_args(['--foo', '0xFA'])
Không gian tên(foo=250)
>>> Parser.parse_args(['--foo', '1.2'])
cách sử dụng: PROG [-h] [--foo FOO]
PROG: lỗi: đối số --foo: giá trị 'số nguyên thập lục phân' không hợp lệ: '1.2'

Ngoại lệ

exception argparse.ArgumentError

Lỗi khi tạo hoặc sử dụng đối số (tùy chọn hoặc vị trí).

Giá trị chuỗi của ngoại lệ này là thông báo, được tăng cường thêm thông tin về đối số gây ra ngoại lệ đó.

exception argparse.ArgumentTypeError

Xảy ra khi có sự cố xảy ra khi chuyển đổi chuỗi dòng lệnh thành một loại.

Hướng dẫn và Hướng dẫn