diff --git a/.chronus/changes/copilot-fix-typeddict-camelcase-docstrings-2026-6-24-17-40-35.md b/.chronus/changes/copilot-fix-typeddict-camelcase-docstrings-2026-6-24-17-40-35.md new file mode 100644 index 00000000000..c630f2e8060 --- /dev/null +++ b/.chronus/changes/copilot-fix-typeddict-camelcase-docstrings-2026-6-24-17-40-35.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-python" +--- + +Use wire names in TypedDict docstrings \ No newline at end of file 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 be35a23b89e..61a4744fa56 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 @@ -77,7 +77,10 @@ def _documentation_string( prop: Property, description_keyword: str, docstring_type_keyword: str, **kwargs: Any ) -> list[str]: retval: list[str] = [] - sphinx_prefix = f":{description_keyword} {prop.client_name}:" + doc_name = ( + prop.wire_name if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE else prop.client_name + ) + sphinx_prefix = f":{description_keyword} {doc_name}:" description = prop.description(is_operation_file=False).replace("\\", "\\\\") retval.append(f"{sphinx_prefix} {description}" if description else sphinx_prefix) # In the types file, use type_annotation (the serialized form) for docstrings @@ -85,7 +88,7 @@ def _documentation_string( doc_type = prop.type.type_annotation(**kwargs) else: doc_type = prop.type.docstring_type(**kwargs) - retval.append(f":{docstring_type_keyword} {prop.client_name}: {doc_type}") + retval.append(f":{docstring_type_keyword} {doc_name}: {doc_type}") return retval diff --git a/packages/http-client-python/tests/unit/test_typeddict.py b/packages/http-client-python/tests/unit/test_typeddict.py index 3f26c2890fb..781554ebd68 100644 --- a/packages/http-client-python/tests/unit/test_typeddict.py +++ b/packages/http-client-python/tests/unit/test_typeddict.py @@ -368,6 +368,36 @@ def test_models_mode_typeddict_serialize_contains_class(): assert "TypedDict" in output +def test_models_mode_typeddict_docstring_uses_wire_name(): + """TypedDict docstrings in types.py should document the on-the-wire property name.""" + code_model = _make_code_model(models_mode="typeddict") + string_type = build_type({"type": "string"}, code_model) + model = TypedDictModelType( + yaml_data={"name": "Foo", "type": "model", "snakeCaseName": "foo", "usage": 2}, + code_model=code_model, + properties=[ + Property( + yaml_data={ + "wireName": "paramName", + "clientName": "param_name", + "optional": True, + }, + code_model=code_model, + type=string_type, + ) + ], + ) + code_model.model_types = [model] + + env = _make_env() + output = TypesSerializer(code_model=code_model, env=env, models=[model]).serialize() + + assert ":ivar paramName:" in output + assert ":vartype paramName: str" in output + assert ":ivar param_name:" not in output + assert ":vartype param_name:" not in output + + def test_types_file_has_no_named_unions(): """Serialized types.py should not contain named union definitions.""" code_model = _make_code_model(models_mode="dpg")