configparser --- Trình phân tích cú pháp tệp cấu hình

Source code: Lib/configparser.py

---

Mô-đun này cung cấp lớp ConfigParser thực hiện ngôn ngữ cấu hình cơ bản cung cấp cấu trúc tương tự như những gì được tìm thấy trong các tệp INI của Microsoft Windows. Bạn có thể sử dụng điều này để viết các chương trình Python mà người dùng cuối có thể tùy chỉnh một cách dễ dàng.

Ghi chú

Thư viện này thực hiện not diễn giải hoặc ghi các tiền tố loại giá trị được sử dụng trong phiên bản mở rộng của cú pháp INI trong Windows Register.

Xem thêm

Mô-đun tomllib

TOML là định dạng được chỉ định rõ ràng cho các tệp cấu hình ứng dụng. Nó được thiết kế đặc biệt để trở thành phiên bản cải tiến của INI.

Mô-đun shlex

Hỗ trợ tạo các ngôn ngữ nhỏ giống Unix shell cũng có thể được sử dụng cho các tệp cấu hình ứng dụng.

Mô-đun json

Mô-đun json triển khai một tập hợp con cú pháp JavaScript đôi khi được sử dụng để định cấu hình nhưng không hỗ trợ nhận xét.

Bắt đầu nhanh

Hãy lấy một tệp cấu hình rất cơ bản trông như thế này:

[DEFAULT]
Máy chủAliveInterval = 45
Nén = có
Mức nén = 9
Chuyển tiếpX11 = có

[giả mạo.ví dụ]
Người dùng = hg

[topsecret.server.example]
Cổng = 50022
Chuyển tiếpX11 = không

Cấu trúc của file INI được mô tả in the following section. Về cơ bản, tệp bao gồm các phần, mỗi phần chứa các khóa có giá trị. Các lớp configparser có thể đọc và ghi các tệp như vậy. Hãy bắt đầu bằng cách tạo tệp cấu hình ở trên theo chương trình.

>>> nhập trình phân tích cấu hình
>>> config = configparser.ConfigParser()
>>> config['DEFAULT'] = {'ServerAliveInterval': '45',
... 'Nén': 'có',
... 'Mức nén': '9'}
>>> config['forge.example'] = {}
>>> config['forge.example']['User'] = 'hg'
>>> config['topsecret.server.example'] = {}
>>> topsecret = config['topsecret.server.example']
>>> topsecret['Port'] = '50022' # mutates trình phân tích cú pháp
>>> topsecret['ForwardX11'] = 'no' # same tại đây
>>> config['DEFAULT']['ForwardX11'] = 'có'
>>> với open('example.ini', 'w') dưới dạng tệp cấu hình:
... config.write(tệp cấu hình)
...

Như bạn có thể thấy, chúng ta có thể xử lý trình phân tích cú pháp cấu hình giống như một từ điển. Có sự khác biệt, outlined later, nhưng cách hoạt động rất gần với những gì bạn mong đợi từ một cuốn từ điển.

Bây giờ chúng ta đã tạo và lưu tệp cấu hình, hãy đọc lại và khám phá dữ liệu trong đó.

>>> config = configparser.ConfigParser()
>>> config.sections()
[]
>>> config.read('example.ini')
['example.ini']
>>> config.sections()
['forge.example', 'topsecret.server.example']
>>> 'forge.example' trong cấu hình
đúng
>>> 'python.org' trong cấu hình
sai
>>> config['forge.example']['User']
'hg'
>>> config['DEFAULT']['Nén']
'có'
>>> topsecret = config['topsecret.server.example']
>>> topsecret['ForwardX11']
'không'
>>> topsecret['Port']
'50022'
>>> cho khóa trong config['forge.example']:
... in(khóa)
người dùng
mức độ nén
serveraliveinterval
nén
chuyển tiếpx11
>>> config['forge.example']['ForwardX11']
'có'

Như chúng ta có thể thấy ở trên, API khá đơn giản. Điều kỳ diệu duy nhất liên quan đến phần DEFAULT cung cấp các giá trị mặc định cho tất cả các phần khác [1]. Cũng lưu ý rằng các khóa trong các phần không phân biệt chữ hoa chữ thường và được lưu bằng chữ thường [1].

Có thể đọc một số cấu hình vào một ConfigParser duy nhất, trong đó cấu hình được thêm gần đây nhất có mức độ ưu tiên cao nhất. Mọi khóa xung đột đều được lấy từ cấu hình mới hơn trong khi các khóa hiện có trước đó vẫn được giữ lại. Ví dụ bên dưới đọc trong tệp override.ini, tệp này sẽ ghi đè mọi khóa xung đột từ tệp example.ini.

[DEFAULT]
ServerAliveInterval = -1

>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
>>> với open('override.ini', 'w') dưới dạng configfile:
... config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'ghi đè.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1

Hành vi này tương đương với lệnh gọi ConfigParser.read() với một số tệp được truyền tới tham số filenames.

Kiểu dữ liệu được hỗ trợ

Trình phân tích cú pháp cấu hình không đoán kiểu dữ liệu của các giá trị trong tệp cấu hình, luôn lưu trữ chúng bên trong dưới dạng chuỗi. Điều này có nghĩa là nếu bạn cần các kiểu dữ liệu khác, bạn nên tự chuyển đổi:

>>> int(topsecret['Port'])
50022
>>> float(topsecret['CompressionLevel'])
9,0

Vì tác vụ này rất phổ biến nên trình phân tích cú pháp cấu hình cung cấp một loạt các phương thức getter tiện dụng để xử lý số nguyên, số float và boolean. Điều cuối cùng là thú vị nhất vì chỉ chuyển giá trị cho bool() sẽ không có tác dụng gì vì bool('False') vẫn là True. Đây là lý do tại sao trình phân tích cú pháp cấu hình cũng cung cấp getboolean(). Phương pháp này không phân biệt chữ hoa chữ thường và nhận dạng các giá trị Boolean từ 'yes'/'no', 'on'/'off', 'true'/'false' và '1'/'0' [1]. Ví dụ:

>>> topsecret.getboolean('ForwardX11')
sai
>>> config['forge.example'].getboolean('ForwardX11')
đúng
>>> config.getboolean('forge.example', 'Nén')
đúng

Ngoài getboolean(), trình phân tích cú pháp cấu hình cũng cung cấp các phương thức getint() và getfloat() tương đương. Bạn có thể đăng ký bộ chuyển đổi của riêng mình và tùy chỉnh những bộ chuyển đổi được cung cấp. [1]

Giá trị dự phòng

Giống như từ điển, bạn có thể sử dụng phương pháp get() của một phần để cung cấp các giá trị dự phòng:

>>> topsecret.get('Port')
'50022'
>>> topsecret.get('CompressionLevel')
'9'
>>> topsecret.get('Mật mã')
>>> topsecret.get('Mật mã', '3des-cbc')
'3des-cbc'

Xin lưu ý rằng các giá trị mặc định được ưu tiên hơn các giá trị dự phòng. Ví dụ: trong ví dụ của chúng tôi, khóa 'CompressionLevel' chỉ được chỉ định trong phần 'DEFAULT'. Nếu chúng tôi cố gắng lấy nó từ phần 'topsecret.server.example', chúng tôi sẽ luôn nhận được giá trị mặc định, ngay cả khi chúng tôi chỉ định một dự phòng:

>>> topsecret.get('CompressionLevel', '3')
'9'

