tstr 0.2.0__tar.gz → 0.3.1.dev1__tar.gz

tstr-0.3.1.dev1/.github/workflows/build.yml

@@ -0,0 +1,58 @@
+# The following build script copied from hatch/.github/workflows/build-hatchling.yml (MIT License)
+name: build a package
+
+on:
+  push:
+    tags:
+    - v*
+
+env:
+  PYTHON_VERSION: "3.12"
+
+jobs:
+  build:
+    name: Build wheels and source distribution
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ env.PYTHON_VERSION }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+
+    - name: Install UV
+      uses: astral-sh/setup-uv@v3
+
+    - name: Install build dependencies
+      run: uv pip install --system --upgrade build
+
+    - name: Build source distribution
+      run: python -m build .
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: artifacts
+        path: dist
+        if-no-files-found: error
+
+  publish:
+    name: Publish release
+    needs:
+    - build
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+
+    steps:
+    - uses: actions/download-artifact@v4
+      with:
+        name: artifacts
+        path: dist
+
+    - name: Push build artifacts to PyPI
+      uses: pypa/gh-action-pypi-publish@v1.12.3
+      with:
+        skip-existing: true

{tstr-0.2.0 → tstr-0.3.1.dev1}/.github/workflows/codeql.yml

@@ -41,11 +41,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v5
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -59,7 +59,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v3
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -72,6 +72,6 @@ jobs:
     #     ./location_of_script_within_repo/buildscript.sh
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3
       with:
         category: "/language:${{matrix.language}}"

{tstr-0.2.0 → tstr-0.3.1.dev1}/.github/workflows/testing.yaml

@@ -12,22 +12,31 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python-version: ['3.10', '3.11', '3.12', '3.13', '3.14-dev']
+
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v4
+
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
+
+    - name: Install UV
+      uses: astral-sh/setup-uv@v3
+
     - name: Install dependencies
       run: |
-        python -m pip install pytest pytest-cov
-        python -m pip install -e .
+        # python -m pip install pytest pytest-cov
+        # python -m pip install -e .
+        uv sync
+
     - name: Test with pytest
       run: |
         python -m pytest --cov --cov-report lcov
-    - name: Coveralls
-      uses: coverallsapp/github-action@master
+
+    - name: Upload coverage information to Coveralls
+      uses: coverallsapp/github-action@v2
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
         path-to-lcov: coverage.lcov

{tstr-0.2.0 → tstr-0.3.1.dev1}/.vscode/settings.json

@@ -1,6 +1,8 @@
 {
     "cSpell.words": [
+        "dedented",
         "fetchone",
+        "fstring",
         "interp",
         "intp",
         "intrp",
@@ -8,7 +10,9 @@
         "renderable",
         "repr",
         "templatelib",
-        "tstr"
+        "tstr",
+        "tstring",
+        "tstrings"
     ],
     "python.analysis.typeCheckingMode": "standard"
 }

{tstr-0.2.0 → tstr-0.3.1.dev1}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: tstr
-Version: 0.2.0
+Version: 0.3.1.dev1
 Summary: Template string utilities and backports
 Project-URL: Repository, https://github.com/ilotoki0804/tstr
 Author-email: ilotoki0804 <ilotoki0804@gmail.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: backport,string,template,utility
+Keywords: backport,pep 750,pep-750,pep750,string,t-string,template,template string,tstring,utility
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -43,70 +43,23 @@ pip install tstr
 - `render` (alias: `f`): Render a template to a string, mimicking f-string behavior.
 - `generate_template` (alias: `t`): Create a Template object from a string and context.
     This function is especially useful on Python versions that do not support template strings natively.
-- `bind`: Apply a function to all interpolations in a template.
+- `bind`: Apply a function to all interpolations and join all the parts.
 - `binder`: Decorator to create template processors from an interpolation processor.
-- `normalize`: Convert an interpolation to its value, preserving type when possible.
-- `normalize_str`: Convert an interpolation to a string.
-- `convert`: Apply f-string-style conversion to a value.
+- `normalize` / `normalize_str`: Apply conversion and format to value.
+- `convert`: Apply conversion to a value.
 - `template_eq`: Check if two templates are equivalent.
