improve: Improved how we handle warning messages

qdrant_client/async_qdrant_client.py

@@ -14,7 +14,7 @@
 from typing import Any, Awaitable, Callable, Iterable, Mapping, Optional, Sequence, Union
 from qdrant_client import grpc as grpc
 from qdrant_client.async_client_base import AsyncQdrantBase
-from qdrant_client.common.deprecations import deprecation_warning_once
+from qdrant_client.common.client_warnings import show_warning_once
 from qdrant_client.conversions import common_types as types
 from qdrant_client.embed.type_inspector import Inspector
 from qdrant_client.http import AsyncApiClient, AsyncApis
@@ -1495,8 +1495,9 @@ async def upsert(
             and len(points) > 0
             and isinstance(points[0], grpc.PointStruct)
         ):
-            deprecation_warning_once(
-                "\n            Usage of `grpc.PointStruct` is deprecated. Please use `models.PointStruct` instead.\n            ",
+            show_warning_once(
+                message="\n            Usage of `grpc.PointStruct` is deprecated. Please use `models.PointStruct` instead.\n            ",
+                category=DeprecationWarning,
                 idx="grpc-input",
             )
         requires_inference = self._inference_inspector.inspect(points)

qdrant_client/common/client_warnings.py

@@ -0,0 +1,21 @@
+import warnings
+from typing import Optional
+
+SEEN_MESSAGES = set()
+
+
+def show_warning(message: str, category: type[Warning] = UserWarning) -> None:
+    warnings.warn(message, category, stacklevel=2)
+
+
+def show_warning_once(
+    message: str, category: type[Warning] = UserWarning, idx: Optional[str] = None
+) -> None:
+    """
+    Show a warning of the specified category only once per program run.
+    """
+    key = idx if idx is not None else message
+
+    if key not in SEEN_MESSAGES:
+        SEEN_MESSAGES.add(key)
+        show_warning(message, category)

qdrant_client/local/async_qdrant_local.py

@@ -21,7 +21,7 @@
 from uuid import uuid4
 import numpy as np
 import portalocker
-from qdrant_client.common.warnings import user_warning_once
+from qdrant_client.common.client_warnings import show_warning_once
 from qdrant_client._pydantic_compat import to_dict
 from qdrant_client.async_client_base import AsyncQdrantBase
 from qdrant_client.conversions import common_types as types
@@ -108,9 +108,10 @@ def _load(self) -> None:
                     )
                     self.collections[collection_name] = collection
                     if len(collection.ids) > self.LARGE_DATA_THRESHOLD:
-                        user_warning_once(
-                            f"Local mode is not recommended for collections with more than {self.LARGE_DATA_THRESHOLD:,} points. Consider using Qdrant docker (http/grpc) or Qdrant cloud for better performance with large datasets.",
-                            "large-local-collection",
+                        show_warning_once(
+                            message=f"Local mode is not recommended for collections with more than {self.LARGE_DATA_THRESHOLD:,} points. Consider using Qdrant docker (http/grpc) or Qdrant cloud for better performance with large datasets.",
+                            category=UserWarning,
+                            idx="large-local-collection",
                         )
                 self.aliases = meta["aliases"]
         lock_file_path = os.path.join(self.location, ".lock")

qdrant_client/local/local_collection.py

@@ -15,7 +15,7 @@
 import numpy as np
 
 from qdrant_client import grpc as grpc
-from qdrant_client.common.warnings import user_warning_once
+from qdrant_client.common.client_warnings import show_warning_once
 from qdrant_client._pydantic_compat import construct, to_jsonable_python as _to_jsonable_python
 from qdrant_client.conversions import common_types as types
 from qdrant_client.conversions.common_types import get_args_subscribed
@@ -2169,10 +2169,11 @@ def upsert(self, points: Union[Sequence[models.PointStruct], models.Batch]) -> N
             else 0
         )
         if len(self.ids) + points_count > self.LARGE_DATA_THRESHOLD:
-            user_warning_once(
+            show_warning_once(
                 f"Local mode is not recommended for collections with more than {self.LARGE_DATA_THRESHOLD:,} points. "
                 "Consider using Qdrant docker (http/grpc) or Qdrant cloud for better performance with large datasets.",
-                "large-local-collection",
+                category=UserWarning,
+                idx="large-local-collection",
             )
         if isinstance(points, list):
             for point in points:

qdrant_client/local/qdrant_local.py

@@ -21,7 +21,7 @@
 import numpy as np
 import portalocker
 
-from qdrant_client.common.warnings import user_warning_once
+from qdrant_client.common.client_warnings import show_warning_once
 from qdrant_client._pydantic_compat import to_dict
 from qdrant_client.client_base import QdrantBase
 from qdrant_client.conversions import common_types as types
@@ -111,10 +111,11 @@ def _load(self) -> None:
                     )
                     self.collections[collection_name] = collection
                     if len(collection.ids) > self.LARGE_DATA_THRESHOLD:
-                        user_warning_once(
-                            f"Local mode is not recommended for collections with more than {self.LARGE_DATA_THRESHOLD:,} points. "
+                        show_warning_once(
+                            message=f"Local mode is not recommended for collections with more than {self.LARGE_DATA_THRESHOLD:,} points. "
                             "Consider using Qdrant docker (http/grpc) or Qdrant cloud for better performance with large datasets.",
-                            "large-local-collection",
+                            category=UserWarning,
+                            idx="large-local-collection",
                         )
                 self.aliases = meta["aliases"]
 

qdrant_client/qdrant_client.py

@@ -13,7 +13,7 @@
 
 from qdrant_client import grpc as grpc
 from qdrant_client.client_base import QdrantBase
-from qdrant_client.common.deprecations import deprecation_warning_once
+from qdrant_client.common.client_warnings import show_warning_once
 from qdrant_client.conversions import common_types as types
 from qdrant_client.embed.type_inspector import Inspector
 from qdrant_client.http import ApiClient, SyncApis
@@ -1578,10 +1578,11 @@ def upsert(
             and isinstance(points[0], grpc.PointStruct)
         ):
             # gRPC structures won't support local inference feature, so we deprecated it
-            deprecation_warning_once(
-                """
+            show_warning_once(
+                message="""
             Usage of `grpc.PointStruct` is deprecated. Please use `models.PointStruct` instead.
             """,
+                category=DeprecationWarning,
                 idx="grpc-input",
             )