| Name | viewtext JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | generates text from generators and provides as grid |
| upload_time | 2025-10-18 11:46:21 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >3.8.0 |
| license | MIT License
Copyright (c) 2025 Holger Nahrstaedt
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
text
toml
grid
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
[](https://pypi.org/project/viewtext/)
[](https://codecov.io/gh/holgern/viewtext)
# ViewText
**Declarative text grid layouts from structured data**
ViewText is a lightweight Python library for building dynamic text-based grid layouts.
It provides a simple, declarative way to map structured data to formatted text output
through a flexible registry and layout system.
## Features
- **Field Registry**: Register data getters that extract values from context objects
- **Computed Fields**: Perform calculations on data (unit conversions, arithmetic,
aggregates)
- **Formatter System**: Built-in formatters for text, numbers, prices, dates, and
relative times
- **Layout Engine**: TOML-based layout definitions that map fields to grid positions
- **Extensible**: Easy to add custom fields and formatters for domain-specific needs
## Use Cases
- Terminal/CLI dashboards
- E-ink/LCD displays
- Text-based data visualization
- Any scenario requiring structured text layouts
## Quick Example
```python
from viewtext import LayoutEngine, LayoutLoader, FieldRegistry
# Define your field registry
registry = FieldRegistry()
registry.register("temperature", lambda ctx: ctx["temp"])
# Load layout from TOML
loader = LayoutLoader("layouts.toml")
layout = loader.get_layout("weather")
# Build grid output
engine = LayoutEngine()
lines = engine.build_line_str(layout, {"temp": 72})
```
### Computed Fields
Perform calculations on your data directly in TOML configuration:
```toml
[fields.temperature_f]
operation = "celsius_to_fahrenheit"
sources = ["temp_c"]
default = 0.0
[fields.total_price]
operation = "multiply"
sources = ["price", "quantity"]
default = 0.0
[fields.average_score]
operation = "average"
sources = ["score1", "score2", "score3"]
```
### Available Operations
**Temperature Conversions:**
- `celsius_to_fahrenheit` - Convert Celsius to Fahrenheit
- `fahrenheit_to_celsius` - Convert Fahrenheit to Celsius
**Arithmetic Operations:**
- `multiply` - Multiply values
- `divide` - Divide values
- `add` - Add values
- `subtract` - Subtract values
- `modulo` - Modulo operation
**Aggregate Operations:**
- `average` - Calculate average of values
- `min` - Find minimum value
- `max` - Find maximum value
**Math Operations:**
- `abs` - Absolute value
- `round` - Round to specified decimals
- `floor` - Round down to nearest integer
- `ceil` - Round up to nearest integer
**String Operations:**
- `concat` - Concatenate strings with separator, prefix, suffix, and skip_empty options
- `split` - Split string by separator and get index
- `substring` - Extract substring with start/end indices
**Formatting Operations:**
- `format_number` - Format numbers with thousands/decimal separators
**Transform Operations:**
- `linear_transform` - Apply linear transformation (multiply, divide, add)
**Conditional Operations:**
- `conditional` - If/else logic with field references
See `examples/computed_fields.toml` and `examples/README_computed_fields.md` for more
details.
## Installation
```bash
pip install viewtext
```
## Command Line Interface
Viewtext includes a CLI for inspecting and testing layouts:
```bash
# Show all available layouts
viewtext list
# Show specific layout configuration
viewtext show weather
# Show field mappings from config
viewtext fields
# Render a layout with mock data
viewtext render weather
# Show all available formatters
viewtext formatters
# Show all template formatters in config
viewtext templates
# Show configuration info
viewtext info
# Use custom config file (global option)
viewtext -c my_layouts.toml list
viewtext --config examples/layouts.toml show weather
```
### CLI Commands
- **list**: List all layouts in the configuration file
- **show**: Display detailed configuration for a specific layout
- **fields**: Display all field mappings from the configuration file
- **render**: Render a layout with mock data
- **formatters**: List all available formatters and their descriptions
- **templates**: List all template formatters used in layouts
- **test**: Test individual fields with custom context values and formatters
- **info**: Show configuration file information and global formatters
### Testing Fields
The `test` command allows you to test individual fields with custom values:
```bash
# Test a computed field
viewtext test total_price price=19.99 quantity=3
# Test with a formatter
viewtext test temp_f temp_c=25 --formatter temperature
# Test template formatters (requires --layout option)
viewtext test current_price \
'current_price={"fiat": "€1.234", "usd": 1.15, "sat_usd": 115000}' \
--formatter template --layout crypto_composite_price
```
### JSON Pipeline Support
Pipe JSON data from external sources directly to ViewText:
```bash
# From API
curl -s https://api.example.com/data | viewtext render layout --json
# From Python
python3 -c "import json; print(json.dumps({'field': 'value'}))" | viewtext render layout --json
# From file with jq
cat data.json | jq '.users[0]' | viewtext render layout --json
# Live dashboard
watch -n 5 'curl -s API_URL | viewtext -c config.toml render layout --json'
```
See `examples/json_pipeline_example.md` for detailed examples and use cases.
### Global Options
- **--config, -c**: Path to layouts.toml file (can be placed before any command)
## Editor Support
ViewText provides a JSON Schema for TOML validation and autocomplete. Install the
[Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)
extension in VS Code or use Taplo LSP in other editors for:
- **Validation**: Catch errors in field definitions, formatters, and layouts
- **Autocomplete**: Get intelligent suggestions for property names and values
- **Hover Documentation**: View descriptions of all configuration options
The schema is automatically configured in `.taplo.toml` for all layout files.
## Documentation
Full documentation is available at [Read the Docs](https://viewtext.readthedocs.io/):
- [Quick Start Guide](https://viewtext.readthedocs.io/en/latest/quickstart.html) - Get
started quickly
- [User Guide](https://viewtext.readthedocs.io/en/latest/user_guide.html) - Core
concepts and features
- [Fields Reference](https://viewtext.readthedocs.io/en/latest/fields_reference.html) -
Complete field definition reference
- [Validation Reference](https://viewtext.readthedocs.io/en/latest/validation_reference.html) -
Field validation and type checking
- [Computed Fields Reference](https://viewtext.readthedocs.io/en/latest/computed_fields_reference.html) -
Complete list of data transformation operations
- [Formatters Reference](https://viewtext.readthedocs.io/en/latest/formatters_reference.html) -
Complete list of display formatters with examples
- [API Reference](https://viewtext.readthedocs.io/en/latest/api_reference.html) - Python
API documentation
- [Examples](https://viewtext.readthedocs.io/en/latest/examples.html) - Real-world
examples and use cases
## License
See LICENSE file in the root directory.
Raw data
{
"_id": null,
"home_page": null,
"name": "viewtext",
"maintainer": null,
"docs_url": null,
"requires_python": ">3.8.0",
"maintainer_email": null,
"keywords": "text, toml, grid",
"author": null,
"author_email": "Holger Nahrstaedt <nahrstaedt@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/63/a3/a5ed712a2ad8170d860f73eac7d5be2dd8e86fd876a185d070ad3364a6c5/viewtext-0.3.0.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/viewtext/)\n\n\n[](https://codecov.io/gh/holgern/viewtext)\n\n# ViewText\n\n**Declarative text grid layouts from structured data**\n\nViewText is a lightweight Python library for building dynamic text-based grid layouts.\nIt provides a simple, declarative way to map structured data to formatted text output\nthrough a flexible registry and layout system.\n\n## Features\n\n- **Field Registry**: Register data getters that extract values from context objects\n- **Computed Fields**: Perform calculations on data (unit conversions, arithmetic,\n aggregates)\n- **Formatter System**: Built-in formatters for text, numbers, prices, dates, and\n relative times\n- **Layout Engine**: TOML-based layout definitions that map fields to grid positions\n- **Extensible**: Easy to add custom fields and formatters for domain-specific needs\n\n## Use Cases\n\n- Terminal/CLI dashboards\n- E-ink/LCD displays\n- Text-based data visualization\n- Any scenario requiring structured text layouts\n\n## Quick Example\n\n```python\nfrom viewtext import LayoutEngine, LayoutLoader, FieldRegistry\n\n# Define your field registry\nregistry = FieldRegistry()\nregistry.register(\"temperature\", lambda ctx: ctx[\"temp\"])\n\n# Load layout from TOML\nloader = LayoutLoader(\"layouts.toml\")\nlayout = loader.get_layout(\"weather\")\n\n# Build grid output\nengine = LayoutEngine()\nlines = engine.build_line_str(layout, {\"temp\": 72})\n```\n\n### Computed Fields\n\nPerform calculations on your data directly in TOML configuration:\n\n```toml\n[fields.temperature_f]\noperation = \"celsius_to_fahrenheit\"\nsources = [\"temp_c\"]\ndefault = 0.0\n\n[fields.total_price]\noperation = \"multiply\"\nsources = [\"price\", \"quantity\"]\ndefault = 0.0\n\n[fields.average_score]\noperation = \"average\"\nsources = [\"score1\", \"score2\", \"score3\"]\n```\n\n### Available Operations\n\n**Temperature Conversions:**\n\n- `celsius_to_fahrenheit` - Convert Celsius to Fahrenheit\n- `fahrenheit_to_celsius` - Convert Fahrenheit to Celsius\n\n**Arithmetic Operations:**\n\n- `multiply` - Multiply values\n- `divide` - Divide values\n- `add` - Add values\n- `subtract` - Subtract values\n- `modulo` - Modulo operation\n\n**Aggregate Operations:**\n\n- `average` - Calculate average of values\n- `min` - Find minimum value\n- `max` - Find maximum value\n\n**Math Operations:**\n\n- `abs` - Absolute value\n- `round` - Round to specified decimals\n- `floor` - Round down to nearest integer\n- `ceil` - Round up to nearest integer\n\n**String Operations:**\n\n- `concat` - Concatenate strings with separator, prefix, suffix, and skip_empty options\n- `split` - Split string by separator and get index\n- `substring` - Extract substring with start/end indices\n\n**Formatting Operations:**\n\n- `format_number` - Format numbers with thousands/decimal separators\n\n**Transform Operations:**\n\n- `linear_transform` - Apply linear transformation (multiply, divide, add)\n\n**Conditional Operations:**\n\n- `conditional` - If/else logic with field references\n\nSee `examples/computed_fields.toml` and `examples/README_computed_fields.md` for more\ndetails.\n\n## Installation\n\n```bash\npip install viewtext\n```\n\n## Command Line Interface\n\nViewtext includes a CLI for inspecting and testing layouts:\n\n```bash\n# Show all available layouts\nviewtext list\n\n# Show specific layout configuration\nviewtext show weather\n\n# Show field mappings from config\nviewtext fields\n\n# Render a layout with mock data\nviewtext render weather\n\n# Show all available formatters\nviewtext formatters\n\n# Show all template formatters in config\nviewtext templates\n\n# Show configuration info\nviewtext info\n\n# Use custom config file (global option)\nviewtext -c my_layouts.toml list\nviewtext --config examples/layouts.toml show weather\n```\n\n### CLI Commands\n\n- **list**: List all layouts in the configuration file\n- **show**: Display detailed configuration for a specific layout\n- **fields**: Display all field mappings from the configuration file\n- **render**: Render a layout with mock data\n- **formatters**: List all available formatters and their descriptions\n- **templates**: List all template formatters used in layouts\n- **test**: Test individual fields with custom context values and formatters\n- **info**: Show configuration file information and global formatters\n\n### Testing Fields\n\nThe `test` command allows you to test individual fields with custom values:\n\n```bash\n# Test a computed field\nviewtext test total_price price=19.99 quantity=3\n\n# Test with a formatter\nviewtext test temp_f temp_c=25 --formatter temperature\n\n# Test template formatters (requires --layout option)\nviewtext test current_price \\\n 'current_price={\"fiat\": \"\u20ac1.234\", \"usd\": 1.15, \"sat_usd\": 115000}' \\\n --formatter template --layout crypto_composite_price\n```\n\n### JSON Pipeline Support\n\nPipe JSON data from external sources directly to ViewText:\n\n```bash\n# From API\ncurl -s https://api.example.com/data | viewtext render layout --json\n\n# From Python\npython3 -c \"import json; print(json.dumps({'field': 'value'}))\" | viewtext render layout --json\n\n# From file with jq\ncat data.json | jq '.users[0]' | viewtext render layout --json\n\n# Live dashboard\nwatch -n 5 'curl -s API_URL | viewtext -c config.toml render layout --json'\n```\n\nSee `examples/json_pipeline_example.md` for detailed examples and use cases.\n\n### Global Options\n\n- **--config, -c**: Path to layouts.toml file (can be placed before any command)\n\n## Editor Support\n\nViewText provides a JSON Schema for TOML validation and autocomplete. Install the\n[Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)\nextension in VS Code or use Taplo LSP in other editors for:\n\n- **Validation**: Catch errors in field definitions, formatters, and layouts\n- **Autocomplete**: Get intelligent suggestions for property names and values\n- **Hover Documentation**: View descriptions of all configuration options\n\nThe schema is automatically configured in `.taplo.toml` for all layout files.\n\n## Documentation\n\nFull documentation is available at [Read the Docs](https://viewtext.readthedocs.io/):\n\n- [Quick Start Guide](https://viewtext.readthedocs.io/en/latest/quickstart.html) - Get\n started quickly\n- [User Guide](https://viewtext.readthedocs.io/en/latest/user_guide.html) - Core\n concepts and features\n- [Fields Reference](https://viewtext.readthedocs.io/en/latest/fields_reference.html) -\n Complete field definition reference\n- [Validation Reference](https://viewtext.readthedocs.io/en/latest/validation_reference.html) -\n Field validation and type checking\n- [Computed Fields Reference](https://viewtext.readthedocs.io/en/latest/computed_fields_reference.html) -\n Complete list of data transformation operations\n- [Formatters Reference](https://viewtext.readthedocs.io/en/latest/formatters_reference.html) -\n Complete list of display formatters with examples\n- [API Reference](https://viewtext.readthedocs.io/en/latest/api_reference.html) - Python\n API documentation\n- [Examples](https://viewtext.readthedocs.io/en/latest/examples.html) - Real-world\n examples and use cases\n\n## License\n\nSee LICENSE file in the root directory.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Holger Nahrstaedt\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "generates text from generators and provides as grid",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/holgern/viewtext"
},
"split_keywords": [
"text",
" toml",
" grid"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4bdea5757b3883eee3337100dbdffeb7a3f5ad1ed861f1d76002a1979d4689c9",
"md5": "4f045e35e9de2b4e5345c60eed95e5da",
"sha256": "0c5aefa3019463ecc9190fe22b2066195b91e1e75e62d0e3f93344c4dbffeaae"
},
"downloads": -1,
"filename": "viewtext-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4f045e35e9de2b4e5345c60eed95e5da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.8.0",
"size": 31115,
"upload_time": "2025-10-18T11:46:20",
"upload_time_iso_8601": "2025-10-18T11:46:20.672791Z",
"url": "https://files.pythonhosted.org/packages/4b/de/a5757b3883eee3337100dbdffeb7a3f5ad1ed861f1d76002a1979d4689c9/viewtext-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "63a3a5ed712a2ad8170d860f73eac7d5be2dd8e86fd876a185d070ad3364a6c5",
"md5": "196425437b062e98b92e4c7fa750a634",
"sha256": "e4fd972a7e11a8c6e988e76ab5120da3c34384d70ff5945de875332444dfbd58"
},
"downloads": -1,
"filename": "viewtext-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "196425437b062e98b92e4c7fa750a634",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.8.0",
"size": 98604,
"upload_time": "2025-10-18T11:46:21",
"upload_time_iso_8601": "2025-10-18T11:46:21.826582Z",
"url": "https://files.pythonhosted.org/packages/63/a3/a5ed712a2ad8170d860f73eac7d5be2dd8e86fd876a185d070ad3364a6c5/viewtext-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-18 11:46:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "holgern",
"github_project": "viewtext",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "viewtext"
}
