getopt --- Trình phân tích cú pháp kiểu C cho các tùy chọn dòng lệnh

Source code: Lib/getopt.py

Ghi chú

Mô-đun này được coi là tính năng hoàn chỉnh. Một giải pháp thay thế khai báo và mở rộng hơn cho API này được cung cấp trong mô-đun optparse. Các cải tiến chức năng khác để xử lý tham số dòng lệnh được cung cấp dưới dạng mô-đun của bên thứ ba trên PyPI hoặc dưới dạng các tính năng trong mô-đun argparse.

---

Mô-đun này giúp các tập lệnh phân tích các đối số dòng lệnh trong sys.argv. Nó hỗ trợ các quy ước tương tự như hàm Unix getopt() (bao gồm ý nghĩa đặc biệt của các đối số có dạng '-' và '--'). Các tùy chọn dài tương tự như các tùy chọn được phần mềm GNU hỗ trợ cũng có thể được sử dụng thông qua đối số thứ ba tùy chọn.

Người dùng không quen với chức năng Unix getopt() nên cân nhắc sử dụng mô-đun argparse để thay thế. Người dùng đã quen với chức năng Unix getopt() nhưng muốn có hành vi tương đương trong khi viết ít mã hơn và nhận được trợ giúp cũng như thông báo lỗi tốt hơn nên cân nhắc sử dụng mô-đun optparse. Xem Chọn thư viện phân tích đối số để biết thêm chi tiết.

Mô-đun này cung cấp hai chức năng và một ngoại lệ:

getopt.getopt(args, shortopts, longopts=[])

Phân tích các tùy chọn dòng lệnh và danh sách tham số. args là danh sách đối số được phân tích cú pháp mà không có tham chiếu chính đến chương trình đang chạy. Thông thường, điều này có nghĩa là sys.argv[1:]. shortopts là chuỗi các chữ cái tùy chọn mà tập lệnh muốn nhận dạng, với các tùy chọn yêu cầu đối số theo sau là dấu hai chấm (':') và các tùy chọn chấp nhận đối số tùy chọn theo sau là hai dấu hai chấm ('::'); tức là, cùng định dạng mà Unix getopt() sử dụng.

Ghi chú

Không giống như GNU getopt(), sau một đối số không phải tùy chọn, tất cả các đối số tiếp theo cũng được coi là không phải tùy chọn. Điều này tương tự như cách hoạt động của các hệ thống Unix không phải GNU.

longopts, nếu được chỉ định, phải là danh sách các chuỗi có tên của các tùy chọn dài cần được hỗ trợ. Không được đưa các ký tự '--' hàng đầu vào tên tùy chọn. Các tùy chọn dài yêu cầu đối số phải được theo sau bởi dấu bằng ('='). Các tùy chọn dài chấp nhận đối số tùy chọn phải được theo sau bởi dấu bằng và dấu chấm hỏi ('=?'). Để chỉ chấp nhận các tùy chọn dài, shortopts phải là một chuỗi trống. Các tùy chọn dài trên dòng lệnh có thể được nhận dạng miễn là chúng cung cấp tiền tố của tên tùy chọn khớp chính xác với một trong các tùy chọn được chấp nhận. Ví dụ: nếu longopts là ['foo', 'frob'], tùy chọn --fo sẽ khớp là --foo, nhưng --f sẽ không khớp duy nhất, vì vậy GetoptError sẽ được tăng lên.

Giá trị trả về bao gồm hai phần tử: phần tử đầu tiên là danh sách các cặp (option, value); thứ hai là danh sách các đối số chương trình còn lại sau khi danh sách tùy chọn bị loại bỏ (đây là phần cuối của args). Mỗi cặp tùy chọn và giá trị được trả về có tùy chọn là phần tử đầu tiên, có tiền tố là dấu gạch nối cho các tùy chọn ngắn (ví dụ: '-x') hoặc hai dấu gạch ngang cho các tùy chọn dài (ví dụ: '--long-option') và đối số tùy chọn là phần tử thứ hai hoặc một chuỗi trống nếu tùy chọn không có đối số. Các tùy chọn xuất hiện trong danh sách theo đúng thứ tự mà chúng được tìm thấy, do đó cho phép xuất hiện nhiều lần. Các tùy chọn dài và ngắn có thể được trộn lẫn.

Thay đổi trong phiên bản 3.14: Đối số tùy chọn được hỗ trợ.

getopt.gnu_getopt(args, shortopts, longopts=[])

Chức năng này hoạt động giống như getopt(), ngoại trừ chế độ quét kiểu GNU được sử dụng theo mặc định. Điều này có nghĩa là các đối số tùy chọn và không tùy chọn có thể được trộn lẫn. Hàm getopt() dừng xử lý các tùy chọn ngay khi gặp phải đối số không phải tùy chọn.

Nếu ký tự đầu tiên của chuỗi tùy chọn là '+' hoặc nếu biến môi trường POSIXLY_CORRECT được đặt thì quá trình xử lý tùy chọn sẽ dừng ngay khi gặp phải đối số không phải tùy chọn.

