diff --git a/docs/extending.rst b/docs/extending.rst index 8a6767cf..8994940f 100644 --- a/docs/extending.rst +++ b/docs/extending.rst @@ -47,7 +47,7 @@ An example for that is the package `environ-config `_ mypy's ``attrs`` plugin. At the moment, the best workaround is to hold your nose, write a fake mypy plugin, and mutate a bunch of global variables:: @@ -90,9 +90,9 @@ Then tell mypy about your plugin using your project's ``mypy.ini``: You can only use this trick to tell mypy that a class is actually an ``attrs`` class. Pyright -************* +^^^^^^^ -Generic decorator wrapping is supported in ``pyright`` via the provisional dataclass_transform_ specification. +Generic decorator wrapping is supported in `pyright `_ via their dataclass_transform_ specification. For a custom wrapping of the form:: @@ -112,11 +112,12 @@ This is implemented via a ``__dataclass_transform__`` type decorator in the cust @__dataclass_transform__(field_descriptors=(attr.attrib, attr.field)) def custom_define(f): ... -.. note:: +.. warning:: - ``dataclass_transform`` is supported provisionally as of ``pyright`` 1.1.135. + ``dataclass_transform`` is supported **provisionally** as of ``pyright`` 1.1.135. + + Both the ``pyright`` dataclass_transform_ specification and ``attrs`` implementation may change in future versions. - Both the ``pyright`` dataclass_transform_ specification and ``attrs`` implementation may changed in future versions. Types ----- @@ -306,4 +307,4 @@ It has the signature ***** -.. _dataclass_transform: https://github.com/microsoft/pyright/blob/1.1.135/specs/dataclass_transforms.md +.. _dataclass_transform: https://github.com/microsoft/pyright/blob/master/specs/dataclass_transforms.md diff --git a/docs/types.rst b/docs/types.rst index 0b57e1a7..f2dffca7 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -41,12 +41,13 @@ Also, starting in Python 3.10 (:pep:`526`) **all** annotations will be string li When this happens, ``attrs`` will simply put these string literals into the ``type`` attributes. If you need to resolve these to real types, you can call `attr.resolve_types` which will update the attribute in place. -In practice though, types show their biggest usefulness in combination with tools like mypy_, pytype_ or pyright_ that have dedicated support for ``attrs`` classes. +In practice though, types show their biggest usefulness in combination with tools like mypy_, pytype_, or pyright_ that have dedicated support for ``attrs`` classes. The addition of static types is certainly one of the most exciting features in the Python ecosystem and helps you writing *correct* and *verified self-documenting* code. If you don't know where to start, Carl Meyer gave a great talk on `Type-checked Python in the Real World `_ at PyCon US 2018 that will help you to get started in no time. + mypy ---- @@ -83,27 +84,26 @@ and requires explicit type annotations using the :ref:`next-gen` or ``@attr.s(au Given the following definition, ``pyright`` will generate static type signatures for ``SomeClass`` attribute access, ``__init__``, ``__eq__``, and comparison methods:: @attr.define - class SomeClass(object): + class SomeClass: a_number: int = 42 list_of_numbers: typing.List[int] = attr.field(factory=list) -.. note:: +.. warning:: ``dataclass_transform``-based types are supported provisionally as of ``pyright`` 1.1.135 and ``attrs`` 21.1. Both the ``pyright`` dataclass_transform_ specification and ``attrs`` implementation may changed in future versions. The ``pyright`` inferred types are a subset of those supported by ``mypy``, including: - - The generated ``__init__`` signature only includes the attribute type annotations, - and does not include attribute ``converter`` types. + - The generated ``__init__`` signature only includes the attribute type annotations. + It currently does not include attribute ``converter`` types. - The ``attr.frozen`` decorator is not typed with frozen attributes, which are properly typed via ``attr.define(frozen=True)``. Your constructive feedback is welcome in both `attrs#795 `_ and `pyright#1782 `_. -***** .. _mypy: http://mypy-lang.org .. _pytype: https://google.github.io/pytype/ .. _pyright: https://github.com/microsoft/pyright -.. _dataclass_transform: https://github.com/microsoft/pyright/blob/1.1.135/specs/dataclass_transforms.md +.. _dataclass_transform: https://github.com/microsoft/pyright/blob/master/specs/dataclass_transforms.md diff --git a/tox.ini b/tox.ini index ad201936..a79d406e 100644 --- a/tox.ini +++ b/tox.ini @@ -133,5 +133,5 @@ basepython = python3.9 deps = nodeenv commands = nodeenv --prebuilt --node=lts --force {envdir} - npm install -g --no-package-lock --no-save pyright@1.1.135 + npm install -g --no-package-lock --no-save pyright pytest tests/test_pyright.py -vv