I/O facility for Idefix/Pluto configuration files
Project description
inifix
inifix in a small Python library with I/O methods to read and write
Pluto/Idefix inifiles as Python dictionaries.
Its primary goal is to support Idefix's model (which is intended as identical to
Pluto's), though the following file format specification is intended as a
superset of the one used in Pluto and Idefix. Namely, while Pluto and Idefix
require that each and every (key, value) pair be part of a section, inifix
supports section-free definitions.
File format specifications
Unroll !
- parameter names are strings - names and values are separated by non-newline white spaces - values are represented in unicode characters - all values are considered numbers if possible (e.g., `1e3` is read as `1000`) - number values are read as integers if no loss of precision ensues, and floats otherwise - `true` and `false` (resp. `yes` and `no`) are cast to booleans (case-insensitive) - values that can't be read as number or booleans are read as strings. - string delimiters `"` and `'` can be used for strings containing whitespace, or to force string type for values that would otherwise be read as numbers and booleans. - a parameter can be associated to a single value or a list of whitespace-separated values - sections titles start with `[` and end with `]` - comments start with `#` and are ignoredA file is considered valid if calling inifix.load(<filename>) doesn't raise an
error.
Examples
The following content is considered valid
# My awesome experiment
[Grid]
x 1 2 u 10 # a comment
y 4 5 l 100
[Time Integrator]
CFL 1e-3
tstop 1E3
and maps to
{
"Grid": {
"x": [1, 2, "u", 10],
"y": [4, 5, "l", 100]
},
"Time Integrator": {
"CFL": 0.001,
"tstop": 1000.0
}
}
The following section-less format doesn't comply to Pluto/Idefix's specifications, but it is considered valid for inifix. This is the one intentional differences in specifications, which makes inifix format a superset of Pluto's inifile format.
mode fargo
# Time integrator
CFL 1e-3
tstop 1e3
and maps to
{
"mode": "fargo",
"CFL": 0.001,
"tstop": 1000.0
}
Note that strings using e-notation (e.g. 1e-3 or 1E3 here) are decoded as
floats. Reversely, when writing files, floats are re-encoded using e-notation
if it leads to a more compact representation. For instance, 100000.0 is encoded
as 1e5, but 189.0 is left unchanged because 1.89e2 takes one more character.
In cases where both reprensations are equally compact (e.g. 1.0 VS 1e0),
decimal is prefered in encoding.
While decoding, e can be lower or upper case, but they are always encoded as
lower case.
Installation
pip install inifix
Usage
The public API mimicks that of Python's standard library json,
and consists in four main functions:
inifix.loadandinifix.dumpread from and write to files respectivelyinifix.loadsreads from astrand returns adict, whileinifix.dumpsdoes the reverse operation.
Reading data
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.
... and writing back to disk
inifix.dump allows to write 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.
Schema Validation
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)
CLI
Command line tools are shipped with the package to validate or format compatible inifiles.
Validation
This checks that your inifiles can be loaded with inifix.load from the command line
$ inifix-validate pluto.ini
Validated pluto.ini
This simple validator can be used as a hook for pre-commit. Simply add the
following to your project's .pre-commit-config.yaml
- repo: https://github.com/neutrinoceros/inifix.git
rev: v2.3.0
hooks:
- id: inifix-validate
Formatting
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.
Options
- To print a diff patch to stdout instead of editing the file, use the
--diffflag
$ inifix-format pluto.ini --diff
This program also doubles as pre-commit hook
- repo: https://github.com/neutrinoceros/inifix.git
rev: v2.3.0
hooks:
- id: inifix-format
Contribution guidelines
We use the pre-commit framework to automatically lint for code style and common pitfalls.
Before you commit to your local copy of the repo, please run this from the top level
$ python3 -m pip install -u -e .[dev]
$ pre-commit install
Testing
We use the pytest framework to test
inifix. The test suite can be run from the top level with a simple pytest
invocation.
$ pytest
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file inifix-3.0.0.tar.gz.
File metadata
- Download URL: inifix-3.0.0.tar.gz
- Upload date:
- Size: 26.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.0 CPython/3.9.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 4447a90ae24b35d3c984de569fb5505b9b071a490cf60d19fda15bcf95b61c9d |
|
| MD5 | a57cbebe73363dc3cbf0a419cc23249c |
|
| BLAKE2b-256 | bd5c3018b8b0c81f1f94773da3e932aa482ae9cc12f4530b550571343ff5b926 |
File details
Details for the file inifix-3.0.0-py3-none-any.whl.
File metadata
- Download URL: inifix-3.0.0-py3-none-any.whl
- Upload date:
- Size: 25.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.0 CPython/3.9.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 0555206c3518f795090a2da880bf805a718754b62089e78e22eebffddaf21839 |
|
| MD5 | 4ec34e9b70d09b90a1368f928d8ad8ea |
|
| BLAKE2b-256 | 439d6a39ef8c1004477121ab2b57922fc7926d281373a9de55f445add91096e2 |
