string.templatelib — תמיכה ב-Template String

מודול זה מספק תמיכה ב-template strings (t-strings) כפי שמוגדר ב-PEP 750. Template strings נוצרים באמצעות הקידומת t ומספקים גישה הן לחלקי המחרוזת המילוליים והן לערכים המשולבים לפני שהם מצורפים.

זמינות: Template strings אינם נתמכים על מצלמות OpenMV Cam המבוססות STM32. הם זמינים רק על מצלמות OpenMV Cam המבוססות Alif ו-i.MX RT.

מחלקות

class string.templatelib.Template(*args)

מייצג template string. אובייקטי Template נוצרים בדרך כלל על ידי תחביר t-string (t"...") אך ניתן גם לבנותם ישירות באמצעות הבנאי.

strings

tuple של ליטרלים של מחרוזת המופיעים בין שילובים.

interpolations

tuple של אובייקטי Interpolation המייצגים את הביטויים המשולבים.

values

תכונה לקריאה בלבד המחזירה tuple המכיל את התכונה value מכל שילוב בתבנית.

__iter__() → Iterator

מבצע איטרציה על תוכן התבנית, ומניב חלקי מחרוזת ואובייקטי Interpolation בסדר שבו הם מופיעים. מחרוזות ריקות מושמטות.

__add__(other: Template) → Template

משרשר שתי תבניות. מחזיר Template חדש המשלב את המחרוזות והשילובים משתי התבניות.

מעלה:

TypeError – אם other אינו Template

שרשור תבנית עם str אסור כדי להימנע מעמימות לגבי האם יש להתייחס למחרוזת כליטרל או כשילוב:

t1 = t"Hello "
t2 = t"World"
result = t1 + t2  # Valid

# TypeError: cannot concatenate str to Template
result = t1 + "World"
class string.templatelib.Interpolation(value: Any, expression: str = '', conversion: str | None = None, format_spec: str = '')

מייצג ביטוי משולב בתוך template string. ניתן להעביר את כל הארגומנטים כארגומנטי מילת מפתח.

value

הערך המוערך של הביטוי המשולב.

expression

ייצוג המחרוזת של הביטוי כפי שהופיע ב-template string.

conversion

מציין ההמרה ('s' או 'r') אם קיים, אחרת None. שימו לב ש-MicroPython אינו תומך בהמרת 'a'.

format_spec

מחרוזת מפרט הפורמט אם קיימת, אחרת מחרוזת ריקה.

תחביר Template String

Template strings משתמשים באותו תחביר כמו f-strings אך עם קידומת t

name = "World"
template = t"Hello {name}!"

# Access template components
print(template.strings)        # ('Hello ', '!')
print(template.values)         # ('World',)
print(template.interpolations[0].expression)  # 'name'

מציינֵי המרה

Template strings מאחסנים מציינֵי המרה כ-metadata. בניגוד ל-f-strings, ההמרה אינה מיושמת באופן אוטומטי:

value = "test"
t = t"{value!r}"
# t.interpolations[0].value == "test" (not repr(value))
# t.interpolations[0].conversion == "r"

קוד העיבוד חייב ליישם המרות במפורש בעת הצורך.

מפרטי פורמט

מפרטי פורמט מאוחסנים כ-metadata באובייקט ה-Interpolation. בניגוד ל-f-strings, הפורמט אינו מיושם באופן אוטומטי:

pi = 3.14159
t = t"{pi:.2f}"
# t.interpolations[0].value == 3.14159 (not formatted)
# t.interpolations[0].format_spec == ".2f"

לפי PEP 750, קוד העיבוד אינו נדרש להשתמש במפרטי פורמט, אך כשהם קיימים יש לכבד אותם ולהתאים להתנהגות f-string היכן שאפשר.

פורמט Debug

פורמט ה-debug {expr=} נתמך:

x = 42
t = t"{x=}"
# t.strings == ("x=", "")
# t.interpolations[0].expression == "x"
# t.interpolations[0].conversion == "r"

חשוב

כפי שב-PEP 750, בניגוד ל-f-strings, template strings אינם מיישמים אוטומטית המרות או מפרטי פורמט. זאת בכוונת תחילה כדי לאפשר לקוד העיבוד לשלוט באופן הטיפול בהם. קוד העיבוד חייב לטפל בתכונות אלה במפורש.

MicroPython אינו מספק את הפונקציה המובנית format(). השתמשו במתודות פורמט מחרוזת כמו str.format() במקום.

דוגמת שימוש

עיבוד בסיסי ללא תמיכת פורמט:

def simple_process(template):
    """Simple template processing"""
    parts = []
    for item in template:
        if isinstance(item, str):
            parts.append(item)
        else:
            parts.append(str(item.value))
    return "".join(parts)

עיבוד תבנית עם תמיכת פורמט:

from string.templatelib import Template, Interpolation

def convert(value, conversion):
    """Apply conversion specifier to value"""
    if conversion == "r":
        return repr(value)
    elif conversion == "s":
        return str(value)
    return value

def process_template(template):
    """Process template with conversion and format support"""
    result = []
    for part in template:
        if isinstance(part, str):
            result.append(part)
        else:  # Interpolation
            value = convert(part.value, part.conversion)
            if part.format_spec:
                # Apply format specification using str.format
                value = ("{:" + part.format_spec + "}").format(value)
            else:
                value = str(value)
            result.append(value)
    return "".join(result)

pi = 3.14159
name = "Alice"
t = t"{name!r}: {pi:.2f}"
print(process_template(t))
# Output: "'Alice': 3.14"

# Other format specifications work too
value = 42
print(process_template(t"{value:>10}"))  # "        42"
print(process_template(t"{value:04d}"))  # "0042"

דוגמת בריחת HTML:

def html_escape(value):
    """Escape HTML special characters"""
    if not isinstance(value, str):
        value = str(value)
    return value.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")

def safe_html(template):
    """Convert template to HTML-safe string"""
    result = []
    for part in template:
        if isinstance(part, str):
            result.append(part)
        else:
            result.append(html_escape(part.value))
    return "".join(result)

user_input = "<script>alert('xss')</script>"
t = t"User said: {user_input}"
print(safe_html(t))
# Output: "User said: &lt;script&gt;alert('xss')&lt;/script&gt;"

ראו גם