Nếu ký tự đầu tiên của chuỗi tùy chọn là '-', thì các đối số không phải tùy chọn theo sau là các tùy chọn sẽ được thêm vào danh sách các cặp tùy chọn và giá trị dưới dạng một cặp có None là phần tử đầu tiên và danh sách các đối số không phải tùy chọn là phần tử thứ hai. Phần tử thứ hai của kết quả gnu_getopt() là danh sách các đối số chương trình sau tùy chọn cuối cùng.

Thay đổi trong phiên bản 3.14: Hỗ trợ trả về các tùy chọn trộn lẫn và các đối số không phải tùy chọn theo thứ tự.

exception getopt.GetoptError

Điều này được nêu ra khi tìm thấy một tùy chọn không được nhận dạng trong danh sách đối số hoặc khi không có tùy chọn yêu cầu đối số nào được đưa ra. Đối số của ngoại lệ là một chuỗi chỉ ra nguyên nhân gây ra lỗi. Đối với các tùy chọn dài, một đối số được đưa ra cho một tùy chọn không yêu cầu tùy chọn này cũng sẽ khiến ngoại lệ này được đưa ra. Các thuộc tính msg và opt đưa ra thông báo lỗi và tùy chọn liên quan; nếu không có tùy chọn cụ thể nào liên quan đến ngoại lệ thì opt là một chuỗi trống.

exception getopt.error

Bí danh cho GetoptError; để tương thích ngược.

Một ví dụ chỉ sử dụng các tùy chọn kiểu Unix:

>>> nhập getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> lập luận
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> danh sách chọn, args = getopt.getopt(args, 'abc:d:')
>>> danh sách chọn
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> lập luận
['a1', 'a2']

Sử dụng tên tùy chọn dài cũng dễ dàng như nhau:

>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> lập luận
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> danh sách chọn, args = getopt.getopt(args, 'x', [
... 'điều kiện=', 'tệp đầu ra=', 'kiểm tra'])
>>> danh sách chọn
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
>>> lập luận
['a1', 'a2']

Các đối số tùy chọn phải được chỉ định rõ ràng:

>>> s = '-Con -C --color=off --color a1 a2'
>>> args = s.split()
>>> lập luận
['-Con', '-C', '--color=off', '--color', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'C::', ['color=?'])
>>> danh sách chọn
[('-C', 'bật'), ('-C', ''), ('--color', 'tắt'), ('--color', '')]
>>> lập luận
['a1', 'a2']

Thứ tự của các tùy chọn và đối số không phải tùy chọn có thể được giữ nguyên:

>>> s = 'a1 -x a2 a3 a4 --dài a5 a6'
>>> args = s.split()
>>> lập luận
['a1', '-x', 'a2', 'a3', 'a4', '--long', 'a5', 'a6']
>>> optlist, args = getopt.gnu_getopt(args, '-x:', ['long='])
>>> danh sách chọn
[(Không, ['a1']), ('-x', 'a2'), (Không, ['a3', 'a4']), ('--long', 'a5')]
>>> lập luận
['a6']

Trong một tập lệnh, cách sử dụng thông thường là như thế này:

nhập getopt, sys

chắc chắn chính():
    thử:
        opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
    ngoại trừ getopt.GetoptError là lỗi:
        thông tin trợ giúp # print và thoát:
        print(err) # will in một cái gì đó như "tùy chọn -a không được nhận dạng"
        cách sử dụng()
        sys.exit(2)
    đầu ra = Không có
    dài dòng = Sai
    cho o, a trong opts:
        nếu o == "-v":
            dài dòng = Đúng
        Elif o in ("-h", "--help"):
            cách sử dụng()
            sys.exit()
        elif o in ("-o", "--output"):
            đầu ra = một
        khác:
            khẳng định Sai, "tùy chọn chưa được xử lý"
    quá trình (args, đầu ra = đầu ra, dài dòng = dài dòng)

nếu __name__ == "__main__":
    chính()

Lưu ý rằng một giao diện dòng lệnh tương đương có thể được tạo ra với ít mã hơn và nhiều thông tin trợ giúp cũng như thông báo lỗi hơn bằng cách sử dụng mô-đun optparse:

nhập khẩu optparse

nếu __name__ == '__main__':
    trình phân tích cú pháp = optparse.OptionParser()
    parser.add_option('-o', '--output')
    parser.add_option('-v', dest='verbose', action='store_true')
    opts, args = parser.parse_args()
    quá trình (args, đầu ra=opts.output, chi tiết=opts.verbose)

Giao diện dòng lệnh gần tương đương cho trường hợp này cũng có thể được tạo bằng cách sử dụng mô-đun argparse:

nhập khẩu argparse

nếu __name__ == '__main__':
    trình phân tích cú pháp = argparse.ArgumentParser()
    parser.add_argument('-o', '--output')
    parser.add_argument('-v', dest='verbose', action='store_true')
    parser.add_argument('rest', nargs='*')
    args = trình phân tích cú pháp.parse_args()
    quá trình(args.rest, đầu ra=args.output, chi tiết=args.verbose)

Xem Chọn thư viện phân tích đối số để biết chi tiết về sự khác biệt của phiên bản argparse của mã này so với phiên bản optparse (và getopt).

Xem thêm

Mô-đun optparse

Phân tích tùy chọn dòng lệnh khai báo.

Mô-đun argparse

Tùy chọn dòng lệnh và thư viện phân tích đối số có nhiều ý kiến hơn.