# Varformat Library
Varformat can format and un-format (parse) strings containing various styles of variables.
```python
>>> import varformat as vf
>>> vf.format('Hi ${name}!', name='mom')
'Hi mom!'
>>> vf.parse('archive-${date}.tar.gz', 'archive-1970-01-01.tar.gz')
{'date': '1970-01-01'}
>>> from varformat.formats import python
>>> python.format('Classic {style}', style='python braces')
'Classic python braces'
>>> from varformat.formats import posix_shell as sh
>>> sh.format('POSIX compliant $style', style='dollar variables')
'POSIX compliant dollar variables'
```
## Getting Started
Varformat is available to install via pip:
```
pip install varformat
```
When installed, the modules `varformat` and `varformat.formats` will be available. Global functions `format`, `vformat`, and `parse` represent the default formmatter with a `${}` style:
```python
>>> import varformat as vf
>>> vf.format('my name ${name}', name='jeff')
'my name jeff'
```
If it is necessary to specify keys which are not valid python identifiers, such as numbers or string with spaces, you can use `vformat` instead:
```python
>>> import varformat as vf
>>> vf.vformat('My three favorite foods: ${1}, ${2}, and ${1} again',
... {'1': 'pizza', '2': 'chocolate'})
'My three favorite foods: pizza, chocolate, and pizza again'
```
`vformat` also supports keyword arguments to customize formatting behavior. `partial_ok` (default `False`) and `extra_ok` (default: `True`) control whether it is allowed to provide less (or more) arguments than the format string requires. `ambiguity_check` (default: `False`) will raise an error if your resulting string will be ambiguous:
```python
>>> import varformat as vf
>>> vf.vformat('package-${os}-${arch}', {'os': 'ubuntu-22.04', 'arch': 'amd64'}, ambiguity_check=True)
Traceback (most recent call last):
...
varformat.AmbiguityError: refusing to format because parsing would be ambiguous:
could be: {'os': 'ubuntu-22.04', 'arch': 'amd64'}
or: {'os': 'ubuntu', 'arch': '22.04-amd64'}
```
The `parse` function, which performs the inverse of `vformat`, also supports `ambiguity_check` (default: `True`):
```python
>>> import varformat as vf
>>> vf.parse('package-${os}-${arch}', 'package-ubuntu-22.04-amd64')
Traceback (most recent call last):
...
varformat.AmbiguityError: parsing is ambiguous:
could be: {'os': 'ubuntu-22.04', 'arch': 'amd64'}
or: {'os': 'ubuntu', 'arch': '22.04-amd64'}
```
You can of course set `ambiguity_check` to `False`, and `parse` will parse using the regular expression rules (greedily).
### Other formatters
Module `varformat.formats` contains formatters with other syntaxes:
- `varformat.formats.posix_shell` follows POSIX shell variable rules: it disallows numeric identifiers, identifiers with spaces, but allows referencing variables like `$var` in addition to `${var}`;
- `varformat.formats.python` follows classic python format string rules (e.g. `{var}`).
You can define your own formatter with your own custom syntax by subclassing either `varformat.RegexFormatter` and defining a regular expression that detects placeholders, or `varformat.AbstractFormatter` and defining a parsing function. See class docstrings for more information.
Raw data
{
"_id": null,
"home_page": null,
"name": "varformat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "string, interpolation, variable, shell, format, parse",
"author": "Anna Zhukova",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9f/1a/84a29903bf1256315f0c902c11739ffa6d064c94af18f40f84832afe7640/varformat-1.0.0.tar.gz",
"platform": null,
"description": "# Varformat Library\nVarformat can format and un-format (parse) strings containing various styles of variables.\n```python\n>>> import varformat as vf\n>>> vf.format('Hi ${name}!', name='mom')\n'Hi mom!'\n>>> vf.parse('archive-${date}.tar.gz', 'archive-1970-01-01.tar.gz')\n{'date': '1970-01-01'}\n\n>>> from varformat.formats import python\n>>> python.format('Classic {style}', style='python braces')\n'Classic python braces'\n\n>>> from varformat.formats import posix_shell as sh\n>>> sh.format('POSIX compliant $style', style='dollar variables')\n'POSIX compliant dollar variables'\n\n```\n\n## Getting Started\nVarformat is available to install via pip:\n```\npip install varformat\n```\n\nWhen installed, the modules `varformat` and `varformat.formats` will be available. Global functions `format`, `vformat`, and `parse` represent the default formmatter with a `${}` style:\n```python\n>>> import varformat as vf\n>>> vf.format('my name ${name}', name='jeff')\n'my name jeff'\n\n```\n\nIf it is necessary to specify keys which are not valid python identifiers, such as numbers or string with spaces, you can use `vformat` instead:\n```python\n>>> import varformat as vf\n>>> vf.vformat('My three favorite foods: ${1}, ${2}, and ${1} again',\n... {'1': 'pizza', '2': 'chocolate'})\n'My three favorite foods: pizza, chocolate, and pizza again'\n\n```\n\n`vformat` also supports keyword arguments to customize formatting behavior. `partial_ok` (default `False`) and `extra_ok` (default: `True`) control whether it is allowed to provide less (or more) arguments than the format string requires. `ambiguity_check` (default: `False`) will raise an error if your resulting string will be ambiguous:\n```python\n>>> import varformat as vf\n>>> vf.vformat('package-${os}-${arch}', {'os': 'ubuntu-22.04', 'arch': 'amd64'}, ambiguity_check=True)\nTraceback (most recent call last):\n ...\nvarformat.AmbiguityError: refusing to format because parsing would be ambiguous:\n could be: {'os': 'ubuntu-22.04', 'arch': 'amd64'}\n or: {'os': 'ubuntu', 'arch': '22.04-amd64'}\n\n```\n\nThe `parse` function, which performs the inverse of `vformat`, also supports `ambiguity_check` (default: `True`):\n```python\n>>> import varformat as vf\n>>> vf.parse('package-${os}-${arch}', 'package-ubuntu-22.04-amd64')\nTraceback (most recent call last):\n ...\nvarformat.AmbiguityError: parsing is ambiguous:\n could be: {'os': 'ubuntu-22.04', 'arch': 'amd64'}\n or: {'os': 'ubuntu', 'arch': '22.04-amd64'}\n\n```\n\nYou can of course set `ambiguity_check` to `False`, and `parse` will parse using the regular expression rules (greedily).\n\n### Other formatters\nModule `varformat.formats` contains formatters with other syntaxes:\n- `varformat.formats.posix_shell` follows POSIX shell variable rules: it disallows numeric identifiers, identifiers with spaces, but allows referencing variables like `$var` in addition to `${var}`;\n- `varformat.formats.python` follows classic python format string rules (e.g. `{var}`).\n\nYou can define your own formatter with your own custom syntax by subclassing either `varformat.RegexFormatter` and defining a regular expression that detects placeholders, or `varformat.AbstractFormatter` and defining a parsing function. See class docstrings for more information.\n",
"bugtrack_url": null,
"license": null,
"summary": "Format an parse strings with ${variables} of any syntax.",
"version": "1.0.0",
"project_urls": {
"Issues": "https://github.com/bindreams/varformat/issues",
"Repository": "https://github.com/bindreams/varformat"
},
"split_keywords": [
"string",
" interpolation",
" variable",
" shell",
" format",
" parse"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "07132d15f426a5c5040f2b94819c3949c30ec96d9e10731ef0112309203558a5",
"md5": "68aa061a0c98f83e0795dfe7d349f14b",
"sha256": "3b68b25959489f9187e594a8e75ace9974c12f220108f81e9b994344ddda3a35"
},
"downloads": -1,
"filename": "varformat-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "68aa061a0c98f83e0795dfe7d349f14b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13521,
"upload_time": "2024-03-31T11:20:05",
"upload_time_iso_8601": "2024-03-31T11:20:05.646964Z",
"url": "https://files.pythonhosted.org/packages/07/13/2d15f426a5c5040f2b94819c3949c30ec96d9e10731ef0112309203558a5/varformat-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9f1a84a29903bf1256315f0c902c11739ffa6d064c94af18f40f84832afe7640",
"md5": "e12c769298cca2100ad0150743c965a8",
"sha256": "f83f7d67af0d41fc0ad41f1771eec4dd642b573c43f3f5eff2dc865253ceafa2"
},
"downloads": -1,
"filename": "varformat-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "e12c769298cca2100ad0150743c965a8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14425,
"upload_time": "2024-03-31T11:20:06",
"upload_time_iso_8601": "2024-03-31T11:20:06.695001Z",
"url": "https://files.pythonhosted.org/packages/9f/1a/84a29903bf1256315f0c902c11739ffa6d064c94af18f40f84832afe7640/varformat-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-31 11:20:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bindreams",
"github_project": "varformat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "varformat"
}
JSON
