From 92b408657f5678064406a357ebc4091c7fed6a2d Mon Sep 17 00:00:00 2001 From: Lukasz Socha Date: Thu, 27 Jan 2022 18:21:21 +0100 Subject: [PATCH] feat: Deprecate `use_index` param from MDQ of files/folders Closes: SDK-1938 --- README.rst | 4 +--- boxsdk/object/search.py | 8 ++++---- boxsdk/util/api_call_decorator.py | 2 +- boxsdk/util/deprecation_decorator.py | 20 ++++++++++++++++++-- docs/usage/search.md | 22 ++++++++++++---------- test/unit/object/test_search.py | 19 ++++++++----------- 6 files changed, 44 insertions(+), 31 deletions(-) diff --git a/README.rst b/README.rst index a825c735..5e7b94c0 100644 --- a/README.rst +++ b/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 `_ - -.. _changelog: https://github.com/box/box-python-sdk/blob/main/HISTORY.rst#200 +`1.5 branch `_. Getting Started diff --git a/boxsdk/object/search.py b/boxsdk/object/search.py index d04d32fc..768aad3f 100644 --- a/boxsdk/object/search.py +++ b/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 diff --git a/boxsdk/util/api_call_decorator.py b/boxsdk/util/api_call_decorator.py index f6679657..c701a80f 100644 --- a/boxsdk/util/api_call_decorator.py +++ b/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`, diff --git a/boxsdk/util/deprecation_decorator.py b/boxsdk/util/deprecation_decorator.py index 19e5cd8f..89e893ca 100644 --- a/boxsdk/util/deprecation_decorator.py +++ b/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 diff --git a/docs/usage/search.md b/docs/usage/search.md index 91cb75b9..4cdf6edd 100644 --- a/docs/usage/search.md +++ b/docs/usage/search.md @@ -68,6 +68,10 @@ 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 @@ -75,7 +79,6 @@ 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}') diff --git a/test/unit/object/test_search.py b/test/unit/object/test_search.py index c95168c2..e6374261 100644 --- a/test/unit/object/test_search.py +++ b/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,7 +352,6 @@ 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 @@ -361,15 +359,14 @@ def test_metadata_query( 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()