Implement pyright support via dataclass_transforms

[asford]

Implements baseline support for pyright as described in #795.

Pull Request Check List

This is just a friendly reminder about the most common mistakes. Please make sure that you tick all boxes. But please read our contribution guide at least once, it will save you unnecessary review cycles!

If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing left to do. If your pull request is a documentation fix or a trivial typo, feel free to delete the whole thing.

• Clarify support for frozen either in upstream spec or attrs docs.
• Added tests for changed code.
• New features have been added to our Hypothesis testing strategy.
• Changes or additions to public APIs are reflected in our type stubs (files ending in .pyi).
  • ...and used in the stub test file tests/typing_example.py.
• Updated documentation for changed code.
  • New functions/classes have to be added to docs/api.rst by hand.
  • Changes to the signature of @attr.s() have to be added by hand too.
  • Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives. Find the appropriate next version in our __init__.py file.
• Documentation in .rst files is written using semantic newlines.
• Changes (and possible deprecations) have news fragments in changelog.d.

If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!

[asford]

Please view as a starting point, I don't have super strong ownership over this feature and would happily cede the conn if this should be fast-tracked for 21.1.

This feature can be implemented via annotations on custom decorator wrappers for projects that want to use pyright and attrs now, so I don't think there's an absolute need to implement this 21.1 if attrs would like to provide more feedback upstream.

There are a number of disparities with the existing mypy types including:

• The attr.frozen decorator does not properly read-only properties, which is supported are supported via attr.define(frozen=True).
• Converters are explicitly not implemented.

[euresti]

There should probably be an implementation of this somewhere right? Otherwise this won't be useful outside of attrs.

[asford]

This is a little strange, the decorator is just being used as a marker for pyright. The upstream spec specifies that the __dataclass_transform__ decorator is defined on a per-project basis either in the a .py or .pyi source file, essentially as a compatibility layer until this is moved into typing_extensions.

[euresti]

Hmm. I'm a little concerned (ok not too much but it definitely feels weird) about having a def in the pyi file that doesn't exist in the .py file. It means that someone could try to use this function in their own code but mypy wouldn't warn them that it doesn't really exist. It would fail at runtime. Are we sure we don't want to put an implementation in _funcs.py or something?

[asford]

🤔 I've done a little test of this. Under the 1.1.135 pyright implementation if we:

• Define a __dataclass_transform__ decorator in __init__.pyi file.
• Define a __dataclass_transform__ method in __funcs.py and import in __init__.py.

Then a custom annotation of the form has types inferred properly.

import attr

@attr.__dataclass_transform__(fields=(attr.field, attr.attrib))
def custom_define(cls):
   return attr.define(cls)

@custom_define
class Custom:
    a: int

However, given that this is a very early and provisional specification and implementation in pyright, adding a "surprisingly functional" shim in attrs introduces a potentially risky coupling. We've a choice between:

1. An immediate and loud runtime failure if you "try to use" the attrs-internal __dataclass_transform__ .pyi definition, that won't be caught static type checkers.
2. A surprisingly functional form that "works" (a no-op a runtime, currently works at typingtime), but relies on unspecified upstream behavior.

Given how bleeding-edge this feature is I have a weakly held preference that we opt for 2 for this release to ensure that folks don't implictly rely on the import attr.__dataclass_transform__ behavior and instead wait until the spec bakes enough for the dataclass_transform to show up in typing_extensions.

Of course, happy to reconsider.

[euresti]

Since this is only for pyright and doesn't currently get mypy to do the right thing (i.e. it doesn't tell mypy that this is an attrs class creator) perhaps it's best if we leave this only inside the pyi file. I might add a comment on here that says that this method doesn't actually exist at runtime.

[asford]

Roger, comment added.

[hynek]

Ah @erictraut it would be great if you could give it a casual glance!

If everything goes well, we'll be able to publish 21.1 within a week. 🤞

[erictraut]

This looks good to me.

My only word of caution is that my spec is not yet final. It's still in the review stage, so I'm a little nervous about a major library adopting it at this phase. On the other hand, the worst that would happen if I need to change the spec is that pyright/pylance users would be no worse off than they are today with respect to type support for attrs. Sounds like a reasonable risk to take.

[asford]

My only word of caution is that my spec is not yet final. It's still in the review stage, so I'm a little nervous about a major library adopting it at this phase. On the other hand, the worst that would happen if I need to change the spec is that pyright/pylance users would be no worse off than they are today with respect to type support for attrs. Sounds like a reasonable risk to take.

Fully agree with this. My operating assumption is that this is highly provisional and primarily intended to allow for rapid feedback on the upstream specification.

@hynek, would you be comfortable with additional minor releases in this release series if/when the upstream spec evolves?

[asford]

This is ready for a "near final" review.
I've added baseline coverage for the feature in an additional tox environment that includes pyright,
the current tox environment could be reconfigured to install node and pyright into the standard test env.

[hynek]

lint is failing 😇

also could you please move the pyright stuff to 3.9? 3.8 is overflowing already anyways :)

[hynek]

Oh and some markup problems too – check out https://attrs--796.org.readthedocs.build/en/796/types.html#pyright pls. I looks like unbalanced backticks

[hynek]

OK thank you very much for the quick turnaround everyone; I'm very excited by this!

I'm merging it but there's one thing that's a bit weird to me and that's the hard pin of pyright's version everywhere – down to the micro. I don't think this is necessary?

[hynek]

JFTR I've unpinned in f41db43 and added some docs polish. I didn't want to pester you with more review rounds, feel free to yell at me if you disagree with anything.

I hope to publish later this week – as far as I can tell, everything has landed.

[erictraut]

The code and documentation look good to me.

[asford]

Agreed, thank you for the polish on the docs.

On Wed, May 5, 2021 at 07:46 Eric Traut ***@***.***> wrote: The code and documentation look good to me. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#796 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACFBKHI34DIGY5AZPIGXBTTMFK6FANCNFSM43VVKLKA> .

-- Alex Ford ***@***.*** 206.659.6559

[hynek]

Thanks all!

Eric quick question since I don't have a good way to test this: does this mean that attrs 21.1 will also automagically work with pylance / VS Code? (Working on the release announcement)

[jakebailey]

Yes, Pylance has had this dataclass transform support since version 2021.4.2 (released a couple of weeks ago).