[python] fix sphinx documentation for errors thrown from methods (microsoft#5640)

fixes Azure/autorest.python#2955

---------

Co-authored-by: iscai-msft <[email protected]>

Author: iscai-msft

packages/http-client-python/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 0.6.6
 
+### Bug Fixes
+
+- Fix sphinx typing for raising documentation
+
 ### Other Changes
 
 - Order keyword-only args overload first in generated operations

packages/http-client-python/generator/pygen/codegen/models/code_model.py

@@ -313,7 +313,7 @@ def lookup_type(self, schema_id: int) -> BaseType:
         :param int schema_id: The yaml id of the schema
         :return: If created, we return the created schema, otherwise, we throw.
         :rtype: ~autorest.models.BaseType
-        :raises: KeyError if schema is not found
+        :raises KeyError: if schema is not found
         """
         try:
             return next(type for id, type in self.types_map.items() if id == schema_id)

packages/http-client-python/generator/pygen/codegen/templates/serialization.py.jinja2

@@ -389,7 +389,7 @@ class Model:
         :param str data: A str using RestAPI structure. JSON by default.
         :param str content_type: JSON by default, set application/xml if XML.
         :returns: An instance of this model
-        :raises: DeserializationError if something went wrong
+        :raises DeserializationError: if something went wrong
         :rtype: ModelType
         """
         deserializer = Deserializer(cls._infer_class_models())
@@ -412,7 +412,7 @@ class Model:
         :param function key_extractors: A key extractor function.
         :param str content_type: JSON by default, set application/xml if XML.
         :returns: An instance of this model
-        :raises: DeserializationError if something went wrong
+        :raises DeserializationError: if something went wrong
         :rtype: ModelType
         """
         deserializer = Deserializer(cls._infer_class_models())
@@ -559,7 +559,7 @@ class Serializer:  # pylint: disable=too-many-public-methods
         :param object target_obj: The data to be serialized.
         :param str data_type: The type to be serialized from.
         :rtype: str, dict
-        :raises: SerializationError if serialization fails.
+        :raises SerializationError: if serialization fails.
         :returns: The serialized data.
         """
         key_transformer = kwargs.get("key_transformer", self.key_transformer)
@@ -669,8 +669,8 @@ class Serializer:  # pylint: disable=too-many-public-methods
         :param object data: The data to be serialized.
         :param str data_type: The type to be serialized from.
         :rtype: dict
-        :raises: SerializationError if serialization fails.
-        :raises: ValueError if data is None
+        :raises SerializationError: if serialization fails.
+        :raises ValueError: if data is None
         :returns: The serialized request body
         """
 
@@ -714,8 +714,8 @@ class Serializer:  # pylint: disable=too-many-public-methods
         :param str data_type: The type to be serialized from.
         :rtype: str
         :returns: The serialized URL path
-        :raises: TypeError if serialization fails.
-        :raises: ValueError if data is None
+        :raises TypeError: if serialization fails.
+        :raises ValueError: if data is None
         """
         try:
             output = self.serialize_data(data, data_type, **kwargs)
@@ -738,8 +738,8 @@ class Serializer:  # pylint: disable=too-many-public-methods
         :param object data: The data to be serialized.
         :param str data_type: The type to be serialized from.
         :rtype: str, list
-        :raises: TypeError if serialization fails.
-        :raises: ValueError if data is None
+        :raises TypeError: if serialization fails.
+        :raises ValueError: if data is None
         :returns: The serialized query parameter
         """
         try:
@@ -768,8 +768,8 @@ class Serializer:  # pylint: disable=too-many-public-methods
         :param object data: The data to be serialized.
         :param str data_type: The type to be serialized from.
         :rtype: str
-        :raises: TypeError if serialization fails.
-        :raises: ValueError if data is None
+        :raises TypeError: if serialization fails.
+        :raises ValueError: if data is None
         :returns: The serialized header
         """
         try:
@@ -788,9 +788,9 @@ class Serializer:  # pylint: disable=too-many-public-methods
 
         :param object data: The data to be serialized.
         :param str data_type: The type to be serialized from.
-        :raises: AttributeError if required data is None.
-        :raises: ValueError if data is None
-        :raises: SerializationError if serialization fails.
+        :raises AttributeError: if required data is None.
+        :raises ValueError: if data is None
+        :raises SerializationError: if serialization fails.
         :returns: The serialized data.
         :rtype: str, int, float, bool, dict, list
         """
@@ -1125,7 +1125,7 @@ class Serializer:  # pylint: disable=too-many-public-methods
 
         :param Datetime attr: Object to be serialized.
         :rtype: str
-        :raises: TypeError if format invalid.
+        :raises TypeError: if format invalid.
         :return: serialized rfc
         """
         try:
@@ -1151,7 +1151,7 @@ class Serializer:  # pylint: disable=too-many-public-methods
 
         :param Datetime attr: Object to be serialized.
         :rtype: str
-        :raises: SerializationError if format invalid.
+        :raises SerializationError: if format invalid.
         :return: serialized iso
         """
         if isinstance(attr, str):
@@ -1184,7 +1184,7 @@ class Serializer:  # pylint: disable=too-many-public-methods
 
         :param Datetime attr: Object to be serialized.
         :rtype: int
-        :raises: SerializationError if format invalid
+        :raises SerializationError: if format invalid
         :return: serialied unix
         """
         if isinstance(attr, int):
@@ -1421,7 +1421,7 @@ class Deserializer:
         :param str target_obj: Target data type to deserialize to.
         :param requests.Response response_data: REST response object.
         :param str content_type: Swagger "produces" if available.
-        :raises: DeserializationError if deserialization fails.
+        :raises DeserializationError: if deserialization fails.
         :return: Deserialized object.
         :rtype: object
         """
@@ -1435,7 +1435,7 @@ class Deserializer:
 
         :param str target_obj: Target data type to deserialize to.
         :param object data: Object to deserialize.
-        :raises: DeserializationError if deserialization fails.
+        :raises DeserializationError: if deserialization fails.
         :return: Deserialized object.
         :rtype: object
         """
@@ -1650,7 +1650,7 @@ class Deserializer:
 
         :param str data: The response string to be deserialized.
         :param str data_type: The type to deserialize to.
-        :raises: DeserializationError if deserialization fails.
+        :raises DeserializationError: if deserialization fails.
         :return: Deserialized object.
         :rtype: object
         """
@@ -1732,7 +1732,7 @@ class Deserializer:
         :param dict attr: Dictionary to be deserialized.
         :return: Deserialized object.
         :rtype: dict
-        :raises: TypeError if non-builtin datatype encountered.
+        :raises TypeError: if non-builtin datatype encountered.
         """
         if attr is None:
             return None
@@ -1778,7 +1778,7 @@ class Deserializer:
         :param str data_type: deserialization data type.
         :return: Deserialized basic type.
         :rtype: str, int, float or bool
-        :raises: TypeError if string format is not valid.
+        :raises TypeError: if string format is not valid.
         """
         # If we're here, data is supposed to be a basic type.
         # If it's still an XML node, take the text
@@ -1869,7 +1869,7 @@ class Deserializer:
         :param str attr: response string to be deserialized.
         :return: Deserialized bytearray
         :rtype: bytearray
-        :raises: TypeError if string format invalid.
+        :raises TypeError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -1882,7 +1882,7 @@ class Deserializer:
         :param str attr: response string to be deserialized.
         :return: Deserialized base64 string
         :rtype: bytearray
-        :raises: TypeError if string format invalid.
+        :raises TypeError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -1897,7 +1897,7 @@ class Deserializer:
 
         :param str attr: response string to be deserialized.
         :return: Deserialized decimal
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         :rtype: decimal
         """
         if isinstance(attr, ET.Element):
@@ -1915,7 +1915,7 @@ class Deserializer:
         :param str attr: response string to be deserialized.
         :return: Deserialized int
         :rtype: long or int
-        :raises: ValueError if string format invalid.
+        :raises ValueError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -1928,7 +1928,7 @@ class Deserializer:
         :param str attr: response string to be deserialized.
         :return: Deserialized duration
         :rtype: TimeDelta
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -1946,7 +1946,7 @@ class Deserializer:
         :param str attr: response string to be deserialized.
         :return: Deserialized date
         :rtype: Date
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -1962,7 +1962,7 @@ class Deserializer:
         :param str attr: response string to be deserialized.
         :return: Deserialized time
         :rtype: datetime.time
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -1977,7 +1977,7 @@ class Deserializer:
         :param str attr: response string to be deserialized.
         :return: Deserialized RFC datetime
         :rtype: Datetime
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -2000,7 +2000,7 @@ class Deserializer:
         :param str attr: response string to be deserialized.
         :return: Deserialized ISO datetime
         :rtype: Datetime
-        :raises: DeserializationError if string format invalid.
+        :raises DeserializationError: if string format invalid.
         """
         if isinstance(attr, ET.Element):
             attr = attr.text
@@ -2038,7 +2038,7 @@ class Deserializer:
         :param int attr: Object to be serialized.
         :return: Deserialized datetime
         :rtype: Datetime
-        :raises: DeserializationError if format invalid
+        :raises DeserializationError: if format invalid
         """
         if isinstance(attr, ET.Element):
             attr = int(attr.text)  # type: ignore