From acb704df255d7045c31a66f72fe0d509b17e0789 Mon Sep 17 00:00:00 2001 From: jennypng <63012604+JennyPng@users.noreply.github.com> Date: Thu, 16 Jul 2026 22:35:52 -0700 Subject: [PATCH 1/4] fix(http-client-python): remove duplicate model docstrings and useless pylint suppressions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 703c4fd4-5e78-4f26-b389-f4d336687010 --- .../pygen/codegen/models/operation_group.py | 2 -- .../codegen/serializers/model_serializer.py | 27 ++++++++----------- .../codegen/templates/model_dpg.py.jinja2 | 5 ---- 3 files changed, 11 insertions(+), 23 deletions(-) diff --git a/packages/http-client-python/generator/pygen/codegen/models/operation_group.py b/packages/http-client-python/generator/pygen/codegen/models/operation_group.py index 798c7ae5b96..5c0f467806c 100644 --- a/packages/http-client-python/generator/pygen/codegen/models/operation_group.py +++ b/packages/http-client-python/generator/pygen/codegen/models/operation_group.py @@ -82,8 +82,6 @@ def pylint_disable(self) -> str: retval: str = "" if self.has_abstract_operations: retval = add_to_pylint_disable(retval, "abstract-class-instantiated") - if not self.is_mixin: - retval = add_to_pylint_disable(retval, "docstring-missing-param") if len(self.operations) > 20: retval = add_to_pylint_disable(retval, "too-many-public-methods") if len(self.class_name) > NAME_LENGTH_LIMIT and self.class_name[0] != "_": diff --git a/packages/http-client-python/generator/pygen/codegen/serializers/model_serializer.py b/packages/http-client-python/generator/pygen/codegen/serializers/model_serializer.py index 15e82108a89..a46bfee9fc3 100644 --- a/packages/http-client-python/generator/pygen/codegen/serializers/model_serializer.py +++ b/packages/http-client-python/generator/pygen/codegen/serializers/model_serializer.py @@ -122,15 +122,6 @@ def input_documentation_string(prop: Property) -> list[str]: # building the param line of the property doc return _documentation_string(prop, "keyword", "paramtype") - def keyword_documentation_string(self, model: ModelType) -> list[str]: - # building the ``:keyword:``/``:paramtype:`` lines for the keyword-only - # arguments of the generated ``__init__`` overload so that the docstring - # keeps a 1:1 correlation with the keyword-only arguments in the signature. - retval: list[str] = [] - for prop in sorted(self._init_line_parameters(model), key=lambda x: x.optional): - retval.extend(self.input_documentation_string(prop)) - return retval - @staticmethod def variable_documentation_string(prop: Property) -> list[str]: return _documentation_string(prop, "ivar", "vartype") @@ -210,13 +201,7 @@ def pylint_disable(self, model: ModelType) -> str: def class_pylint_disable(self, model: ModelType) -> str: """Class-level pylint disables for the model declaration line.""" - retval = model.pylint_disable() - # When the model's only constructor is ``def __init__(self, *args, **kwargs)`` (i.e. no - # typed overload is generated), the guideline checker reports the ``*args`` vararg as an - # undocumented param. There is no meaningful param to document, so silence the check. - if not self.need_init(model) and self.initialize_properties(model): - retval = add_to_pylint_disable(retval, "docstring-missing-param") - return retval + return model.pylint_disable() def global_pylint_disables(self) -> str: return "" @@ -428,6 +413,16 @@ def declare_model(self, model: ModelType) -> str: basename += f", discriminator='{model.discriminator_value}'" return f"class {model.name}({basename}):{self.class_pylint_disable(model)}" + def class_pylint_disable(self, model: ModelType) -> str: + retval = super().class_pylint_disable(model) + # DPG models render an empty ``@overload def __init__(self, *, ...)`` body, so the + # guideline checker validates the keyword-only arguments against the *class* docstring. + # We only document those arguments as instance variables (``:ivar:``) to avoid a redundant + # ``:keyword:`` entry per property, so silence the keyword/keyword-only correlation check. + if self._init_line_parameters(model): + retval = add_to_pylint_disable(retval, "docstring-keyword-should-match-keyword-only") + return retval + @staticmethod def get_properties_to_declare(model: ModelType) -> list[Property]: if model.parents: diff --git a/packages/http-client-python/generator/pygen/codegen/templates/model_dpg.py.jinja2 b/packages/http-client-python/generator/pygen/codegen/templates/model_dpg.py.jinja2 index 6a2b533ae55..8bcbbf4af41 100644 --- a/packages/http-client-python/generator/pygen/codegen/templates/model_dpg.py.jinja2 +++ b/packages/http-client-python/generator/pygen/codegen/templates/model_dpg.py.jinja2 @@ -16,11 +16,6 @@ {% endfor %} {% endfor %} {% endif %} - {% if serializer.need_init(model) %} - {% for line in serializer.keyword_documentation_string(model) %} - {{ macros.wrap_model_string(line, '\n ') -}} - {% endfor %} - {% endif %} """ {% if model.is_polymorphic %} From 40ee93c502aad6612a2df0dcf800c1da1ebd7346 Mon Sep 17 00:00:00 2001 From: jennypng <63012604+JennyPng@users.noreply.github.com> Date: Thu, 16 Jul 2026 22:38:38 -0700 Subject: [PATCH 2/4] chore: add changelog entry Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 703c4fd4-5e78-4f26-b389-f4d336687010 --- .../python-docstring-duplicate-fix-2026-7-16-22-38-0.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 .chronus/changes/python-docstring-duplicate-fix-2026-7-16-22-38-0.md diff --git a/.chronus/changes/python-docstring-duplicate-fix-2026-7-16-22-38-0.md b/.chronus/changes/python-docstring-duplicate-fix-2026-7-16-22-38-0.md new file mode 100644 index 00000000000..9440496bf9b --- /dev/null +++ b/.chronus/changes/python-docstring-duplicate-fix-2026-7-16-22-38-0.md @@ -0,0 +1,8 @@ +--- +# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking +changeKind: fix +packages: + - "@typespec/http-client-python" +--- + +[Python] Fix duplicate `:keyword:`/`:paramtype:` lines in generated model docstrings and remove `docstring-missing-param` pylint suppressions that became useless with `azure-pylint-guidelines-checker` `0.5.9` From a766ba8ed1bb2a70a8c8810dcb3db3fe7c3e5bf3 Mon Sep 17 00:00:00 2001 From: jennypng <63012604+JennyPng@users.noreply.github.com> Date: Thu, 16 Jul 2026 23:19:38 -0700 Subject: [PATCH 3/4] Restore docstring-missing-param suppressions; keep only duplicate-docstring fix The previous commit removed docstring-missing-param suppressions on passthrough operations classes and passthrough-only models based on a tainted local 0.5.9 checker that (incorrectly) exempted (*args, **kwargs) constructors. The real 0.5.9 used by integration CI still requires those suppressions, so restore them. The only net change from the base commit is now: remove the duplicate :keyword:/:paramtype: docstring lines on DPG models and silence docstring-keyword-should-match-keyword-only instead. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 703c4fd4-5e78-4f26-b389-f4d336687010 --- .../generator/pygen/codegen/models/operation_group.py | 2 ++ .../pygen/codegen/serializers/model_serializer.py | 8 +++++++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/packages/http-client-python/generator/pygen/codegen/models/operation_group.py b/packages/http-client-python/generator/pygen/codegen/models/operation_group.py index 5c0f467806c..798c7ae5b96 100644 --- a/packages/http-client-python/generator/pygen/codegen/models/operation_group.py +++ b/packages/http-client-python/generator/pygen/codegen/models/operation_group.py @@ -82,6 +82,8 @@ def pylint_disable(self) -> str: retval: str = "" if self.has_abstract_operations: retval = add_to_pylint_disable(retval, "abstract-class-instantiated") + if not self.is_mixin: + retval = add_to_pylint_disable(retval, "docstring-missing-param") if len(self.operations) > 20: retval = add_to_pylint_disable(retval, "too-many-public-methods") if len(self.class_name) > NAME_LENGTH_LIMIT and self.class_name[0] != "_": diff --git a/packages/http-client-python/generator/pygen/codegen/serializers/model_serializer.py b/packages/http-client-python/generator/pygen/codegen/serializers/model_serializer.py index a46bfee9fc3..be35a23b89e 100644 --- a/packages/http-client-python/generator/pygen/codegen/serializers/model_serializer.py +++ b/packages/http-client-python/generator/pygen/codegen/serializers/model_serializer.py @@ -201,7 +201,13 @@ def pylint_disable(self, model: ModelType) -> str: def class_pylint_disable(self, model: ModelType) -> str: """Class-level pylint disables for the model declaration line.""" - return model.pylint_disable() + retval = model.pylint_disable() + # When the model's only constructor is ``def __init__(self, *args, **kwargs)`` (i.e. no + # typed overload is generated), the guideline checker reports the ``*args`` vararg as an + # undocumented param. There is no meaningful param to document, so silence the check. + if not self.need_init(model) and self.initialize_properties(model): + retval = add_to_pylint_disable(retval, "docstring-missing-param") + return retval def global_pylint_disables(self) -> str: return "" From 0497f9f94ebbca6f38dfa6a11d9c4867ad661a97 Mon Sep 17 00:00:00 2001 From: jennypng <63012604+JennyPng@users.noreply.github.com> Date: Thu, 16 Jul 2026 23:20:23 -0700 Subject: [PATCH 4/4] chore: update changelog to reflect duplicate-docstring-only scope Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 703c4fd4-5e78-4f26-b389-f4d336687010 --- .../changes/python-docstring-duplicate-fix-2026-7-16-22-38-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chronus/changes/python-docstring-duplicate-fix-2026-7-16-22-38-0.md b/.chronus/changes/python-docstring-duplicate-fix-2026-7-16-22-38-0.md index 9440496bf9b..b25638ff083 100644 --- a/.chronus/changes/python-docstring-duplicate-fix-2026-7-16-22-38-0.md +++ b/.chronus/changes/python-docstring-duplicate-fix-2026-7-16-22-38-0.md @@ -5,4 +5,4 @@ packages: - "@typespec/http-client-python" --- -[Python] Fix duplicate `:keyword:`/`:paramtype:` lines in generated model docstrings and remove `docstring-missing-param` pylint suppressions that became useless with `azure-pylint-guidelines-checker` `0.5.9` +[Python] Fix duplicate `:keyword:`/`:paramtype:` lines in generated DPG model docstrings that duplicated the existing `:ivar:`/`:vartype:` entries