Một điều nữa cần lưu ý là phương pháp get() cấp trình phân tích cú pháp cung cấp một giao diện tùy chỉnh, phức tạp hơn, được duy trì để tương thích ngược. Khi sử dụng phương pháp này, giá trị dự phòng có thể được cung cấp thông qua đối số chỉ từ khóa fallback:

>>> config.get('forge.example', 'monster',
... fallback='Không có thứ gì như quái vật')
'Không có thứ gì gọi là quái vật'

Đối số fallback tương tự có thể được sử dụng với các phương thức getint(), getfloat() và getboolean(), ví dụ:

>>> 'BatchMode' trong topsecret
sai
>>> topsecret.getboolean('BatchMode', fallback=True)
đúng
>>> config['DEFAULT']['BatchMode'] = 'no'
>>> topsecret.getboolean('BatchMode', fallback=True)
sai

Cấu trúc tệp INI được hỗ trợ

Tệp cấu hình bao gồm các phần, mỗi phần được dẫn đầu bởi tiêu đề [section], theo sau là các mục nhập khóa/giá trị được phân tách bằng một chuỗi cụ thể (= hoặc : theo mặc định [1]). Theo mặc định, tên các phần có phân biệt chữ hoa chữ thường nhưng khóa thì không [1]. Khoảng trắng đầu và cuối bị xóa khỏi khóa và giá trị. Các giá trị có thể bị bỏ qua nếu trình phân tích cú pháp được định cấu hình để cho phép nó [1], trong trường hợp đó, dấu phân cách khóa/giá trị cũng có thể bị bỏ qua. Các giá trị cũng có thể trải dài trên nhiều dòng, miễn là chúng được thụt vào sâu hơn dòng đầu tiên của giá trị. Tùy thuộc vào chế độ của trình phân tích cú pháp, các dòng trống có thể được coi là một phần của giá trị nhiều dòng hoặc bị bỏ qua.

Theo mặc định, tên phần hợp lệ có thể là bất kỳ chuỗi nào không chứa '\n'. Để thay đổi điều này, hãy xem ConfigParser.SECTCRE.

Tên phần đầu tiên có thể bị bỏ qua nếu trình phân tích cú pháp được định cấu hình để cho phép phần cấp cao nhất không được đặt tên với allow_unnamed_section=True. Trong trường hợp này, khóa/giá trị có thể được UNNAMED_SECTION truy xuất như trong config[UNNAMED_SECTION].

Các tệp cấu hình có thể bao gồm các nhận xét, có tiền tố là các ký tự cụ thể (# và ; theo mặc định [1]). Các nhận xét có thể tự xuất hiện trên một dòng trống, có thể được thụt lề. [1]

Ví dụ:

[Giá trị đơn giản]
khóa=giá trị
dấu cách trong phím=được phép
khoảng trắng trong giá trị = cũng được phép
khoảng trắng xung quanh dấu phân cách = rõ ràng
bạn cũng có thể sử dụng : để phân cách các khóa khỏi các giá trị

[Tất cả các giá trị là chuỗi]
các giá trị như thế này: 1000000
hoặc thế này: 3.14159265359
chúng có được coi là số không? : không
số nguyên, số float và booleans được giữ dưới dạng: chuỗi
có thể sử dụng API để nhận trực tiếp các giá trị được chuyển đổi: true

[Giá trị nhiều dòng]
điệp khúc: Tôi là người đốn gỗ và tôi ổn
    Tôi ngủ cả đêm và tôi làm việc cả ngày

[Không có giá trị]
key_without_value
giá trị chuỗi trống ở đây =

[Bạn có thể sử dụng bình luận]
# like cái này
; hoặc cái này

# By mặc định chỉ ở một dòng trống.
Bình luận # Inline có thể có hại vì chúng cản trở người dùng
# from sử dụng các ký tự phân cách làm một phần của giá trị.
# That đang được nói, điều này có thể được tùy chỉnh.

    [Các phần có thể được thụt lề]
        can_values_be_as_well = Đúng
        Does_that_mean_anything_special = Sai
        mục đích = định dạng để dễ đọc
        multiline_values = là
            xử lý tốt như
            miễn là chúng được thụt vào
            sâu hơn dòng đầu tiên
            có giá trị
        # Did Tôi đề cập đến việc chúng ta cũng có thể thụt lề nhận xét phải không?

Phần chưa đặt tên

Tên của phần đầu tiên (hoặc duy nhất) có thể bị bỏ qua và các giá trị được truy xuất bởi thuộc tính UNNAMED_SECTION.

>>> cấu hình = """
... tùy chọn = giá trị
...
... [ Phần 2 ]
... cái khác = val
... """
>>> chưa đặt tên = configparser.ConfigParser(allow_unnamed_section=True)
>>> unnamed.read_string(config)
>>> unnamed.get(configparser.UNNAMED_SECTION, 'tùy chọn')
'giá trị'

Nội suy các giá trị

Ngoài chức năng cốt lõi, ConfigParser còn hỗ trợ nội suy. Điều này có nghĩa là các giá trị có thể được xử lý trước trước khi trả về chúng từ các lệnh gọi get().

class configparser.BasicInterpolation

Việc triển khai mặc định được sử dụng bởi ConfigParser. Nó cho phép các giá trị chứa các chuỗi định dạng tham chiếu đến các giá trị khác trong cùng một phần hoặc các giá trị trong phần mặc định đặc biệt [1]. Các giá trị mặc định bổ sung có thể được cung cấp khi khởi tạo.

Ví dụ:

[Đường dẫn]
home_dir: /Người dùng
my_dir: %(home_dir)s/lumberjack
my_pictures: %(my_dir)s/Ảnh

[Thoát]
# use a %% để thoát dấu % (% là ký tự duy nhất cần thoát):
đạt được: 80%%

Trong ví dụ trên, ConfigParser với interpolation được đặt thành BasicInterpolation() sẽ phân giải %(home_dir)s thành giá trị của home_dir (/Users trong trường hợp này). %(my_dir)s có hiệu lực sẽ phân giải thành /Users/lumberjack. Tất cả các phép nội suy được thực hiện theo yêu cầu nên các khóa được sử dụng trong chuỗi tham chiếu không cần phải được chỉ định theo bất kỳ thứ tự cụ thể nào trong tệp cấu hình.

Với interpolation được đặt thành None, trình phân tích cú pháp sẽ chỉ trả về %(my_dir)s/Pictures là giá trị của my_pictures và %(home_dir)s/lumberjack là giá trị của my_dir.

class configparser.ExtendedInterpolation

Một trình xử lý thay thế cho phép nội suy thực hiện cú pháp nâng cao hơn, chẳng hạn như được sử dụng trong zc.buildout. Nội suy mở rộng đang sử dụng ${section:option} để biểu thị một giá trị từ phần nước ngoài. Nội suy có thể trải rộng trên nhiều cấp độ. Để thuận tiện, nếu phần section: bị bỏ qua, nội suy sẽ mặc định là phần hiện tại (và có thể là các giá trị mặc định từ phần đặc biệt).

Ví dụ: cấu hình được chỉ định ở trên với phép nội suy cơ bản, sẽ trông như thế này với phép nội suy mở rộng:

[Đường dẫn]
home_dir: /Người dùng
my_dir: ${home_dir}/lumberjack
my_pictures: ${my_dir}/Hình ảnh

[Thoát]
# use a $$ để thoát khỏi dấu $ ($ là ký tự duy nhất cần được thoát):
chi phí: $$80

Các giá trị từ các phần khác cũng có thể được tìm nạp:

[Chung]
home_dir: /Người dùng
thư viện_dir: /Thư viện
system_dir: /Hệ thống
macports_dir:/opt/local

[Khung]
Trăn: 3.2
đường dẫn: ${Common:system_dir}/Library/Frameworks/

[Arthur]
Biệt danh: Hai nhà kho
họ_tên: Jackson
my_dir: ${Common:home_dir}/twosheds
my_pictures: ${my_dir}/Hình ảnh
python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}

