set __annotations__, describe intellisense limitations (#29)

Author: wpbonelli

attrs_mypy.py

@@ -17,6 +17,7 @@ An `xarray <https://docs.xarray.dev/en/stable/index.html>`_ integration for `att
    md/what
    md/how
    md/rules
+   md/gotchas
    examples/basics
    examples/indexes
 

docs/index.rst

@@ -0,0 +1,11 @@
+# Gotchas
+
+## Intellisense
+
+Your average felid is aloof by constitution — similarly, this library keeps to itself, though it will not prevent you from exposing *your* (classes') guts in public if you so choose.
+
+Since `xattree`-managed fields are attached via [`field_transformer`](https://www.attrs.org/en/stable/extending.html#automatic-field-transformation-and-modification), *they are not visible to static type checkers*. Static checkers don't run your code, they just look at it. This means you will not see fields like `data` (or whatever else you called your `DataTree` field), `parent`, etc in the initializer signature on hovering over your class, nor will you see an informative type hint on hovering over `xattree`-managed attributes. Intellisense *will* work properly on your own fields.
+
+## `__annotations__`
+
+Despite the above, `xattree` updates your class' `__anotations__` with the `xattree`-managed field information, in case you need it at runtime.

docs/md/gotchas.md

@@ -79,4 +79,3 @@ By default, `xattree` names the datatree attribute `data`. To name it something
 Unlike typical appointments of wood and fabric, wherever you put the tree, that's where it stays. If you try to move it (at runtime), things will break. If you regret your choice, tough luck — find a new apartment (i.e. kill the program and set `where` to something else).
 
 **Note**: some names are reserved, namely the core `xattree`-managed fields (`name`, `parent`, `children`, `dims`, and `strict`).
-

docs/md/rules.md

@@ -97,9 +97,6 @@ ignore = [
 
 [tool.mypy]
 mypy_path = "xattree"
-plugins = [
-    "attrs_mypy.py",
-]
 ignore_missing_imports = true
 warn_unreachable = true
 

pyproject.toml

@@ -1571,6 +1571,12 @@ def post_init(self):
         converters = {}
         validators = {}
 
+        # rename the datatree field to `where`
+        xtra_attrs = _XTRA_ATTRS.copy()
+        datatree = xtra_attrs.pop(_DATA)
+        xtra_attrs[where] = datatree
+        xtra_attrs = {n: f(cls) if callable(f) else f for n, f in xtra_attrs.items()}
+
         def transformer(cls: type, fields: list[Attribute]) -> Iterator[Attribute]:
             def _transform_field(field: Attribute) -> Attribute:
                 if field.name in _XTRA_ATTRS.keys():
@@ -1671,17 +1677,11 @@ def _transform_field(field: Attribute) -> Attribute:
                     alias=field.alias,
                 )
 
-            # rename the datatree field
-            xtra_attrs = _XTRA_ATTRS.copy()
-            datatree = xtra_attrs.pop(_DATA)
-            xtra_attrs[where] = datatree
-
             if is_xattree:
                 fields = [f for f in fields if f.name not in xtra_attrs.keys()]
 
             attrs_ = [_transform_field(f) for f in fields]
-            extra = [f(cls) if callable(f) else f for f in xtra_attrs.values()]
-            return attrs_ + extra  # type: ignore
+            return attrs_ + list(xtra_attrs.values())  # type: ignore
 
         old_setattr = cls.__setattr__
 
@@ -1747,10 +1747,11 @@ def drop_matching_children(node: xr.DataTree) -> xr.DataTree:
             _CONVERTERS: converters,
             _VALIDATORS: validators,
         }
-        # Register this class for parent lookup
+        cls.__annotations__ = {
+            **getattr(cls, "__annotations__", {}),
+            **{n: field.type for n, field in xtra_attrs.items()},
+        }
         _XATTREE_CLASSES.add(cls)
-
-        # Update dimension groups for all classes now that we have a new class
         _update_dim_groups()
 
         return cls