TextCompose is a Python library for creating dynamic, structured text templates with an intuitive, component-based approach. Inspired by aiogram-dialog.
- ๐งฑ Flexible text composition from components
- ๐ Conditional rendering support (
when) - ๐ Grouping and repeating blocks
- ๐จ Formatting via f-string and Jinja2
- ๐ Easily extensible with new components
uv add textcompose
# or
pip install textcomposeTemplateโ main class for combining and rendering components
Element โ abstract base class for all element components
Textโ static text.Formatโ dynamic python f-string formattingJinjaโ Jinja2 template renderingProgressBarโ show progress visually
Container โ abstract base class for all container components
Groupโ group children with custom separators.Listโ repeat templates for each item in a collection.
Logic โ abstract base class for all container components
Ifโ conditionally show different blocks (useif_,then_,else_)
Tip
All components support the when parameter for conditional display (value, expression, function, or magic_filter).
All usage examples can be found in the example folder.
See how easy it is to build structured, interactive text blocks:
from magic_filter import F
from textcompose import Template
from textcompose.containers import Group, List
from textcompose.elements import Format, Jinja, Text
from textcompose.logics import If
template = Template(
Format("Hello, {name}!"),
Format("Status: {status}"), # or `lambda ctx: f"Status: {ctx['status']}"` with function
If(
F["notifications"] > 0, # `if_`: condition to check if there are notifications
Format("You have {notifications} new notifications."), # `then_`: content to render if condition is True
Format("You not have new notifications."), # `else_`: content to render if condition is False
),
Group(
Jinja("\nTotal messages {{ messages|length }}:"),
List(
Format("Time - {item[time]}:"),
Format("- {item[text]}"),
sep="\n", # `sep`: separator between list items
inner_sep="\n", # `inner_sep`: separator between parts of a single item
getter=lambda ctx: ctx["messages"], # `getter`: function or F to extract the list of messages from context
),
sep="\n", # `sep`: separator between children of Group
when=F["messages"].len() > 0, # `when`: show this block only if there are messages
),
Text("\nThank you for using our service!"), # or "Recent messages:" without class
)
context = {
"name": "Alexey",
"status": "Online",
"notifications": 2,
"messages": [
{"text": "Your package has been delivered.", "time": "09:15"},
{"text": "Reminder: meeting tomorrow at 10:00.", "time": "18:42"},
],
}
print(template.render(context))Output:
Hello, Alexey!
Status: Online
You have 2 new notifications.
Total messages 2:
Time - 09:15:
- Your package has been delivered.
Time - 18:42:
- Reminder: meeting tomorrow at 10:00.
Thank you for using our service!
The ProgressBar component renders a textual progress bar. It supports various styles, customizable width, templates, and dynamic values.
from textcompose.elements import ProgressBar
bar = ProgressBar(
current=42, # `current`: Current progress value
total=100, # `total`: Total value for the progress bar
width=20, # `width`: Number of characters in the bar.
style="symbol_square", # `style`: Style (string โ built-in style name, or `ProgressBarStyle` object).
)
print(bar.render({}))Output:
[โ โ โ โ โ โ โ โ ] 42%
Built-in styles are listed in the PROGRESS_BAR_STYLES dictionary (see textcompose/styles/progress_bar.py). Examples:
"symbol_square":[โ โ โ โ โ ]"symbol_classic":[#####-----]"emoj_square":๐ฉ๐ฉ๐ฉโฌโฌโฌ"emoji_circle":๐ข๐ขโชโชโช
You can create a custom style using ProgressBarStyle:
from textcompose.styles import ProgressBarStyle
from textcompose.elements import ProgressBar
custom_style = ProgressBarStyle(
left="<", fill="*", empty="-", right=">", template="{percent} {left}{bar}{right}"
)
bar = ProgressBar(current=7, total=10, width=10, style=custom_style)
print(bar.render({}))Output:
70% <*******--->
The template parameter in the style allows you to customize the output string. Available placeholders:
{left}โ left border{bar}โ the bar itself (filled + empty part){right}โ right border{percent}โ percent complete (e.g.,42%){total}โ maximum value{current}โ current value
๐ก Ideas? Issues? PRs are welcome!
Open an issue or pull request to help TextCompose get even better.
Ready to supercharge your text formatting?
Try TextCompose today and make your bots, reports, and notifications shine! โจ