fix: NOT IN NULL semantics, lock decode safety, tighten Any types

- NOT IN (val, NULL) now returns UNKNOWN (FALSE in WHERE) per SQL spec
- Lock file reader handles corrupted/non-ASCII content gracefully
- reflection.py: connection params typed as ExcelConnection (TYPE_CHECKING)
- connection.py: credential param uses Credential type alias
- Add 4 tests for NOT IN/IN NULL semantics
- Add .hypothesis and :memory: to .gitignore

Author: yeongseon

.gitignore

@@ -39,3 +39,7 @@ site/
 
 # OS
 .DS_Store
+
+# Test artifacts
+.hypothesis/
+:memory:

src/excel_dbapi/connection.py

@@ -13,6 +13,11 @@
 from .engines.result import ExecutionResult
 from .exceptions import InterfaceError, NotSupportedError, OperationalError
 
+#: Credential accepted by cloud backends.  Concrete forms:
+#: ``str`` (static token), ``TokenProvider`` protocol,
+#: azure-identity credential (``get_token(scope)``), or zero-arg callable.
+Credential = str | Callable[[], str] | object | None
+
 _MUTATING_ACTIONS = frozenset({"INSERT", "CREATE", "DROP", "UPDATE", "DELETE", "ALTER"})
 
 P = ParamSpec("P")
