Skip to content

Add type hints and PEP 561 compliance for improved IDE support#31

Open
HyperNaser wants to merge 4 commits into
serpapi:masterfrom
HyperNaser:feat/add-type-support
Open

Add type hints and PEP 561 compliance for improved IDE support#31
HyperNaser wants to merge 4 commits into
serpapi:masterfrom
HyperNaser:feat/add-type-support

Conversation

@HyperNaser

Copy link
Copy Markdown

Description

This PR introduces explicit static typing infrastructure to comply with PEP 561. It adds the missing py.typed marker file and comprehensive type annotations to allow modern IDE type checkers to correctly resolve types without throwing missing stub errors.

Changes

  • Added an empty py.typed marker file to the serpapi/ directory.
  • Updated pyproject.toml configuration to package the type markers.
  • Added type hints to core modules (http.py, models.py, core.py, textui.py, exceptions.py)
  • Refactored textui.py to use get_lexer_by_name("JSON")

@adarshdigievo

Copy link
Copy Markdown
Member

@HyperNaser Thanks for working on this. The PR looks great overall. I have added a few suggestions below:

  • Annotating **kwargs: Currently, **kwargs is annotated using Any. I think using dict is more suitable.
  • For locations and account functions in the core.py file, the return type annotation can be Dict.
  • Can you revert the code logic changes in models.py, which are unrelated to typing (changes to .next_page_url(), .next_page(), .yield_pages() methods of the SerpResults class)?
    If you think the current implementation is buggy, please add an example if possible, and we can add fixes in a separate PR.

@adarshdigievo adarshdigievo self-assigned this Jun 30, 2026
@HyperNaser

Copy link
Copy Markdown
Author

Thanks for the review!
I reverted the pagination logic in the model methods as you suggested because I mixed the SerpResults case with the string case returned when the response is a raw HTML rather than JSON.
I don’t think **kwargs needs a more specific annotation here, since they represent an arbitrary set of keyword arguments via a dict by default and the Any annotation here is for the value type of that dict. I also left the client is not None check in next_page(), because a SerpResults instance can be created without a client and accessing self.client.api_key would otherwise raise an attribute error.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants