software-dlc-tile 0.2.2__py3-none-any.whl

software_dlc_tile/__init__.py

@@ -0,0 +1,10 @@
+from .first_class import encode_first_class_tables_to_tile
+from .text import escape_tile_text, resolve_tile_delimiter, unescape_tile_text
+
+__all__ = [
+    "encode_first_class_tables_to_tile",
+    "escape_tile_text",
+    "resolve_tile_delimiter",
+    "unescape_tile_text",
+]
+

software_dlc_tile/first_class.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from .text import escape_tile_text, resolve_tile_delimiter
+
+
+JsonTileFirstClassCell = str | int | float | bool | None
+
+
+def encode_first_class_tables_to_tile(document: Mapping[str, Any]) -> str:
+    delimiter = resolve_tile_delimiter(str(document.get("delimiter", "tab")))
+    tables = document.get("tables")
+    if not isinstance(tables, Sequence) or isinstance(tables, (str, bytes)):
+        raise TypeError("First-class TILE document requires a tables sequence")
+
+    return "\n\n".join(_encode_first_class_table(table, delimiter) for table in tables)
+
+
+def _encode_first_class_table(table: Any, delimiter: str) -> str:
+    if not isinstance(table, Mapping):
+        raise TypeError("First-class TILE tables must be mappings")
+
+    columns = table.get("columns")
+    rows = table.get("rows")
+    if not isinstance(columns, Sequence) or isinstance(columns, (str, bytes)):
+        raise TypeError("First-class TILE table columns must be a sequence")
+
+    if not isinstance(rows, Sequence) or isinstance(rows, (str, bytes)):
+        raise TypeError("First-class TILE table rows must be a sequence")
+
+    lines = [
+        _encode_first_class_table_definition(table, delimiter),
+        delimiter.join(_format_first_class_table_column(column, delimiter) for column in columns),
+    ]
+
+    for row in rows:
+        if not isinstance(row, Sequence) or isinstance(row, (str, bytes)):
+            raise TypeError("First-class TILE table rows must contain cell sequences")
+        lines.append(delimiter.join(_format_first_class_table_cell(cell, delimiter) for cell in row))
+
+    return "\n".join(lines)
+
+
+def _format_first_class_table_column(column: Any, delimiter: str) -> str:
+    if isinstance(column, str):
+        return escape_tile_text(column, delimiter)
+
+    if not isinstance(column, Mapping):
+        raise TypeError("First-class TILE columns must be strings or embedded column mappings")
+
+    embedded_columns = column.get("embedded_columns")
+    if (
+        not isinstance(embedded_columns, Sequence)
+        or isinstance(embedded_columns, (str, bytes))
+        or len(embedded_columns) == 0
+    ):
+        raise ValueError("First-class TILE embedded column groups cannot be empty")
+
+    join_delimiter = ";" if delimiter == "," else ","
+    return (
+        "["
+        + join_delimiter.join(
+            _format_first_class_embedded_column_name(embedded_column, delimiter)
+            for embedded_column in embedded_columns
+        )
+        + "]"
+    )
+
+
+def _format_first_class_embedded_column_name(column: Any, delimiter: str) -> str:
+    if not isinstance(column, str):
+        raise TypeError("First-class TILE embedded column names must be strings")
+
+    if "[" in column or "]" in column or (delimiter != "," and "," in column):
+        raise ValueError(
+            "First-class TILE embedded column names cannot contain comma or brackets"
+        )
+
+    return escape_tile_text(column, delimiter)
+
+
+def _encode_first_class_table_definition(table: Mapping[str, Any], delimiter: str) -> str:
+    table_id = table.get("id")
+    if not isinstance(table_id, str):
+        raise TypeError("First-class TILE table id must be a string")
+
+    definition_parts = [table_id]
+    kind = table.get("kind")
+    path = table.get("path")
+
+    if kind is not None and not isinstance(kind, str):
+        raise TypeError("First-class TILE table kind must be a string")
+
+    if path is not None and not isinstance(path, str):
+        raise TypeError("First-class TILE table path must be a string")
+
+    if kind or path:
+        definition_parts.append(kind or "")
+
+    if path:
+        definition_parts.append(path)
+
+    return delimiter.join(escape_tile_text(part, delimiter) for part in definition_parts)
+
+
+def _format_first_class_table_cell(cell: Any, delimiter: str) -> str:
+    if cell is None:
+        return ""
+
+    return escape_tile_text(_format_cell_value(cell), delimiter)
+
+
+def _format_cell_value(cell: JsonTileFirstClassCell) -> str:
+    if isinstance(cell, bool):
+        return "true" if cell else "false"
+
+    if isinstance(cell, str):
+        return cell
+
+    if isinstance(cell, int):
+        return str(cell)
+
+    if isinstance(cell, float):
+        if not math.isfinite(cell):
+            raise ValueError("First-class TILE only supports finite numbers")
+        return _format_javascript_number(cell)
+
+    raise TypeError("First-class TILE cells must be strings, numbers, booleans, or None")
+
+
+def _format_javascript_number(value: float) -> str:
+    if value == 0:
+        return "0"
+
+    sign = "-" if value < 0 else ""
+    digits, decimal_exponent = _decimal_parts(abs(value))
+    digit_count = len(digits)
+
+    if digit_count <= decimal_exponent <= 21:
+        return f"{sign}{digits}{'0' * (decimal_exponent - digit_count)}"
+
+    if 0 < decimal_exponent <= 21:
+        return f"{sign}{digits[:decimal_exponent]}.{digits[decimal_exponent:]}"
+
+    if -6 < decimal_exponent <= 0:
+        return f"{sign}0.{'0' * (-decimal_exponent)}{digits}"
+
+    mantissa = digits if digit_count == 1 else f"{digits[0]}.{digits[1:]}"
+    exponent = decimal_exponent - 1
+    exponent_sign = "+" if exponent >= 0 else ""
+    return f"{sign}{mantissa}e{exponent_sign}{exponent}"
+
+
+def _decimal_parts(value: float) -> tuple[str, int]:
+    text = repr(value)
+    if "e" in text or "E" in text:
+        mantissa_text, exponent_text = text.lower().split("e", 1)
+        exponent = int(exponent_text)
+        integer_part, _, fractional_part = mantissa_text.partition(".")
+        digits = f"{integer_part}{fractional_part}".lstrip("0")
+        return digits, exponent + len(integer_part)
+
+    integer_part, _, fractional_part = text.partition(".")
+    if integer_part == "0":
+        trimmed_fractional_part = fractional_part.rstrip("0")
+        leading_zero_count = len(trimmed_fractional_part) - len(
+            trimmed_fractional_part.lstrip("0")
+        )
+        digits = trimmed_fractional_part.lstrip("0")
+        return digits or "0", -leading_zero_count
+
+    digits = f"{integer_part}{fractional_part}".rstrip("0")
+    return digits, len(integer_part)