@@ -59,7 +64,7 @@ def __init__(
         create: bool = False,
         data_only: bool = True,
         sanitize_formulas: bool = True,
-        credential: Any = None,
+        credential: Credential = None,
         **backend_options: Any,
     ):
         """

src/excel_dbapi/engines/base.py

@@ -82,9 +82,9 @@ def _acquire_lock(self) -> None:
 
     def _clear_stale_lock(self) -> bool:
         try:
-            with open(self._lock_path, "r", encoding="ascii") as handle:
+            with open(self._lock_path, "r", encoding="ascii", errors="replace") as handle:
                 raw_pid = handle.read().strip()
-        except OSError:
+        except (OSError, UnicodeDecodeError):
             return False
 
         try:

src/excel_dbapi/executor.py

@@ -2955,12 +2955,17 @@ def _resolve_operand(operand: Any, *, as_column: bool) -> Any:
             else:
                 candidates = (resolved_candidates,)
 
+            has_null = False
             for candidate in candidates:
                 candidate_value = _resolve_operand(candidate, as_column=False)
+                if candidate_value is None:
+                    has_null = True
+                    continue
                 left, right = self._coerce_for_compare(row_value, candidate_value)
                 if left == right:
                     return False
-            return True
+            # SQL: x NOT IN (..., NULL, ...) is UNKNOWN when no match → FALSE in WHERE
+            return not has_null
         if operator == "BETWEEN":
             if row_value is None:
                 return False

src/excel_dbapi/reflection.py

@@ -4,35 +4,38 @@
 
 import datetime
 from collections import Counter
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any
 
 from excel_dbapi.engines.base import TableData
 
+if TYPE_CHECKING:
+    from excel_dbapi.connection import ExcelConnection
+
 METADATA_SHEET = "__excel_meta__"
 
 
-def list_tables(connection: Any, include_meta: bool = False) -> list[str]:
+def list_tables(connection: ExcelConnection, include_meta: bool = False) -> list[str]:
     """Return worksheet names, excluding metadata sheet by default."""
-    sheets = cast(list[str], connection.engine.list_sheets())
+    sheets: list[str] = connection.engine.list_sheets()
     if not include_meta:
         sheets = [sheet for sheet in sheets if sheet != METADATA_SHEET]
     return sheets
 
 
-def has_table(connection: Any, table_name: str) -> bool:
+def has_table(connection: ExcelConnection, table_name: str) -> bool:
     """Check if a worksheet exists (case-insensitive)."""
     return _resolve_sheet_name(connection, table_name) is not None
 
 
-def _resolve_sheet_name(connection: Any, table_name: str) -> str | None:
-    for sheet_name in cast(list[str], connection.engine.list_sheets()):
+def _resolve_sheet_name(connection: ExcelConnection, table_name: str) -> str | None:
+    for sheet_name in connection.engine.list_sheets():
         if sheet_name.lower() == table_name.lower():
             return sheet_name
     return None
 
 
 def get_columns(
-    connection: Any, table_name: str, sample_size: int | None = 100
+    connection: ExcelConnection, table_name: str, sample_size: int | None = 100
 ) -> list[dict[str, Any]]:
     """Return column metadata by sampling data rows."""
     resolved_table_name = _resolve_sheet_name(connection, table_name)
@@ -98,7 +101,7 @@ def _classify_value_type(value: Any) -> str:
 
 
 def write_table_metadata(
-    connection: Any, table_name: str, columns: list[dict[str, Any]]
+    connection: ExcelConnection, table_name: str, columns: list[dict[str, Any]]
 ) -> None:
     """Write column metadata to the hidden metadata sheet."""
     engine = connection.engine
@@ -150,7 +153,7 @@ def write_table_metadata(
 
 
 def read_table_metadata(
-    connection: Any, table_name: str
+    connection: ExcelConnection, table_name: str
 ) -> list[dict[str, Any]] | None:
     """Read column metadata from the metadata sheet."""
     sheets = connection.engine.list_sheets()
@@ -175,7 +178,7 @@ def read_table_metadata(
     ]
 
 
-def remove_table_metadata(connection: Any, table_name: str) -> None:
+def remove_table_metadata(connection: ExcelConnection, table_name: str) -> None:
     """Remove metadata for a table from the metadata sheet."""
     sheets = connection.engine.list_sheets()
     if METADATA_SHEET not in sheets:

tests/test_not_and_parens.py

@@ -913,3 +913,84 @@ def test_join_rejects_subquery_in_precedence_group(self, tmp_path: Path) -> None
             )
             rows = cur.fetchall()
             assert rows == [("Alice",)]
+
+
+class TestNotInNullSemantics:
+    """SQL-standard NULL handling for IN/NOT IN operators.
+
+    Per SQL spec: ``x NOT IN (1, NULL)`` yields UNKNOWN when x != 1,
+    which is treated as FALSE in WHERE clauses.
+    """
+
+    def test_not_in_with_null_candidate(self, tmp_path: Path) -> None:
+        """NOT IN with NULL candidate should return empty when no match."""
+        f = tmp_path / "test.xlsx"
+        wb = Workbook()
+        ws = wb.active
+        assert ws is not None
+        ws.title = "data"
+        ws.append(["id", "val"])
+        ws.append([1, 10])
+        ws.append([2, 20])
+        ws.append([3, 30])
+        wb.save(f)
+
+        with ExcelConnection(str(f), engine="openpyxl") as conn:
+            cur = conn.cursor()
+            # val NOT IN (10, NULL): 10 matches → excluded; 20, 30 → UNKNOWN → excluded
+            cur.execute("SELECT id FROM data WHERE val NOT IN (10, NULL)")
+            assert cur.fetchall() == []
+
+    def test_not_in_without_null(self, tmp_path: Path) -> None:
+        """NOT IN without NULL works normally."""
+        f = tmp_path / "test.xlsx"
+        wb = Workbook()
+        ws = wb.active
+        assert ws is not None
+        ws.title = "data"
+        ws.append(["id", "val"])
+        ws.append([1, 10])
+        ws.append([2, 20])
+        ws.append([3, 30])
+        wb.save(f)
+
+        with ExcelConnection(str(f), engine="openpyxl") as conn:
+            cur = conn.cursor()
+            cur.execute("SELECT id FROM data WHERE val NOT IN (10, 20)")
+            assert cur.fetchall() == [(3,)]
+
+    def test_not_in_only_null(self, tmp_path: Path) -> None:
+        """NOT IN (NULL) → UNKNOWN for all rows → no rows returned."""
+        f = tmp_path / "test.xlsx"
+        wb = Workbook()
+        ws = wb.active
+        assert ws is not None
+        ws.title = "data"
+        ws.append(["id", "val"])
+        ws.append([1, 10])
+        ws.append([2, 20])
+        wb.save(f)
+
+        with ExcelConnection(str(f), engine="openpyxl") as conn:
+            cur = conn.cursor()
+            cur.execute("SELECT id FROM data WHERE val NOT IN (NULL)")
+            assert cur.fetchall() == []
+
+    def test_in_with_null_candidate(self, tmp_path: Path) -> None:
+        """IN with NULL candidate should find matches, skip NULLs."""
+        f = tmp_path / "test.xlsx"
+        wb = Workbook()
+        ws = wb.active
+        assert ws is not None
+        ws.title = "data"
+        ws.append(["id", "val"])
+        ws.append([1, 10])
+        ws.append([2, 20])
+        ws.append([3, 30])
+        wb.save(f)
+
+        with ExcelConnection(str(f), engine="openpyxl") as conn:
+            cur = conn.cursor()
+            # val IN (10, NULL): 10 matches → included; 20, 30 don't match → excluded
+            cur.execute("SELECT id FROM data WHERE val IN (10, NULL)")
+            assert cur.fetchall() == [(1,)]