refactor(sqlstream): adopt PEP 585 type hinting

- Replace `List`, `Dict`, `Optional`, and `Tuple` with built-in generics `list`, `dict`, `None`, and `tuple`
- Update function signatures across multiple modules to use new type hinting
- Modify import statements to reflect changes in type usage

This refactor aligns the codebase with PEP 585, simplifying type hinting and improving readability. Note that these changes introduce breaking changes due to updated function signatures.

Author: subhayu99

examples/json_nested_paths.py

@@ -6,6 +6,7 @@
 import json
 import tempfile
 from pathlib import Path
+
 from sqlstream import query
 
 # Create example data
@@ -18,30 +19,28 @@
                 "name": "Alice",
                 "transactions": [
                     {"id": "t1", "amount": 50, "status": "completed"},
-                    {"id": "t2", "amount": 75, "status": "pending"}
-                ]
+                    {"id": "t2", "amount": 75, "status": "pending"},
+                ],
             },
             {
                 "id": 2,
                 "name": "Bob",
                 "transactions": [
                     {"id": "t3", "amount": 100, "status": "completed"},
-                    {"id": "t4", "amount": 125, "status": "completed"}
-                ]
+                    {"id": "t4", "amount": 125, "status": "completed"},
+                ],
             },
             {
                 "id": 3,
                 "name": "Charlie",
-                "transactions": [
-                    {"id": "t5", "amount": 200, "status": "failed"}
-                ]
-            }
+                "transactions": [{"id": "t5", "amount": 200, "status": "failed"}],
+            },
         ]
-    }
+    },
 }
 
 # Save to temporary file
-with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
     json.dump(data, f)
     json_file = f.name
 
@@ -58,7 +57,9 @@
 # Example 2: Array indexing
 print("\n2. Get first user's transactions: result.users[0].transactions")
 print("   Query: SELECT * FROM transactions")
-for row in query(f"{json_file}#json:result.users[0].transactions").sql("SELECT * FROM transactions"):
+for row in query(f"{json_file}#json:result.users[0].transactions").sql(
+    "SELECT * FROM transactions"
+):
     print(f"   {row}")
 
 # Example 3: Array flattening
@@ -72,10 +73,12 @@
 # Example 4: Aggregation on flattened data
 print("\n4. Total amount of completed transactions")
 print("   Query: SELECT amount FROM transactions WHERE status = 'completed'")
-completed = list(query(f"{json_file}#json:result.users[].transactions").sql(
-    "SELECT amount FROM transactions WHERE status = 'completed'"
-))
-total = sum(row['amount'] for row in completed)
+completed = list(
+    query(f"{json_file}#json:result.users[].transactions").sql(
+        "SELECT amount FROM transactions WHERE status = 'completed'"
+    )
+)
+total = sum(row["amount"] for row in completed)
 print(f"   Total: ${total} from {len(completed)} transactions")
 
 # Clean up

scripts/generate_api_docs.py

@@ -13,7 +13,6 @@
 import os
 import re
 from pathlib import Path
-from typing import Dict, List
 
 
 class APIDocGenerator:
@@ -51,7 +50,7 @@ def __init__(self, source_dir: str = "sqlstream", docs_dir: str = "docs/api/refe
             "utils": "Utility functions and helpers.",
         }
 
-    def discover_modules(self) -> Dict[str, List[str]]:
+    def discover_modules(self) -> dict[str, list[str]]:
         """Automatically discover all Python modules in the source directory"""
         modules_by_category = {}
 
@@ -87,7 +86,7 @@ def discover_modules(self) -> Dict[str, List[str]]:
 
         return modules_by_category
 
-    def get_classes_and_functions(self, module_path: str) -> Dict[str, List[str]]:
+    def get_classes_and_functions(self, module_path: str) -> dict[str, list[str]]:
         """Extract classes and functions from a Python module"""
         # Convert module path to file path
         relative_path = module_path.replace("sqlstream.", "").replace(".", "/")