+- `interpolation_replace`: Create a new `Interpolation` by selectively replacing attributes of an existing one.
+- `dedent`: `textwrap.dedent` for template strings
+- `template_from_parts`: Construct template strings from iterable
 
-Experimental applications:
-
-- `render_html`: Render templates with HTML escaping.
-- `execute`: Safely execute SQL with templates, preventing injection.
-- `TemplateFormatter`: Enable Python's logging module to accept template strings.
-
-Below are usage examples for each function. For more details, see the [API documentation](/docs/api.md).
-
-```python
-from tstr import Template, Interpolation, generate_template, render, bind, binder, f, normalize, normalize_str, convert, template_eq
-
-# Rendering templates
-x = 12
-template = t"Value: {x}"
-print(render(template))  # "Value: 12"
-print(f(template))  # "Value: 12"
-
-# Generating templates
-template = generate_template("Hello, {name}!", {"name": "Alice"})  # with explicit context
-print(f(template))  # "Hello, Alice!"
-
-name = "Bob"
-template = generate_template("Nice to meet you, {name}!")  # without explicit context
-print(f(template))  # "Nice to meet you, Bob!"
-
-template = t("Nice to meet you, {name}!")  # with an alias `t`
-print(f(template))  # "Nice to meet you, Bob!"
-
-# Binding all interpolations
-def double(i: Interpolation):
-    return str(i.value * 2)
-n = 10
-template = t"Double: {n}"
-print(bind(template, double))  # "Double: 20"
-
-@binder
-def upper(i):
-    return normalize_str(i).upper()
-name = 'bob'
-template = t"Hi, {name}!"
-print(upper(template))  # "Hi, BOB!"
-
-# Applying conversion and formatting
-age = 20
-template = t"Age: {age:04d}"
-intp = template.interpolations[0]
-print(normalize(intp))  # "0020"
-
-# Applying conversion
-print(convert(42, "r"))  # e.g., "42"
-
-# Template equivalence
-x = 123
-t1 = t"A: {x}"
-t2 = t"A: {x}"
-print(template_eq(t1, t2))  # True
-```
+This library also provides several useful extensions where template strings can be effectively utilized.
+These extensions are available in the `tstr.ext` submodule, and below is a list with brief descriptions:
+
+- `ext._html`: Render templates with HTML escaping.
+- `ext._sqlite`: Safely execute SQL with templates, preventing SQL injection attacks.
+- `ext._logging`: Enable Python's logging module to accept template strings.
+
+For more details, see the [API documentation](/docs/api.md).
 
 ## Compatibility
 
@@ -117,15 +70,18 @@ print(template_eq(t1, t2))  # True
 
 Use the `TEMPLATE_STRING_SUPPORTED` constant to check if template strings are natively supported in your Python version.
 
+For details on how the compatible backport of template string works and what similarities and differences it has with native template strings, see the [compatible template strings](/docs/compat.md) documentation.
+
 # Contributing
 
 This project welcomes contributions of all kinds from anyone willing to help improve it! Whether you're fixing a typo in documentation, reporting a bug, proposing a new feature, or implementing code changes - every contribution matters and is highly appreciated.
 
 ## Releases
 
+* 0.3.0: Revamp various things
 * 0.2.0: Rename html_render to render_html, add `_logging` module, fix various bugs and improve documentation
 * 0.1.1.post1: Initial release
 
 ## License
 
-Apache License 2.0
+This library is licensed under the Apache License 2.0.

{tstr-0.2.0 → tstr-0.3.1.dev1}/README.md

@@ -23,70 +23,23 @@ pip install tstr
 - `render` (alias: `f`): Render a template to a string, mimicking f-string behavior.
 - `generate_template` (alias: `t`): Create a Template object from a string and context.
     This function is especially useful on Python versions that do not support template strings natively.
-- `bind`: Apply a function to all interpolations in a template.
+- `bind`: Apply a function to all interpolations and join all the parts.
 - `binder`: Decorator to create template processors from an interpolation processor.
-- `normalize`: Convert an interpolation to its value, preserving type when possible.
-- `normalize_str`: Convert an interpolation to a string.
-- `convert`: Apply f-string-style conversion to a value.
+- `normalize` / `normalize_str`: Apply conversion and format to value.
+- `convert`: Apply conversion to a value.
 - `template_eq`: Check if two templates are equivalent.
+- `interpolation_replace`: Create a new `Interpolation` by selectively replacing attributes of an existing one.
+- `dedent`: `textwrap.dedent` for template strings
+- `template_from_parts`: Construct template strings from iterable
 
-Experimental applications:
-
-- `render_html`: Render templates with HTML escaping.
-- `execute`: Safely execute SQL with templates, preventing injection.
-- `TemplateFormatter`: Enable Python's logging module to accept template strings.
-
-Below are usage examples for each function. For more details, see the [API documentation](/docs/api.md).
-
-```python
-from tstr import Template, Interpolation, generate_template, render, bind, binder, f, normalize, normalize_str, convert, template_eq
-
-# Rendering templates
-x = 12
-template = t"Value: {x}"
-print(render(template))  # "Value: 12"
-print(f(template))  # "Value: 12"
-
-# Generating templates
-template = generate_template("Hello, {name}!", {"name": "Alice"})  # with explicit context
-print(f(template))  # "Hello, Alice!"
-
-name = "Bob"
-template = generate_template("Nice to meet you, {name}!")  # without explicit context
-print(f(template))  # "Nice to meet you, Bob!"
-
-template = t("Nice to meet you, {name}!")  # with an alias `t`
-print(f(template))  # "Nice to meet you, Bob!"
-
-# Binding all interpolations
-def double(i: Interpolation):
-    return str(i.value * 2)
-n = 10
-template = t"Double: {n}"
-print(bind(template, double))  # "Double: 20"
-
-@binder
-def upper(i):
-    return normalize_str(i).upper()
-name = 'bob'
-template = t"Hi, {name}!"
-print(upper(template))  # "Hi, BOB!"
-
-# Applying conversion and formatting
-age = 20
-template = t"Age: {age:04d}"
-intp = template.interpolations[0]
-print(normalize(intp))  # "0020"
-
-# Applying conversion
-print(convert(42, "r"))  # e.g., "42"
-
-# Template equivalence
-x = 123
-t1 = t"A: {x}"
-t2 = t"A: {x}"
-print(template_eq(t1, t2))  # True
-```
+This library also provides several useful extensions where template strings can be effectively utilized.
+These extensions are available in the `tstr.ext` submodule, and below is a list with brief descriptions:
+
+- `ext._html`: Render templates with HTML escaping.
+- `ext._sqlite`: Safely execute SQL with templates, preventing SQL injection attacks.
+- `ext._logging`: Enable Python's logging module to accept template strings.
+
+For more details, see the [API documentation](/docs/api.md).
 
 ## Compatibility
 
@@ -97,15 +50,18 @@ print(template_eq(t1, t2))  # True
 
 Use the `TEMPLATE_STRING_SUPPORTED` constant to check if template strings are natively supported in your Python version.
 
+For details on how the compatible backport of template string works and what similarities and differences it has with native template strings, see the [compatible template strings](/docs/compat.md) documentation.
+
 # Contributing
 
 This project welcomes contributions of all kinds from anyone willing to help improve it! Whether you're fixing a typo in documentation, reporting a bug, proposing a new feature, or implementing code changes - every contribution matters and is highly appreciated.
 
 ## Releases
 
+* 0.3.0: Revamp various things
 * 0.2.0: Rename html_render to render_html, add `_logging` module, fix various bugs and improve documentation
 * 0.1.1.post1: Initial release
 
 ## License
 
-Apache License 2.0
+This library is licensed under the Apache License 2.0.

{tstr-0.2.0 → tstr-0.3.1.dev1}/pyproject.toml

