inifix is a small Python library of I/O functions to read and write 'ini' configuration files in the style of Pluto and Idefix.

While its primary goal is to follow Idefix's 'ini' format specification, it supports a small superset of it.

The key differences are:

• inifix supports section-free definitions. This means configuration files from FARGO 3D are also supported.
• in inifix, strings can be escaped using ' or ". This allows to have whitespaces in string values and to force string type decoding where numeric and boolean types would work.

In rare cases where Idefix's 'ini' format doesn't match Pluto's, inifix will follow the former. Known differences are:

• Idefix allows booleans to be written as yes and no.
• Idefix allows integers to be written using scientific notation (e.g. 1e3)

# My awesome experiment
[Grid]
x   1 2 u 10    # a comment
y   4 5 l 100
[Time Integrator]
CFL  1e-3
tstop 1E3

{
    "Grid": {
        "x": [1, 2, "u", 10],
        "y": [4, 5, "l", 100]
    },
    "Time Integrator": {
        "CFL": 0.001,
        "tstop": 1000.0
    }
}

mode   fargo

# Time integrator
CFL    1e-3
tstop  1e3

{
    "mode": "fargo",
    "CFL": 0.001,
    "tstop": 1000.0
}

python -m pip install inifix

The public API mimicks that of Python's standard library json, and consists in four main functions:

• inifix.load and inifix.dump read from and write to files respectively
• inifix.loads reads from a str and returns a dict, while inifix.dumps does the reverse operation.

inifix.load reads from a file and returns a dict

import inifix

with open("pluto.ini", "rb") as fh:
    conf = inifix.load(fh)

# or equivalently
conf = inifix.load("pluto.ini")

Files are assumed to be encoded as UTF-8.

inifix.load and inifix.loads accept a optional boolean flag parse_scalars_as_list (new in inifix v4.0.0), that is useful to simplify handling unknown data: all values can be safely treated as arrays, and iterated over, even in the presence of scalar strings. For illustration

>>> import inifix
>>> from pprint import pprint
>>> pprint(inifix.load("example.ini"))
{'Grid': {'x': [1, 2, 'u', 10], 'y': [4, 5, 'l', 100]},
 'Time Integrator': {'CFL': 0.001, 'tstop': 1000.0}}
>>> pprint(inifix.load("example.ini", parse_scalars_as_lists=True))
{'Grid': {'x': [1, 2, 'u', 10], 'y': [4, 5, 'l', 100]},
 'Time Integrator': {'CFL': [0.001], 'tstop': [1000.0]}}

By default, inifix.load and inifix.loads validate input data. This step can be skipped by specifying skip_validation=True.

inifix.dump writes data back to a file.

This allows to change a value on the fly and create new configuration files programmatically, for instance.

conf["Time"]["CFL"] = 0.1

with open("pluto-mod.ini", "wb") as fh:
    inifix.dump(conf, fh)

# or equivalently
inifix.dump(conf, "pluto-mod.ini")

Data will be validated against inifix's format specification at write time. Files are always encoded as UTF-8.

inifix.dumps is the same as inifix.dump except that it returns a string instead of writing to a file.

By default, inifix.dump and inifix.dumps validate input data. This step can be skipped by specifying skip_validation=True.

inifix.validate_inifile_schema can be used to validate an arbitrary dictionary as writable to an inifile, following Pluto/Idefix's format. This will raise an exception (ValueError) if the dictionnary data is invalid.

inifix.validate_inifile_schema(data)

Command line tools are shipped with the package to validate or format compatible inifiles.

This checks that your inifiles can be loaded with inifix.load from the command line

$ inifix-validate pluto.ini
Validated pluto.ini

To format a file in place, use

$ inifix-format pluto.ini

inifix-format is guaranteed to preserve comments and to only edit (add or remove) whitespace characters.

Files are always encoded as UTF-8.

To print a diff patch to stdout instead of editing the file, use the --diff flag

$ inifix-format pluto.ini --diff

By default, inifix-format also validates input data. This step can be skipped with the --skip-validation flag

inifix-validate and inifix-format can be used as pre-commit hooks with the following configuration (add to .pre-commit-config.yaml)

  - repo: https://github.com/neutrinoceros/inifix.git
    rev: v4.4.3
    hooks:
      - id: inifix-validate

or

  - repo: https://github.com/neutrinoceros/inifix.git
    rev: v4.4.3
    hooks:
      - id: inifix-format

Note that inifix-format also validates data by default, so it is redundant to utilize both hooks. Validation and formatting may nonetheless be decoupled as

  - repo: https://github.com/neutrinoceros/inifix.git
    rev: v4.3.2
    hooks:
    - id: inifix-validate
    - id: inifix-format
+     args: [--skip-validation]

By default, both hooks target files matching the regular expression (\.ini)$. It is possible to override this expression as, e.g.,

   hooks:
   - id: inifix-format
+    files: (\.ini|\.par)$

We use the pytest framework to test inifix. The test suite can be run from the top level with a simple pytest invocation.

$ python -m pip install --requirement requirements/tests.txt
$ pytest