@@ -131,7 +130,7 @@ def generate_mkdocstrings_block(
       show_source: true
 """
 
-    def generate_category_doc(self, category_name: str, modules: List[str]) -> str:
+    def generate_category_doc(self, category_name: str, modules: list[str]) -> str:
         """Generate markdown file for a category"""
         title = self.category_titles.get(category_name, f"{category_name.title()} Reference")
         description = self.category_descriptions.get(
@@ -160,7 +159,7 @@ def generate_category_doc(self, category_name: str, modules: List[str]) -> str:
         return "\n".join(lines)
 
     def update_mkdocs_nav(
-        self, modules_by_category: Dict[str, List[str]], mkdocs_file: str = "mkdocs.yml"
+        self, modules_by_category: dict[str, list[str]], mkdocs_file: str = "mkdocs.yml"
     ):
         """Update mkdocs.yml navigation with generated API reference pages using text manipulation"""
         mkdocs_path = Path(mkdocs_file)

sqlstream/cli/formatters/base.py

@@ -4,13 +4,13 @@
 All formatters must implement the format() method.
 """
 
-from typing import Any, Dict, List
+from typing import Any
 
 
 class BaseFormatter:
     """Base class for all output formatters"""
 
-    def format(self, results: List[Dict[str, Any]], **kwargs) -> str:
+    def format(self, results: list[dict[str, Any]], **kwargs) -> str:
         """
         Format query results for output
 

sqlstream/cli/formatters/csv.py

@@ -4,15 +4,15 @@
 
 import csv
 import io
-from typing import Any, Dict, List
+from typing import Any
 
 from sqlstream.cli.formatters.base import BaseFormatter
 
 
 class CSVFormatter(BaseFormatter):
     """Format results as CSV"""
 
-    def format(self, results: List[Dict[str, Any]], **kwargs) -> str:
+    def format(self, results: list[dict[str, Any]], **kwargs) -> str:
         """
         Format results as CSV
 

sqlstream/cli/formatters/json.py

@@ -4,15 +4,15 @@
 
 import json
 import math
-from typing import Any, Dict, List
+from typing import Any
 
 from sqlstream.cli.formatters.base import BaseFormatter
 
 
 class JSONFormatter(BaseFormatter):
     """Format results as JSON"""
 
-    def format(self, results: List[Dict[str, Any]], **kwargs) -> str:
+    def format(self, results: list[dict[str, Any]], **kwargs) -> str:
         """
         Format results as JSON
 

sqlstream/cli/formatters/markdown.py

@@ -2,15 +2,15 @@
 Markdown formatter for documentation and sharing
 """
 
-from typing import Any, Dict, List
+from typing import Any
 
 from sqlstream.cli.formatters.base import BaseFormatter
 
 
 class MarkdownFormatter(BaseFormatter):
     """Format results as a Markdown table"""
 
-    def format(self, results: List[Dict[str, Any]], **kwargs) -> str:
+    def format(self, results: list[dict[str, Any]], **kwargs) -> str:
         """
         Format results as a Markdown table
 

sqlstream/cli/formatters/table.py

@@ -2,7 +2,7 @@
 Rich table formatter for beautiful terminal output
 """
 
-from typing import Any, Dict, List
+from typing import Any
 
 try:
     from rich import box
@@ -22,7 +22,7 @@
 class TableFormatter(BaseFormatter):
     """Format results as a beautiful Rich table"""
 
-    def format(self, results: List[Dict[str, Any]], **kwargs) -> str:
+    def format(self, results: list[dict[str, Any]], **kwargs) -> str:
         """
         Format results as a Rich table
 

sqlstream/cli/interactive.py

@@ -6,7 +6,7 @@
 
 import shutil
 import sys
-from typing import Any, Dict, List
+from typing import Any
 
 try:
     from textual.app import App, ComposeResult
@@ -25,7 +25,7 @@
 
 
 def should_use_interactive(
-    results: List[Dict[str, Any]],
+    results: list[dict[str, Any]],
     force: bool = False,
     no_interactive: bool = False,
     output_file: str = None,
@@ -116,7 +116,7 @@ class TableApp(App):
             ("l", "cursor_right", "Right"),
         ]
 
-        def __init__(self, results: List[Dict[str, Any]], **kwargs):
+        def __init__(self, results: list[dict[str, Any]], **kwargs):
             super().__init__(**kwargs)
             self.results = results
 
@@ -159,7 +159,7 @@ def action_quit(self) -> None:
     TableApp = None
 
 
-def launch_interactive(results: List[Dict[str, Any]]) -> None:
+def launch_interactive(results: list[dict[str, Any]]) -> None:
     """
     Launch interactive table viewer.
 

sqlstream/core/duckdb_executor.py

@@ -7,7 +7,8 @@
 
 from __future__ import annotations
 
-from typing import Any, Callable, Iterator
+from collections.abc import Callable, Iterator
+from typing import Any
 
 from sqlstream.readers.base import BaseReader
 

sqlstream/core/executor.py

@@ -5,7 +5,8 @@
 that implement the query using the Volcano pull-based model.
 """
 
-from typing import Any, Callable, Dict, Iterator, Optional
+from collections.abc import Callable, Iterator
+from typing import Any
 
 from sqlstream.operators.filter import Filter
 from sqlstream.operators.groupby import GroupByOperator
@@ -48,8 +49,8 @@ def execute(
         self,
         ast: SelectStatement,
         reader: BaseReader,
-        reader_factory: Optional[Callable[[str], BaseReader]] = None,
-    ) -> Iterator[Dict[str, Any]]:
+        reader_factory: Callable[[str], BaseReader] | None = None,
+    ) -> Iterator[dict[str, Any]]:
         """
         Execute query and return iterator over results
 
@@ -81,7 +82,7 @@ def _build_plan(
         self,
         ast: SelectStatement,
         reader: BaseReader,
-        reader_factory: Optional[Callable[[str], BaseReader]] = None,
+        reader_factory: Callable[[str], BaseReader] | None = None,
     ):
         """
         Build operator tree from AST
@@ -158,7 +159,7 @@ def explain(
         self,
         ast: SelectStatement,
         reader: BaseReader,
-        reader_factory: Optional[Callable[[str], BaseReader]] = None,
+        reader_factory: Callable[[str], BaseReader] | None = None,
     ) -> str:
         """
         Explain query execution plan (for debugging)