sqlspec 0.47.0__cp314-cp314-win_amd64.whl

sqlspec/utils/text.py

@@ -0,0 +1,109 @@
+"""Text processing utilities for SQLSpec.
+
+Provides functions for string manipulation including case conversion,
+slugification, and email validation. Used primarily for identifier
+generation and data validation.
+"""
+
+import re
+import unicodedata
+from functools import lru_cache
+
+__all__ = ("camelize", "kebabize", "pascalize", "slugify", "snake_case")
+
+
+_SLUGIFY_REMOVE_NON_ALPHANUMERIC = re.compile(r"[^\w]+", re.UNICODE)
+_SLUGIFY_HYPHEN_COLLAPSE = re.compile(r"-+")
+
+_SNAKE_CASE_LOWER_OR_DIGIT_TO_UPPER = re.compile(r"(?<=[a-z0-9])(?=[A-Z])", re.UNICODE)
+_SNAKE_CASE_UPPER_TO_UPPER_LOWER = re.compile(r"(?<=[A-Z])(?=[A-Z][a-z])", re.UNICODE)
+_SNAKE_CASE_HYPHEN_SPACE = re.compile(r"[.\s@-]+", re.UNICODE)
+_SNAKE_CASE_REMOVE_NON_WORD = re.compile(r"[^\w]+", re.UNICODE)
+_SNAKE_CASE_MULTIPLE_UNDERSCORES = re.compile(r"__+", re.UNICODE)
+
+
+def slugify(value: str, allow_unicode: bool = False, separator: str | None = None) -> str:
+    """Convert a string to a URL-friendly slug.
+
+    Args:
+        value: The string to slugify
+        allow_unicode: Allow unicode characters in slug.
+        separator: Separator character for word boundaries. Defaults to "-".
+
+    Returns:
+        A slugified string.
+    """
+    if allow_unicode:
+        value = unicodedata.normalize("NFKC", value)
+    else:
+        value = unicodedata.normalize("NFKD", value).encode("ascii", "ignore").decode("ascii")
+    value = value.lower().strip()
+    sep = separator if separator is not None else "-"
+    if not sep:
+        return _SLUGIFY_REMOVE_NON_ALPHANUMERIC.sub("", value)
+    value = _SLUGIFY_REMOVE_NON_ALPHANUMERIC.sub(sep, value)
+    if sep == "-":
+        value = value.strip("-")
+        return _SLUGIFY_HYPHEN_COLLAPSE.sub("-", value)
+    value = re.sub(rf"^{re.escape(sep)}+|{re.escape(sep)}+$", "", value)
+    return re.sub(rf"{re.escape(sep)}+", sep, value)
+
+
+@lru_cache(maxsize=100)
+def camelize(string: str) -> str:
+    """Convert a string to camel case.
+
+    Args:
+        string: The string to convert.
+
+    Returns:
+        The converted string.
+    """
+    return "".join(word if index == 0 else word.capitalize() for index, word in enumerate(string.split("_")))
+
+
+@lru_cache(maxsize=100)
+def kebabize(string: str) -> str:
+    """Convert a string to kebab-case.
+
+    Args:
+        string: The string to convert.
+
+    Returns:
+        The kebab-case version of the string.
+    """
+    return "-".join(word.lower() for word in string.split("_") if word)
+
+
+@lru_cache(maxsize=100)
+def pascalize(string: str) -> str:
+    """Convert a string to PascalCase.
+
+    Args:
+        string: The string to convert.
+
+    Returns:
+        The PascalCase version of the string.
+    """
+    return "".join(word.capitalize() for word in string.split("_") if word)
+
+
+@lru_cache(maxsize=100)
+def snake_case(string: str) -> str:
+    """Convert a string to snake_case.
+
+    Args:
+        string: The string to convert.
+
+    Returns:
+        The snake_case version of the string.
+    """
+    if not string:
+        return ""
+    s = _SNAKE_CASE_HYPHEN_SPACE.sub("_", string)
+    s = _SNAKE_CASE_REMOVE_NON_WORD.sub("", s)
+    s = _SNAKE_CASE_LOWER_OR_DIGIT_TO_UPPER.sub("_", s)
+    s = _SNAKE_CASE_UPPER_TO_UPPER_LOWER.sub("_", s)
+    s = s.lower()
+    s = s.strip("_")
+    return _SNAKE_CASE_MULTIPLE_UNDERSCORES.sub("_", s)

