feat: add static type checking support using .pyi stub files

Author: adarshdigievo

.github/workflows/ci.yml

@@ -30,6 +30,10 @@ jobs:
     - name: Install dependencies
       run: pip install -e .[test]
 
+    - name: Verify generated typing stubs
+      if: matrix.python-version == '3.13'
+      run: python typing/generate_type_stubs.py --check
+
     - name: Run tests
       run: pytest -k "not example"
       env:

.github/workflows/release.yml

@@ -25,6 +25,10 @@ jobs:
       - name: Install dependencies
         run: pip install -e .[test]
 
+      - name: Verify generated typing stubs
+        if: matrix.python-version == '3.13'
+        run: python typing/generate_type_stubs.py --check
+
       - name: Run tests
         run: pytest -k "not example"
         env:
@@ -50,6 +54,7 @@ jobs:
       - name: Build sdist and wheel
         run: |
           pip install build
+          python typing/generate_type_stubs.py --check
           python -m build
 
       - uses: actions/upload-artifact@v7

MANIFEST.in

@@ -1,2 +1,3 @@
 include README.md HISTORY.md LICENSE
-recursive-include tests *.py
+recursive-include serpapi *.pyi py.typed
+recursive-include tests *.py

pyproject.toml

@@ -10,7 +10,7 @@ readme = "README.md"
 license = { text = "MIT" }
 authors = [{ name = "SerpApi", email = "support@serpapi.com" }]
 requires-python = ">=3.6"
-dependencies = ["requests"]
+dependencies = ["requests", "typing_extensions"]
 keywords = [
   "scrape", "serp", "api", "serpapi", "scraping", "json", "search",
   "localized", "rank", "google", "bing", "baidu", "yandex", "yahoo",
@@ -39,6 +39,7 @@ classifiers = [
 [project.optional-dependencies]
 color = ["pygments"]
 test = ["pytest"]
+dev = ["markdownify"]
 
 [project.urls]
 Homepage = "https://github.com/serpapi/serpapi-python"
@@ -50,6 +51,10 @@ version = { attr = "serpapi.__version__.__version__" }
 
 [tool.setuptools.packages.find]
 exclude = ["tests", "tests.*"]
+namespaces = false
+
+[tool.setuptools.package-data]
+serpapi = ["*.pyi", "py.typed"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

serpapi/__init__.pyi

@@ -0,0 +1,6 @@
+# This file is generated by typing/generate_type_stubs.py.
+# Do not edit by hand; update typing/engines/*.json and rerun the generator.
+from .__version__ import __version__ as __version__
+from .core import Client as Client, account as account, locations as locations, search as search, search_archive as search_archive
+from .exceptions import APIKeyNotProvided as APIKeyNotProvided, HTTPConnectionError as HTTPConnectionError, HTTPError as HTTPError, SearchIDNotProvided as SearchIDNotProvided, SerpApiError as SerpApiError, TimeoutError as TimeoutError
+from .models import SerpResults as SerpResults