# lenient-string-formatter
A lenient string formatter that leaves unmatched fields untouched in the output string instead of raising exceptions.
The following exceptions that are normally raised by the built-in string formatter are caught and handled as follows:
- KeyError and IndexError will not be raised if a field in the template is not matched by the arguments. Instead, the field will be left untouched in the output string.
- ValueError in case numbered and auto-numbered fields are mixed in the template (e.g. "{1} {}") will not be raised. Explicitly numbered fields will be matched according to their index (remaining untouched if the index is out of bounds), while auto-numbered fields will be matched according to their order in the arguments (again, remaining untouched if the index is out of bounds) independent of the explicit numbering.
- KeyError is not raised on unnumbered field with key/attribute access. (https://bugs.python.org/issue27307)
## Installation
You can install this package with pip.
```sh
$ pip install lenient-string-formatter
```
## Links
[](https://abrahammurciano.github.io/python-lenient-string-formatter)
[](https://github.com/abrahammurciano/python-lenient-string-formatter.git)
[](https://pypi.org/project/lenient-string-formatter/)
## Usage
This package provides a function called `lformat` that you can use to format strings in a lenient way. You can use it in the same way as you would use Python's built-in `str.format` method.
This package also provides the `LenientFormatter` class, a subclass of Python's built-in `string.Formatter`. It is used internally by the `lformat` function, but it can be used directly or subclassed if you need more control over the formatting process.
The examples below will use the `lformat` function. `LenientFormatter().format` can be used in the same way.
### Basic example
```python
from lenient_string_formatter import lformat
template = "{} {} {a} {b}"
formatted = lformat(template, 1, 2, a=3, b=4)
assert formatted == "1 2 3 4"
```
### Unmatched fields
Unmatched fields are left untouched instead of raising exceptions.
```python
template = "{} {} {a} {b}"
formatted = lformat(template, 1, a=3)
assert formatted == "1 {} 3 {b}"
```
### Mixing numbered and auto-numbered fields
Explicitly numbered fields are matched according to their index, while auto-numbered fields are matched according to their order in the arguments. They are matched independently of each other.
```python
template = "{1} {}"
formatted = lformat(template, 1, 2)
assert formatted == "2 1"
```
### Unnumbered field with key/attribute access
The built-in formatter raises a KeyError when an unnumbered field is used with key/attribute access. This is a bug in the built-in formatter (https://bugs.python.org/issue27307). This implementation doesn't have this bug.
```python
from types import SimpleNamespace
template = "{.attr} {[0]}"
formatted = lformat(template, SimpleNamespace(attr=1), [2])
assert formatted == "1 2"
```
### Format specifiers and conversion flags for unmatched fields
Unmatched fields are left untouched. This includes any format specifiers and conversion flags that are applied to the field. Furthermore, if the field is matched but the format specifier has a field which is unmatched, or vice versa, the field is still left untouched.
For example, below `{a:3}` and `{b!r}` have no matching values, and neither `c=3` nor `f=4` provide enough values to completely fill the fields `{c:{d}}` and `{e:{f}}`, so all fields are left untouched.
```python
template = "{a:3} {b!r} {c:{d}} {e:{f}}"
formatted = lformat(template, c=3, f=4)
assert formatted == template
```
Raw data
{
"_id": null,
"home_page": "https://github.com/abrahammurciano/python-lenient-string-formatter",
"name": "lenient-string-formatter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Abraham Murciano",
"author_email": "abrahammurciano@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/83/72/75c11f8d515844d90c7610fe4eaa1b8688fb334d5453f3da10a15db8bb9f/lenient_string_formatter-1.1.2.tar.gz",
"platform": null,
"description": "# lenient-string-formatter\n\nA lenient string formatter that leaves unmatched fields untouched in the output string instead of raising exceptions.\n\nThe following exceptions that are normally raised by the built-in string formatter are caught and handled as follows:\n\n- KeyError and IndexError will not be raised if a field in the template is not matched by the arguments. Instead, the field will be left untouched in the output string.\n- ValueError in case numbered and auto-numbered fields are mixed in the template (e.g. \"{1} {}\") will not be raised. Explicitly numbered fields will be matched according to their index (remaining untouched if the index is out of bounds), while auto-numbered fields will be matched according to their order in the arguments (again, remaining untouched if the index is out of bounds) independent of the explicit numbering.\n- KeyError is not raised on unnumbered field with key/attribute access. (https://bugs.python.org/issue27307)\n\n## Installation\n\nYou can install this package with pip.\n```sh\n$ pip install lenient-string-formatter\n```\n\n## Links\n\n[](https://abrahammurciano.github.io/python-lenient-string-formatter)\n\n[](https://github.com/abrahammurciano/python-lenient-string-formatter.git)\n\n[](https://pypi.org/project/lenient-string-formatter/)\n\n## Usage\n\nThis package provides a function called `lformat` that you can use to format strings in a lenient way. You can use it in the same way as you would use Python's built-in `str.format` method.\n\nThis package also provides the `LenientFormatter` class, a subclass of Python's built-in `string.Formatter`. It is used internally by the `lformat` function, but it can be used directly or subclassed if you need more control over the formatting process.\n\nThe examples below will use the `lformat` function. `LenientFormatter().format` can be used in the same way.\n\n### Basic example\n\n```python\nfrom lenient_string_formatter import lformat\n\ntemplate = \"{} {} {a} {b}\"\nformatted = lformat(template, 1, 2, a=3, b=4)\nassert formatted == \"1 2 3 4\"\n```\n\n### Unmatched fields\n\nUnmatched fields are left untouched instead of raising exceptions.\n\n```python\ntemplate = \"{} {} {a} {b}\"\nformatted = lformat(template, 1, a=3)\nassert formatted == \"1 {} 3 {b}\"\n```\n\n### Mixing numbered and auto-numbered fields\n\nExplicitly numbered fields are matched according to their index, while auto-numbered fields are matched according to their order in the arguments. They are matched independently of each other.\n\n```python\ntemplate = \"{1} {}\"\nformatted = lformat(template, 1, 2)\nassert formatted == \"2 1\"\n```\n\n### Unnumbered field with key/attribute access\n\nThe built-in formatter raises a KeyError when an unnumbered field is used with key/attribute access. This is a bug in the built-in formatter (https://bugs.python.org/issue27307). This implementation doesn't have this bug.\n\n```python\nfrom types import SimpleNamespace\n\ntemplate = \"{.attr} {[0]}\"\nformatted = lformat(template, SimpleNamespace(attr=1), [2])\nassert formatted == \"1 2\"\n```\n\n### Format specifiers and conversion flags for unmatched fields\n\nUnmatched fields are left untouched. This includes any format specifiers and conversion flags that are applied to the field. Furthermore, if the field is matched but the format specifier has a field which is unmatched, or vice versa, the field is still left untouched.\n\nFor example, below `{a:3}` and `{b!r}` have no matching values, and neither `c=3` nor `f=4` provide enough values to completely fill the fields `{c:{d}}` and `{e:{f}}`, so all fields are left untouched.\n\n```python\ntemplate = \"{a:3} {b!r} {c:{d}} {e:{f}}\"\nformatted = lformat(template, c=3, f=4)\nassert formatted == template\n```",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A lenient string formatter that leaves unmatched fields untouched in the output string instead of raising a KeyError.",
"version": "1.1.2",
"project_urls": {
"Documentation": "https://abrahammurciano.github.io/python-lenient-string-formatter/lenient-string-formatter",
"Homepage": "https://github.com/abrahammurciano/python-lenient-string-formatter",
"Repository": "https://github.com/abrahammurciano/python-lenient-string-formatter"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a95af53287c3711136599ab0c23f0c7be63cb62fd3bcce02c30e6b30712af4b3",
"md5": "cc8378969334f414a306c4f07b607f4e",
"sha256": "4f962e725ac67b0afd4b9631cd35b7b4a336549d77e60e264ee26e9ca9a8855f"
},
"downloads": -1,
"filename": "lenient_string_formatter-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc8378969334f414a306c4f07b607f4e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 17627,
"upload_time": "2024-05-22T08:51:39",
"upload_time_iso_8601": "2024-05-22T08:51:39.571676Z",
"url": "https://files.pythonhosted.org/packages/a9/5a/f53287c3711136599ab0c23f0c7be63cb62fd3bcce02c30e6b30712af4b3/lenient_string_formatter-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "837275c11f8d515844d90c7610fe4eaa1b8688fb334d5453f3da10a15db8bb9f",
"md5": "c2c881bcdf185bfcb35929899c6f5a97",
"sha256": "6629d3ad67341d09d5d05ebd3c98087c84f89298f8199b9588cd31ea9d47de0f"
},
"downloads": -1,
"filename": "lenient_string_formatter-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "c2c881bcdf185bfcb35929899c6f5a97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 15885,
"upload_time": "2024-05-22T08:51:40",
"upload_time_iso_8601": "2024-05-22T08:51:40.551295Z",
"url": "https://files.pythonhosted.org/packages/83/72/75c11f8d515844d90c7610fe4eaa1b8688fb334d5453f3da10a15db8bb9f/lenient_string_formatter-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-22 08:51:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abrahammurciano",
"github_project": "python-lenient-string-formatter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lenient-string-formatter"
}
JSON
