Summary

This PR adds Python type stub files so editors and type checker tools can better understand valid SerpApi search parameters and return types. Type stubs are metadata for developer tooling only: they improve autocomplete and static analysis, but they are not loaded by the client at runtime and do not add runtime validation.

Changes

• Adds generated .pyi stub files for static type checking.
• Adds serpapi/py.typed so type checkers know this package includes typing information.
• Adds a typing/ helper folder with scripts and engine schema inputs used to generate the stubs.
• Adds a build-engines.py helper copied from the SerpApi MCP repo: build-engines.py.
• The build engine script fetches supported SerpApi parameters from the playground and writes engine schemas.
• generate_type_stubs.py converts those engine schemas into Python type information.
• Adds CI checks to verify that checked-in .pyi files match the locally committed engine schemas and generator output.
• Adds typing_extensions as a dependency because generated stubs use compatibility typing helpers like Literal, TypedDict, Required, and NotRequired.

Files Added

• serpapi/*.pyi
  Generated type stub files that describe the public API, search arguments, overloads, and return types for type checkers and editors.

• serpapi/py.typed
  PEP 561 marker file that tells type checkers the installed serpapi package includes typing information.

• typing/build-engines.py
  Helper script that fetches supported SerpApi engine parameters from the SerpApi playground and writes local engine schema JSON files.

• typing/generate_type_stubs.py
  Generator script that converts the local engine schema JSON files into Python .pyi type stubs.

• typing/engines/*.json
  Local engine schema inputs. These are committed, so stub generation is deterministic, and CI check python typing/generate_type_stubs.py --check uses these engine schema to validate .pyi stubs

• tests/test_build_typing.py
  Tests for the stub generator, including syntax validation, stale/corruption prevention, output path defaults, and return-type overload behavior.

Reference Links

• PEP 561, distributing type information: https://peps.python.org/pep-0561/
• Stub file reference: https://typing.python.org/en/latest/spec/distributing.html#stub-files
• typing_extensions: https://typing-extensions.readthedocs.io/

Before / After

Before

All the usages above have invalid param usages, but the earlier package versions lack type hints/type stubs, so IDEs do not suggest anything.

After

type_hints.mp4

With this update, IDEs and type-checking extensions can identify invalid parameters and show warnings. (Note: these are just IDE warnings; the code will run without errors and the request will be sent to SerpApi beacuse Python is not strict with type enforcements).

Notes

• Engine JSON schemas are not packaged as runtime package data. These are excluded from the built package.
• A new step: python typing/generate_type_stubs.py --check is added in CI. This does not fetch live schema data; it only verifies the consistency of the repo among committed engine schemas, and generated stubs.
• This PR should not introduce breaking code changes because Python type hints and .pyi stub files are not enforced at runtime. However, it does add one new runtime package dependency: typing_extensions. Previously, requests was the only required dependency, so this packaging change warrants a minor version bump.