Truy cập giao thức ánh xạ

Added in version 3.2.

Truy cập giao thức ánh xạ là tên chung cho chức năng cho phép sử dụng các đối tượng tùy chỉnh như thể chúng là từ điển. Trong trường hợp configparser, việc triển khai giao diện ánh xạ đang sử dụng ký hiệu parser['section']['option'].

parser['section'] nói riêng trả về proxy cho dữ liệu của phần trong trình phân tích cú pháp. Điều này có nghĩa là các giá trị không được sao chép mà được lấy từ trình phân tích cú pháp gốc theo yêu cầu. Điều quan trọng hơn nữa là khi các giá trị được thay đổi trên proxy phần, chúng thực sự bị thay đổi trong trình phân tích cú pháp gốc.

Các đối tượng configparser hoạt động gần với từ điển thực tế nhất có thể. Giao diện ánh xạ đã hoàn tất và tuân thủ MutableMapping ABC. Tuy nhiên, có một số khác biệt cần được tính đến:

• Theo mặc định, tất cả các khóa trong các phần đều có thể truy cập được theo cách không phân biệt chữ hoa chữ thường [1]. Ví dụ. for option in parser["section"] chỉ mang lại tên khóa tùy chọn optionxform'ed. Điều này có nghĩa là các phím được viết thường theo mặc định. Đồng thời, đối với phần chứa khóa 'a', cả hai biểu thức đều trả về True:

  "a" trong trình phân tích cú pháp["section"]
  "A" trong trình phân tích cú pháp["section"]
  

• Tất cả các phần cũng bao gồm các giá trị DEFAULTSECT, điều đó có nghĩa là .clear() trên một phần không được để phần đó trống. Điều này là do không thể xóa các giá trị mặc định khỏi phần này (vì về mặt kỹ thuật chúng không có ở đó). Nếu chúng bị ghi đè trong phần này, việc xóa sẽ khiến giá trị mặc định hiển thị lại. Cố gắng xóa giá trị mặc định sẽ gây ra KeyError.

• DEFAULTSECT không thể xóa khỏi trình phân tích cú pháp:

  • cố gắng xóa nó làm tăng ValueError,

  • parser.clear() để nó nguyên vẹn,

  • parser.popitem() không bao giờ trả lại nó.

• parser.get(section, option, **kwargs) - đối số thứ hai là not một giá trị dự phòng. Tuy nhiên, xin lưu ý rằng các phương thức get() cấp phần tương thích với cả giao thức ánh xạ và trình phân tích cấu hình cổ điển API.

• parser.items() tương thích với giao thức ánh xạ (trả về danh sách các cặp section_name, section_proxy bao gồm cả DEFAULTSECT). Tuy nhiên, phương thức này cũng có thể được gọi bằng các đối số: parser.items(section, raw, vars). Lệnh gọi thứ hai trả về danh sách các cặp option, value cho một section được chỉ định, với tất cả các phép nội suy được mở rộng (trừ khi raw=True được cung cấp).

Giao thức ánh xạ được triển khai dựa trên API cũ hiện có để các lớp con ghi đè giao diện ban đầu vẫn phải có ánh xạ hoạt động như mong đợi.

Tùy chỉnh hành vi của trình phân tích cú pháp

Gần như có nhiều biến thể định dạng INI cũng như số lượng ứng dụng sử dụng nó. configparser đã nỗ lực rất nhiều để cung cấp sự hỗ trợ cho bộ kiểu INI hợp lý nhất hiện có. Chức năng mặc định chủ yếu được quyết định bởi bối cảnh lịch sử và rất có thể bạn sẽ muốn tùy chỉnh một số tính năng.

Cách phổ biến nhất để thay đổi cách hoạt động của trình phân tích cú pháp cấu hình cụ thể là sử dụng các tùy chọn __init__():

• defaults, giá trị mặc định: None

  Tùy chọn này chấp nhận từ điển gồm các cặp khóa-giá trị ban đầu sẽ được đặt trong phần DEFAULT. Điều này tạo nên một cách hay để hỗ trợ các tệp cấu hình ngắn gọn không chỉ định các giá trị giống với giá trị mặc định được ghi lại.

  Gợi ý: nếu bạn muốn chỉ định các giá trị mặc định cho một phần cụ thể, hãy sử dụng read_dict() trước khi đọc tệp thực.

• dict_type, giá trị mặc định: dict

  Tùy chọn này có tác động lớn đến cách hoạt động của giao thức ánh xạ và cách các tệp cấu hình được viết trông như thế nào. Với từ điển tiêu chuẩn, mọi phần được lưu trữ theo thứ tự chúng được thêm vào trình phân tích cú pháp. Tương tự với các tùy chọn trong các phần.

  Ví dụ, một loại từ điển thay thế có thể được sử dụng để sắp xếp các phần và tùy chọn khi ghi lại.

  Xin lưu ý: có nhiều cách để thêm một tập hợp các cặp khóa-giá trị trong một thao tác. Khi bạn sử dụng từ điển thông thường trong các thao tác đó, thứ tự các phím sẽ được sắp xếp theo thứ tự. Ví dụ:

  >>> trình phân tích cú pháp = configparser.ConfigParser()
  >>> Parser.read_dict({'section1': {'key1': 'value1',
  ... 'key2': 'value2',
  ... 'key3': 'value3'},
  ... 'section2': {'keyA': 'valueA',
  ... 'keyB': 'giá trịB',
  ... 'keyC': 'valueC'},
  ... 'phần3': {'foo': 'x',
  ... 'thanh': 'y',
  ... 'baz': 'z'}
  ... })
  >>> trình phân tích cú pháp.sections()
  ['phần1', 'phần2', 'phần3']
  >>> [tùy chọn cho tùy chọn trong trình phân tích cú pháp['section3']]
  ['foo', 'thanh', 'baz']
  

• allow_no_value, giá trị mặc định: False

  Một số tệp cấu hình được biết là bao gồm các cài đặt không có giá trị nhưng mặt khác lại tuân theo cú pháp được configparser hỗ trợ. Tham số allow_no_value cho hàm tạo có thể được sử dụng để chỉ ra rằng các giá trị đó phải được chấp nhận:

  >>> nhập trình phân tích cấu hình
  
  >>> sample_config = """
  ... [mysqld]
  ... người dùng = mysql
  ... pid-file = /var/run/mysqld/mysqld.pid
  ... bỏ qua khóa bên ngoài
  ... old_passwords = 1
  ... bỏ qua-bdb
  ... # we hôm nay không cần ACID
  ... bỏ qua-innodb
  ... """
  >>> config = configparser.ConfigParser(allow_no_value=True)
  >>> config.read_string(sample_config)
  
  >>> # Settings với các giá trị được xử lý như trước:
  >>> cấu hình["mysqld"]["người dùng"]
  'mysql'
  
  >>> # Settings không có giá trị cung cấp Không có:
  >>> cấu hình["mysqld"]["skip-bdb"]
  
  >>> # Settings không được chỉ định vẫn gây ra lỗi:
  >>> config["mysqld"]["không tồn tại"]
  Traceback (cuộc gọi gần đây nhất):
    ...
  KeyError: 'không tồn tại'
  

