fix: deprecate public api_client property. warn on async api_client footgun on sync client (#2618)

Author: haakonvt

cognite/client/_cognite_client.py

@@ -171,9 +171,21 @@ def __init__(self, config: ClientConfig | None = None) -> None:
     def api_client(self) -> APIClient:
         """Returns the underlying API client used for HTTP requests.
 
+        .. deprecated:: 8.0
+            Use :meth:`post`, :meth:`get`, or :meth:`put` instead.
+            Will be removed in v9.
+
         Returns:
             APIClient: The API client instance.
         """
+        import warnings
+
+        warnings.warn(
+            "'api_client' is deprecated and will be removed in v9. "
+            "Use client.post(), client.get(), or client.put() instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
         return self._api_client
 
     def get_sync_client(self) -> CogniteClient:

cognite/client/_sync_cognite_client.py

@@ -142,9 +142,33 @@ def config(self) -> ClientConfig:
     def api_client(self) -> APIClient:
         """Returns the underlying API client used for HTTP requests.
 
+        .. deprecated:: 8.0
+            Use :meth:`post`, :meth:`get`, or :meth:`put` instead.
+            Will be removed in v9.
+
+        .. warning::
+            This returns the **async** API client. Calling its methods directly
+            requires ``await`` and will not work in a synchronous context.
+            Use :meth:`post`, :meth:`get`, or :meth:`put` instead.
+
         Returns:
-            APIClient: The API client instance.
+            APIClient: The async API client instance.
         """
+        import warnings
+
+        warnings.warn(
+            "'api_client' is deprecated and will be removed in v9. "
+            "Use client.post(), client.get(), or client.put() instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        warnings.warn(
+            "'api_client' returns the underlying async API client. Calling its methods directly requires "
+            "'await' and will not work in a synchronous context. "
+            "Use client.post(), client.get(), or client.put() for synchronous HTTP requests instead.",
+            UserWarning,
+            stacklevel=2,
+        )
         return self.__async_client._api_client
 
     def get_async_client(self) -> AsyncCogniteClient:

scripts/sync_client_codegen/sync_client_template.txt

@@ -86,9 +86,33 @@ class CogniteClient:
     def api_client(self) -> APIClient:
         """Returns the underlying API client used for HTTP requests.
 
+        .. deprecated:: 8.0
+            Use :meth:`post`, :meth:`get`, or :meth:`put` instead.
+            Will be removed in v9.
+
+        .. warning::
+            This returns the **async** API client. Calling its methods directly
+            requires ``await`` and will not work in a synchronous context.
+            Use :meth:`post`, :meth:`get`, or :meth:`put` instead.
+
         Returns:
-            APIClient: The API client instance.
+            APIClient: The async API client instance.
         """
+        import warnings
+
+        warnings.warn(
+            "'api_client' is deprecated and will be removed in v9. "
+            "Use client.post(), client.get(), or client.put() instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        warnings.warn(
+            "'api_client' returns the underlying async API client. Calling its methods directly requires "
+            "'await' and will not work in a synchronous context. "
+            "Use client.post(), client.get(), or client.put() for synchronous HTTP requests instead.",
+            UserWarning,
+            stacklevel=2,
+        )
         return self.__async_client._api_client
 
     def get_async_client(self) -> AsyncCogniteClient: