I've split this off from #3068 to keep each PR self-contained and because this is perhaps a bit more of a controversial change. Also related to #3005.

In short, this change adds and exports a type, DrawFn that people using type annotations can use to annotate the draw function provided by @composite. This goal of this new type is similar to DataObject, with one big difference being that this one exists solely for typing and doesn't serve any functional goals. Its main benefit is that it's reusable and a single point of definition of the interface that can be evolved if hypothesis evolves, which is much better than everyone copying over the suggested typevars from #3005 into their own files.

If anyone can suggest a better name for this type, I'd be happy to change it!

A note on the implementation: I've implemented this as a class rather than a typevar (as suggested in #3005), since the draw function seems to take an optional argument label and it isn't possible to specify that with just a typing.Callable alone. Callback protocols do support this, but typing.Protocol has only landed in the stdlib since Python 3.8. Instead, this class acts like a protocol without actually inheriting from one. Its sole purpose is to describe something which, when called with a SearchStrategy[Ex] and an optional label, returns an Ex. We never have to use this within hypothesis itself, it's purely a hint/tool for the user to use in their wrapped function annotation.

A note for future maintenance: If you ever decide to make this an actual typing.Protocol, make sure not to make the protocol itself generic, just the __call__ method. So, class DrawFn(Protocol): ..., not class DrawFn(Protocol[Ex]): .... The latter would require providing a type argument whenever the DrawFn type is used in an annotation (with strict mypy settings), the former does not.

Also, although PEP 612 will allow for better typing of @composite, I'm not sure whether type checkers would then be able to infer the parameter types of the decorated functions. The PEP provides an example regarding Concatenate, and there, the concatenated parameter (Request) is still annotated in the wrapped function. Moreover, strict settings for type checkers might continue to require annotations on each parameter, regardless of whether they can somehow infer the type. Therefore, I don't think this contribution would become obsolete once 3.10 becomes the minimum supported version.

An example (adapted from the linked issue):

@st.composite
def foo(draw: st.DrawFn) -> st.SearchStrategy[Tuple[int, int]]:
    s = draw(st.text())
    i = draw(st.integers())
    t = draw(st.tuples(st.text(), st.integers()))
    reveal_type(s)  # str
    reveal_type(i)  # int
    reveal_type(t)  # tuple[str, int]
    
    return (i, t[1])

This type-checks correctly and without errors under the strictest mypy settings (excluding --disallow-any-decorated).

Similarly to #3068, I've pondered on the appropriate version bump type, and I feel like minor is more appropriate here than in #3068. If I may weigh in on the release strategy for these, I'd suggest releasing both PRs as a single release rather than each one individually.