python / python/mypy

emit attribute/variable docstrings

オープン
#21,645 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

feature topic-stubgen
主要言語
Python
スター
20.6k
フォーク
3.3k
PR マージ指標
PR 指標を取得中

説明

Feature

stubgen --include-docstrings currently emits module, class, and function/method docstrings, but drops attribute (variable) docstrings — the string literal immediately following a variable assignment (PEP 224-style), which Pyright/Pylance read for hover and completion docs. I'd like --include-docstrings to also carry these through into the generated .pyi, for module-level variables, class/instance attributes, dataclass fields, and TypedDict items.

Pitch

minimal repro on mypy 2.1.0:

class ResourceAttrs(TypedDict, total=False):
"""Shared resource attributes."""
name: NotRequired[str]
"""Resource name."""
Actual: the field docstring is dropped; only the class docstring survives.
Expected: the """Resource name.""" line is preserved under name:.

Why it matters: attribute docstrings are the standard, tool-supported way to document TypedDict/dataclass/class fields; when a project ships a stub-only package built by stubgen, all per-field docs are silently lost even though the source has them. In my case, I am trying to build stubs for type completion on kwargs in an IDE like VS Code. I am trying to better document kwargs where they have been used historically, and with the full source code the IDE can tooltip the class property docstrings on hover (hover over the name key above shows "Resource name.", but this could be a more detailed docstring explaining the usage and impact of each keyword argument in the kwargs.

Workaround: class property documentation could be bubbled up into the class docstring, but this can be a bit more overwhelming as kwargs grows.

Context: this is the unfinished "members" part of #11965 (closed by #13284, which did module/class/function only). Related: #16114, #16543, #17200, #17964.

コントリビューションガイド

コントリビューションガイドを開く

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

stubgen --include-docstrings のエントリポイントから開始し、モジュール、クラス、関数の docstring が現在どのように収集され、出力されているかを追跡します。モジュールレベルの変数、クラス属性とインスタンス属性、dataclass フィールド、TypedDict 項目の変数 docstring を対象にし、その後、ResourceAttrs の例で生成された .pyi にフィールドのドキュメントが保持されることを確認します。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
python
領域
tooling
issue の種類
機能追加
難易度
4/5
見積もり時間
3〜5日
活発さ
静か
明瞭さ
おおむね明確
初心者へのやさしさ
55/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。