imperfect


Nameimperfect JSON
Version 0.3.0 PyPI version JSON
download
home_pagehttps://github.com/thatch/imperfect/
SummaryA CST-based config editor for configparser
upload_time2020-03-13 13:54:56
maintainer
docs_urlNone
authorTim Hatch
requires_python>=3.6
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Imperfect

This is a module for making automated edits to an existing
configparser-compatible ini file.  It operates like a CST, parsing into a tree
of nodes which can then be edited and written back, preserving whitespace and
comments.

# Quick Start

(Tested as `test_example_from_readme` in the test suite)

Let's say you have the following in `setup.cfg`:

```ini
[metadata]
# the package name
name = imperfect
# slurp the readme
long_description = file: README.md

[options]
packages = imperfect
```

and you'd like to make an edit setting `long_description_content_type` in
`[metadata]` but don't care where it goes.  Default is at the end.

```py
import difflib
import imperfect
import io
with open("setup.cfg") as f:
    data = f.read()

conf: imperfect.ConfigFile = imperfect.parse_string(data)
conf.set_value("metadata", "long_description_content_type", "text/markdown")

print(conf.text)
```

What if you want to have control over the odering, and want it right after
`long_description`?  Now with diffing and more internals...

```py
import difflib
import imperfect
import io
with open("setup.cfg") as f:
    data = f.read()

conf: imperfect.ConfigFile = imperfect.parse_string(data)
metadata_section = conf["metadata"]

# Ignoring some whitespace for now, this looks like
# long_description_content_type =  text/markdown\n
# [                   entry                      ]
# [            key            ][eq][    value    ]

value = imperfect.ValueLine(
    whitespace_before_text='',
    text='text/markdown',
    whitespace_after_text='',
    newline='\n',
)
new_entry = imperfect.ConfigEntry(
    key="long_description_content_type",
    equals="=",
    value = [value],
    whitespace_before_equals=" ",
    whitespace_before_value="  ",
)
for i, entry in enumerate(metadata_section.entries):
    if entry.key == "long_description":
        metadata_section.entries.insert(i+1, new_entry)
        break

print(moreorless.unified_diff(data, conf.text, "config.cfg", end=""))
with open("setup.cfg", "w") as f:
    f.write(conf.text)
# or
with open("setup.cfg", "w") as f:
    conf.build(f)
```


# A note on whitespace

Following the convention used by configobj, whitespace generally is accumulated
and stored on the node that follows it.  This does reasonably well for adding
entries, but can have unexpected consequences when removing them.  For example,

```ini
[section1]
# this belongs to k1
k1 = foo
# this belongs to k2
k2 = foo
# k3 = foo (actually belongs to the following section)

[section2]
```

An insertion to the end of `section1` would go between k2 and the k3 comment.
Removing `section2` would also remove the commented-out `k3`.

I'm open to ideas that improve this.


# A note on formats

The goal is to be as compatible as possible with `RawConfigParser`, which
includes keeping some odd behaviors that are bugs that have been around for a
decade and probably can't be changed now.

1. Section names are very lenient.  `[[x]]yy` is a legal section line, and the
   resulting section name is `[x`.  The `yy` here is always allowed (we keep it
   in the tree though), even with `inline_comments` off.
2. `\r` (carriage return) is considered a whitespace, but not a line terminator.
   This is a difference in behavior between `str.splitlines(True)` and
   `list(io)` -- configparser uses the latter.
3. `\t` counts as single whitespace.


# Supported parse options

```
Option                 Default  Imperfect supports
allow_no_value         False    only False
delimiters             =,:      only =,:
comment_prefixes       #,;      only #,;
empty_lines_in_values  True     True (False is very close to working)
```


# Testing

We use hypothesis to generate plausible ini files and for all the ones that
RawConfigParser can accept, we test that we accept, have the same keys/values,
and can roundtrip it.

This currently happens in text mode only.

If you would like to test support on your file, try `python -m imperfect.verify <filename>`


# Why not...

* `configobj` has a completely different method for line continuations
* I'm not aware of others with the goal of preserving whitespace


# License

Imperfect is copyright [Tim Hatch](http://timhatch.com/), and licensed under
the MIT license.  I am providing code in this repository to you under an open
source license.  This is my personal repository; the license you receive to
my code is from me and not from my employer. See the `LICENSE` file for details.



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/thatch/imperfect/",
    "name": "imperfect",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "",
    "keywords": "",
    "author": "Tim Hatch",
    "author_email": "tim@timhatch.com",
    "download_url": "https://files.pythonhosted.org/packages/ca/33/a768bd7628a30d729d656739db5d8b92542de5bb596c9150c37d8a561c42/imperfect-0.3.0.tar.gz",
    "platform": "",
    "description": "# Imperfect\n\nThis is a module for making automated edits to an existing\nconfigparser-compatible ini file.  It operates like a CST, parsing into a tree\nof nodes which can then be edited and written back, preserving whitespace and\ncomments.\n\n# Quick Start\n\n(Tested as `test_example_from_readme` in the test suite)\n\nLet's say you have the following in `setup.cfg`:\n\n```ini\n[metadata]\n# the package name\nname = imperfect\n# slurp the readme\nlong_description = file: README.md\n\n[options]\npackages = imperfect\n```\n\nand you'd like to make an edit setting `long_description_content_type` in\n`[metadata]` but don't care where it goes.  Default is at the end.\n\n```py\nimport difflib\nimport imperfect\nimport io\nwith open(\"setup.cfg\") as f:\n    data = f.read()\n\nconf: imperfect.ConfigFile = imperfect.parse_string(data)\nconf.set_value(\"metadata\", \"long_description_content_type\", \"text/markdown\")\n\nprint(conf.text)\n```\n\nWhat if you want to have control over the odering, and want it right after\n`long_description`?  Now with diffing and more internals...\n\n```py\nimport difflib\nimport imperfect\nimport io\nwith open(\"setup.cfg\") as f:\n    data = f.read()\n\nconf: imperfect.ConfigFile = imperfect.parse_string(data)\nmetadata_section = conf[\"metadata\"]\n\n# Ignoring some whitespace for now, this looks like\n# long_description_content_type =  text/markdown\\n\n# [                   entry                      ]\n# [            key            ][eq][    value    ]\n\nvalue = imperfect.ValueLine(\n    whitespace_before_text='',\n    text='text/markdown',\n    whitespace_after_text='',\n    newline='\\n',\n)\nnew_entry = imperfect.ConfigEntry(\n    key=\"long_description_content_type\",\n    equals=\"=\",\n    value = [value],\n    whitespace_before_equals=\" \",\n    whitespace_before_value=\"  \",\n)\nfor i, entry in enumerate(metadata_section.entries):\n    if entry.key == \"long_description\":\n        metadata_section.entries.insert(i+1, new_entry)\n        break\n\nprint(moreorless.unified_diff(data, conf.text, \"config.cfg\", end=\"\"))\nwith open(\"setup.cfg\", \"w\") as f:\n    f.write(conf.text)\n# or\nwith open(\"setup.cfg\", \"w\") as f:\n    conf.build(f)\n```\n\n\n# A note on whitespace\n\nFollowing the convention used by configobj, whitespace generally is accumulated\nand stored on the node that follows it.  This does reasonably well for adding\nentries, but can have unexpected consequences when removing them.  For example,\n\n```ini\n[section1]\n# this belongs to k1\nk1 = foo\n# this belongs to k2\nk2 = foo\n# k3 = foo (actually belongs to the following section)\n\n[section2]\n```\n\nAn insertion to the end of `section1` would go between k2 and the k3 comment.\nRemoving `section2` would also remove the commented-out `k3`.\n\nI'm open to ideas that improve this.\n\n\n# A note on formats\n\nThe goal is to be as compatible as possible with `RawConfigParser`, which\nincludes keeping some odd behaviors that are bugs that have been around for a\ndecade and probably can't be changed now.\n\n1. Section names are very lenient.  `[[x]]yy` is a legal section line, and the\n   resulting section name is `[x`.  The `yy` here is always allowed (we keep it\n   in the tree though), even with `inline_comments` off.\n2. `\\r` (carriage return) is considered a whitespace, but not a line terminator.\n   This is a difference in behavior between `str.splitlines(True)` and\n   `list(io)` -- configparser uses the latter.\n3. `\\t` counts as single whitespace.\n\n\n# Supported parse options\n\n```\nOption                 Default  Imperfect supports\nallow_no_value         False    only False\ndelimiters             =,:      only =,:\ncomment_prefixes       #,;      only #,;\nempty_lines_in_values  True     True (False is very close to working)\n```\n\n\n# Testing\n\nWe use hypothesis to generate plausible ini files and for all the ones that\nRawConfigParser can accept, we test that we accept, have the same keys/values,\nand can roundtrip it.\n\nThis currently happens in text mode only.\n\nIf you would like to test support on your file, try `python -m imperfect.verify <filename>`\n\n\n# Why not...\n\n* `configobj` has a completely different method for line continuations\n* I'm not aware of others with the goal of preserving whitespace\n\n\n# License\n\nImperfect is copyright [Tim Hatch](http://timhatch.com/), and licensed under\nthe MIT license.  I am providing code in this repository to you under an open\nsource license.  This is my personal repository; the license you receive to\nmy code is from me and not from my employer. See the `LICENSE` file for details.\n\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A CST-based config editor for configparser",
    "version": "0.3.0",
    "project_urls": {
        "Homepage": "https://github.com/thatch/imperfect/"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "adc1469cc0d9ac261c1c98620d65bed23c69565696963562fd14f1583a116b9b",
                "md5": "82c1644e20c48458041bb3f15da398a3",
                "sha256": "212bfbfc435746e64d437e75542416a426c08c78bcd6b1cdb10ef1e5c5a16fce"
            },
            "downloads": -1,
            "filename": "imperfect-0.3.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "82c1644e20c48458041bb3f15da398a3",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 13361,
            "upload_time": "2020-03-13T13:54:55",
            "upload_time_iso_8601": "2020-03-13T13:54:55.415231Z",
            "url": "https://files.pythonhosted.org/packages/ad/c1/469cc0d9ac261c1c98620d65bed23c69565696963562fd14f1583a116b9b/imperfect-0.3.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "ca33a768bd7628a30d729d656739db5d8b92542de5bb596c9150c37d8a561c42",
                "md5": "11b71151fafd103874c803205f23a1f2",
                "sha256": "c7d89d9d0c2d8f6ea2b8e7ae3e5ebf3410ea1f092cfdc18355c21af483e7b5c9"
            },
            "downloads": -1,
            "filename": "imperfect-0.3.0.tar.gz",
            "has_sig": false,
            "md5_digest": "11b71151fafd103874c803205f23a1f2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 16004,
            "upload_time": "2020-03-13T13:54:56",
            "upload_time_iso_8601": "2020-03-13T13:54:56.661053Z",
            "url": "https://files.pythonhosted.org/packages/ca/33/a768bd7628a30d729d656739db5d8b92542de5bb596c9150c37d8a561c42/imperfect-0.3.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2020-03-13 13:54:56",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "thatch",
    "github_project": "imperfect",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [],
    "lcname": "imperfect"
}
        
Elapsed time: 0.22489s