style: clean up formatting and improve readability

* Adjust whitespace in .gitignore for consistency
* Reformat description in setup.py for better readability
* Update type hints in base.py and types.py for consistency
* Improve formatting in SQL queries for better readability
* Add whitespace in utils.py for consistency

Author: atasoglu

.gitignore

@@ -182,9 +182,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 

setup.py

@@ -1,5 +1,6 @@
 from pathlib import Path
-from setuptools import setup, find_packages
+
+from setuptools import find_packages, setup
 
 here = Path(__file__).parent.resolve()
 
@@ -8,7 +9,9 @@
     version="0.1.0",
     author="Ahmet Atasoglu",
     author_email="[email protected]",
-    description="A tiny Python client around sqlite-vec for CRUD and similarity search.",
+    description=(
+        "A tiny Python client around sqlite-vec for CRUD and similarity search."
+    ),
     long_description=(here / "README.md").read_text(encoding="utf-8"),
     long_description_content_type="text/markdown",
     url="https://github.com/atasoglu/sqlite-vec-client",

sqlite_vec_client/base.py

@@ -6,13 +6,16 @@
 """
 
 from __future__ import annotations
+
 import json
 import sqlite3
-import sqlite_vec
 from types import TracebackType
-from typing import Optional, List, Dict, Any, Literal, Type
-from .types import Embeddings, Result, SimilaritySearchResult, Rowids, Metadata, Text
-from .utils import serialize_f32, deserialize_f32
+from typing import Any, Literal
+
+import sqlite_vec
+
+from .types import Embeddings, Metadata, Result, Rowids, SimilaritySearchResult, Text
+from .utils import deserialize_f32, serialize_f32
 
 
 class SQLiteVecClient:
@@ -36,7 +39,7 @@ def create_connection(db_path: str) -> sqlite3.Connection:
         return connection
 
     @staticmethod
-    def rows_to_results(rows: List[sqlite3.Row]) -> List[Result]:
+    def rows_to_results(rows: list[sqlite3.Row]) -> list[Result]:
         """Convert `sqlite3.Row` items into `(rowid, text, metadata, embedding)`."""
         return [
             (
@@ -59,13 +62,12 @@ def __enter__(self) -> SQLiteVecClient:
 
     def __exit__(
         self,
-        exc_type: Optional[Type[BaseException]],
-        exc: Optional[BaseException],
-        tb: Optional[TracebackType],
-    ) -> Optional[bool]:
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
         """Close the connection on exit; do not suppress exceptions."""
         self.close()
-        return False
 
     def create_table(
         self,
@@ -96,11 +98,11 @@ def create_table(
         )
         self.connection.execute(
             f"""
-            CREATE TRIGGER IF NOT EXISTS {self.table}_embed_text 
+            CREATE TRIGGER IF NOT EXISTS {self.table}_embed_text
             AFTER INSERT ON {self.table}
             BEGIN
                 INSERT INTO {self.table}_vec(rowid, text_embedding)
