Skip to content

bug: Doc in module attributes are not picked up #12

Open
Open
bug: Doc in module attributes are not picked up#12
Assignees
pawamoy
Labels
featureNew feature or request

Description

@willemkokke
willemkokke
opened on Feb 5, 2025

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.

Activity

  1. willemkokke
    added
    unconfirmedThis bug was not reproduced yet
    on Feb 5, 2025
  2. willemkokke
    assigned
    pawamoy
    on Feb 5, 2025

  3. pawamoy commented on Feb 5, 2025

    @pawamoy
    pawamoy
    on Feb 5, 2025
    Member

    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 😄

  4. pawamoy
    added
    bugSomething isn't working
    and removed
    unconfirmedThis bug was not reproduced yet
    on Feb 5, 2025
  5. pawamoy
    changed the title [-]bug:[/-] [+]bug: Doc in module attributes are not picked up[/+] on Feb 5, 2025

  6. pawamoy commented on Feb 5, 2025

    @pawamoy
    pawamoy
    on Feb 5, 2025
    Member

    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."""

  7. pawamoy commented on Feb 5, 2025

    @pawamoy
    pawamoy
    on Feb 5, 2025
    Member

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

  8. pawamoy commented on Feb 5, 2025

    @pawamoy
    pawamoy
    on Feb 5, 2025
    Member

    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.

  9. pawamoy
    added
    featureNew feature or request
    fundIssue priority can be boosted
    and removed
    bugSomething isn't working
    on Feb 5, 2025

  10. willemkokke commented on Feb 5, 2025

    @willemkokke
    willemkokke
    on Feb 5, 2025
    Author

    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!

  11. willemkokke
    closed this as completedon Feb 5, 2025

  12. willemkokke commented on Feb 5, 2025

    @willemkokke
    willemkokke
    on Feb 5, 2025
    Author

    Sorry, didn't mean to close :-(

  13. pawamoy
    reopened this on Feb 5, 2025

  14. pawamoy commented on Feb 5, 2025

    @pawamoy
    pawamoy
    on Feb 5, 2025
    Member

    No worries! Keeping open as this is a cool feature 🙂 I think you can do this though:

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

  15. willemkokke commented on Feb 5, 2025

    @willemkokke
    willemkokke
    on Feb 5, 2025
    Author

    It does, nice!

    It makes pylance unhappy though. It looks like pylance doesn't unwrap the Annotated TypeAlias during the analysis of checksum.

    Image

    Thanks for your time!

  16. pawamoy commented on Feb 5, 2025

    @pawamoy
    pawamoy
    on Feb 5, 2025
    Member

    Pylance is dumb then /s 🤡

    You're welcome!

  17. pawamoy
    removed
    fundIssue priority can be boosted
    on Mar 2, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

featureNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions