feat: Consider adding py.typed file marker for type-checking support

[FBruzzesi]

Currently type checkers raises a warning when importing skyfield:

Stub file not found for "skyfield."

[brandon-rhodes]

I have lots of other projects to tackle at the moment, so it might be a while before I get around to this — because, if I understand correctly, I would need to not only add the py.typed file, but also generate basic stub files for each of Skyfield's .py files giving the types of its function and method calls?

[FBruzzesi]

Hey @brandon-rhodes thanks for getting back to me!

---

Not necessarily! Adding py.typed is actually a two-step spectrum, it doesn't have to do everything at once.

• The minimal approach is to just add an empty py.typed marker file to the package directory and include it in your package data. This alone signals to type checkers that the package opts into typing, and it stops the "stub file not found" warning. You wouldn't need any stub files for this. Of course, without actual type annotations or stubs, users would then get Unknown or Any types for most things, but that's already the situation today, just without the warning noise.

• Over time type annotations could gradually be added to individual modules, no need to do it all in one shot.

• Regarding Python 2.7 compatibility (which I understand it's still a concern), inline type annotations (the def foo(x: int) -> str: syntax) aren't available. But separate .pyi stub files that live alongside the .py files would work. These are only read by type checkers and never executed, so they can use modern Python 3 annotation syntax without affecting runtime compatibility at all.

---

So the smallest possible PR would literally be:

1. Create an empty skyfield/py.typed file
2. Ensure it's included in the distributed package

---

I am happy to get involved and help to get started with the effort

[FBruzzesi]

If #1127 gets accepts, I got a couple of follow ups already:

• typing/data-module to add stubs to the data module
• typing/timelib-module: to add stubs to timelib.py and all the files that it depends on. This is a fairly larger one and I can split it into multiple PRs if needed

Both these might not be perfect, but I think they would be a a good start to expose stubs and get users feedback