feat: Deprecate use_index param from MDQ of files/folders

README.rst

@@ -38,9 +38,7 @@ Installing
 
 The current version of the SDK is v3.x — With this release support for Python 3.5 and earlier (including 2.x) has been dropped.
 if you're looking for the code or documentation for v1.5.x, please see the
-`1.5 branch <https://github.com/box/box-python-sdk/tree/1.5>`_
-
-.. _changelog: https://github.com/box/box-python-sdk/blob/main/HISTORY.rst#200
+`1.5 branch <https://github.com/box/box-python-sdk/tree/1.5>`_.
 
 
 Getting Started

boxsdk/object/search.py

@@ -6,6 +6,7 @@
 from ..pagination.limit_offset_based_object_collection import LimitOffsetBasedObjectCollection
 from ..pagination.marker_based_object_collection import MarkerBasedObjectCollection
 from ..util.api_call_decorator import api_call
+from ..util.deprecation_decorator import deprecated_param
 from ..util.text_enum import TextEnum
 
 if TYPE_CHECKING:
@@ -261,6 +262,7 @@ def query(
             return_full_pages=False,
         )
 
+    @deprecated_param(name="use_index", position=5, message="Parameter will be ignored. See docs for details.")
     @api_call
     def metadata_query(
             self,
@@ -274,6 +276,7 @@ def metadata_query(
             limit: int = None,
             fields: Iterable[Optional[str]] = None
     ) -> 'BoxObjectCollection':
+        # pylint:disable=unused-argument
         """Query Box items by their metadata.
 
         :param from_template:
@@ -284,8 +287,7 @@ def metadata_query(
             The logical expression of the query
         :param query_params:
             Required if query present. The arguments for the query.
-        :param use_index:
-            The name of the index to use
+        :param use_index is deprecated
         :param order_by:
             The field_key(s) to order on and the corresponding direction(s)
         :param marker:
@@ -306,8 +308,6 @@ def metadata_query(
             data['query'] = query
         if query_params is not None:
             data['query_params'] = query_params
-        if use_index is not None:
-            data['use_index'] = use_index
         if order_by is not None:
             data['order_by'] = order_by
 

boxsdk/util/api_call_decorator.py

@@ -6,7 +6,7 @@
 from ..object.cloneable import Cloneable
 
 
-def api_call(method: Callable) -> 'APICallWrapper':
+def api_call(method: Callable) -> Any:
     """
     Designates the decorated method as one that makes a Box API call.
     The decorated method can then accept a new keyword argument `extra_network_parameters`,

boxsdk/util/deprecation_decorator.py

@@ -1,8 +1,9 @@
 import warnings
+from typing import Callable, Any
 
 
-def deprecated(message):
-    def deprecated_decorator(func):
+def deprecated(message: str):
+    def deprecated_decorator(func: Callable) -> Any:
         def deprecated_func(*args, **kwargs):
             warnings.simplefilter('default', DeprecationWarning)
             warnings.warn(f'{func.__name__} is a deprecated function. {message}',
@@ -11,3 +12,18 @@ def deprecated_func(*args, **kwargs):
             return func(*args, **kwargs)
         return deprecated_func
     return deprecated_decorator
+
+
+def deprecated_param(*, name: str, position: int, message: str):
+    def deprecated_decorator(func: Callable) -> Any:
+        def deprecated_func(*args, **kwargs):
+            if len(args) >= position + 1 or name in kwargs:
+                warnings.simplefilter('default', DeprecationWarning)
+                warnings.warn(
+                    f'{func.__name__} function parameter `{name}` at position {position} is deprecated. {message}',
+                    category=DeprecationWarning,
+                    stacklevel=2
+                )
+            return func(*args, **kwargs)
+        return deprecated_func
+    return deprecated_decorator

docs/usage/search.md

@@ -68,14 +68,17 @@ Metadata Query
 --------------
 To search using SQL-like syntax to return items that match specific metadata, call `search.metadata_query(from_template, ancestor_folder_id, query=None, query_params=None, use_index=None, order_by=None, marker=None, limit=None, fields=None)` 
 
+**Note:** paramter `use_index` is deprecated and if provided, will be ignored. The current way to create an index is to contact the MDQ team directly via email. MDQ will now use static query analysis to use the index that is most efficient for the call.
+
+
+
 By default, this method returns only the most basic info about the items for which the query matches. To get additional fields for each item, including any of the metadata, use the fields parameter.
 
 ```python
 from_template = 'enterprise_12345.someTemplate'
 ancestor_folder_id = '5555'
 query = 'amount >= :arg'
 query_params = {'arg': 100}
-use_index = 'amountAsc'
 order_by = [
     {
         'field_key': 'amount',
@@ -86,15 +89,14 @@ fields = ['type', 'id', 'name', 'metadata.enterprise_67890.catalogImages.$parent
 limit = 2
 marker = 'AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKs'
 items = client.search().metadata_query(
-        from_template,
-        ancestor_folder_id,
-        query,
-        query_params,
-        use_index,
-        order_by,
-        marker,
-        limit,
-        fields
+    from_template=from_template,
+    ancestor_folder_id=ancestor_folder_id,
+    query=query,
+    query_params=query_params,
+    order_by=order_by,
+    marker=marker,
+    limit=limit,
+    fields=fields
     )
 for item in items:
     print(f'The item ID is {item.id} and the item name is {item.name}')

test/unit/object/test_search.py

@@ -337,7 +337,6 @@ def test_metadata_query(
     ancestor_folder_id = '5555'
     query = 'amount >= :arg'
     query_params = {'arg': 100}
-    use_index = 'amountAsc'
     order_by = [
         {
             'field_key': 'amount',
@@ -353,23 +352,21 @@ def test_metadata_query(
         'ancestor_folder_id': ancestor_folder_id,
         'query': query,
         'query_params': query_params,
-        'use_index': use_index,
         'order_by': order_by,
         'marker': marker,
         'fields': fields
     }
     expected_headers = {b'Content-Type': b'application/json'}
     mock_box_session.post.return_value, _ = make_mock_box_request(response=metadata_query_response)
     items = test_search.metadata_query(
-        from_template,
-        ancestor_folder_id,
-        query,
-        query_params,
-        use_index,
-        order_by,
-        marker,
-        limit,
-        fields
+        from_template=from_template,
+        ancestor_folder_id=ancestor_folder_id,
+        query=query,
+        query_params=query_params,
+        order_by=order_by,
+        marker=marker,
+        limit=limit,
+        fields=fields
     )
     item1 = items.next()
     item2 = items.next()