bug: Doc in module attributes are not picked up

[willemkokke]

Description of the bug

griffe-typingdoc seems to not work on module attributes.

"""Module to test griffe-typingdoc."""

from typing import Annotated

from pydantic import StringConstraints
from typing_extensions import Doc

ChecksumString = Annotated[
    str, Doc("A sha256 checksum."), StringConstraints(pattern="^[a-fA-F0-9]{64}$")
]

ChecksumString2 = Annotated[str, StringConstraints(pattern="^[a-fA-F0-9]{64}$")]
"""Alternative checksum string."""

NormalString = Annotated[str, Doc("A normal string.")]


def hi(to: Annotated[str, Doc("Who to say hi to")]) -> None:
    """Say hi to someone."""
    print(f"Hi {to}!")


def hi_no_docstring(to: Annotated[str, Doc("Who to say hi to")]) -> None:
    print(f"Hi {to}!")

To Reproduce

 ```
 git clone https://github.com/willemkokke/griffe-typingdoc-repro/
 cd griffe-typingdoc-repro
 uv run mkdocs serve --verbose --open
 ```

Expected behavior

The generated docs should have a description for ChecksumString and NormalString.

Environment information

• System: macOS-15.2-arm64-arm-64bit
• Python: cpython 3.11.11 (/Users/willem/Documents/Repositories/griffe-typingdoc-repro/.venv/bin/python3)
• Environment variables:
• Installed packages:
  • griffe-typingdoc v0.2.7

Additional context

Only learned about pep 727 yesterday when fine-tuning my mkdocstrings configuration. I might be misunderstanding it completely!

I've also tried this with unwrap_annotated: false with identical results.

Urgency is low, the alternative of just using a docstring after the module attribute works fine.

[pawamoy]

Hey @willemkokke, thanks a lot for the report! I was able to confirm. I also added the relevant code to the issue body, to be sure not to lose it if you ever delete the repro repository 🙂

So, yeah, that's surprising! I'll investigate asap 😄

[pawamoy]

Ah, right, griffe-typingdoc only finds Doc annotations in, well, type annotations (after :), not in values. I'd say this would be part of a larger feature (which was explicitly rejected in the PEP I think) where docstrings attached to type are reused in other objects that reference/use these types.

ChecksumString = Annotated[
    str, Doc("A sha256 checksum."), StringConstraints(pattern="^[a-fA-F0-9]{64}$")
]

def check(checksum: ChecksumString) -> None:
    """Hey. Parameters section added, checksum param has doc from ChecksumString type."""

[pawamoy]

https://peps.python.org/pep-0727/#transferring-documentation-from-type-aliases

[pawamoy]

I think it's too bad this idea is rejected by the way, would have used it myself 😄 Anyway griffe-typingdoc is already taking a few liberties so we could still consider implementing this feature.

[willemkokke]

Oh dear.. Just after posting this I found https://gist.github.com/pawamoy/a12cb4a5f66d913519070b52b2a9d54b, and I realise the syntax should be

ChecksumString: Annotated[
    str, Doc("A sha256 checksum."), StringConstraints(pattern="^[a-fA-F0-9]{64}$")
]

instead of

ChecksumString = Annotated[
    str, Doc("A sha256 checksum."), StringConstraints(pattern="^[a-fA-F0-9]{64}$")
]

I think what I actually did when assigning was creating an implicit TypeAlias, not a .... Yeah what you said ;)

Hmm, I do actually want to create a TypeAlias in this case, because I want a reusable string type that can only hold checksums in a Pydantic model. Ah well that is enough yak shaving, good old fashioned docstrings will do the job in this case.

Sorry for the noise!

[willemkokke]

Sorry, didn't mean to close :-(