From ec80acb668b361e395ecfa5ee381391bd3b3b859 Mon Sep 17 00:00:00 2001
From: "lancedb-gatefixer[bot]"
 <313497061+lancedb-gatefixer[bot]@users.noreply.github.com>
Date: Fri, 7 Aug 2026 17:31:42 +0800
Subject: [PATCH] fix(python): expose inline types to downstream checkers
 (#3817)

## Summary

- publish the PEP 561 `py.typed` marker so downstream type checkers
consume the inline public annotations
- add a Pyright contract test that distinguishes synchronous `connect`
from awaited `connect_async`
- verify the marker is present in the installed package

## Root cause

The public Python module already annotated `lancedb.connect` as
synchronous and `lancedb.connect_async` as asynchronous. The private
native `_lancedb.connect` stub is intentionally awaitable because it
backs `connect_async`. However, the distribution did not include a PEP
561 marker, so downstream tools such as mypy could ignore the public
inline annotations and expose misleading or incomplete type information.

## Validation

- `python/.venv/bin/ruff format --check python/python/tests/test_db.py
python/python/type_tests/connect.py`
- `python/.venv/bin/ruff check .`
- `cd python && .venv/bin/pytest
python/tests/test_db.py::test_package_includes_pep_561_marker -q`
- `cd python && .venv/bin/pyright --pythonpath .venv/bin/python`
- downstream mypy contract check for both public connection functions

Fixes #2159

<!-- lance-gatekeeper-fix:v1 agent=b07901451487187fc03f61890d3aa6bb
generation=1 -->

Co-authored-by: lancedb-gatefixer[bot] <313497061+lancedb-gatefixer[bot]@users.noreply.github.com>
---
 python/pyproject.toml               |  1 +
 python/python/lancedb/py.typed      |  1 +
 python/python/tests/test_db.py      |  5 +++++
 python/python/type_tests/connect.py | 15 +++++++++++++++
 4 files changed, 22 insertions(+)
 create mode 100644 python/python/lancedb/py.typed
 create mode 100644 python/python/type_tests/connect.py

diff --git a/python/pyproject.toml b/python/pyproject.toml
index cb175bd6d..348058957 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -140,6 +140,7 @@ include = [
     "python/lancedb/remote/errors.py",
     "python/lancedb/embeddings/__init__.py",
     "python/lancedb/_lancedb.pyi",
+    "python/type_tests/connect.py",
 ]
 exclude = ["python/tests/"]
 pythonVersion = "3.13"
diff --git a/python/python/lancedb/py.typed b/python/python/lancedb/py.typed
new file mode 100644
index 000000000..8b1378917
--- /dev/null
+++ b/python/python/lancedb/py.typed
@@ -0,0 +1 @@
+
diff --git a/python/python/tests/test_db.py b/python/python/tests/test_db.py
index 8f4a8850c..84e78fd8f 100644
--- a/python/python/tests/test_db.py
+++ b/python/python/tests/test_db.py
@@ -6,6 +6,7 @@ import inspect
 import re
 import sys
 from datetime import timedelta
+from importlib import resources
 import os
 from types import SimpleNamespace
 
@@ -18,6 +19,10 @@ from lance_namespace.errors import NamespaceNotEmptyError, TableNotFoundError
 from lancedb.pydantic import LanceModel, Vector
 
 
+def test_package_includes_pep_561_marker():
+    assert resources.files(lancedb).joinpath("py.typed").is_file()
+
+
 def test_basic(tmp_path):
     db = lancedb.connect(tmp_path)
 
diff --git a/python/python/type_tests/connect.py b/python/python/type_tests/connect.py
new file mode 100644
index 000000000..eb2cba37c
--- /dev/null
+++ b/python/python/type_tests/connect.py
@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+from typing import assert_type
+
+import lancedb
+from lancedb import AsyncConnection, DBConnection
+
+
+def check_connect_type() -> None:
+    assert_type(lancedb.connect("memory://"), DBConnection)
+
+
+async def check_connect_async_type() -> None:
+    assert_type(await lancedb.connect_async("memory://"), AsyncConnection)