Add stubs for python-jenkins

[kasium]

No description provided.

[Avasam]

Thank you for your contribution!
Here's a first pass review:

---

I won't leave a comment on every single line for this, but you can be more precise when it comes to the return type. For example, you can use -> list if a method always returns a list.

(there's an exception to this rule of thumb when it comes to complex return type unions)

You can read the section "Some further tips for good type hints" at https://github.com/python/typeshed/blob/main/CONTRIBUTING.md#conventions for more information

---

Concretely, this means that for all the methods returning JSON data, you can replace Sequence with list and Mapping with dict in the return annotation.

[kasium]

Wow thanks a lot for the review. Let me come back to that after my vacation in next week.

[Avasam]

You still need to update the return types from Sequence and Mapping to list and dict where we know that specific type is always returned.

#12582 (review)

I won't leave a comment on every single line for this, but you can be more precise when it comes to the return type. For example, you can use -> list if a method always returns a list.

(there's an exception to this rule of thumb when it comes to complex return type unions)

You can read the section "Some further tips for good type hints" at https://github.com/python/typeshed/blob/main/CONTRIBUTING.md#conventions for more information

---

Concretely, this means that for all the methods returning JSON data, you can replace Sequence with list and Mapping with dict in the return annotation.

[Avasam]

Almost there! It's our (relatively new) policy to explain any leftover Any. So that we know which python typing limitation was hit at the moment of writing the stubs, and isn't left to future readers to guess (especially since we still have older stubs full of Any instead of Incomplete). This can be done either through comments, or by using a clearly named alias when the same concept is repeated.

---

For instance, all json objects will have a str key, so all your dict[Any, ...] can safely become dict[str, ...].

---

If you simply don't know the actual type, or don't want to bother completing the stubs more than you already have, you can use Incomplete. Having a bunch of Incomplete is fine. It's clear, easy to search for, and anyone with a bit of spare time can contribute to fill them in.

---

All Any that represent a union of different possible JSON value types, can be replaced by an alias named something like _JSONValue. For instance: dict[Any, Any] --> dict[str, _JSONValue.

But only use this if the type is truly something like dict[str, str] | list[str] | str. If it's just an object you don't know the structure of, use dict[str, Incomplete] instead.

---

Outside of avoiding stranded Any, this is otherwise quite satisfactory !

[Avasam]

Thank you! I'll leave some time for another maintainer to come by if they wanna add anything. Looks good to me !

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