| Name | fvalues JSON |
| Version |
0.0.4
JSON |
| download |
| home_page | https://github.com/oughtinc/fvalues |
| Summary | Keep track of components in strings, especially formatted values in f-strings. |
| upload_time | 2023-05-16 13:22:07 |
| maintainer | |
| docs_url | None |
| author | Alex Hall |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# `fvalues`
[](https://github.com/oughtinc/fvalues/actions) [](https://coveralls.io/github/oughtinc/fvalues?branch=main)
This is a Python library for keeping track of the combination of components in a string. In particular it lets you separate out the formatted values in an f-string. Here's an example:
```python
from fvalues import F, FValue
x = 1.2345
f = F(f"twice x is {x * 2:.2f}")
assert f == "twice x is 2.47"
assert f.parts == ("twice x is ", FValue(source="x * 2", value=2.469, formatted="2.47"))
```
Key facts:
- `F` is a subclass of `str` so it can generally be used like any other string.
- Calls to the constructor `F()` are magically detected using the `executing` library, and f-strings within are parsed to extract their components.
- These are saved in the attribute `F.parts`. Each `part` is either a `str` representing a constant section or an `FValue` representing a dynamic expression.
- `FValue.source` contains the source code between the braces (`{}`) but before the colon (`:`) and format spec (`.2f`). In some cases it may not be the exact original source code, but equivalent code produced by `ast.unparse`.
- `FValue.value` and `FValue.formatted` are calculated using `eval()`, so **be careful of expressions that you wouldn't want to evaluate twice due to performance or side effects**.
## Usage in ICE
This library was built to enhance the [Interactive Composition Explorer (ICE)](https://github.com/oughtinc/ice). In the screenshot below, the prompt under 'Inputs' on the right is an `F` object, and the colored text corresponds to dynamic `FValue`s.
## Concatenation
The `F` class also has special support for concatenation with the `+` operator:
```python
f += "!"
assert f == "twice x is 2.47!"
assert f.parts == (
FValue(
source="f",
value="twice x is 2.47",
formatted="twice x is 2.47",
),
"!",
)
```
Similar to deconstructing f-strings, you can see how the parts distinguish between the dynamic expression `f` on the left of `+=`, representing it as an `FValue`, and the static `"!"` on the right.
## Flattening
In the assertion above above, `FValue.value` is shown as a plain string, but remember that it's actually also an `F` object itself. The assertion works because `F` is a subclass of `str` so they can be used interchangeably. But it still has the same `parts` that we saw earlier. Sometimes keeping the tree of parts in its original form can be useful, other times you may want to bring everything to the surface to make things easier. You can produce an equivalent `F` object with a flat list of parts using `F.flatten`:
```python
assert f.flatten().parts == (
"twice x is ",
FValue(
source="x * 2",
value=2.469,
formatted="2.47",
),
"!",
)
```
## Other string methods
Most `F` methods (e.g. `.lower()`) are directly inherited from `str`, which means that they return a plain `str` rather than another `F` object. So be careful with those methods if you don't want to lose information about the parts! The methods below have specialised implementations to avoid this. More may be added in the future.
### `strip`
`F.strip` does the same thing as the usual `str.strip` as far as the whole string is concerned, but also strips the internal parts in the way you'd probably expect. See the docstring for more details. The related methods `lstrip` and `rstrip` strip the left/right sides as expected.
Make sure to write `F(f"...").strip()` rather than `F(f"...".strip())` or the f-string magic won't work.
### `join`
`separator.join(strings)` will return an `F` object only if `separator` is an `F` object. If `separator` is a plain `str`, then the result will be a plain `str`, even if `strings` is a list of `F` objects. In practice, this typically means you should write e.g. `F(" ").join(strings)` rather than `" ".join(strings)`.
Raw data
{
"_id": null,
"home_page": "https://github.com/oughtinc/fvalues",
"name": "fvalues",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "Alex Hall",
"author_email": "alex.mojaki@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/06/a7/c9bf5d5392ecf7e0ef0d7aa92e949320f4361d8703e1d42022efa4ecccd6/fvalues-0.0.4.tar.gz",
"platform": null,
"description": "# `fvalues`\n\n[](https://github.com/oughtinc/fvalues/actions) [](https://coveralls.io/github/oughtinc/fvalues?branch=main)\n\nThis is a Python library for keeping track of the combination of components in a string. In particular it lets you separate out the formatted values in an f-string. Here's an example:\n\n```python\nfrom fvalues import F, FValue\n\nx = 1.2345\nf = F(f\"twice x is {x * 2:.2f}\")\nassert f == \"twice x is 2.47\"\nassert f.parts == (\"twice x is \", FValue(source=\"x * 2\", value=2.469, formatted=\"2.47\"))\n```\n\nKey facts:\n\n- `F` is a subclass of `str` so it can generally be used like any other string.\n- Calls to the constructor `F()` are magically detected using the `executing` library, and f-strings within are parsed to extract their components.\n- These are saved in the attribute `F.parts`. Each `part` is either a `str` representing a constant section or an `FValue` representing a dynamic expression.\n- `FValue.source` contains the source code between the braces (`{}`) but before the colon (`:`) and format spec (`.2f`). In some cases it may not be the exact original source code, but equivalent code produced by `ast.unparse`.\n- `FValue.value` and `FValue.formatted` are calculated using `eval()`, so **be careful of expressions that you wouldn't want to evaluate twice due to performance or side effects**.\n\n## Usage in ICE\n\nThis library was built to enhance the [Interactive Composition Explorer (ICE)](https://github.com/oughtinc/ice). In the screenshot below, the prompt under 'Inputs' on the right is an `F` object, and the colored text corresponds to dynamic `FValue`s.\n\n\n\n## Concatenation\n\nThe `F` class also has special support for concatenation with the `+` operator:\n\n```python\nf += \"!\"\nassert f == \"twice x is 2.47!\"\nassert f.parts == (\n FValue(\n source=\"f\",\n value=\"twice x is 2.47\",\n formatted=\"twice x is 2.47\",\n ),\n \"!\",\n)\n```\n\nSimilar to deconstructing f-strings, you can see how the parts distinguish between the dynamic expression `f` on the left of `+=`, representing it as an `FValue`, and the static `\"!\"` on the right.\n\n## Flattening\n\nIn the assertion above above, `FValue.value` is shown as a plain string, but remember that it's actually also an `F` object itself. The assertion works because `F` is a subclass of `str` so they can be used interchangeably. But it still has the same `parts` that we saw earlier. Sometimes keeping the tree of parts in its original form can be useful, other times you may want to bring everything to the surface to make things easier. You can produce an equivalent `F` object with a flat list of parts using `F.flatten`:\n\n```python\nassert f.flatten().parts == (\n \"twice x is \",\n FValue(\n source=\"x * 2\",\n value=2.469,\n formatted=\"2.47\",\n ),\n \"!\",\n)\n```\n\n## Other string methods\n\nMost `F` methods (e.g. `.lower()`) are directly inherited from `str`, which means that they return a plain `str` rather than another `F` object. So be careful with those methods if you don't want to lose information about the parts! The methods below have specialised implementations to avoid this. More may be added in the future.\n\n### `strip`\n\n`F.strip` does the same thing as the usual `str.strip` as far as the whole string is concerned, but also strips the internal parts in the way you'd probably expect. See the docstring for more details. The related methods `lstrip` and `rstrip` strip the left/right sides as expected.\n\nMake sure to write `F(f\"...\").strip()` rather than `F(f\"...\".strip())` or the f-string magic won't work.\n\n### `join`\n\n`separator.join(strings)` will return an `F` object only if `separator` is an `F` object. If `separator` is a plain `str`, then the result will be a plain `str`, even if `strings` is a list of `F` objects. In practice, this typically means you should write e.g. `F(\" \").join(strings)` rather than `\" \".join(strings)`.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Keep track of components in strings, especially formatted values in f-strings.",
"version": "0.0.4",
"project_urls": {
"Homepage": "https://github.com/oughtinc/fvalues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f04db545ecb90ad851ea6bc913b116cf247a7736fe910cb85e61abe8a3aa85f7",
"md5": "c9fb0c3abbe74e8a8555a5e4a7f1fdc0",
"sha256": "9ed462e2b305004b145d95e8d57e81a744f70978a226c5916f488ac6e51609e6"
},
"downloads": -1,
"filename": "fvalues-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9fb0c3abbe74e8a8555a5e4a7f1fdc0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9153,
"upload_time": "2023-05-16T13:22:04",
"upload_time_iso_8601": "2023-05-16T13:22:04.347248Z",
"url": "https://files.pythonhosted.org/packages/f0/4d/b545ecb90ad851ea6bc913b116cf247a7736fe910cb85e61abe8a3aa85f7/fvalues-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "06a7c9bf5d5392ecf7e0ef0d7aa92e949320f4361d8703e1d42022efa4ecccd6",
"md5": "1c9c0bb29d8c93943e61772bde57e01a",
"sha256": "d629d0fff4a5c47b926d94c77d385efed1947c40c5a53f686615c4edb387f56e"
},
"downloads": -1,
"filename": "fvalues-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "1c9c0bb29d8c93943e61772bde57e01a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 327189,
"upload_time": "2023-05-16T13:22:07",
"upload_time_iso_8601": "2023-05-16T13:22:07.207466Z",
"url": "https://files.pythonhosted.org/packages/06/a7/c9bf5d5392ecf7e0ef0d7aa92e949320f4361d8703e1d42022efa4ecccd6/fvalues-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-16 13:22:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oughtinc",
"github_project": "fvalues",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "fvalues"
}
