sqlspec 0.26.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

sqlspec/utils/type_guards.py

@@ -7,7 +7,9 @@ understand type narrowing, replacing defensive hasattr() and duck typing pattern
 from collections.abc import Sequence
 from collections.abc import Set as AbstractSet
 from functools import lru_cache
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, cast
+
+from typing_extensions import is_typeddict
 
 from sqlspec.typing import (
     ATTRS_INSTALLED,
@@ -24,9 +26,9 @@ from sqlspec.typing import (
 
 if TYPE_CHECKING:
     from dataclasses import Field
+    from typing import TypeGuard
 
     from sqlglot import exp
-    from typing_extensions import TypeGuard
 
     from sqlspec._typing import AttrsInstanceStub, BaseModelStub, DTODataStub, StructStub
     from sqlspec.builder import Select
@@ -46,6 +48,7 @@ if TYPE_CHECKING:
         ObjectStoreItemProtocol,
         ParameterValueProtocol,
         SQLBuilderProtocol,
+        SupportsArrowResults,
         WithMethodProtocol,
     )
     from sqlspec.typing import SupportedSchemaModel
@@ -100,6 +103,7 @@ __all__ = (
     "is_indexable_row",
     "is_iterable_parameters",
     "is_limit_offset_filter",
+    "is_local_path",
     "is_msgspec_struct",
     "is_msgspec_struct_with_field",
     "is_msgspec_struct_without_field",
@@ -117,8 +121,11 @@ __all__ = (
     "is_select_builder",
     "is_statement_filter",
     "is_string_literal",
+    "is_typed_dict",
     "is_typed_parameter",
     "schema_dump",
+    "supports_arrow_native",
+    "supports_arrow_results",
     "supports_limit",
     "supports_offset",
     "supports_order_by",
@@ -126,6 +133,18 @@ __all__ = (
 )
 
 
+def is_typed_dict(obj: Any) -> "TypeGuard[type]":
+    """Check if an object is a TypedDict class.
+
+    Args:
+        obj: The object to check
+
+    Returns:
+        True if the object is a TypedDict class, False otherwise
+    """
+    return is_typeddict(obj)
+
+
 def is_statement_filter(obj: Any) -> "TypeGuard[StatementFilter]":
     """Check if an object implements the StatementFilter protocol.
 
@@ -434,7 +453,7 @@ def is_msgspec_struct_without_field(obj: Any, field_name: str) -> "TypeGuard[Str
 
 
 @lru_cache(maxsize=500)
-def _detect_rename_pattern(field_name: str, encode_name: str) -> "Optional[str]":
+def _detect_rename_pattern(field_name: str, encode_name: str) -> "str | None":
     """Detect the rename pattern by comparing field name transformations.
 
     Args:
@@ -458,7 +477,7 @@ def _detect_rename_pattern(field_name: str, encode_name: str) -> "Optional[str]"
     return None
 
 
-def get_msgspec_rename_config(schema_type: type) -> "Optional[str]":
+def get_msgspec_rename_config(schema_type: type) -> "str | None":
     """Extract msgspec rename configuration from a struct type.
 
     Analyzes field name transformations to detect the rename pattern used by msgspec.
@@ -611,7 +630,7 @@ def is_schema(obj: Any) -> "TypeGuard[SupportedSchemaModel]":
     )
 
 
-def is_schema_or_dict(obj: Any) -> "TypeGuard[Union[SupportedSchemaModel, dict[str, Any]]]":
+def is_schema_or_dict(obj: Any) -> "TypeGuard[SupportedSchemaModel | dict[str, Any]]":
     """Check if a value is a msgspec Struct, Pydantic model, or dict.
 
     Args:
@@ -649,7 +668,7 @@ def is_schema_without_field(obj: Any, field_name: str) -> "TypeGuard[SupportedSc
     return not is_schema_with_field(obj, field_name)
 
 
-def is_schema_or_dict_with_field(obj: Any, field_name: str) -> "TypeGuard[Union[SupportedSchemaModel, dict[str, Any]]]":
+def is_schema_or_dict_with_field(obj: Any, field_name: str) -> "TypeGuard[SupportedSchemaModel | dict[str, Any]]":
     """Check if a value is a msgspec Struct, Pydantic model, or dict with a specific field.
 
     Args:
@@ -662,9 +681,7 @@ def is_schema_or_dict_with_field(obj: Any, field_name: str) -> "TypeGuard[Union[
     return is_schema_with_field(obj, field_name) or is_dict_with_field(obj, field_name)
 
 
-def is_schema_or_dict_without_field(
-    obj: Any, field_name: str
-) -> "TypeGuard[Union[SupportedSchemaModel, dict[str, Any]]]":
+def is_schema_or_dict_without_field(obj: Any, field_name: str) -> "TypeGuard[SupportedSchemaModel | dict[str, Any]]":
     """Check if a value is a msgspec Struct, Pydantic model, or dict without a specific field.
 
     Args:
@@ -721,8 +738,8 @@ def extract_dataclass_fields(
     obj: "DataclassProtocol",
     exclude_none: bool = False,
     exclude_empty: bool = False,
-    include: "Optional[AbstractSet[str]]" = None,
-    exclude: "Optional[AbstractSet[str]]" = None,
+    include: "AbstractSet[str] | None" = None,
+    exclude: "AbstractSet[str] | None" = None,
 ) -> "tuple[Field[Any], ...]":
     """Extract dataclass fields.
 
@@ -767,8 +784,8 @@ def extract_dataclass_items(
     obj: "DataclassProtocol",
     exclude_none: bool = False,
     exclude_empty: bool = False,
-    include: "Optional[AbstractSet[str]]" = None,
-    exclude: "Optional[AbstractSet[str]]" = None,
+    include: "AbstractSet[str] | None" = None,
+    exclude: "AbstractSet[str] | None" = None,
 ) -> "tuple[tuple[str, Any], ...]":
     """Extract name-value pairs from a dataclass instance.
 
@@ -791,7 +808,7 @@ def dataclass_to_dict(
     exclude_none: bool = False,
     exclude_empty: bool = False,
     convert_nested: bool = True,
-    exclude: "Optional[AbstractSet[str]]" = None,
+    exclude: "AbstractSet[str] | None" = None,
 ) -> "dict[str, Any]":
     """Convert a dataclass instance to a dictionary.
 
@@ -978,7 +995,7 @@ def has_attr(obj: Any, attr: str) -> bool:
     return True
 
 
-def get_node_this(node: "exp.Expression", default: Optional[Any] = None) -> Any:
+def get_node_this(node: "exp.Expression", default: Any | None = None) -> Any:
     """Safely get the 'this' attribute from a SQLGlot node.
 
     Args:
@@ -1010,7 +1027,7 @@ def has_this_attribute(node: "exp.Expression") -> bool:
     return True
 
 
-def get_node_expressions(node: "exp.Expression", default: Optional[Any] = None) -> Any:
+def get_node_expressions(node: "exp.Expression", default: Any | None = None) -> Any:
     """Safely get the 'expressions' attribute from a SQLGlot node.
 
     Args:
@@ -1042,7 +1059,7 @@ def has_expressions_attribute(node: "exp.Expression") -> bool:
     return True
 
 
-def get_literal_parent(literal: "exp.Expression", default: Optional[Any] = None) -> Any:
+def get_literal_parent(literal: "exp.Expression", default: Any | None = None) -> Any:
     """Safely get the 'parent' attribute from a SQLGlot literal.
 
     Args:
@@ -1113,7 +1130,7 @@ def is_number_literal(literal: "exp.Literal") -> bool:
         return False
 
 
-def get_initial_expression(context: Any) -> "Optional[exp.Expression]":
+def get_initial_expression(context: Any) -> "exp.Expression | None":
     """Safely get initial_expression from context.
 
     Args:
@@ -1128,7 +1145,7 @@ def get_initial_expression(context: Any) -> "Optional[exp.Expression]":
         return None
 
 
-def expression_has_limit(expr: "Optional[exp.Expression]") -> bool:
+def expression_has_limit(expr: "exp.Expression | None") -> bool:
     """Check if an expression has a limit clause.
 
     Args:
@@ -1160,7 +1177,7 @@ def get_value_attribute(obj: Any) -> Any:
         return obj
 
 
-def get_param_style_and_name(param: Any) -> "tuple[Optional[str], Optional[str]]":
+def get_param_style_and_name(param: Any) -> "tuple[str | None, str | None]":
     """Safely get style and name attributes from a parameter.
 
     Args:
@@ -1242,3 +1259,102 @@ def has_expression_and_parameters(obj: Any) -> bool:
         True if the object has both attributes, False otherwise
     """
     return hasattr(obj, "expression") and hasattr(obj, "parameters")
+
+
+WINDOWS_DRIVE_PATTERN_LENGTH = 3
+
+
+def is_local_path(uri: str) -> bool:
+    r"""Check if URI represents a local filesystem path.
+
+    Detects local paths including:
+    - file:// URIs
+    - Absolute paths (Unix: /, Windows: C:\\)
+    - Relative paths (., .., ~)
+
+    Args:
+        uri: URI or path string to check.
+
+    Returns:
+        True if uri is a local path, False for remote URIs.
+
+    Examples:
+        >>> is_local_path("file:///data/file.txt")
+        True
+        >>> is_local_path("/absolute/path")
+        True
+        >>> is_local_path("s3://bucket/key")
+        False
+    """
+    if not uri:
+        return False
+
+    if "://" in uri and not uri.startswith("file://"):
+        return False
+
+    if uri.startswith("file://"):
+        return True
+
+    if uri.startswith("/"):
+        return True
+
+    if uri.startswith((".", "~")):
+        return True
+
+    if len(uri) >= WINDOWS_DRIVE_PATTERN_LENGTH and uri[1:3] == ":\\":
+        return True
+
+    return "/" in uri or "\\" in uri
+
+
+def supports_arrow_native(backend: Any) -> bool:
+    """Check if storage backend supports native Arrow operations.
+
+    Some storage backends (like certain obstore stores) have native
+    Arrow read/write support, which is faster than going through bytes.
+
+    Args:
+        backend: Storage backend instance to check.
+
+    Returns:
+        True if backend has native read_arrow/write_arrow methods.
+
+    Examples:
+        >>> from sqlspec.storage.backends.obstore import ObStoreBackend
+        >>> backend = ObStoreBackend("file:///tmp")
+        >>> supports_arrow_native(backend)
+        False
+    """
+    from sqlspec.protocols import ObjectStoreProtocol
+
+    if not isinstance(backend, ObjectStoreProtocol):
+        return False
+
+    try:
+        store = backend.store  # type: ignore[attr-defined]
+        return callable(getattr(store, "read_arrow", None))
+    except AttributeError:
+        return False
+
+
+def supports_arrow_results(obj: Any) -> "TypeGuard[SupportsArrowResults]":
+    """Check if object supports Arrow result format.
+
+    Use this type guard to check if a driver or adapter supports returning
+    query results in Apache Arrow format via select_to_arrow() method.
+
+    Args:
+        obj: Object to check for Arrow results support.
+
+    Returns:
+        True if object implements SupportsArrowResults protocol.
+
+    Examples:
+        >>> from sqlspec.adapters.duckdb import DuckDBDriver
+        >>> driver = DuckDBDriver(...)
+        >>> supports_arrow_results(driver)
+        True
+    """
+    from sqlspec.protocols import SupportsArrowResults
+
+    return isinstance(obj, SupportsArrowResults)