sqlspec/utils/type_converters.py

@@ -0,0 +1,216 @@
+"""Reusable converter builders for parameter configuration."""
+
+import decimal
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.utils.dispatch import TypeDispatcher
+
+if TYPE_CHECKING:
+    import datetime
+    from collections.abc import Callable, Sequence
+
+__all__ = (
+    "DEFAULT_DECIMAL_MODE",
+    "build_decimal_converter",
+    "build_json_list_converter",
+    "build_json_tuple_converter",
+    "build_nested_decimal_normalizer",
+    "build_time_iso_converter",
+    "build_uuid_coercions",
+    "should_json_encode_sequence",
+)
+
+JSON_NESTED_TYPES: "tuple[type[Any], ...]" = (dict, list, tuple)
+DEFAULT_DECIMAL_MODE: str = "preserve"
+_DECIMAL_NORMALIZER_DISPATCHER = TypeDispatcher["Callable[['_DecimalNormalizer', Any], Any]"]()
+
+
+def _decimal_identity(value: "decimal.Decimal") -> "decimal.Decimal":
+    return value
+
+
+def _decimal_to_string(value: "decimal.Decimal") -> str:
+    return str(value)
+
+
+def _decimal_to_float(value: "decimal.Decimal") -> float:
+    return float(value)
+
+
+class _JsonListConverter:
+    __slots__ = ("_preserve_arrays", "_serializer")
+
+    def __init__(self, serializer: "Callable[[Any], str]", preserve_arrays: bool) -> None:
+        self._serializer = serializer
+        self._preserve_arrays = preserve_arrays
+
+    def __call__(self, value: "list[Any]") -> Any:
+        if not value:
+            return value
+        if self._preserve_arrays and not should_json_encode_sequence(value):
+            return value
+        return self._serializer(value)
+
+
+class _JsonTupleConverter:
+    __slots__ = ("_list_converter",)
+
+    def __init__(self, list_converter: _JsonListConverter) -> None:
+        self._list_converter = list_converter
+
+    def __call__(self, value: "tuple[Any, ...]") -> Any:
+        if not value:
+            return value
+        return self._list_converter(list(value))
+
+
+class _DecimalNormalizer:
+    __slots__ = ("_decimal_converter",)
+
+    def __init__(self, decimal_converter: "Callable[[decimal.Decimal], Any]") -> None:
+        self._decimal_converter = decimal_converter
+
+    def __call__(self, value: Any) -> Any:
+        handler = _DECIMAL_NORMALIZER_DISPATCHER.get(value)
+        if handler is None:
+            return value
+        return handler(self, value)
+
+    def convert_decimal(self, value: "decimal.Decimal") -> Any:
+        return self._decimal_converter(value)
+
+
+def _normalize_decimal_value(normalizer: "_DecimalNormalizer", value: Any) -> Any:
+    return normalizer.convert_decimal(value)
+
+
+def _normalize_decimal_list(normalizer: "_DecimalNormalizer", value: Any) -> Any:
+    normalized_list: list[Any] | None = None
+    for index, item in enumerate(value):
+        normalized_item = normalizer(item)
+        if normalized_list is None:
+            if normalized_item is item:
+                continue
+            normalized_list = list(value[:index])
+        normalized_list.append(normalized_item)
+    return value if normalized_list is None else normalized_list
+
+
+def _normalize_decimal_tuple(normalizer: "_DecimalNormalizer", value: Any) -> Any:
+    normalized_tuple: list[Any] | None = None
+    for index, item in enumerate(value):
+        normalized_item = normalizer(item)
+        if normalized_tuple is None:
+            if normalized_item is item:
+                continue
+            normalized_tuple = list(value[:index])
+        normalized_tuple.append(normalized_item)
+    return value if normalized_tuple is None else tuple(normalized_tuple)
+
+
+def _normalize_decimal_dict(normalizer: "_DecimalNormalizer", value: Any) -> Any:
+    normalized_dict: dict[Any, Any] | None = None
+    for key, item in value.items():
+        normalized_item = normalizer(item)
+        if normalized_dict is None:
+            if normalized_item is item:
+                continue
+            normalized_dict = dict(value)
+        normalized_dict[key] = normalized_item
+    return value if normalized_dict is None else normalized_dict
+
+
+_DECIMAL_NORMALIZER_DISPATCHER.register(decimal.Decimal, _normalize_decimal_value)
+_DECIMAL_NORMALIZER_DISPATCHER.register(list, _normalize_decimal_list)
+_DECIMAL_NORMALIZER_DISPATCHER.register(tuple, _normalize_decimal_tuple)
+_DECIMAL_NORMALIZER_DISPATCHER.register(dict, _normalize_decimal_dict)
+
+
+def _time_iso_convert(value: "datetime.date | datetime.datetime | datetime.time") -> str:
+    return value.isoformat()
+
+
+def should_json_encode_sequence(sequence: "Sequence[Any]") -> bool:
+    """Return ``True`` when a sequence should be JSON serialized."""
+
+    return any(isinstance(item, JSON_NESTED_TYPES) for item in sequence if item is not None)
+
+
+def build_json_list_converter(
+    serializer: "Callable[[Any], str]", *, preserve_arrays: bool = True
+) -> "Callable[[list[Any]], Any]":
+    """Create a converter that serializes lists containing nested structures."""
+    return _JsonListConverter(serializer, preserve_arrays)
+
+
+def build_json_tuple_converter(
+    serializer: "Callable[[Any], str]", *, preserve_arrays: bool = True
+) -> "Callable[[tuple[Any, ...]], Any]":
+    """Create a converter that mirrors list handling for tuples."""
+    list_converter = _JsonListConverter(serializer, preserve_arrays)
+    return _JsonTupleConverter(list_converter)
+
+
+def build_decimal_converter(*, mode: str = DEFAULT_DECIMAL_MODE) -> "Callable[[decimal.Decimal], Any]":
+    """Create a Decimal converter according to the desired mode."""
+
+    if mode == "preserve":
+        return _decimal_identity
+    if mode == "string":
+        return _decimal_to_string
+    if mode == "float":
+        return _decimal_to_float
+
+    msg = f"Unsupported decimal converter mode: {mode}"
+    raise ValueError(msg)
+
+
+def build_nested_decimal_normalizer(*, mode: str = DEFAULT_DECIMAL_MODE) -> "Callable[[Any], Any]":
+    """Return a callable that coerces ``Decimal`` values within nested structures."""
+    decimal_converter = build_decimal_converter(mode=mode)
+    return _DecimalNormalizer(decimal_converter)
+
+
+def build_time_iso_converter() -> "Callable[[datetime.date | datetime.datetime | datetime.time], str]":
+    """Return a converter that formats temporal values using ISO 8601."""
+    return _time_iso_convert
+
+
+def _uuid_to_string(value: Any) -> str:
+    return str(value)
+
+
+def _uuid_utils_to_stdlib(value: Any) -> Any:
+    import uuid as _uuid_mod
+
+    return _uuid_mod.UUID(bytes=value.bytes)
+
+
+def build_uuid_coercions(*, native: bool = False) -> "dict[type[Any], Callable[[Any], Any]]":
+    """Return coercions for UUID parameter binding.
+
+    Includes coercions for ``uuid_utils.UUID`` (if installed) and standard
+    library ``uuid.UUID``.
+
+    Args:
+        native: When ``True``, convert ``uuid_utils.UUID`` → ``uuid.UUID``
+            (via ``.bytes``, for drivers that bind ``uuid.UUID`` natively).
+            When ``False`` (default), convert to ``str`` (for drivers that
+            need a plain string, e.g. DuckDB/SQLite).
+    """
+    import uuid as _uuid_mod
+
+    coercions: dict[type[Any], Callable[[Any], Any]] = {}
+
+    if not native:
+        coercions[_uuid_mod.UUID] = _uuid_to_string
+
+    try:
+        import uuid_utils as _uuid_utils_mod  # pyright: ignore[reportMissingImports]
+
+        converter = _uuid_utils_to_stdlib if native else _uuid_to_string
+        coercions[_uuid_utils_mod.UUID] = converter
+    except ImportError:
+        pass
+
+    return coercions