Add a py.typed file to export type annotations

[brianhelba]

In order for any of the type annotations used within django-extensions to be available to downstream users, PEP-561 requires that an empty py.typed marker file be present as package data. For more details, see:
https://blog.whtsky.me/tech/2021/dont-forget-py.typed-for-your-typed-python-package/

This allows downstream users to have type checking when directly using any Python APIs which happen to have type annotations.

More importantly, it allows Django and DRF mixin classes (like ModelUserFieldPermissionMixin) and subclasses (like TimeStampedModel) to inherit type information if type stub packages for Django or DRF are in use.

[adamchainz]

I like to see Django projects rolling out type hints. Great work. That said, I would encourage improving the type hints in the package before exposing them to users with a py.typed file.

I've learned from typing my own packages and client projects that it's best for packages to use Mypy's strict mode (which enables several flags), in order for users be able to adopt type hints as much as they like (up to strict mode). If a package has type hints but isn't fully covered, or conformant with the other flags in strict mode, then exposing those hints can make it harder for user projects to adopt typing. Rather than the package being typed as Any throughout, its partial hints will require user code to ignore issues with # type: ignore comments, or cast()s, even when using the API's correctly.

I tried enabling strict mode, and adding django-stubs to the mypy env:

$ git diff tox.ini
diff --git a/tox.ini b/tox.ini
index 51c777bf..3b234c04 100644
--- a/tox.ini
+++ b/tox.ini
@@ -66,6 +66,7 @@ allowlist_externals=
 deps =
     pip >= 21.1
     mypy
+    django-stubs
     types-requests
     types-boto
     types-PyYAML
$ cat pyproject.toml
[tool.mypy]
strict = true

I found this finds 1248 more warnings/errors from Mypy:

$ tox -e mypy
Found 1248 errors in 83 files (checked 103 source files)

Many of these are repeats, so it's not necessarily a huge amount of work to fix them.

If you'd like assistance enabling the flag and fixing the issues, I'm happy to help with reviews.

Anyway this is an input, you can also try adding the py.typed file and allow users to report issues and improve the hints too.

[trbs]

It would be really good if we can make this as clean as possible before committing it into the code base...
We should also add a check for this in the pipeline I think, so we avoid regressions later...

[adamchainz]

Check for what in the pipeline? Mypy is already running in CI, within the "Linters" workflow.

[trbs]

Yeah I meant having it error out on the mypy step of the pipeline :-)

[sshishov]

Hello guys, I can see 2 years passed and no work is done. I completely understand that it is almost impossible to add typing to the whole repo in one go especially without conflicts etc.

Therefore there should be another approach here, you should add py.typed and start adding types to your repo with strict flag (file by file) or (package by package) or even (function by function).

Eventually we can come up with typed repository.

What do you think about it? Otherwise it will never be done... Especially if you want the help from the community!