python-ini
… powered by
Python APG
|
Introduction
GitHub Installation
PyPi Installation
INI File Syntax
Parser Usage
Writer Usage
License
INI or initialization files are text-based files using simple key/value pairs in optionally named sections for organizational purposes. python-ini
is a simple and easy to use INI file parser and yet it retains most of the stable and varying features of this WikiPedia article. It supports an extremely liberal INI file syntax, operates in single- or multiple-value mode and has "getter" functions which support default values if the key or section does not exist. Key and comment delimiters are very flexible and section and key names can contain almost any character that is not used as a special character elsewhere.
Its chief ommission is that it does not directly support subsections. However, since the period is a valid section name character, section names such as [A], [A.B] and [A.B.C] are unique section names and could be used to simulate subsections.
python-ini
can be installed from GitHub by either cloning it or downloading the zip file. Throughout an Ubuntu-flavored Linux OS is assumed.
From the project directory execute
Download the zip file from https://github.com/ldthomas/python-ini and execute
Unit tests are in the tests
directory. Run
which should indicate something like 42 successful tests.
There is also a set of examples demonstrating most aspects of using python-ini in the examples
directory. Each example displays a short description of the test and its output.
See these quick start guides for using using the GitHub installation of python-ini
in your project.
The simplest way to install python-ini
is simply
This will install python-ini
and the CLI stand-alone help function but none of the tests or examples that are available from the GitHub installation.
See these quick start guides for using using the pip
installation of python-ini
in your project.
Key names must begin at the first character on a line, are case sensitive and must be one or more characters from the set
That is, almost any character that is not used elsewhere as a special character.
Keys are "disjoint". That is, the values for a key name appearing multiple times within a section are combined as if they had been specified all on one line.
Note on key values:
Keys may have a single value or a list of multiple values. In fact, values are always interpeted as a list. When the parser is in single-value mode, a request for a key value will simply return the last value in the list. When in multi-value mode it will return the entire list, even if it is only a single value. For example, consider the INI file
In single-value mode the parser will return the key values
In multi-value mode the parser will return the key values
Sections are enclosed in square brackets which must begin on the first character of a line. Sections names, like key names, are case sensitive and are formed from one or more characters of the same set as for keys. White space is allowed between brackets and section names. For example, these would all be valid sections.
A section ends at the beginning of another section or at the end of the file. Sections are "disjoint". That is, if a section name appears more than once, the keys and values are merged as if they had occurred in a single section.
Values may be numbers, booleans or strings.
Numbers
Numbers may be positive or negative integers or floating point.
Booleans
Booleans are case insensitive and may be
(OK, "None" is not exactly boolean.) Boolean values are reserved key words and must be quoted if needed as strings.
Note that a key without a value is interpreted as a "true" flag. That is, consider the INI file
The parser will return the values
Strings
Control characters, tab, line feed, carriage return, etc., are not allowed in any of the string forms. Escaped characters must be used (see below).
unquoted
Unquoted strings may not be any of the reserved boolean key words. Otherwise, they may contain any characters except [space " # ' , / : ; = \]. (Square braces not included. They simply delimit the disallowed set.)
single-quoted
Single-quoted strings, 'single quoted', may contain any characters except [' \].
double-quoted
Double-quoted strings, "double quoted", may contain any characters except [" \].
escaped characters
Characters otherwise not allowed in any of the string forms must be escaped. Escaped characters begin with a back slash or reverse solidus(\). Escaped characters and their meaning are:
escaped | rendered |
---|---|
\\ | \ |
\" | " |
\# | # |
\' | ' |
\, | , |
\: | : |
\; | ; |
\= | = |
\b | space |
\t | tab |
\n | line feed |
\r | carriage return |
\xhh | 8-bit hexadecimal |
\uhhhh | 16-bit Unicode |
\Uhhhhhhhh | 32-bit Unicode |
Notes:
h = hex digit, 0-9a-fA-F
16-bit Unicode, surrogate values, 0xD800 - 0xDFFF, not allowed
32-bit Unicode, surrogate values, 0xD800 - 0xDFFF, and values > 0x10FFFF not allowed
key dilimiters
Keys may be delimited from the values with equals(=), colon(:) or simply with a space. For example, all of the following would be valid key/value definitions.
value dilimiters
Multiple values may be delimited with commas or spaces. For example, the following INI file
would return the multi-value list
Lines may be continued with a forward slash(/) with at least one space or tab beginning the next line. For example,
Comments begin with either a hash(#) or semicolon(;) and continue to the end of the line. For example,
Implemented with a single class and five member "getter" functions, it is easy to use with a short learning curve. For example, this simple program would print all values for all keys in all sections from the file INI_FILE_NAME.
See the constructor and member functions, python_ini.ini_file.IniFile, for detailed descriptions of options and usage.
Note that the parser is designed to report errors in the INI file syntax without halting. That is, the parser should never fail. It should collect all syntacticly correct section, key values and report errors for any file lines that are syntacticly incorrect.
Implemented with a single class with functions to write comments, key/value pairs and sections, it is easy to use with a short learning curve. For example, this simple program would configure all defaults and write a short INI file.
The file output.ini
would look like this:
See the IniWriter class, python_ini.ini_writer.IniWriter, for the details.
2-Clause BSD License.
Copyright © 2023 Lowell D. Thomas, all rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.