Allow deserialization of undefined object

doc/source/api/index.rst

@@ -35,14 +35,15 @@ This section summarizes OpenAPI-Common helper functions.
 Exceptions and warnings
 =======================
 
-This section summarizes OpenAPI-Common attributes.
+This section summarizes OpenAPI-Common exceptions and warnings.
 
 .. autosummary::
    :toctree: _autosummary
 
    ApiException
    ApiConnectionException
    AuthenticationWarning
+   UndefinedObjectWarning
 
 
 ============

src/ansys/openapi/common/__init__.py

@@ -6,7 +6,12 @@
 
 from ._api_client import ApiClient
 from ._base import ApiBase, ApiClientBase, ModelBase, Unset, Unset_Type
-from ._exceptions import ApiConnectionException, ApiException, AuthenticationWarning
+from ._exceptions import (
+    ApiConnectionException,
+    ApiException,
+    AuthenticationWarning,
+    UndefinedObjectWarning,
+)
 from ._session import ApiClientFactory, OIDCSessionBuilder
 from ._util import SessionConfiguration, generate_user_agent
 
@@ -22,6 +27,7 @@
     "ApiBase",
     "ApiClientBase",
     "ModelBase",
+    "UndefinedObjectWarning",
     "Unset",
     "Unset_Type",
 ]

src/ansys/openapi/common/_api_client.py

@@ -21,12 +21,16 @@
     cast,
 )
 from urllib.parse import quote
+import warnings
 
-from dateutil.parser import parse
 import requests
 
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore", category=DeprecationWarning)
+    from dateutil.parser import parse
+
 from ._base import ApiClientBase, DeserializedType, ModelBase, PrimitiveType, SerializedType, Unset
-from ._exceptions import ApiException
+from ._exceptions import ApiException, UndefinedObjectWarning
 from ._util import SessionConfiguration, handle_response
 
 
@@ -346,10 +350,20 @@ def __deserialize(self, data: SerializedType, klass_name: str) -> DeserializedTy
 
             * String class name
             * String type definition for list or dictionary
+            * "object" literal, which returns the dictionary as-is
         """
         if data is None:
             return None
 
+        if klass_name == "object":
+            warnings.warn(
+                "Attempting to deserialize an object with no defined type. Returning "
+                "the raw data as a dictionary. Check your OpenAPI definition and ensure "
+                "all types are fully defined.",
+                UndefinedObjectWarning,
+            )
+            return data
+
         list_match = self.LIST_MATCH_REGEX.match(klass_name)
         if list_match is not None:
             assert isinstance(data, list)

src/ansys/openapi/common/_exceptions.py

@@ -106,3 +106,15 @@ def __str__(self) -> str:
     def __repr__(self) -> str:
         """Printable representation of the object."""
         return f"ApiException({self.status_code}, '{self.reason_phrase}', '{self.body}')"
+
+
+class UndefinedObjectWarning(UserWarning):
+    """
+    Provides a warning for when a model is incompletely described in the OpenAPI definition.
+
+    The data received from the server cannot be fully deserialized, and so the response is provided
+    as an un-deserialized dictionary.
+
+    This warning can be safely suppressed if the required detail cannot be added to the OpenAPI
+    definition, but in this case the deserialization must be defined manually.
+    """

tests/test_api_client.py

@@ -15,7 +15,12 @@
 from requests_mock.request import _RequestObjectProxy
 from requests_mock.response import _FakeConnection, _IOReader
 
-from ansys.openapi.common import ApiClient, ApiException, SessionConfiguration
+from ansys.openapi.common import (
+    ApiClient,
+    ApiException,
+    SessionConfiguration,
+    UndefinedObjectWarning,
+)
 
 TEST_URL = "http://localhost/api/v1.svc"
 UA_STRING = "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
@@ -390,6 +395,15 @@ def test_deserialize_primitive_of_wrong_type_does_nothing(self, data, target_typ
         assert isinstance(output, type(data))
         assert output == data
 
+    def test_deserialize_undefined_object_returns_dict_and_warns(self):
+        data = {"foo": "bar", "baz": [1, 2, 3]}
+        with pytest.warns(
+            UndefinedObjectWarning,
+            match="Attempting to deserialize an object with no defined type",
+        ):
+            output = self._client._ApiClient__deserialize(data, "object")
+        assert output == data
+
 
 class TestResponseParsing:
     from requests.adapters import HTTPAdapter