@@ -10,6 +10,12 @@ keywords = [
     "string",
     "utility",
     "backport",
+    "template string",
+    "t-string",
+    "tstring",
+    "pep-750",
+    "pep750",
+    "pep 750",
 ]
 dependencies = []
 classifiers = [

{tstr-0.2.0 → tstr-0.3.1.dev1}/src/tstr/__init__.py

@@ -1,3 +1,9 @@
+from ._interpolation_tools import (
+    convert,
+    interpolation_replace,
+    normalize,
+    normalize_str,
+)
 from ._template import (
     TEMPLATE_STRING_SUPPORTED,
     Conversion,
@@ -5,15 +11,13 @@ from ._template import (
     StringOrTemplate,
     Template,
 )
-from ._utils import (
-    CONVERTERS,
-    TemplateGenerationError,
+from ._template_tools import (
     bind,
     binder,
-    convert,
+    dedent,
     f,
+    template_from_parts,
     generate_template,
-    normalize,
     normalize_str,
     render,
     t,
@@ -21,7 +25,6 @@ from ._utils import (
 )
 
 __all__ = [
-    "CONVERTERS",
     "bind",
     "binder",
     "f",
@@ -34,9 +37,11 @@ __all__ = [
     "Conversion",
     "generate_template",
     "t",
-    "TemplateGenerationError",
     "TEMPLATE_STRING_SUPPORTED",
     "template_eq",
     "StringOrTemplate",
+    "interpolation_replace",
+    "template_from_parts",
+    "dedent",
 ]
-__version__ = "0.2.0"
+__version__ = "0.3.1.dev1"

{tstr-0.2.0 → tstr-0.3.1.dev1}/src/tstr/_compat.py

@@ -3,7 +3,10 @@ from __future__ import annotations
 import typing
 from itertools import zip_longest
 
+__all__ = ["Template", "Interpolation"]
 
+
+@typing.final
 class Template:
     __strings: tuple[str, ...]
     __interpolations: tuple[Interpolation, ...]
@@ -80,7 +83,8 @@ class Template:
 
     def __add__(self, other: str | Template) -> Template:
         if isinstance(other, str):
-            return Template(*self, other)
+            raise TypeError(
+                'can only concatenate tstr.Template (not "str") to tstr.Template')
         elif isinstance(other, Template):
             return Template(*self, *other)
         else:
@@ -88,7 +92,8 @@ class Template:
 
     def __radd__(self, other: str | Template) -> Template:
         if isinstance(other, str):
-            return Template(other, *self)
+            raise TypeError(
+                'can only concatenate str (not "tstr.Template") to str')
         elif isinstance(other, Template):
             return Template(*other, *self)
         else:
@@ -98,6 +103,7 @@ class Template:
         return f"Template(strings={self.strings!r}, interpolations={self.interpolations!r})"
 
 
+@typing.final
 class Interpolation:
     __match_args__ = ("value", "expression", "conversion", "format_spec")
     __value: object

tstr-0.3.1.dev1/src/tstr/_interpolation_tools.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import typing
+
+from ._template import Conversion, Interpolation
+
+__all__ = [
+    "convert",
+    "normalize",
+    "normalize_str",
+    "interpolation_replace",
+]
+
+T = typing.TypeVar("T")
+
+
+@typing.overload
+def convert(
+    value: typing.Any,
+    conversion: Conversion,
+) -> str: ...
+
+@typing.overload
+def convert(
+    value: typing.Any,
+    conversion: str,
+) -> str: ...
+
+@typing.overload
+def convert(
+    value: T,
+    conversion: Conversion | None,
+) -> T | str: ...
+
+@typing.overload
+def convert(
+    value: T,
+    conversion: str | None,
+) -> T | str: ...
+
+
+def convert(
+    value: T,
+    conversion: str | None,
+) -> T | str:
+    """
+    Applies a conversion to a value, similar to how f-strings handle conversions.
+
+    Args:
+        value (T): The value to convert, typically from an Interpolation.value.
+        conversion (Conversion | None): The conversion specifier ('a', 'r', or 's'), or None.
+
+    Returns:
+        T | str: The value converted according to the specified conversion;
+            if 'conversion' is None, returns the original value unchanged.
+    """
+    if conversion is None:
+        return value
+    if conversion == "s":
+        return str(value)
+    if conversion == "r":
+        return repr(value)
+    if conversion == "a":
+        return ascii(value)
+    raise ValueError(f"Invalid conversion: {conversion}")
+
+
+def normalize(interp: Interpolation) -> str | object:
+    """
+    Normalizes a PEP 750 Interpolation, preserving its type when possible.
+
+    This is a more flexible version of normalize_str() that preserves the original
+    value's type when no conversion is specified.
+
+    If neither a conversion nor a format spec is specified, the original value
+    is returned without any modification, ensuring that the value's type is preserved.
+
+    Args:
+        interp (Interpolation): The interpolation to normalize.
+
+    Returns:
+        str | object: The normalized string if conversion or format spec is specified, otherwise
+            the original value.
+    """
+    if interp.conversion or interp.format_spec:
+        return normalize_str(interp)
+    else:
+        return interp.value
+
+
+def normalize_str(interp: Interpolation) -> str:
+    """
+    Normalizes a PEP 750 Interpolation to a formatted string.
+
+    This processes an Interpolation object similarly to how f-strings process
+    interpolated expressions: it applies conversion and format specification.
+    Unlike normalize(), this always returns a string.
+
+    Args:
+        interp (Interpolation): The interpolation to normalize.
+
+    Returns:
+        str: The formatted string representation of the interpolation.
+    """
+    converted = convert(interp.value, interp.conversion)
+    return format(converted, interp.format_spec)
+
+
+_NOTSET = object()
+
+
+def interpolation_replace(
+    interp: Interpolation,
+    *,
+    value: object = _NOTSET,
+    expression: str = _NOTSET,  # type: ignore
+    conversion: typing.Literal["a", "r", "s"] | None = _NOTSET,  # type: ignore
+    format_spec: str = _NOTSET,  # type: ignore
+) -> Interpolation:
+    """
+    Creates a new Interpolation by selectively replacing attributes of an existing one.
+
+    This function allows you to create a modified copy of an Interpolation object
+    by specifying which attributes to replace. Any attribute not explicitly provided
+    will retain its original value from the input interpolation.
+
+    Args:
+        interp (Interpolation): The original interpolation object.
+        value (object, optional): New value to use instead of the original.
+        expression (str, optional): New expression to use instead of the original.
+        conversion (Literal["a", "r", "s"] | None, optional): New conversion to use.
+        format_spec (str, optional): New format specification to use.
+
+    Returns:
+        Interpolation: A new Interpolation with the specified replacements.
+    """
+    value = interp.value if value is _NOTSET else value
+    expression = interp.expression if expression is _NOTSET else expression
+    conversion = interp.conversion if conversion is _NOTSET else conversion
+    format_spec = interp.format_spec if format_spec is _NOTSET else format_spec
+    return Interpolation(value, expression, conversion, format_spec)  # type: ignore

{tstr-0.2.0 → tstr-0.3.1.dev1}/src/tstr/_template.py

@@ -8,12 +8,12 @@ Conversion: typing.TypeAlias = typing.Literal["a", "r", "s"]
 
 try:
     from string.templatelib import Interpolation, Template  # type: ignore
+
+    TEMPLATE_STRING_SUPPORTED = True
+    StringOrTemplate: typing.TypeAlias = typing.LiteralString | Template  # type: ignore
 except Exception:
     # Fallback to compatible implementation if template strings are not supported
     from ._compat import Interpolation, Template
 
     TEMPLATE_STRING_SUPPORTED = False
     StringOrTemplate: typing.TypeAlias = str | Template  # type: ignore
-else:
-    TEMPLATE_STRING_SUPPORTED = True
-    StringOrTemplate: typing.TypeAlias = typing.LiteralString | Template  # type: ignore

tstr-0.3.1.dev1/src/tstr/_template.pyi

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import sys
+import typing
+
+__all__ = ["Template", "Interpolation", "Conversion"]
+
+Conversion: typing.TypeAlias = typing.Literal["a", "r", "s"]
+
+if sys.version_info >= (3, 14):
+    TEMPLATE_STRING_SUPPORTED = True
+    StringOrTemplate: typing.TypeAlias = typing.LiteralString | Template
+
+    from string.templatelib import Interpolation, Template
+
+else:
+    TEMPLATE_STRING_SUPPORTED = False
+    StringOrTemplate: typing.TypeAlias = str | Template
+
+    from ._compat import Interpolation, Template