• delimiters, giá trị mặc định: ('=', ':')

  Dấu phân cách là chuỗi con phân cách các khóa khỏi các giá trị trong một phần. Sự xuất hiện đầu tiên của chuỗi con phân cách trên một dòng được coi là dấu phân cách. Điều này có nghĩa là các giá trị (không phải khóa) có thể chứa dấu phân cách.

  Xem thêm đối số space_around_delimiters cho ConfigParser.write().

• comment_prefixes, giá trị mặc định: ('#', ';')

• inline_comment_prefixes, giá trị mặc định: None

  Tiền tố nhận xét là các chuỗi cho biết bắt đầu nhận xét hợp lệ trong tệp cấu hình. comment_prefixes chỉ được sử dụng trên các dòng trống (thụt lề tùy chọn) trong khi inline_comment_prefixes có thể được sử dụng sau mỗi giá trị hợp lệ (ví dụ: tên phần, tùy chọn và cả dòng trống). Theo mặc định, nhận xét nội tuyến bị tắt và '#' và ';' được sử dụng làm tiền tố cho nhận xét cả dòng.

  Thay đổi trong phiên bản 3.2: Trong các phiên bản trước, hành vi của configparser khớp với comment_prefixes=('#',';') và inline_comment_prefixes=(';',).

  Xin lưu ý rằng trình phân tích cú pháp cấu hình không hỗ trợ thoát tiền tố nhận xét nên việc sử dụng inline_comment_prefixes có thể ngăn người dùng chỉ định giá trị tùy chọn bằng các ký tự được sử dụng làm tiền tố nhận xét. Khi nghi ngờ, hãy tránh cài đặt inline_comment_prefixes. Trong mọi trường hợp, cách duy nhất để lưu trữ các ký tự tiền tố nhận xét ở đầu dòng trong các giá trị nhiều dòng là nội suy tiền tố, ví dụ:

  >>> from configparser import ConfigParser, ExtendedInterpolation
  >>> parser = ConfigParser(interpolation=ExtendedInterpolation())
  >>> # the default BasicInterpolation could be used as well
  >>> parser.read_string("""
  ... [DEFAULT]
  ... hash = #
  ...
  ... [hashes]
  ... shebang =
  ...   ${hash}!/usr/bin/env python
  ...   ${hash} -*- coding: utf-8 -*-
  ...
  ... extensions =
  ...   enabled_extension
  ...   another_extension
  ...   #disabled_by_comment
  ...   yet_another_extension
  ...
  ... interpolation not necessary = if # is not at line start
  ... even in multiline values = line #1
  ...   line #2
  ...   line #3
  ... """)
  >>> print(parser['hashes']['shebang'])
  
  #!/usr/bin/env python
  # -*- coding: utf-8 -*-
  >>> print(parser['hashes']['extensions'])
  
  enabled_extension
  another_extension
  yet_another_extension
  >>> print(parser['hashes']['interpolation not necessary'])
  if # is not at line start
  >>> print(parser['hashes']['even in multiline values'])
  line #1
  line #2
  line #3
  

• strict, giá trị mặc định: True

  Khi được đặt thành True, trình phân tích cú pháp sẽ không cho phép bất kỳ phần hoặc tùy chọn nào trùng lặp trong khi đọc từ một nguồn duy nhất (sử dụng read_file(), read_string() hoặc read_dict()). Nên sử dụng các trình phân tích cú pháp nghiêm ngặt trong các ứng dụng mới.

  Thay đổi trong phiên bản 3.2: Trong các phiên bản trước, hành vi của configparser khớp với strict=False.

• empty_lines_in_values, giá trị mặc định: True

  Trong trình phân tích cú pháp cấu hình, các giá trị có thể trải dài trên nhiều dòng miễn là chúng được thụt lề nhiều hơn khóa chứa chúng. Theo mặc định, trình phân tích cú pháp cũng cho phép các dòng trống trở thành một phần của giá trị. Đồng thời, các phím có thể được thụt vào tùy ý để cải thiện khả năng đọc. Hậu quả là khi các tệp cấu hình trở nên lớn và phức tạp, người dùng rất dễ mất dấu cấu trúc tệp. Lấy ví dụ:

  [Phần]
  phím = đa dòng
    giá trị với một gotcha
  
   this = vẫn là một phần của giá trị nhiều dòng của 'key'
  

  Điều này có thể đặc biệt khó khăn đối với người dùng trong việc xem liệu cô ấy có đang sử dụng phông chữ tỷ lệ để chỉnh sửa tệp hay không. Đó là lý do tại sao khi ứng dụng của bạn không cần các giá trị có dòng trống, bạn nên cân nhắc việc không cho phép chúng. Điều này sẽ làm cho các dòng trống bị phân chia mỗi lần. Trong ví dụ trên, nó sẽ tạo ra hai khóa, key và this.

• default_section, giá trị mặc định: configparser.DEFAULTSECT (tức là: "DEFAULT")

  Quy ước cho phép một phần đặc biệt có giá trị mặc định cho các phần khác hoặc mục đích nội suy là một khái niệm mạnh mẽ của thư viện này, cho phép người dùng tạo các cấu hình khai báo phức tạp. Phần này thường được gọi là "DEFAULT" nhưng có thể tùy chỉnh để trỏ đến bất kỳ tên phần hợp lệ nào khác. Một số giá trị điển hình bao gồm: "general" hoặc "common". Tên được cung cấp được sử dụng để nhận dạng các phần mặc định khi đọc từ bất kỳ nguồn nào và được sử dụng khi ghi lại cấu hình vào tệp. Giá trị hiện tại của nó có thể được truy xuất bằng thuộc tính parser_instance.default_section và có thể được sửa đổi trong thời gian chạy (tức là để chuyển đổi tệp từ định dạng này sang định dạng khác).

• interpolation, giá trị mặc định: configparser.BasicInterpolation

  Hành vi nội suy có thể được tùy chỉnh bằng cách cung cấp trình xử lý tùy chỉnh thông qua đối số interpolation. None có thể được sử dụng để tắt hoàn toàn nội suy, ExtendedInterpolation() cung cấp một biến thể cao cấp hơn lấy cảm hứng từ zc.buildout. Thông tin thêm về chủ đề này trong dedicated documentation section. RawConfigParser có giá trị mặc định là None.

• converters, giá trị mặc định: chưa được đặt

  Trình phân tích cú pháp cấu hình cung cấp các trình lấy giá trị tùy chọn để thực hiện chuyển đổi loại. Theo mặc định, getint(), getfloat() và getboolean() được triển khai. Nếu muốn sử dụng các getters khác, người dùng có thể định nghĩa chúng trong một lớp con hoặc chuyển một từ điển trong đó mỗi khóa là tên của trình chuyển đổi và mỗi giá trị là một giá trị có thể gọi được khi triển khai chuyển đổi nói trên. Ví dụ: chuyển {'decimal': decimal.Decimal} sẽ thêm getdecimal() trên cả đối tượng trình phân tích cú pháp và tất cả các proxy của phần. Nói cách khác, có thể viết cả parser_instance.getdecimal('section', 'key', fallback=0) và parser_instance['section'].getdecimal('key', 0).

  Nếu trình chuyển đổi cần truy cập vào trạng thái của trình phân tích cú pháp, thì nó có thể được triển khai như một phương thức trên lớp con của trình phân tích cú pháp cấu hình. Nếu tên của phương thức này bắt đầu bằng get, nó sẽ có sẵn trên tất cả các proxy của phần, ở dạng tương thích với dict (xem ví dụ getdecimal() ở trên).

