Add Aliasing Decorators section to libraries.rst

[Drino]

I believe I'm not the only one who will struggle with behavior of Callable type aliases.
I hope if this is added to the documentation - some people will save an hour on figuring how TypeAlias work.

I'm not sure if it is worth introducing "decorator factory" term here, but it is used in mypy documentation.

Related discussion:
#1236

[cpython-cla-bot]

All commit authors signed the Contributor License Agreement.

[JelleZijlstra]

Thanks, this is a useful addition.

I'm not sure it should be in the "libraries" document, but there's already a TODO on moving it out.

[srittau]

Thanks, this makes sense. But I think we should rather recommend to use the _typeshed.IdentityFunction protocol, instead of recommending a custom protocol.

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from _typeshed import IdentityFunction

def decorator_factory(*, mode: str) -> "IdentityFunction":
    """
    Decorator factory is invoked with arguments like this:
        @decorator_factory(mode="easy")
        def my_function(): ...
    """
    ...

[AlexWaygood]

But I think we should rather recommend to use the _typeshed.IdentityFunction protocol, instead of recommending a custom protocol.

I think it's important to note that this only works in stub files, if you have from __future__ annotations enabled, or if you use -> "IdentityFunction" instead of -> IdentityFunction.

[srittau]

I think it's important to note that this only works in stub files, if you have from __future__ annotations enabled, or if you use -> "IdentityFunction" instead of -> IdentityFunction.

Thanks, easy to forget when always using the future import. :)

[Drino]

Thanks for the fast review and cool suggestion!

I've rewritten the example using IdentityFunction, though I'm a little bit concerned to show a "proper" example of decorator protocol definition, so I've added another one with slightly less trivial decorator.

[Drino]

@srittau Hello, I've went through your comments and it seems that I've resolved the issues. Would you look at this PR one more time please?