Add type hints for django-polymorphic

[huynguyengl99]

Hi @bckohan,

It looks like our project currently doesn’t have type hints, so tools like mypy or pyright can’t properly perform static type checking. I’d love to contribute by adding type hints to the project.

There are two ways we could approach this:
1. Add type hints directly within this project – This would involve modifying a large portion of the codebase.
2. Contribute external type hints to the typeshed project – This keeps the main codebase untouched. I’ve done something similar before for the django-channels package (PR #13939). The downside is that types in typeshed would need to be kept in sync with this project over time.

I believe adding type hints will improve maintainability and tooling support for the project. I’m happy to follow whichever approach you prefer, and I’d appreciate your help reviewing the code once I get started.

What do you think about this suggestion?

[bckohan]

Hi @huynguyengl99 thank you for your offer to help!! I needed some time to consider this.

I think we should use pyi stubs and ship them in this package. I'm open to push back on this, but here's my reasoning:

1. Until 3.14 is widely adopted, types are still loaded eagerly (or as strings) so putting them in the code incurs import time penalties (I'm already annoyed by django's startup time because management command tab completion is annoyingly slow)
2. I'd like to keep dependencies on django's type stubs as extra/dev dependency and I'd like to avoid a lot of imports guarded by if TYPE_CHECKING. I'm just assuming we'll have to pull in types from those packages.
3. There are a backlog of PRs I would like to consider and I'd just like to avoid the overhead of merge conflicts while this work proceeds in parallel.
4. Maintaing a separate stubs package would be annoying and error prone.

Thoughts?

[huynguyengl99]

Hi @bckohan, thanks for sharing your reasoning. After considering the points you mentioned, I think the best option might be to create type hints for django-polymorphic under the typeshed project. Here are a few advantages that could address your concerns:
1. No import-time penalties, since the stubs would live in a separate package and only be used for development.
2. No need for TYPE_CHECKING imports in the main codebase, because everything stays in the stubs.
3. No merge conflicts with the current codebase, making it easier for contributors to work on type hints without interfering with ongoing PRs (you’d only need to review if you have time).
4. Typeshed is the official Python stubs repository, with established best practices and reviewers who are very familiar with Python, Django, and typing. This should make the process smoother, more reliable, and less burdensome.

[bckohan]

@huynguyengl99 sounds good to me. I assume this will require a dependency on django-stubs - but I see django-filters already has a project in typeshed that does the same. Do you have the bandwidth to do this?

[huynguyengl99]

Actually, I initially added the base django-filters types in Typeshed, and later received some help from others during the review. I’ll put some of my effort into doing the same for django-polymorphic in my spare time, and I hope I can get some of your reviews once my work is done.