Có thể đạt được tùy chỉnh nâng cao hơn bằng cách ghi đè các giá trị mặc định của các thuộc tính trình phân tích cú pháp này. Các giá trị mặc định được xác định trên các lớp, do đó chúng có thể bị ghi đè bởi các lớp con hoặc bằng cách gán thuộc tính.

ConfigParser.BOOLEAN_STATES

Theo mặc định khi sử dụng getboolean(), trình phân tích cú pháp cấu hình sẽ xem xét các giá trị sau True: '1', 'yes', 'true', 'on' và các giá trị sau False: '0', 'no', 'false', 'off'. Bạn có thể ghi đè điều này bằng cách chỉ định từ điển tùy chỉnh của chuỗi và kết quả Boolean của chúng. Ví dụ:

>>> tùy chỉnh = configparser.ConfigParser()
>>> custom['section1'] = {'funky': 'nope'}
>>> custom['section1'].getboolean('funky')
Traceback (cuộc gọi gần đây nhất):
...
ValueError: Không phải là boolean: không
>>> custom.BOOLEAN_STATES = {'chắc chắn': Đúng, 'không': Sai}
>>> custom['section1'].getboolean('funky')
sai

Các cặp Boolean điển hình khác bao gồm accept/reject hoặc enabled/disabled.

ConfigParser.optionxform(option)

Phương thức này biến đổi tên tùy chọn trong mỗi thao tác đọc, nhận hoặc đặt. Mặc định chuyển đổi tên thành chữ thường. Điều này cũng có nghĩa là khi tệp cấu hình được ghi, tất cả các khóa sẽ ở dạng chữ thường. Ghi đè phương pháp này nếu nó không phù hợp. Ví dụ:

>>> cấu hình = """
... [Phần 1]
... Khóa = Giá trị
...
... [Phần 2]
... AnotherKey = Giá trị
... """
>>> điển hình = configparser.ConfigParser()
>>> điển hình.read_string(config)
>>> list(điển hình['Section1'].keys())
['chìa khóa']
>>> list(điển hình['Section2'].keys())
['khóa khác']
>>> tùy chỉnh = configparser.RawConfigParser()
>>> custom.optionxform = tùy chọn lambda: tùy chọn
>>> custom.read_string(config)
>>> list(custom['Section1'].keys())
['Chìa khóa']
>>> list(custom['Section2'].keys())
['Khóa khác']

Ghi chú

Hàm optionxform chuyển đổi tên tùy chọn thành dạng chuẩn. Đây phải là một hàm bình thường: nếu tên đã ở dạng chuẩn, nó sẽ được trả về không thay đổi.

ConfigParser.SECTCRE

Một biểu thức chính quy được biên dịch dùng để phân tích các tiêu đề của phần. Mặc định khớp [section] với tên "section". Khoảng trắng được coi là một phần của tên phần, do đó [  larch  ] sẽ được đọc như một phần của tên "  larch  ". Ghi đè thuộc tính này nếu thuộc tính đó không phù hợp. Ví dụ:

>>> nhập lại
>>> cấu hình = """
... [Phần 1]
... tùy chọn = giá trị
...
... [ Phần 2 ]
... cái khác = val
... """
>>> điển hình = configparser.ConfigParser()
>>> điển hình.read_string(config)
>>> điển hình.sections()
['Phần 1', 'Phần 2']
>>> tùy chỉnh = configparser.ConfigParser()
>>> custom.SECTCRE = re.compile(r"\[ *(?P<header>[^]]+?) *\]")
>>> custom.read_string(config)
>>> custom.sections()
['Phần 1', 'Phần 2']

Ghi chú

Mặc dù các đối tượng ConfigParser cũng sử dụng thuộc tính OPTCRE để nhận dạng các dòng tùy chọn, nhưng bạn không nên ghi đè nó vì điều đó sẽ ảnh hưởng đến các tùy chọn hàm tạo allow_no_value và delimiters.

Ví dụ về API kế thừa

Chủ yếu là do những lo ngại về khả năng tương thích ngược, configparser cũng cung cấp một API kế thừa với các phương thức get/set rõ ràng. Mặc dù có các trường hợp sử dụng hợp lệ cho các phương pháp được nêu bên dưới, nhưng quyền truy cập giao thức ánh xạ được ưu tiên cho các dự án mới. Zz004zz truyền thống đôi khi tiên tiến hơn, ở cấp độ thấp và hoàn toàn phản trực giác.

Một ví dụ về ghi vào tệp cấu hình:

nhập trình phân tích cấu hình

config = configparser.RawConfigParser()

# Please lưu ý rằng bằng cách sử dụng các hàm đã đặt của RawConfigParser, bạn có thể gán
# non-string cho các khóa bên trong nhưng sẽ gặp lỗi khi
# attempting để ghi vào một tập tin hoặc khi bạn lấy nó ở chế độ không phải là thô. Cài đặt
# values sử dụng giao thức ánh xạ hoặc set() của ConfigParser không cho phép
nhiệm vụ # such sẽ diễn ra.
config.add_section('Section1')
config.set('Section1', 'an_int', '15')
config.set('Section1', 'a_bool', 'true')
config.set('Section1', 'a_float', '3.1415')
config.set('Section1', 'baz', 'fun')
config.set('Section1', 'bar', 'Python')
config.set('Section1', 'foo', '%(bar)s là %(baz)s!')

# Writing tệp cấu hình của chúng tôi thành 'example.cfg'
với open('example.cfg', 'w') dưới dạng tệp cấu hình:
    config.write(tệp cấu hình)

Một ví dụ về đọc lại tệp cấu hình:

nhập trình phân tích cấu hình

config = configparser.RawConfigParser()
config.read('example.cfg')

# getfloat() đưa ra một ngoại lệ nếu giá trị không phải là số float
# getint() và getboolean() cũng thực hiện điều này cho các loại tương ứng của chúng
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
in(a_float + an_int)

# Notice rằng đầu ra tiếp theo không nội suy '%(bar)s' hoặc '%(baz)s'.
# This là do chúng tôi đang sử dụng RawConfigParser().
nếu config.getboolean('Section1', 'a_bool'):
    print(config.get('Section1', 'foo'))

Để có được nội suy, hãy sử dụng ConfigParser:

nhập trình phân tích cấu hình

cfg = configparser.ConfigParser()
cfg.read('example.cfg')

# Set đối số *raw* tùy chọn của get() thành True nếu bạn muốn tắt
# interpolation chỉ trong một thao tác lấy.
print(cfg.get('Section1', 'foo', raw=False)) # -> "Python thật thú vị!"
print(cfg.get('Section1', 'foo', raw=True)) # -> "%(bar)s là %(baz)s!"

# The đối số *vars* tùy chọn là một mệnh lệnh với các thành viên sẽ thực hiện
# precedence trong nội suy.
print(cfg.get('Section1', 'foo', vars={'bar': 'Tài liệu',
                                       'baz': 'ác quỷ'}))

# The đối số *fallback* tùy chọn có thể được sử dụng để cung cấp giá trị dự phòng
print(cfg.get('Section1', 'foo'))
      # -> "Python thật thú vị!"

print(cfg.get('Section1', 'foo', fallback='Monty thì không.'))
      # -> "Python thật thú vị!"

print(cfg.get('Section1', 'monster', fallback='Không có thứ gì như quái vật.'))
      # -> "Không có thứ gì gọi là quái vật."

# A bare print(cfg.get('Section1', 'monster')) sẽ tăng NoOptionError
# but chúng ta cũng có thể sử dụng:

print(cfg.get('Section1', 'monster', fallback=None))
      # -> Không có

Các giá trị mặc định có sẵn trong cả hai loại ConfigParser. Chúng được sử dụng trong phép nội suy nếu một tùy chọn được sử dụng không được xác định ở nơi khác.

nhập trình phân tích cấu hình

Ví dụ # New có 'bar' và 'baz' mặc định là 'Life' và 'hard'
config = configparser.ConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')

print(config.get('Section1', 'foo')) # -> "Python thật thú vị!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print(config.get('Section1', 'foo')) # -> "Cuộc sống thật khó khăn!"

Đối tượng ConfigParser

class configparser.ConfigParser(defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={}, allow_unnamed_section=False)

Trình phân tích cú pháp cấu hình chính. Khi defaults được cung cấp, nó sẽ được khởi tạo vào từ điển mặc định nội tại. Khi dict_type được cung cấp, nó sẽ được sử dụng để tạo các đối tượng từ điển cho danh sách các phần, cho các tùy chọn trong một phần và cho các giá trị mặc định.

Khi delimiters được đưa ra, nó được sử dụng làm tập hợp các chuỗi con phân chia khóa khỏi giá trị. Khi comment_prefixes được cung cấp, nó sẽ được sử dụng làm tập hợp các chuỗi con có tiền tố nhận xét trong các dòng trống. Bình luận có thể được thụt lề. Khi inline_comment_prefixes được cung cấp, nó sẽ được sử dụng làm tập hợp các chuỗi con có tiền tố nhận xét trong các dòng không trống.

Khi strict là True (mặc định), trình phân tích cú pháp sẽ không cho phép bất kỳ phần hoặc tùy chọn nào trùng lặp trong khi đọc từ một nguồn duy nhất (tệp, chuỗi hoặc từ điển), nâng cao DuplicateSectionError hoặc DuplicateOptionError. Khi empty_lines_in_values là False (mặc định: True), mỗi dòng trống đánh dấu sự kết thúc của một tùy chọn. Mặt khác, các dòng trống bên trong của tùy chọn nhiều dòng sẽ được giữ lại như một phần của giá trị. Khi allow_no_value là True (mặc định: False), các tùy chọn không có giá trị sẽ được chấp nhận; giá trị được giữ cho những giá trị này là None và chúng được sắp xếp theo thứ tự mà không có dấu phân cách ở cuối.

Khi default_section được cung cấp, nó chỉ định tên cho phần đặc biệt chứa các giá trị mặc định cho các phần khác và mục đích nội suy (thường được đặt tên là "DEFAULT"). Giá trị này có thể được truy xuất và thay đổi trong thời gian chạy bằng thuộc tính phiên bản default_section. Điều này sẽ không đánh giá lại tệp cấu hình đã được phân tích cú pháp nhưng sẽ được sử dụng khi ghi cài đặt được phân tích cú pháp vào tệp cấu hình mới.

Hành vi nội suy có thể được tùy chỉnh bằng cách cung cấp trình xử lý tùy chỉnh thông qua đối số interpolation. None có thể được sử dụng để tắt hoàn toàn nội suy, ExtendedInterpolation() cung cấp một biến thể cao cấp hơn lấy cảm hứng từ zc.buildout. Thông tin thêm về chủ đề này trong dedicated documentation section.

Tất cả các tên tùy chọn được sử dụng trong phép nội suy sẽ được chuyển qua phương thức optionxform() giống như bất kỳ tham chiếu tên tùy chọn nào khác. Ví dụ: sử dụng cách triển khai mặc định là optionxform() (chuyển đổi tên tùy chọn thành chữ thường), các giá trị foo %(bar)s và foo %(BAR)s là tương đương.

Khi converters được cung cấp, nó phải là một từ điển trong đó mỗi khóa biểu thị tên của một trình chuyển đổi loại và mỗi giá trị là một giá trị có thể gọi được thực hiện chuyển đổi từ chuỗi sang kiểu dữ liệu mong muốn. Mỗi bộ chuyển đổi đều có phương thức get*() tương ứng của riêng nó trên đối tượng trình phân tích cú pháp và các proxy phần.

Khi allow_unnamed_section là True (mặc định: False), tên phần đầu tiên có thể được bỏ qua. Xem "Unnamed Sections" section.

Có thể đọc một số cấu hình vào một ConfigParser duy nhất, trong đó cấu hình được thêm gần đây nhất có mức độ ưu tiên cao nhất. Mọi khóa xung đột đều được lấy từ cấu hình mới hơn trong khi các khóa hiện có trước đó vẫn được giữ lại. Ví dụ bên dưới đọc trong tệp override.ini, tệp này sẽ ghi đè mọi khóa xung đột từ tệp example.ini.

[DEFAULT]
ServerAliveInterval = -1

>>> config_override = configparser.ConfigParser()
>>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
>>> với open('override.ini', 'w') dưới dạng configfile:
... config_override.write(configfile)
...
>>> config_override = configparser.ConfigParser()
>>> config_override.read(['example.ini', 'override.ini'])
['example.ini', 'ghi đè.ini']
>>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
-1

Thay đổi trong phiên bản 3.1: Zz001zz mặc định là collections.OrderedDict.

Thay đổi trong phiên bản 3.2: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section và interpolation đã được thêm vào.

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

Thay đổi trong phiên bản 3.7: Đối số defaults được đọc bằng read_dict(), cung cấp hành vi nhất quán trên toàn bộ trình phân tích cú pháp: các khóa và giá trị không phải chuỗi được chuyển đổi hoàn toàn thành chuỗi.

Thay đổi trong phiên bản 3.8: dict_type mặc định là dict, vì hiện tại nó giữ nguyên thứ tự chèn.

Thay đổi trong phiên bản 3.13: Tăng MultilineContinuationError khi allow_no_value là True và khóa không có giá trị được tiếp tục bằng một dòng thụt lề.

Thay đổi trong phiên bản 3.13: Đối số allow_unnamed_section đã được thêm vào.

defaults()

Trả về một từ điển chứa các giá trị mặc định trên toàn phiên bản.

sections()

Trả về danh sách các phần có sẵn; default section không có trong danh sách.

add_section(section)

Thêm một phần có tên section vào phiên bản. Nếu một phần có tên đã tồn tại, DuplicateSectionError sẽ được nâng lên. Nếu tên default section được thông qua, ValueError sẽ được nâng lên. Tên của phần phải là một chuỗi; nếu không, TypeError sẽ được nâng lên.

Thay đổi trong phiên bản 3.2: Tên phần không có chuỗi tăng TypeError.

has_section(section)

Cho biết liệu section có tên trong cấu hình hay không. Zz001zz không được thừa nhận.

options(section)

Trả về danh sách các tùy chọn có sẵn trong section đã chỉ định.

has_option(section, option)

Nếu section đã cho tồn tại và chứa option đã cho, hãy trả về True; nếu không thì trả về False. Nếu section được chỉ định là None hoặc một chuỗi trống thì DEFAULT được giả định.

read(filenames, encoding=None)

Cố gắng đọc và phân tích tên tệp lặp lại, trả về danh sách tên tệp đã được phân tích cú pháp thành công.

Nếu filenames là một chuỗi, một đối tượng bytes hoặc path-like object thì nó được coi là một tên tệp duy nhất. Nếu không thể mở được tệp có tên trong filenames thì tệp đó sẽ bị bỏ qua. Điều này được thiết kế để bạn có thể chỉ định một vị trí tệp cấu hình tiềm năng có thể lặp lại (ví dụ: thư mục hiện tại, thư mục chính của người dùng và một số thư mục trên toàn hệ thống) và tất cả các tệp cấu hình hiện có trong iterable sẽ được đọc.

Nếu không có tệp được đặt tên nào tồn tại, phiên bản ConfigParser sẽ chứa tập dữ liệu trống. Một ứng dụng yêu cầu tải các giá trị ban đầu từ một tệp sẽ tải tệp được yêu cầu hoặc các tệp bằng cách sử dụng read_file() trước khi gọi read() cho bất kỳ tệp tùy chọn nào:

nhập trình cấu hình, os

config = configparser.ConfigParser()
config.read_file(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')],
            mã hóa='cp1250')

Thay đổi trong phiên bản 3.2: Đã thêm tham số encoding. Trước đây, tất cả các tệp đều được đọc bằng mã hóa mặc định cho open().

Thay đổi trong phiên bản 3.6.1: Tham số filenames chấp nhận path-like object.

Thay đổi trong phiên bản 3.7: Tham số filenames chấp nhận đối tượng bytes.

read_file(f, source=None)

Đọc và phân tích cú pháp dữ liệu cấu hình từ f, dữ liệu này phải là chuỗi Unicode có khả năng lặp lại (ví dụ: các tệp được mở ở chế độ văn bản).

Đối số tùy chọn source chỉ định tên của tệp đang được đọc. Nếu không được cung cấp và f có thuộc tính name, thuộc tính đó sẽ được sử dụng cho source; mặc định là '<???>'.

Added in version 3.2: Thay thế readfp().

read_string(string, source='<string>')

Phân tích dữ liệu cấu hình từ một chuỗi.

Đối số tùy chọn source chỉ định tên theo ngữ cảnh cụ thể của chuỗi được truyền. Nếu không được cung cấp, '<string>' sẽ được sử dụng. Đây thường phải là đường dẫn hệ thống tập tin hoặc URL.

Added in version 3.2.

read_dict(dictionary, source='<dict>')

Tải cấu hình từ bất kỳ đối tượng nào cung cấp phương thức items() giống như dict. Khóa là tên phần, giá trị là từ điển có khóa và giá trị phải có trong phần đó. Nếu loại từ điển đã sử dụng giữ nguyên thứ tự, các phần và khóa của chúng sẽ được thêm vào theo thứ tự. Các giá trị được tự động chuyển đổi thành chuỗi.

Đối số tùy chọn source chỉ định tên theo ngữ cảnh cụ thể của từ điển được truyền. Nếu không được cung cấp, <dict> sẽ được sử dụng.

Phương pháp này có thể được sử dụng để sao chép trạng thái giữa các trình phân tích cú pháp.

Added in version 3.2.

get(section, option, *, raw=False, vars=None[, fallback])

Nhận giá trị option cho section được đặt tên. Nếu vars được cung cấp thì nó phải là một từ điển. Zz004zz được tra cứu theo thứ tự vars (nếu được cung cấp), section và DEFAULTSECT. Nếu không tìm thấy khóa và fallback được cung cấp, nó sẽ được sử dụng làm giá trị dự phòng. None có thể được cung cấp dưới dạng giá trị fallback.

Tất cả các phép nội suy '%' đều được mở rộng theo giá trị trả về, trừ khi đối số raw là đúng. Các giá trị cho khóa nội suy được tra cứu theo cách tương tự như tùy chọn.

Thay đổi trong phiên bản 3.2: Các đối số raw, vars và fallback chỉ là từ khóa để bảo vệ người dùng khỏi cố gắng sử dụng đối số thứ ba làm dự phòng fallback (đặc biệt khi sử dụng giao thức ánh xạ).

getint(section, option, *, raw=False, vars=None[, fallback])

Một phương thức tiện lợi ép option trong section được chỉ định thành một số nguyên. Xem get() để biết giải thích về raw, vars và fallback.

getfloat(section, option, *, raw=False, vars=None[, fallback])

Một phương pháp tiện lợi ép buộc option trong section được chỉ định thành số dấu phẩy động. Xem get() để biết giải thích về raw, vars và fallback.

getboolean(section, option, *, raw=False, vars=None[, fallback])

Một phương pháp tiện lợi ép option trong section được chỉ định thành giá trị Boolean. Lưu ý rằng các giá trị được chấp nhận cho tùy chọn này là '1', 'yes', 'true' và 'on', khiến phương thức này trả về True và '0', 'no', 'false' và 'off', khiến phương thức này trả về False. Các giá trị chuỗi này được kiểm tra theo cách không phân biệt chữ hoa chữ thường. Bất kỳ giá trị nào khác sẽ khiến nó tăng ValueError. Xem get() để biết giải thích về raw, vars và fallback.

items(raw=False, vars=None)

items(section, raw=False, vars=None)

Khi section không được cung cấp, hãy trả về danh sách các cặp section_name, section_proxy, bao gồm cả DEFAULTSECT.

Nếu không, hãy trả về danh sách các cặp name, value cho các tùy chọn trong section đã cho. Các đối số tùy chọn có ý nghĩa tương tự như đối với phương thức get().

Thay đổi trong phiên bản 3.8: Các mục có trong vars không còn xuất hiện trong kết quả nữa. Hành vi trước đó đã trộn lẫn các tùy chọn trình phân tích cú pháp thực tế với các biến được cung cấp cho phép nội suy.

set(section, option, value)

Nếu phần đã cho tồn tại, hãy đặt tùy chọn đã cho thành giá trị đã chỉ định; nếu không hãy tăng NoSectionError. option và value phải là chuỗi; nếu không, TypeError sẽ được nâng lên.

write(fileobject, space_around_delimiters=True)

Viết bản trình bày cấu hình cho file object đã chỉ định, cấu hình này phải được mở ở chế độ văn bản (chấp nhận chuỗi). Biểu diễn này có thể được phân tích cú pháp bằng lệnh gọi read() trong tương lai. Nếu space_around_delimiters là đúng, dấu phân cách giữa khóa và giá trị sẽ được bao quanh bởi dấu cách.

Thay đổi trong phiên bản 3.14: Tăng InvalidWriteError nếu điều này sẽ viết một biểu diễn không thể được phân tích cú pháp chính xác bằng lệnh gọi read() trong tương lai từ trình phân tích cú pháp này.

Ghi chú

Các nhận xét trong tệp cấu hình gốc không được giữ nguyên khi ghi lại cấu hình. Những gì được coi là một nhận xét sẽ phụ thuộc vào các giá trị đã cho cho comment_prefix và inline_comment_prefix.

remove_option(section, option)

Xóa option được chỉ định khỏi section được chỉ định. Nếu phần này không tồn tại, hãy tăng NoSectionError. Nếu tùy chọn tồn tại để xóa, hãy trả về True; nếu không thì trả về False.

remove_section(section)

Xóa section được chỉ định khỏi cấu hình. Nếu phần này thực sự tồn tại, hãy trả về True. Nếu không thì trả về False.

optionxform(option)

Chuyển đổi tên tùy chọn option như được tìm thấy trong tệp đầu vào hoặc được mã máy khách chuyển vào thành dạng sẽ được sử dụng trong cấu trúc bên trong. Việc triển khai mặc định trả về phiên bản chữ thường của option; các lớp con có thể ghi đè tên này hoặc mã máy khách có thể đặt thuộc tính của tên này trong các phiên bản để ảnh hưởng đến hành vi này.

