diff --git a/.chronus/changes/python-refine-api-version-doc-2026-4-15.md b/.chronus/changes/python-refine-api-version-doc-2026-4-15.md new file mode 100644 index 00000000000..539c6b12aa1 --- /dev/null +++ b/.chronus/changes/python-refine-api-version-doc-2026-4-15.md @@ -0,0 +1,7 @@ +--- +changeKind: fix +packages: + - "@typespec/http-client-python" +--- + +Refine `api_version` argument doc to show `None` as default value and include note about operation's default API version being used when not set diff --git a/packages/http-client-python/generator/pygen/codegen/models/parameter.py b/packages/http-client-python/generator/pygen/codegen/models/parameter.py index bcca96fa75c..26eb0ba5c9a 100644 --- a/packages/http-client-python/generator/pygen/codegen/models/parameter.py +++ b/packages/http-client-python/generator/pygen/codegen/models/parameter.py @@ -108,25 +108,24 @@ def description(self) -> str: type_description = self.type.description(is_operation_file=True) if type_description: base_description = add_to_description(base_description, type_description) - if self.optional and isinstance(self.type, ConstantType): - if self.is_api_version: - base_description = add_to_description( - base_description, - f"Known values are {self.get_declaration()}.", - ) - else: - base_description = add_to_description( - base_description, - f"Known values are {self.get_declaration()} and None.", - ) + if (self.optional or self.is_api_version) and isinstance(self.type, ConstantType): + base_description = add_to_description( + base_description, + f"Known values are {self.get_declaration()} and None.", + ) if not (self.optional or self.client_default_value): base_description = add_to_description(base_description, "Required.") - if self.client_default_value is not None: + if self.is_api_version: + base_description = add_to_description( + base_description, + "Default value is None. If not set, the operation's default API version will be used.", + ) + elif self.client_default_value is not None: base_description = add_to_description( base_description, f"Default value is {self.client_default_value_declaration}.", ) - if self.optional and self.client_default_value is None: + elif self.optional: base_description = add_to_description( base_description, f"Default value is {self.client_default_value_declaration}.",