Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Aliasing Decorators section to libraries.rst #1243

Open
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

Drino
Copy link

@Drino Drino commented Aug 22, 2022

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

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](https://mypy.readthedocs.io/en/stable/generics.html#decorator-factories).

Related discussion:
python#1236
@cpython-cla-bot
Copy link

cpython-cla-bot bot commented Aug 22, 2022

All commit authors signed the Contributor License Agreement.
CLA signed

Copy link
Member

@JelleZijlstra JelleZijlstra left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

@srittau srittau left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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(): ...
    """
    ...

docs/source/libraries.rst Outdated Show resolved Hide resolved
@AlexWaygood
Copy link
Member

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
Copy link
Collaborator

srittau commented Aug 22, 2022

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 and others added 2 commits August 22, 2022 19:23
Co-authored-by: Sebastian Rittau <srittau@rittau.biz>
@Drino
Copy link
Author

Drino commented Aug 22, 2022

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.

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
@Drino Drino requested a review from srittau August 23, 2022 13:19
@Drino
Copy link
Author

Drino commented Sep 23, 2022

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants