| Name | inifix JSON |
| Version |
5.1.2
JSON |
| download |
| home_page | None |
| Summary | An I/O library for Pluto-style ini files. |
| upload_time | 2024-12-16 10:33:42 |
| maintainer | None |
| docs_url | None |
| author | C.M.T. Robert |
| requires_python | >=3.10 |
| license | GPL-3.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# `inifix`
[](https://pypi.org/project/inifix/)
[](https://anaconda.org/conda-forge/inifix)
[](https://results.pre-commit.ci/badge/github/neutrinoceros/inifix/main.svg)
[](https://github.com/charliermarsh/ruff)
`inifix` is a small Python library offering a `load/dump` interface similar to
standard library modules `json` or `tomllib` (together with `tomli_w`) for ini
configuration files in the style of [Pluto](http://plutocode.ph.unito.it) and
[Idefix](https://github.com/idefix-code/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](https://fargo3d.bitbucket.io) 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` takes
the path of least resistance to support both.
Known differences are:
- Idefix allows booleans to be written as `yes` and `no`, as so does `inifix`,
but these are not valid in Pluto (as of version 4.4).
Note that in contrast to Idefix, which is truly case-insensitive about
these special strings, `inifix` (from version 5.0.0) only parse a restricted
set of unescaped strings as booleans, like `true`, `TRUE`, `True`, `yes`,
`Yes` and `YES`, but `TruE` or `yES` for instance will be parsed as strings.
- Idefix allows integers to be written using decimal notation (e.g. `1.0` or `1e3`).
This creates some ambiguity when deserializing such strings, as the expected type
(`int` or `float`) cannot be unambiguously guessed. By default, `inifix` (from
version 5.0) will parse these as `float`s, allowing for 1-to-1 roundtrips.
Idefix (as of version 2.1) is also resilient against integers written as decimal,
so `inifix` will not break any working inifile by a load/patch/dump routine.
See [Reading Options](#reading-options) for more.
## File format specifications details
<details><summary>Unroll !</summary>
- parameter names are alphanumeric 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
- unescaped strings `true`, `false`, `yes` and `no` are cast to booleans, as well
as their respective upper-case and "title" variants (e.g. `TRUE` or `True`).
- 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 ignored
A file is considered valid if calling `inifix.load(<filename>)` doesn't raise an
error.
### Examples
The following content is considered valid
```ini
# 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
```json
{
"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 is also valid in `inifix`
```ini
mode fargo
# Time integrator
CFL 1e-3
tstop 1e3
```
and maps to
```json
{
"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 preferred in encoding.
While decoding, `e` can be lower or upper case, but they are always encoded as
lower case.
</details>
## Installation
```shell
python -m pip install inifix
```
## Usage
The public API mimics 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.
### Reading data
`inifix.load` reads from a file and returns a `dict`
```python
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.
#### Parsing options
`inifix.load` and `inifix.loads` accept an optional boolean flag
`parse_scalars_as_lists` (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
```python
>>> 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]}}
```
`inifix.load` and `inifix.loads` also accept an `integer_casting` argument (new
in `inifix` v5.0.0), which can be set to decide how numbers written in decimal
notation which happen to have integral values (e.g. `1e2` or `30000.`) should be
parsed.
This argument accepts two values:
`'stable'` (default) gives `float`s while `'aggressive'` gives `int`s,
matching the behavior of `inifix` v4.5.0.
The key difference is that the default strategy is roundtrip-stable on types,
while the aggressive mode isn't:
```python
>>> import inifix
>>> data = {'option_a': [0, 1., 2e3, 4.5]}
>>> data
{'option_a': [0, 1.0, 2000.0, 4.5]}
>>> inifix.loads(inifix.dumps(data))
{'option_a': [0, 1.0, 2000.0, 4.5]}
>>> inifix.loads(inifix.dumps(data), integer_casting='aggressive')
{'option_a': [0, 1, 2000, 4.5]}
```
Aggressive casting may also lead to loss of precision beyond a certain range
```python
>>> import inifix
>>> data = {'option_b': 9_007_199_254_740_993}
>>> inifix.loads(inifix.dumps(data))
{'option_b': 9007199254740993}
>>> inifix.loads(inifix.dumps(data), integer_casting='aggressive')
{'option_b': 9007199254740992}
```
By default, `inifix.load` and `inifix.loads` validate input data, see
[Schema Validation](#schema-validation) for details.
Also see [Type Checking](#type-checking) for how `parse_scalars_as_lists` affects
type checking.
### Writing to a file or a string
`inifix.dump` writes data to a file.
One typical use case is to combine `inifix.load` and `inifix.dump` to
programmatically update an existing configuration file at runtime via a
load/patch/dump routine.
```python
>>> import inifix
>>> with open("pluto.ini", "rb") as fr:
... inifix.load(fr)
>>> conf["Time"]["CFL"] = 0.1
>>> with open("pluto-mod.ini", "wb") as fw:
... inifix.dump(conf, fw)
```
or, equivalently
```python
>>> import inifix
>>> inifix.load("pluto.ini")
>>> conf["Time"]["CFL"] = 0.1
>>> 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.
```python
>>> import inifix
>>> data = {"option_a": 1, "option_b": True}
>>> print(inifix.dumps(data))
option_a 1
option_b True
```
By default, `inifix.dump` and `inifix.dumps` validate input data, see
[Schema Validation](#schema-validation) for details.
### Schema Validation
By default, I/O functions (`inifix.dump`, `inifix.dumps`, `inifix.load` and
`inifix.loads`) all validate that output/input data structures conform to the
library's specification:
- readers (`inifix.load` and `inifix.loads`) validate data post parsing,
and before returning
- writers (`inifix.dump` and `inifix.dumps`) validate input data before writing
to their respective output channels
In case the data is invalid, a `ValueError` is raised.
This behavior can be turned off by passing `skip_validation=True`.
Additionally, all four functions support a `sections` argument (new in `inifix`
v5.1.0), which controls
whether sections (starting with headers, e.g., `[MySection]`) are allowed
(`sections='allow'`, default), forbidden (`sections='forbid'`), or required
(`sections='require'`) at validation.
This argument does not have any effect at runtime if combined with `skip_validation=True`.
However, it will affect the return type of readers, as seen by typecheckers (e.g. `mypy`
or `pyright`), regardless if validation is enabled, see [Type Checking](#type-checking)
`inifix.validate_inifile_schema` can also be used directly and supports the
`sections` argument.
### Runtime formatting
`inifix.format_string` formats a string representing the contents of an ini file.
See [Formatting CLI](#formatting-cli) for how to use this at scale.
### Type Checking
### Narrowing return type of readers
Readers (`inifix.load` and `inifix.loads`) support a diversity of input and output
formats such that their default return type, while technically correct, is too broad
to be really useful in a type checking context. However, passing
`parse_scalars_as_list=True`, `sections='forbid'` or `sections='require'` can
narrow the return type, as seen by a typechecker (e.g. `mypy` or `pyright`).
Note that this effect is intentionally not disabled with `skip_validation=True`,
eventhough the `sections` argument's runtime effect *is* disabled; such a
combination allows to get both optimal runtime performance and type-consistency.
However, `skip_validation=True` may create situations where your code type-checks
but fails at runtime, so this option is only meant to be used if validation is
known to cause a performance bottleneck or a crash in your application. If such
a situation occurs, please report it !
#### Writing type-safe applications of `inifix.load(s)`
`inifix.load` has no built-in expectations on the type of any specific parameter;
instead, all types are inferred at runtime, which allows the function to work
seamlessly with arbitrary parameter files.
However, this also means that the output is not (and cannot be) perfectly type-safe.
In other words, type checkers (e.g. `mypy`) cannot infer exact types of outputs,
which is a problem in applications relying on type-checking.
A solution to this problem, which is actually not specific to `inifix.load` and
works with any arbitrarily formed `dict`, is to create a pipeline around this data
which implements type-checkable code, where data is *also* validated at runtime.
We'll illustrate this with a real-life example inspired from
[`nonos`](https://pypi.org/project/nonos).
Say, for instance, that we only care about a couple parameters from the `[Output]`
and `[Hydro]` sections of `idefix.ini`. Let's build a type-safe `read_parameter_file`
function around these.
```python
class IdefixIni:
def __init__(self, *, Hydro, Output, **kwargs):
self.hydro = IdefixIniHydro(**Hydro)
self.output = IdefixIniOutput(**Output)
class IdefixIniHydro:
def __init__(self, **kwargs):
if "rotation" in kwargs:
self.frame = "COROT"
self.rotation = float(kwargs["rotation"])
else:
self.frame = "UNSET"
self.rotation = 0.0
class IdefixIniOutput:
def __init__(self, *, vtk, **kwargs):
self.vtk = float(vtk)
def read_parameter_file(file) -> IdefixIni:
return IdefixIni(**inifix.load(file))
ini = read_parameter_file("idefix.ini")
```
Type checkers can now safely assume that, `ini.hydro.frame`, `ini.hydro.rotation`
and `ini.output.vtk` all exist and are of type `str`, `float` and `float`, respectively.
If this assumption is not verified at runtime, a `TypeError` will be raised.
Note that we've used the catch-all `**kwargs` construct to capture optional
parameters as well as any other parameters present (possibly none) that we do not
care about.
### CLI
Command line tools are shipped with the package to validate or format compatible
inifiles.
#### Validation CLI
This checks that your inifiles can be loaded with `inifix.load` from the command line
```shell
$ inifix-validate pluto.ini
Validated pluto.ini
```
This CLI can also be called as `python -m inifix.validate`.
#### Formatting CLI
To format a file in place, use
```shell
$ 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
```shell
$ inifix-format pluto.ini --diff
```
This CLI can also be called as `python -m inifix.format`.
By default, `inifix-format` also validates input data. This step can be skipped with the
`--skip-validation` flag
### pre-commit hooks
`inifix-validate` and `inifix-format` can be used as `pre-commit` hooks with the
following configuration (add to `.pre-commit-config.yaml`)
```yaml
- repo: https://github.com/neutrinoceros/inifix.git
rev: v5.1.2
hooks:
- id: inifix-validate
```
or
```yaml
- repo: https://github.com/neutrinoceros/inifix.git
rev: v5.1.2
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
```patch
- repo: https://github.com/neutrinoceros/inifix.git
rev: v5.1.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.,
```patch
hooks:
- id: inifix-format
+ files: (\.ini|\.par)$
```
Raw data
{
"_id": null,
"home_page": null,
"name": "inifix",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "C.M.T. Robert",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/8e/7e/b1a9f3e5770d5b7d70edde8d4c2f9a70678f9c8fac8027dbd7eb8df47e00/inifix-5.1.2.tar.gz",
"platform": null,
"description": "# `inifix`\n\n[](https://pypi.org/project/inifix/)\n[](https://anaconda.org/conda-forge/inifix)\n[](https://results.pre-commit.ci/badge/github/neutrinoceros/inifix/main.svg)\n[](https://github.com/charliermarsh/ruff)\n\n\n`inifix` is a small Python library offering a `load/dump` interface similar to\nstandard library modules `json` or `tomllib` (together with `tomli_w`) for ini\nconfiguration files in the style of [Pluto](http://plutocode.ph.unito.it) and\n[Idefix](https://github.com/idefix-code/idefix).\n\nWhile its primary goal is to follow Idefix's 'ini' format specification, it\nsupports a small superset of it.\n\nThe key differences are:\n- `inifix` supports section-free definitions. This means configuration files\n from [FARGO 3D](https://fargo3d.bitbucket.io) are also supported.\n- in `inifix`, strings can be escaped using `'` or `\"`. This allows to have\n whitespaces in string values and to force string type decoding where numeric\n and boolean types would work.\n\nIn rare cases where Idefix's 'ini' format doesn't match Pluto's, `inifix` takes\nthe path of least resistance to support both.\n\nKnown differences are:\n- Idefix allows booleans to be written as `yes` and `no`, as so does `inifix`,\n but these are not valid in Pluto (as of version 4.4).\n Note that in contrast to Idefix, which is truly case-insensitive about\n these special strings, `inifix` (from version 5.0.0) only parse a restricted\n set of unescaped strings as booleans, like `true`, `TRUE`, `True`, `yes`,\n `Yes` and `YES`, but `TruE` or `yES` for instance will be parsed as strings.\n- Idefix allows integers to be written using decimal notation (e.g. `1.0` or `1e3`).\n This creates some ambiguity when deserializing such strings, as the expected type\n (`int` or `float`) cannot be unambiguously guessed. By default, `inifix` (from\n version 5.0) will parse these as `float`s, allowing for 1-to-1 roundtrips.\n Idefix (as of version 2.1) is also resilient against integers written as decimal,\n so `inifix` will not break any working inifile by a load/patch/dump routine.\n See [Reading Options](#reading-options) for more.\n\n## File format specifications details\n<details><summary>Unroll !</summary>\n- parameter names are alphanumeric strings\n- names and values are separated by non-newline white spaces\n- values are represented in unicode characters\n- all values are considered numbers if possible (e.g., `1e3` is read as `1000`)\n- number values are read as integers if no loss of precision ensues, and floats otherwise\n- unescaped strings `true`, `false`, `yes` and `no` are cast to booleans, as well\n as their respective upper-case and \"title\" variants (e.g. `TRUE` or `True`).\n- values that can't be read as number or booleans are read as strings.\n- string delimiters `\"` and `'` can be used for strings containing whitespace, or to\n force string type for values that would otherwise be read as numbers and booleans.\n- a parameter can be associated to a single value or a list of whitespace-separated values\n- sections titles start with `[` and end with `]`\n- comments start with `#` and are ignored\n\nA file is considered valid if calling `inifix.load(<filename>)` doesn't raise an\nerror.\n\n### Examples\nThe following content is considered valid\n```ini\n# My awesome experiment\n[Grid]\nx 1 2 u 10 # a comment\ny 4 5 l 100\n[Time Integrator]\nCFL 1e-3\ntstop 1E3\n```\nand maps to\n```json\n{\n \"Grid\": {\n \"x\": [1, 2, \"u\", 10],\n \"y\": [4, 5, \"l\", 100]\n },\n \"Time Integrator\": {\n \"CFL\": 0.001,\n \"tstop\": 1000.0\n }\n}\n```\nThe following section-less format doesn't comply to Pluto/Idefix's\nspecifications, but is also valid in `inifix`\n```ini\nmode fargo\n\n# Time integrator\nCFL 1e-3\ntstop 1e3\n```\nand maps to\n```json\n{\n \"mode\": \"fargo\",\n \"CFL\": 0.001,\n \"tstop\": 1000.0\n}\n```\nNote that strings using e-notation (e.g. `1e-3` or `1E3` here) are decoded as\nfloats. Reversely, when writing files, floats are re-encoded using e-notation\nif it leads to a more compact representation. For instance, `100000.0` is encoded\nas `1e5`, but `189.0` is left unchanged because `1.89e2` takes one more character.\nIn cases where both reprensations are equally compact (e.g. `1.0` VS `1e0`),\ndecimal is preferred in encoding.\n\nWhile decoding, `e` can be lower or upper case, but they are always encoded as\nlower case.\n</details>\n\n## Installation\n\n```shell\npython -m pip install inifix\n```\n\n## Usage\n\nThe public API mimics that of Python's standard library `json`,\nand consists in four main functions:\n- `inifix.load` and `inifix.dump` read from and write to files respectively\n- `inifix.loads` reads from a `str` and returns a `dict`, while `inifix.dumps`\n does the reverse operation.\n\n### Reading data\n`inifix.load` reads from a file and returns a `dict`\n\n```python\nimport inifix\n\nwith open(\"pluto.ini\", \"rb\") as fh:\n conf = inifix.load(fh)\n\n# or equivalently\nconf = inifix.load(\"pluto.ini\")\n```\nFiles are assumed to be encoded as UTF-8.\n\n#### Parsing options\n\n`inifix.load` and `inifix.loads` accept an optional boolean flag\n`parse_scalars_as_lists` (new in `inifix` v4.0.0), that is useful to simplify\nhandling unknown data: all values can be safely treated as arrays, and iterated\nover, even in the presence of scalar strings. For illustration\n\n```python\n>>> import inifix\n>>> from pprint import pprint\n>>> pprint(inifix.load(\"example.ini\"))\n{'Grid': {'x': [1, 2, 'u', 10], 'y': [4, 5, 'l', 100]},\n 'Time Integrator': {'CFL': 0.001, 'tstop': 1000.0}}\n>>> pprint(inifix.load(\"example.ini\", parse_scalars_as_lists=True))\n{'Grid': {'x': [1, 2, 'u', 10], 'y': [4, 5, 'l', 100]},\n 'Time Integrator': {'CFL': [0.001], 'tstop': [1000.0]}}\n```\n\n`inifix.load` and `inifix.loads` also accept an `integer_casting` argument (new\nin `inifix` v5.0.0), which can be set to decide how numbers written in decimal\nnotation which happen to have integral values (e.g. `1e2` or `30000.`) should be\nparsed.\nThis argument accepts two values:\n`'stable'` (default) gives `float`s while `'aggressive'` gives `int`s,\nmatching the behavior of `inifix` v4.5.0.\n\nThe key difference is that the default strategy is roundtrip-stable on types,\nwhile the aggressive mode isn't:\n```python\n>>> import inifix\n>>> data = {'option_a': [0, 1., 2e3, 4.5]}\n>>> data\n{'option_a': [0, 1.0, 2000.0, 4.5]}\n>>> inifix.loads(inifix.dumps(data))\n{'option_a': [0, 1.0, 2000.0, 4.5]}\n>>> inifix.loads(inifix.dumps(data), integer_casting='aggressive')\n{'option_a': [0, 1, 2000, 4.5]}\n```\n\nAggressive casting may also lead to loss of precision beyond a certain range\n```python\n>>> import inifix\n>>> data = {'option_b': 9_007_199_254_740_993}\n>>> inifix.loads(inifix.dumps(data))\n{'option_b': 9007199254740993}\n>>> inifix.loads(inifix.dumps(data), integer_casting='aggressive')\n{'option_b': 9007199254740992}\n```\n\nBy default, `inifix.load` and `inifix.loads` validate input data, see\n[Schema Validation](#schema-validation) for details.\nAlso see [Type Checking](#type-checking) for how `parse_scalars_as_lists` affects\ntype checking.\n\n\n### Writing to a file or a string\n\n`inifix.dump` writes data to a file.\n\nOne typical use case is to combine `inifix.load` and `inifix.dump` to\nprogrammatically update an existing configuration file at runtime via a\nload/patch/dump routine.\n```python\n>>> import inifix\n>>> with open(\"pluto.ini\", \"rb\") as fr:\n... inifix.load(fr)\n>>> conf[\"Time\"][\"CFL\"] = 0.1\n>>> with open(\"pluto-mod.ini\", \"wb\") as fw:\n... inifix.dump(conf, fw)\n```\nor, equivalently\n```python\n>>> import inifix\n>>> inifix.load(\"pluto.ini\")\n>>> conf[\"Time\"][\"CFL\"] = 0.1\n>>> inifix.dump(conf, \"pluto-mod.ini\")\n```\nData will be validated against inifix's format specification at write time.\nFiles are always encoded as UTF-8.\n\n`inifix.dumps` is the same as `inifix.dump` except that it returns a string\ninstead of writing to a file.\n```python\n>>> import inifix\n>>> data = {\"option_a\": 1, \"option_b\": True}\n>>> print(inifix.dumps(data))\noption_a 1\noption_b True\n\n```\n\nBy default, `inifix.dump` and `inifix.dumps` validate input data, see\n[Schema Validation](#schema-validation) for details.\n\n\n### Schema Validation\n\nBy default, I/O functions (`inifix.dump`, `inifix.dumps`, `inifix.load` and\n`inifix.loads`) all validate that output/input data structures conform to the\nlibrary's specification:\n- readers (`inifix.load` and `inifix.loads`) validate data post parsing,\n and before returning\n- writers (`inifix.dump` and `inifix.dumps`) validate input data before writing\n to their respective output channels\n\nIn case the data is invalid, a `ValueError` is raised.\nThis behavior can be turned off by passing `skip_validation=True`.\n\nAdditionally, all four functions support a `sections` argument (new in `inifix`\nv5.1.0), which controls\nwhether sections (starting with headers, e.g., `[MySection]`) are allowed\n(`sections='allow'`, default), forbidden (`sections='forbid'`), or required\n(`sections='require'`) at validation.\nThis argument does not have any effect at runtime if combined with `skip_validation=True`.\nHowever, it will affect the return type of readers, as seen by typecheckers (e.g. `mypy`\nor `pyright`), regardless if validation is enabled, see [Type Checking](#type-checking)\n\n`inifix.validate_inifile_schema` can also be used directly and supports the\n`sections` argument.\n\n\n### Runtime formatting\n\n`inifix.format_string` formats a string representing the contents of an ini file.\nSee [Formatting CLI](#formatting-cli) for how to use this at scale.\n\n### Type Checking\n\n### Narrowing return type of readers\n\nReaders (`inifix.load` and `inifix.loads`) support a diversity of input and output\nformats such that their default return type, while technically correct, is too broad\nto be really useful in a type checking context. However, passing\n`parse_scalars_as_list=True`, `sections='forbid'` or `sections='require'` can\nnarrow the return type, as seen by a typechecker (e.g. `mypy` or `pyright`).\nNote that this effect is intentionally not disabled with `skip_validation=True`,\neventhough the `sections` argument's runtime effect *is* disabled; such a\ncombination allows to get both optimal runtime performance and type-consistency.\nHowever, `skip_validation=True` may create situations where your code type-checks\nbut fails at runtime, so this option is only meant to be used if validation is\nknown to cause a performance bottleneck or a crash in your application. If such\na situation occurs, please report it !\n\n#### Writing type-safe applications of `inifix.load(s)`\n\n`inifix.load` has no built-in expectations on the type of any specific parameter;\ninstead, all types are inferred at runtime, which allows the function to work\nseamlessly with arbitrary parameter files.\n\nHowever, this also means that the output is not (and cannot be) perfectly type-safe.\nIn other words, type checkers (e.g. `mypy`) cannot infer exact types of outputs,\nwhich is a problem in applications relying on type-checking.\n\nA solution to this problem, which is actually not specific to `inifix.load` and\nworks with any arbitrarily formed `dict`, is to create a pipeline around this data\nwhich implements type-checkable code, where data is *also* validated at runtime.\n\nWe'll illustrate this with a real-life example inspired from\n[`nonos`](https://pypi.org/project/nonos).\nSay, for instance, that we only care about a couple parameters from the `[Output]`\nand `[Hydro]` sections of `idefix.ini`. Let's build a type-safe `read_parameter_file`\nfunction around these.\n\n```python\nclass IdefixIni:\n def __init__(self, *, Hydro, Output, **kwargs):\n self.hydro = IdefixIniHydro(**Hydro)\n self.output = IdefixIniOutput(**Output)\n\nclass IdefixIniHydro:\n def __init__(self, **kwargs):\n if \"rotation\" in kwargs:\n self.frame = \"COROT\"\n self.rotation = float(kwargs[\"rotation\"])\n else:\n self.frame = \"UNSET\"\n self.rotation = 0.0\n\nclass IdefixIniOutput:\n def __init__(self, *, vtk, **kwargs):\n self.vtk = float(vtk)\n\ndef read_parameter_file(file) -> IdefixIni:\n return IdefixIni(**inifix.load(file))\n\nini = read_parameter_file(\"idefix.ini\")\n```\n\nType checkers can now safely assume that, `ini.hydro.frame`, `ini.hydro.rotation`\nand `ini.output.vtk` all exist and are of type `str`, `float` and `float`, respectively.\nIf this assumption is not verified at runtime, a `TypeError` will be raised.\n\nNote that we've used the catch-all `**kwargs` construct to capture optional\nparameters as well as any other parameters present (possibly none) that we do not\ncare about.\n\n### CLI\n\nCommand line tools are shipped with the package to validate or format compatible\ninifiles.\n\n#### Validation CLI\n\nThis checks that your inifiles can be loaded with `inifix.load` from the command line\n```shell\n$ inifix-validate pluto.ini\nValidated pluto.ini\n```\nThis CLI can also be called as `python -m inifix.validate`.\n\n\n#### Formatting CLI\n\nTo format a file in place, use\n```shell\n$ inifix-format pluto.ini\n```\ninifix-format is guaranteed to preserve comments and to *only* edit (add or remove)\nwhitespace characters.\n\nFiles are always encoded as UTF-8.\n\nTo print a diff patch to stdout instead of editing the file, use the `--diff` flag\n```shell\n$ inifix-format pluto.ini --diff\n```\nThis CLI can also be called as `python -m inifix.format`.\n\nBy default, `inifix-format` also validates input data. This step can be skipped with the\n`--skip-validation` flag\n\n### pre-commit hooks\n\n`inifix-validate` and `inifix-format` can be used as `pre-commit` hooks with the\nfollowing configuration (add to `.pre-commit-config.yaml`)\n\n```yaml\n - repo: https://github.com/neutrinoceros/inifix.git\n rev: v5.1.2\n hooks:\n - id: inifix-validate\n```\nor\n```yaml\n - repo: https://github.com/neutrinoceros/inifix.git\n rev: v5.1.2\n hooks:\n - id: inifix-format\n```\n\nNote that `inifix-format` also validates data by default, so it is redundant to\nutilize both hooks. Validation and formatting may nonetheless be decoupled as\n```patch\n - repo: https://github.com/neutrinoceros/inifix.git\n rev: v5.1.2\n hooks:\n - id: inifix-validate\n - id: inifix-format\n+ args: [--skip-validation]\n```\n\nBy default, both hooks target files matching the regular expression `(\\.ini)$`.\nIt is possible to override this expression as, e.g.,\n```patch\n hooks:\n - id: inifix-format\n+ files: (\\.ini|\\.par)$\n```\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "An I/O library for Pluto-style ini files.",
"version": "5.1.2",
"project_urls": {
"Changelog": "https://github.com/neutrinoceros/inifix/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/neutrinoceros/inifix"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ed2015ff14cf4bb3cfca255f70735aa8be376f7b0c2ca9e127eb291b4cd194c5",
"md5": "7e8ec54595bf533b8b0d67d6dec71fbc",
"sha256": "2e2bb90105c731a5eaae5c70893b575320c013f66848176248a5d511db541e6d"
},
"downloads": -1,
"filename": "inifix-5.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7e8ec54595bf533b8b0d67d6dec71fbc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 32163,
"upload_time": "2024-12-16T10:33:40",
"upload_time_iso_8601": "2024-12-16T10:33:40.139971Z",
"url": "https://files.pythonhosted.org/packages/ed/20/15ff14cf4bb3cfca255f70735aa8be376f7b0c2ca9e127eb291b4cd194c5/inifix-5.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8e7eb1a9f3e5770d5b7d70edde8d4c2f9a70678f9c8fac8027dbd7eb8df47e00",
"md5": "fb3a41e233f00744abf45fd63bdaba63",
"sha256": "47d23b58521fb94da31be0f532d51993250e57162dad8c67c6c6b592662c5668"
},
"downloads": -1,
"filename": "inifix-5.1.2.tar.gz",
"has_sig": false,
"md5_digest": "fb3a41e233f00744abf45fd63bdaba63",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 42486,
"upload_time": "2024-12-16T10:33:42",
"upload_time_iso_8601": "2024-12-16T10:33:42.564982Z",
"url": "https://files.pythonhosted.org/packages/8e/7e/b1a9f3e5770d5b7d70edde8d4c2f9a70678f9c8fac8027dbd7eb8df47e00/inifix-5.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 10:33:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "neutrinoceros",
"github_project": "inifix",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "inifix"
}
