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: https://github.com/python/typing/discussions/1236

[cpython-cla-bot[bot]]

All commit authors signed the Contributor License Agreement.

[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?