# Round Trip INI Parser
For reading and respectfully modifying INI files when dealing with software that still uses this format.
This library aims to be as flexible as possible when it comes to interpreting `ini` files.
## Why roundtripini?
There are already a number of existing ini libraries, including python's builtin configparser, but not only do most of these libraries not support round-trip-parsing, most of them also do not support duplicate sections and keys.
roundtripini simultaneously supports round trip parsing, handling duplicate keys by treating them as lists, and allowing sections to be defined multiple times (with each section being queried when reading values).
## Why INI?
Lots of software still uses this poorly-specified format. roundtripini is designed to help interface with such software.
If you want a library to read configuration files for the software itself, I would recommend instead using a file format which has a specification and consistent implementations in multiple languages and for multiple platforms, like [TOML](https://toml.io) or [YAML](https://yaml.org).
## Usage
```python
from roundtripini import INI
with open("file") as file:
ini = INI(file)
# Unlike configparser, ini takes a tuple, rather than returning a section when accessed with []
# This is necessary as multiple sections may exist in the file.
ini["section", "key"] = "value"
# Multiple values can be included as a list. Each one will be added with a separate key
ini["section", "key"] = ["value 1", "value 2"]
ini["section", "other key"] = "other value"
# When assigning values, single-element lists are equivalent to strings
ini["section", "other key"] = ["other value"]
assert ini.dump() == """[section]
key = value 1
key = value 2
other key = other value
"""
assert isinstance(ini["section", "key"], list)
assert isinstance(ini["section", "other key"], str)
with open("file", "w") as file:
file.write(ini.dump())
```
## Restrictions
- key/value pairs must be separated by =
- keys may not begin or end with whitespace
- values will have beginning or ending whitespace stripped when returned.
- Comments will only be ignored if they are on one line, but not
if they are on the same line as a key/value pair, where they will be treated as part of the value
## Implementation Notes
- Validation of key/value pairs occurs when data is used, not when the file is read.
- When replacing keys with duplicates, all old keys will be removed from all sections (in the
case of duplicate sections), and the new elements will be inserted in a single block at the
location of the first old key.
- Lists returned by the `[]` operator should not be modified, as the underlying data will not change.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/bmwinger/roundtripini",
"name": "roundtripini",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Benjamin Winger",
"author_email": "bmw@disroot.org",
"download_url": "https://files.pythonhosted.org/packages/05/2e/952a543d82d0c45ef4dcc3c7898e1dbaaa3a13a1cf11ac95c6cd5ce3ce30/roundtripini-0.4.0.tar.gz",
"platform": null,
"description": "# Round Trip INI Parser\n\nFor reading and respectfully modifying INI files when dealing with software that still uses this format.\n\nThis library aims to be as flexible as possible when it comes to interpreting `ini` files.\n\n## Why roundtripini?\n\nThere are already a number of existing ini libraries, including python's builtin configparser, but not only do most of these libraries not support round-trip-parsing, most of them also do not support duplicate sections and keys.\n\nroundtripini simultaneously supports round trip parsing, handling duplicate keys by treating them as lists, and allowing sections to be defined multiple times (with each section being queried when reading values).\n\n## Why INI?\n\nLots of software still uses this poorly-specified format. roundtripini is designed to help interface with such software.\n\nIf you want a library to read configuration files for the software itself, I would recommend instead using a file format which has a specification and consistent implementations in multiple languages and for multiple platforms, like [TOML](https://toml.io) or [YAML](https://yaml.org).\n\n## Usage\n\n```python\nfrom roundtripini import INI\n\nwith open(\"file\") as file:\n ini = INI(file)\n\n# Unlike configparser, ini takes a tuple, rather than returning a section when accessed with []\n# This is necessary as multiple sections may exist in the file.\nini[\"section\", \"key\"] = \"value\"\n# Multiple values can be included as a list. Each one will be added with a separate key\nini[\"section\", \"key\"] = [\"value 1\", \"value 2\"]\nini[\"section\", \"other key\"] = \"other value\"\n# When assigning values, single-element lists are equivalent to strings\nini[\"section\", \"other key\"] = [\"other value\"]\n\nassert ini.dump() == \"\"\"[section]\nkey = value 1\nkey = value 2\nother key = other value\n\"\"\"\n\nassert isinstance(ini[\"section\", \"key\"], list)\nassert isinstance(ini[\"section\", \"other key\"], str)\n\nwith open(\"file\", \"w\") as file:\n file.write(ini.dump())\n```\n\n## Restrictions\n\n- key/value pairs must be separated by =\n- keys may not begin or end with whitespace\n- values will have beginning or ending whitespace stripped when returned.\n- Comments will only be ignored if they are on one line, but not\n if they are on the same line as a key/value pair, where they will be treated as part of the value\n\n## Implementation Notes\n- Validation of key/value pairs occurs when data is used, not when the file is read.\n- When replacing keys with duplicates, all old keys will be removed from all sections (in the\n case of duplicate sections), and the new elements will be inserted in a single block at the\n location of the first old key.\n- Lists returned by the `[]` operator should not be modified, as the underlying data will not change.\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A round-trip parser for ini files",
"version": "0.4.0",
"project_urls": {
"Download": "https://gitlab.com/bmwinger/roundtripini/-/releases",
"Homepage": "https://gitlab.com/bmwinger/roundtripini"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4a9d8c7f74da95bf575a42f10bea78bd352d5589b0a79c4e48151ab7ed831659",
"md5": "58b49bb987f9c26c980bc9aeb6d5a783",
"sha256": "d7c9a1beb5cff2b2f6e16504a26a5484a142be6f327c18057b5645549049050d"
},
"downloads": -1,
"filename": "roundtripini-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "58b49bb987f9c26c980bc9aeb6d5a783",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 17977,
"upload_time": "2023-09-17T21:21:44",
"upload_time_iso_8601": "2023-09-17T21:21:44.430111Z",
"url": "https://files.pythonhosted.org/packages/4a/9d/8c7f74da95bf575a42f10bea78bd352d5589b0a79c4e48151ab7ed831659/roundtripini-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "052e952a543d82d0c45ef4dcc3c7898e1dbaaa3a13a1cf11ac95c6cd5ce3ce30",
"md5": "2d8e15ee04f5113a2c0b0b8ad5eaf847",
"sha256": "ec060e1a1723d8e797d838304dc5bb4f8c9322c2c8eac06ba009466ae5f26c1e"
},
"downloads": -1,
"filename": "roundtripini-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "2d8e15ee04f5113a2c0b0b8ad5eaf847",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 17679,
"upload_time": "2023-09-17T21:21:46",
"upload_time_iso_8601": "2023-09-17T21:21:46.154678Z",
"url": "https://files.pythonhosted.org/packages/05/2e/952a543d82d0c45ef4dcc3c7898e1dbaaa3a13a1cf11ac95c6cd5ce3ce30/roundtripini-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-17 21:21:46",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "bmwinger",
"gitlab_project": "roundtripini",
"lcname": "roundtripini"
}
JSON