Added typing stub file (#48)

This adds a stub file, adding type hints in Python. This added the
`connect` function as well as the `Connection` and `Cursor` classes.
Everything is in the `libsql_experimental.pyi` file. According to
[this](https://pyo3.rs/v0.21.0-beta.0/python-typing-hints#if-you-do-not-have-other-python-files)
PyO3 documentation, as long as there is no other Python files (excluding
examples) Maturin will automatically install this file correctly, adding
`__init__.pyi` and `py.typed` to site-packages. Below is a before and
after example for the `connect` function.

If there is anything I missed or misunderstood, let me know and ill fix
it :)
 

![before](https://github.com/tursodatabase/libsql-experimental-python/assets/42066957/e890f7c7-1f06-4980-8d89-1e3ee604190f)

![image](https://github.com/tursodatabase/libsql-experimental-python/assets/42066957/b4c6c23e-df29-4c0b-96de-8d2cc72caed6)

Author: penberg

.github/workflows/pr-tests.yml

@@ -36,6 +36,6 @@ jobs:
       run: |
         python3 -m venv .env # maturin requires a virtualenv
         source .env/bin/activate
-        pip3 install maturin pytest
+        pip3 install maturin pytest mypy
         maturin develop
         pytest

libsql_experimental.pyi

@@ -0,0 +1,65 @@
+"""libSQL's experimental Python implementation"""
+
+from typing import Any, Self, final
+
+
+paramstyle = "qmark"
+sqlite_version_info = (3, 42, 0)
+Error = Exception
+LEGACY_TRANSACTION_CONTROL: int = -1
+
+
+@final
+class Cursor:
+    """libSQL database cursor.
+
+    Implements a superset of the [DB-API 2.0 (PEP249)](https://peps.python.org/pep-0249/) Cursor object protocol."""  # noqa: E501
+    arraysize: int
+
+    @property
+    def description(self) -> tuple[tuple[Any, ...], ...] | None: ...
+
+    @property
+    def rowcount(self) -> int: ...
+
+    @property
+    def lastrowid(self) -> int | None: ...
+
+    def close(self) -> None: ...
+    def execute(self, sql: str, parameters: tuple[Any, ...] = ...) -> Self: ...
+    def executemany(self, sql: str, parameters: list[tuple[Any, ...]] = ...) -> Self: ...  # noqa: E501
+    def executescript(self, script: str) -> Self: ...
+    def fetchone(self) -> tuple[Any, ...] | None: ...
+    def fetchmany(self, size: int = ...) -> list[tuple[Any, ...]]: ...  # noqa: E501
+    def fetchall(self) -> list[tuple[Any, ...]]: ...
+
+
+@final
+class Connection:
+    """libSQL database connection.
+
+    Implements a superset of the [DB-API 2.0 (PEP249)](https://peps.python.org/pep-0249/) Connection object protocol."""  # noqa: E501
+    @property
+    def isolation_level(self) -> str | None: ...
+
+    @property
+    def in_transaction(self) -> bool: ...
+
+    def commit(self) -> None: ...
+    def cursor(self) -> Cursor: ...
+    def sync(self) -> None: ...
+    def rollback(self) -> None: ...
+    def execute(self, sql: str, parameters: tuple[Any, ...] = ...) -> Cursor: ...  # noqa: E501
+    def executemany(self, sql: str, parameters: list[tuple[Any, ...]] = ...) -> Cursor: ...  # noqa: E501
+    def executescript(self, script: str) -> None: ...
+
+
+def connect(database: str,
+            isolation_level: str | None = ...,
+            check_same_thread: bool = True,
+            uri: bool = False,
+            sync_url: str = ...,
+            sync_interval: float = ...,
+            auth_token: str = ...,
+            encryption_key: str = ...) -> Connection:
+    """Open a new libSQL connection, return a Connection object."""

tests/test_suite.py

@@ -298,6 +298,33 @@ def test_int64(provider):
     res = cur.execute("SELECT * FROM data")
     assert [(1, 1099511627776)] == res.fetchall()
 
+def test_type_adherence(capsys):
+    try:
+        from mypy.stubtest import test_stubs, parse_options
+    except (ImportError, ModuleNotFoundError):
+        # skip test if mypy not installed
+        pytest.skip("Cant test type stubs without mypy installed")
+
+    # run mypy stubtest tool. Equivalent to running the following the terminal
+    """
+    stubtest --concise libsql_experimental | \
+        grep -v 'which is incompatible with stub argument type'
+    """
+    test_stubs(parse_options(["--concise", "libsql_experimental"]))
+    cap = capsys.readouterr()
+
+    # this is part of error reported if is default parameter is ellipsis
+    # `arg: type = ...` which is a nicer way to hide implementation from user
+    # than having the more "correct" `arg: type | None = None` everywhere
+    ellipsis_err = "which is incompatible with stub argument type"
+
+    lines = cap.out.split("\n")
+    lines = filter(lambda x: ellipsis_err not in x, lines)  # filter false positives from ellipsis
+    lines = filter(lambda x: len(x) != 0, lines)  # filter empty lines
+
+    # there will always be one error which i dont know how to get rid of
+    # `libsql_experimental.libsql_experimental failed to find stubs`
+    assert len(list(lines)) == 1
 
 def connect(provider, database, isolation_level="DEFERRED", autocommit=-1):
     if provider == "libsql-remote":