-                VALUES (new.rowid, new.text_embedding) 
+                VALUES (new.rowid, new.text_embedding)
                 ;
             END;
             """
@@ -133,7 +135,7 @@ def similarity_search(
         self,
         embedding: Embeddings,
         top_k: int = 5,
-    ) -> List[SimilaritySearchResult]:
+    ) -> list[SimilaritySearchResult]:
         """Return top-k nearest neighbors for the given embedding."""
         cursor = self.connection.cursor()
         cursor.execute(
@@ -143,7 +145,7 @@ def similarity_search(
                 text,
                 distance
             FROM {self.table} AS e
-            INNER JOIN {self.table}_vec AS v on v.rowid = e.rowid  
+            INNER JOIN {self.table}_vec AS v on v.rowid = e.rowid
             WHERE
                 v.text_embedding MATCH ?
                 AND k = ?
@@ -156,9 +158,9 @@ def similarity_search(
 
     def add(
         self,
-        texts: List[Text],
-        embeddings: List[Embeddings],
-        metadata: List[Metadata] = None,
+        texts: list[Text],
+        embeddings: list[Embeddings],
+        metadata: list[Metadata] | None = None,
     ) -> Rowids:
         """Insert texts with embeddings (and optional metadata) and return rowids."""
         max_id = self.connection.execute(
@@ -176,7 +178,8 @@ def add(
             for text, md, embedding in zip(texts, metadata, embeddings)
         ]
         self.connection.executemany(
-            f"INSERT INTO {self.table}(text, metadata, text_embedding) VALUES (?,?,?)",
+            f"""INSERT INTO {self.table}(text, metadata, text_embedding)
+            VALUES (?,?,?)""",
             data_input,
         )
         self.connection.commit()
@@ -185,32 +188,36 @@ def add(
         )
         return [row["rowid"] for row in results]
 
-    def get_by_id(self, rowid: int) -> Optional[Result]:
+    def get_by_id(self, rowid: int) -> Result | None:
         """Get a single record by rowid; return `None` if not found."""
         cursor = self.connection.cursor()
         cursor.execute(
-            f"SELECT rowid, text, metadata, text_embedding FROM {self.table} WHERE rowid = ?",
+            f"""
+            SELECT rowid, text, metadata, text_embedding
+            FROM {self.table} WHERE rowid = ?
+            """,
             [rowid],
         )
         row = cursor.fetchone()
         if row is None:
             return None
         return self.rows_to_results([row])[0]
 
-    def get_many(self, rowids: List[int]) -> List[Result]:
+    def get_many(self, rowids: list[int]) -> list[Result]:
         """Get multiple records by rowids; returns empty list if input is empty."""
         if not rowids:
             return []
         placeholders = ",".join(["?"] * len(rowids))
         cursor = self.connection.cursor()
         cursor.execute(
-            f"SELECT rowid, text, metadata, text_embedding FROM {self.table} WHERE rowid IN ({placeholders})",
+            f"""SELECT rowid, text, metadata, text_embedding FROM {self.table}
+            WHERE rowid IN ({placeholders})""",
             rowids,
         )
         rows = cursor.fetchall()
         return self.rows_to_results(rows)
 
-    def get_by_text(self, text: str) -> List[Result]:
+    def get_by_text(self, text: str) -> list[Result]:
         """Get all records with exact `text`, ordered by rowid ascending."""
         cursor = self.connection.cursor()
         cursor.execute(
@@ -224,7 +231,7 @@ def get_by_text(self, text: str) -> List[Result]:
         rows = cursor.fetchall()
         return self.rows_to_results(rows)
 
-    def get_by_metadata(self, metadata: Dict[str, Any]) -> List[Result]:
+    def get_by_metadata(self, metadata: dict[str, Any]) -> list[Result]:
         """Get all records whose metadata exactly equals the given dict."""
         cursor = self.connection.cursor()
         cursor.execute(
@@ -238,12 +245,12 @@ def get_by_metadata(self, metadata: Dict[str, Any]) -> List[Result]:
         rows = cursor.fetchall()
         return self.rows_to_results(rows)
 
-    def list(
+    def list_results(
         self,
         limit: int = 50,
         offset: int = 0,
         order: Literal["asc", "desc"] = "asc",
-    ) -> List[Result]:
+    ) -> list[Result]:
         """List records with pagination and order by rowid."""
         cursor = self.connection.cursor()
         cursor.execute(
@@ -268,13 +275,13 @@ def update(
         self,
         rowid: int,
         *,
-        text: Optional[str] = None,
-        metadata: Optional[Metadata] = None,
-        embedding: Optional[Embeddings] = None,
+        text: str | None = None,
+        metadata: Metadata | None = None,
+        embedding: Embeddings | None = None,
     ) -> bool:
         """Update fields of a record by rowid; return True if a row changed."""
         sets = []
-        params: List[Any] = []
+        params: list[Any] = []
         if text is not None:
             sets.append("text = ?")
             params.append(text)
@@ -302,7 +309,7 @@ def delete_by_id(self, rowid: int) -> bool:
         self.connection.commit()
         return cur.rowcount > 0
 
-    def delete_many(self, rowids: List[int]) -> int:
+    def delete_many(self, rowids: list[int]) -> int:
         """Delete multiple records by rowids; return number of rows removed."""
         if not rowids:
             return 0

sqlite_vec_client/types.py

@@ -1,12 +1,14 @@
 """Type aliases used across the sqlite-vec client package."""
 
-from typing import List, Dict, Any, Tuple, TypeAlias
+from typing import Any
+
+from typing_extensions import TypeAlias
 
 Text: TypeAlias = str
 Rowid: TypeAlias = int
 Distance: TypeAlias = float
-Metadata: TypeAlias = Dict[str, Any]
-Embeddings: TypeAlias = List[float]
-Rowids: TypeAlias = List[Rowid]
-Result: TypeAlias = Tuple[Rowid, Text, Metadata, Embeddings]
-SimilaritySearchResult: TypeAlias = Tuple[Rowid, Text, Distance]
+Metadata: TypeAlias = dict[str, Any]
+Embeddings: TypeAlias = list[float]
+Rowids: TypeAlias = list[Rowid]
+Result: TypeAlias = tuple[Rowid, Text, Metadata, Embeddings]
+SimilaritySearchResult: TypeAlias = tuple[Rowid, Text, Distance]

sqlite_vec_client/utils.py

@@ -1,6 +1,7 @@
 """Utilities for serializing and deserializing float32 embedding arrays."""
 
 import struct
+
 from .types import Embeddings