Documenting TypeAlias

[patrick91]

Hi there! In Strawberry we have a couple of public attributes (and functions[1] defined as attributes)

strawberry.Parent is one example, which is defined like this:

T = TypeVar("T")

Parent = Annotated[T, StrawberryParent()]
Parent.__doc__ = "Some doc here"

I don't know if Parent.__doc__ = ... works anywhere, I think it did work on VS Code, but I don't use it anymore.

Anyway, I wonder if there's a way to make this work with griffe, my first attempt was to use the Doc function (and that's why I'm opening the issue here), like this:

Parent = Annotated[T, StrawberryParent(), Doc("Some doc here")]

But that doesn't seem to be supported, and maybe it never will? Do you have any suggestion?

While writing this I thought of another option of converting Parent to a class and use __class_get_item__ to return an Annotated type, but I'm not sure I like it

JSON

{
  "kind": "attribute",
  "name": "strawberry.Parent",
  "path": "strawberry.parent.Parent",
  "filepath": "/private/var/folders/tz/d3_033052gg7k7lrj34yj0lr0000gn/T/tmp78iz_csm/strawberry/strawberry/parent.py",
  "relative_filepath": "strawberry/parent.py",
  "relative_package_filepath": "strawberry/parent.py",
  "lineno": 10,
  "endlineno": 14,
  "labels": [
    "module-attribute"
  ],
  "members": [],
  "value": {
    "left": {
      "name": "Annotated",
      "cls": "ExprName"
    },
    "slice": {
      "elements": [
        {
          "name": "T",
          "cls": "ExprName"
        },
        {
          "arguments": [],
          "function": {
            "name": "StrawberryParent",
            "cls": "ExprName"
          },
          "cls": "ExprCall"
        },
        {
          "arguments": [
            "'Example'"
          ],
          "function": {
            "name": "Doc",
            "cls": "ExprName"
          },
          "cls": "ExprCall"
        }
      ],
      "implicit": true,
      "cls": "ExprTuple"
    },
    "cls": "ExprSubscript"
  }
}

[1]: Like these, but we can add docs by creating a real function, so I wouldn't worry about them now

[pawamoy]

Parent = Annotated[T, StrawberryParent(), Doc("Some doc here")]

It definitely looks like it should be supported. Let me look into it 🙂

[pawamoy]

Hmmm.

So actually some people recommended against supporting this in PEP 727, because it would make adoption much more difficult at first.

The thing is, here you're defining a type. And you probably expect its docstring to be reused for every other object that is annotated with this type, correct? That's indeed not supported right now, but I like the functionality (I think it's a great feature of what PEP 727 brings to Python), so I'm willing to support it.

Could you paste some more elaborate snippet to show how you'd like to use such a feature, just so that we're on the same page?

Also note that this could require non-trivial changes to Griffe: this might not be easy to implement 🙂

[patrick91]

So actually some people recommended against supporting this in PEP 727, because it would make adoption much more difficult at first.

That's a good point

The thing is, here you're defining a type. And you probably expect its docstring to be reused for every other object that is annotated with this type, correct? That's indeed not supported right now, but I like the functionality (I think it's a great feature of what PEP 727 brings to Python), so I'm willing to support it.

Ah, not really! I only want do document it for the API Docs, I don't need/want it to be available as a doc everywhere it is used. I guess this is were things would get ambiguous

Maybe the best option for what I'm trying to do is to add a plugin that uses the __doc__ attribute and adds it as a docstring?

[patrick91]

mmh, doesn't look like I can get Parent.__doc__ via a plugin

[pawamoy]

Ah, not really! I only want do document it for the API Docs, I don't need/want it to be available as a doc everywhere it is used. I guess this is were things would get ambiguous

Yes that would make things ambiguous indeed 🤔 Unless you annotate the type itself, but this feels really weird:

Parent: Annotated[TypeAlias, Doc("Some doc here")] = Annotated[T, StrawberryParent()]

There's always the solution to add a docstring below the assignment, no?

Parent = Annotated[T, StrawberryParent()]
"""Some doc here."""

[patrick91]

There's always the solution to add a docstring below the assignment, no?

That too! It doesn't work yet with griffe, right?

[pawamoy]

It does work ^^

[patrick91]

oh! sorry I probably did a mistake when checking then! I think I'm good with that then! thanks 😊