Bạn không cần phải phân lớp trình phân tích cú pháp để sử dụng phương thức này, bạn cũng có thể đặt nó trên một phiên bản, cho một hàm nhận đối số chuỗi và trả về một chuỗi. Ví dụ: đặt nó thành str sẽ làm cho tên tùy chọn phân biệt chữ hoa chữ thường

cfgparser = ConfigParser()
cfgparser.optionxform = str

Lưu ý rằng khi đọc tệp cấu hình, khoảng trắng xung quanh tên tùy chọn sẽ bị xóa trước khi optionxform() được gọi.

configparser.UNNAMED_SECTION

Một đối tượng đặc biệt biểu thị tên phần được sử dụng để tham chiếu phần chưa được đặt tên (xem Phần chưa đặt tên).

configparser.MAX_INTERPOLATION_DEPTH

Độ sâu tối đa cho phép nội suy đệ quy cho get() khi tham số raw sai. Điều này chỉ liên quan khi sử dụng interpolation mặc định.

Đối tượng RawConfigParser

class configparser.RawConfigParser(defaults=None, dict_type=dict, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configparser.DEFAULTSECT, interpolation=BasicInterpolation(), converters={}, allow_unnamed_section=False)

Biến thể kế thừa của ConfigParser. Nó bị tắt tính năng nội suy theo mặc định và cho phép đặt tên phần không phải chuỗi, tên tùy chọn và giá trị thông qua các phương thức add_section và set không an toàn, cũng như xử lý đối số từ khóa defaults= cũ.

Thay đổi trong phiên bản 3.2: allow_no_value, delimiters, comment_prefixes, strict, empty_lines_in_values, default_section và interpolation đã được thêm vào.

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

Thay đổi trong phiên bản 3.8: dict_type mặc định là dict, vì hiện tại nó giữ nguyên thứ tự chèn.

Thay đổi trong phiên bản 3.13: Đối số allow_unnamed_section đã được thêm vào.

Ghi chú

Thay vào đó, hãy cân nhắc sử dụng ConfigParser để kiểm tra các loại giá trị sẽ được lưu trữ nội bộ. Nếu bạn không muốn nội suy, bạn có thể sử dụng ConfigParser(interpolation=None).

add_section(section)

Thêm một phần có tên section hoặc UNNAMED_SECTION vào phiên bản.

Nếu phần đã cho đã tồn tại, DuplicateSectionError sẽ được nâng lên. Nếu tên default section được thông qua, ValueError sẽ được nâng lên. Nếu UNNAMED_SECTION được thông qua và hỗ trợ bị tắt, UnnamedSectionDisabledError sẽ được nâng lên.

Loại section không được chọn, cho phép người dùng tạo các phần có tên không phải chuỗi. Hành vi này không được hỗ trợ và có thể gây ra lỗi nội bộ.

Thay đổi trong phiên bản 3.14: Đã thêm hỗ trợ cho UNNAMED_SECTION.

set(section, option, value)

Nếu phần đã cho tồn tại, hãy đặt tùy chọn đã cho thành giá trị đã chỉ định; nếu không hãy tăng NoSectionError. Mặc dù có thể sử dụng RawConfigParser (hoặc ConfigParser với tham số raw được đặt thành true) để lưu trữ internal các giá trị không phải chuỗi, nhưng chỉ có thể đạt được chức năng đầy đủ (bao gồm nội suy và xuất ra tệp) bằng cách sử dụng các giá trị chuỗi.

Phương pháp này cho phép người dùng gán các giá trị không phải chuỗi cho các khóa bên trong. Hành vi này không được hỗ trợ và sẽ gây ra lỗi khi cố gắng ghi vào tệp hoặc tải tệp đó ở chế độ không phải thô. Use the mapping protocol API không cho phép thực hiện các nhiệm vụ như vậy.

Ngoại lệ

exception configparser.Error

Lớp cơ sở cho tất cả các ngoại lệ configparser khác.

exception configparser.NoSectionError

Ngoại lệ xuất hiện khi không tìm thấy phần được chỉ định.

exception configparser.DuplicateSectionError

Ngoại lệ nảy sinh nếu add_section() được gọi với tên của một phần đã có sẵn hoặc trong các trình phân tích cú pháp nghiêm ngặt khi một phần được tìm thấy nhiều lần trong một tệp đầu vào, chuỗi hoặc từ điển.

Thay đổi trong phiên bản 3.2: Đã thêm các thuộc tính và tham số source và lineno tùy chọn vào __init__().

exception configparser.DuplicateOptionError

Ngoại lệ được đưa ra bởi các trình phân tích cú pháp nghiêm ngặt nếu một tùy chọn xuất hiện hai lần trong khi đọc từ một tệp, chuỗi hoặc từ điển. Điều này giúp phát hiện lỗi chính tả và các lỗi liên quan đến phân biệt chữ hoa chữ thường, ví dụ: một từ điển có thể có hai khóa biểu thị cùng một khóa cấu hình không phân biệt chữ hoa chữ thường.

exception configparser.NoOptionError

Ngoại lệ nảy sinh khi không tìm thấy tùy chọn đã chỉ định trong phần đã chỉ định.

exception configparser.InterpolationError

Lớp cơ sở dành cho các trường hợp ngoại lệ được đưa ra khi xảy ra sự cố khi thực hiện phép nội suy chuỗi.

exception configparser.InterpolationDepthError

Ngoại lệ nảy sinh khi không thể hoàn thành nội suy chuỗi do số lần lặp vượt quá MAX_INTERPOLATION_DEPTH. Lớp con của InterpolationError.

exception configparser.InterpolationMissingOptionError

Ngoại lệ nảy sinh khi tùy chọn được tham chiếu từ một giá trị không tồn tại. Lớp con của InterpolationError.

exception configparser.InterpolationSyntaxError

Ngoại lệ nảy sinh khi văn bản nguồn được thay thế không tuân theo cú pháp được yêu cầu. Lớp con của InterpolationError.

exception configparser.MissingSectionHeaderError

Ngoại lệ nảy sinh khi cố gắng phân tích cú pháp một tệp không có tiêu đề phần.

exception configparser.ParsingError

Ngoại lệ nảy sinh khi xảy ra lỗi khi cố phân tích tệp.

Thay đổi trong phiên bản 3.12: Thuộc tính filename và đối số hàm tạo __init__() đã bị xóa. Chúng đã có sẵn với tên source kể từ phiên bản 3.2.

exception configparser.MultilineContinuationError

Ngoại lệ nảy sinh khi một khóa không có giá trị tương ứng được tiếp tục bằng một dòng thụt lề.

Added in version 3.13.

exception configparser.UnnamedSectionDisabledError

Ngoại lệ nảy sinh khi cố gắng sử dụng UNNAMED_SECTION mà không bật nó.

Added in version 3.14.

exception configparser.InvalidWriteError

Ngoại lệ nảy sinh khi một lệnh gọi ConfigParser.write() được thử sẽ không được phân tích cú pháp chính xác bằng lệnh gọi ConfigParser.read() trong tương lai.

Ví dụ: Viết khóa bắt đầu bằng mẫu ConfigParser.SECTCRE sẽ phân tích thành tiêu đề phần khi đọc. Cố gắng viết điều này sẽ đưa ra ngoại lệ này.

Added in version 3.14.

Chú thích cuối trang

[1] (1,2,3,4,5,6,7,8,9,10,11)

Trình phân tích cú pháp cấu hình cho phép tùy chỉnh nhiều. Nếu bạn quan tâm đến việc thay đổi hành vi được nêu trong phần tham chiếu chú thích cuối trang, hãy tham khảo phần Customizing Parser Behaviour.