software_dlc_tile/text.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+
+def escape_tile_text(value: str, delimiter: str = "\t") -> str:
+    result: list[str] = []
+
+    for char in value:
+        if char == "\\":
+            result.append("\\\\")
+        elif char == "\t":
+            result.append("\\t")
+        elif char == "\n":
+            result.append("\\n")
+        elif char == "\r":
+            result.append("\\r")
+        elif char == " " and delimiter == " ":
+            result.append("\\s")
+        elif char == delimiter and delimiter != "\t":
+            result.append(f"\\{char}")
+        else:
+            result.append(char)
+
+    return "".join(result)
+
+
+def unescape_tile_text(value: str) -> str:
+    result: list[str] = []
+    index = 0
+
+    while index < len(value):
+        char = value[index]
+        if char != "\\":
+            result.append(char)
+            index += 1
+            continue
+
+        if index + 1 >= len(value):
+            raise ValueError("Invalid TILE escape: trailing backslash")
+
+        escaped_char = value[index + 1]
+        if escaped_char == "t":
+            result.append("\t")
+        elif escaped_char == "n":
+            result.append("\n")
+        elif escaped_char == "r":
+            result.append("\r")
+        elif escaped_char == "\\":
+            result.append("\\")
+        elif escaped_char == "s":
+            result.append(" ")
+        elif escaped_char == ",":
+            result.append(",")
+        elif escaped_char == "|":
+            result.append("|")
+        elif escaped_char == "@":
+            result.append("@")
+        elif escaped_char == ":":
+            result.append(":")
+        else:
+            raise ValueError(f"Invalid TILE escape: \\{escaped_char}")
+
+        index += 2
+
+    return "".join(result)
+
+
+def resolve_tile_delimiter(delimiter: str) -> str:
+    if delimiter == "comma":
+        return ","
+
+    if delimiter == "pipe":
+        return "|"
+
+    if delimiter == "space":
+        return " "
+
+    return "\t"

software_dlc_tile-0.2.2.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: software-dlc-tile
+Version: 0.2.2
+Summary: Python helpers for first-class TILE prompt tables.
+Project-URL: Homepage, https://github.com/SoftwareDLC/tile#readme
+Project-URL: Repository, https://github.com/SoftwareDLC/tile
+Project-URL: Issues, https://github.com/SoftwareDLC/tile/issues
+Author: SoftwareDLC
+License-Expression: MIT
+License-File: LICENSE
+Keywords: json,llm,prompt-engineering,prompt-optimization,structured-data,tile
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# software-dlc-tile
+
+Python helpers for first-class TILE prompt tables.
+
+This package is an incubating Python surface for `@software-dlc/tile`. It starts
+with first-class TILE because that is the smallest useful API for Python, data,
+and LLM users who already have structured rows and want compact prompt context.
+
+```python
+from software_dlc_tile import encode_first_class_tables_to_tile
+
+tile = encode_first_class_tables_to_tile({
+    "delimiter": "pipe",
+    "tables": [
+        {
+            "id": "packages",
+            "columns": ["name", {"embedded_columns": ["dependency"]}],
+            "rows": [
+                ["fastapi", "pydantic"],
+                ["", "starlette"],
+            ],
+        }
+    ],
+})
+```
+
+This first Python package does not yet implement lossless JSON-to-TILE encoding
+or TILE-to-JSON decoding. Those should come after shared conformance coverage is
+expanded for the full wire format.

software_dlc_tile-0.2.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+software_dlc_tile/__init__.py,sha256=wHl4SImsT8ZkKsdA92P3HEWCPSw-ZPX8R8Z1vklssKY,275
+software_dlc_tile/first_class.py,sha256=__IzrlkG73Dt8WrBfcG0rG5jieIJgQX-gONxrMHEf5E,6180
+software_dlc_tile/text.py,sha256=pm4JQjUTonYAiCHI2reg3cKpHlt-7MOJ_fDH8HXAa8o,1970
+software_dlc_tile-0.2.2.dist-info/METADATA,sha256=QoE7DwTZf8sIof1R7t9ck__AcfETzwGMjpD8IIwXzaA,1840
+software_dlc_tile-0.2.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+software_dlc_tile-0.2.2.dist-info/licenses/LICENSE,sha256=ctCIPr249tArnEAdWMrn1Bm0CH3Mjo8YEjgCBwcGjns,1068
+software_dlc_tile-0.2.2.dist-info/RECORD,,

software_dlc_tile-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

software_dlc_tile-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SoftwareDLC
+
+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.