chore: add deprecated mark for find_element_by* (#657)

appium · Nov 24, 2021 · d7cb6b5 · d7cb6b5
1 parent ace98dc
commit d7cb6b5
Show file tree

Hide file tree

Showing 6 changed files with 145 additions and 36 deletions.
diff --git a/appium/webdriver/extensions/search_context/android.py b/appium/webdriver/extensions/search_context/android.py
@@ -17,6 +17,7 @@
 import json
 from typing import TYPE_CHECKING, Any, List, Optional, TypeVar, Union
 
+from appium.common.logger import logger
 from appium.webdriver.common.mobileby import MobileBy
 
 from .base_search_context import BaseSearchContext
@@ -33,7 +34,10 @@ class AndroidSearchContext(BaseSearchContext):
     def find_element_by_android_view_matcher(
         self: T, name: Optional[str] = None, args: Optional[Any] = None, className: Optional[str] = None
     ) -> 'WebElement':
-        """Finds element by [onView](https://developer.android.com/training/testing/espresso/basics) in Android
+        """
+        [Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_VIEW_MATCHER' instead.
+
+        Finds element by [onView](https://developer.android.com/training/testing/espresso/basics) in Android
 
         It works with [Espresso Driver](https://github.com/appium/appium-espresso-driver).
 
@@ -57,14 +61,19 @@ def find_element_by_android_view_matcher(
             driver.find_element_by_android_view_matcher(name='withText', args=['Accessibility'], className='ViewMatchers')
         """
 
+        logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_VIEW_MATCHER' instead.")
+
         return self.find_element(
             by=MobileBy.ANDROID_VIEW_MATCHER, value=self._build_data_matcher(name=name, args=args, className=className)
         )
 
     def find_element_by_android_data_matcher(
         self: T, name: Optional[str] = None, args: Optional[Any] = None, className: Optional[str] = None
     ) -> 'WebElement':
-        """Finds element by
+        """
+        [Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_DATA_MATCHER' instead.
+
+        Finds element by
         [onData](https://medium.com/androiddevelopers/adapterviews-and-espresso-f4172aa853cf) in Android
 
         It works with [Espresso Driver](https://github.com/appium/appium-espresso-driver).
@@ -89,14 +98,19 @@ def find_element_by_android_data_matcher(
             driver.find_element_by_android_data_matcher(name='hasEntry', args=['title', 'Animation'])
         """
 
+        logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_DATA_MATCHER' instead.")
+
         return self.find_element(
             by=MobileBy.ANDROID_DATA_MATCHER, value=self._build_data_matcher(name=name, args=args, className=className)
         )
 
     def find_elements_by_android_data_matcher(
         self: T, name: Optional[str] = None, args: Optional[Any] = None, className: Optional[str] = None
     ) -> List['WebElement']:
-        """Finds elements by
+        """
+        [Deprecated] Please use 'find_elements' with 'MobileBy.ANDROID_DATA_MATCHER' instead.
+
+        Finds elements by
         [onData](https://medium.com/androiddevelopers/adapterviews-and-espresso-f4172aa853cf) in Android
         It works with [Espresso Driver](https://github.com/appium/appium-espresso-driver).
 
@@ -117,6 +131,8 @@ def find_elements_by_android_data_matcher(
             driver.find_elements_by_android_data_matcher(name='hasEntry', args=['title', 'Animation'])
         """
 
+        logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.ANDROID_DATA_MATCHER' instead.")
+
         return self.find_elements(
             by=MobileBy.ANDROID_DATA_MATCHER, value=self._build_data_matcher(name=name, args=args, className=className)
         )
@@ -133,7 +149,10 @@ def _build_data_matcher(
         return json.dumps(result)
 
     def find_element_by_android_uiautomator(self: T, uia_string: str) -> 'WebElement':
-        """Finds element by uiautomator in Android.
+        """
+        [Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_UIAUTOMATOR' instead.
+
+        Finds element by uiautomator in Android.
 
         Args:
             uia_string: The element name in the Android UIAutomator library
@@ -144,10 +163,16 @@ def find_element_by_android_uiautomator(self: T, uia_string: str) -> 'WebElement
         Returns:
             `appium.webdriver.webelement.WebElement`: The found element
         """
+
+        logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_UIAUTOMATOR' instead.")
+
         return self.find_element(by=MobileBy.ANDROID_UIAUTOMATOR, value=uia_string)
 
     def find_elements_by_android_uiautomator(self: T, uia_string: str) -> List['WebElement']:
-        """Finds elements by uiautomator in Android.
+        """
+        [Deprecated] Please use 'find_elements' with 'MobileBy.ANDROID_UIAUTOMATOR' instead.
+
+        Finds elements by uiautomator in Android.
 
         Args:
             uia_string: The element name in the Android UIAutomator library
@@ -158,10 +183,16 @@ def find_elements_by_android_uiautomator(self: T, uia_string: str) -> List['WebE
         Returns:
             :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements
         """
+
+        logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.ANDROID_UIAUTOMATOR' instead.")
+
         return self.find_elements(by=MobileBy.ANDROID_UIAUTOMATOR, value=uia_string)
 
     def find_element_by_android_viewtag(self: T, tag: str) -> 'WebElement':
-        """Finds element by [View#tags](https://developer.android.com/reference/android/view/View#tags) in Android.
+        """
+        [Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_VIEWTAG' instead.
+
+        Finds element by [View#tags](https://developer.android.com/reference/android/view/View#tags) in Android.
 
         It works with [Espresso Driver](https://github.com/appium/appium-espresso-driver).
 
@@ -174,10 +205,16 @@ def find_element_by_android_viewtag(self: T, tag: str) -> 'WebElement':
         Returns:
             `appium.webdriver.webelement.WebElement`: The found element
         """
+
+        logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_VIEWTAG' instead.")
+
         return self.find_element(by=MobileBy.ANDROID_VIEWTAG, value=tag)
 
     def find_elements_by_android_viewtag(self: T, tag: str) -> List['WebElement']:
-        """Finds element by [View#tags](https://developer.android.com/reference/android/view/View#tags) in Android.
+        """
+        [Deprecated] Please use 'find_elements' with 'MobileBy.ANDROID_VIEWTAG' instead.
+
+        Finds element by [View#tags](https://developer.android.com/reference/android/view/View#tags) in Android.
 
         It works with [Espresso Driver](https://github.com/appium/appium-espresso-driver).
 
@@ -190,4 +227,7 @@ def find_elements_by_android_viewtag(self: T, tag: str) -> List['WebElement']:
         Returns:
             :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements
         """
+
+        logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ANDROID_VIEWTAG' instead.")
+
         return self.find_elements(by=MobileBy.ANDROID_VIEWTAG, value=tag)
diff --git a/appium/webdriver/extensions/search_context/custom.py b/appium/webdriver/extensions/search_context/custom.py
@@ -16,6 +16,7 @@
 
 from typing import TYPE_CHECKING, List, TypeVar, Union
 
+from appium.common.logger import logger
 from appium.webdriver.common.mobileby import MobileBy
 
 from .base_search_context import BaseSearchContext
@@ -30,7 +31,10 @@ class CustomSearchContext(BaseSearchContext):
     """Define search context for custom plugin"""
 
     def find_element_by_custom(self: T, selector: str) -> 'WebElement':
-        """Finds an element in conjunction with a custom element finding plugin
+        """
+        [Deprecated] Please use 'find_element' with 'MobileBy.CUSTOM' instead.
+
+        Finds an element in conjunction with a custom element finding plugin
 
         Args:
             selector: a string of the form "module:selector", where "module" is
@@ -45,10 +49,16 @@ def find_element_by_custom(self: T, selector: str) -> 'WebElement':
             `appium.webdriver.webelement.WebElement`: The found element
 
         """
+
+        logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.CUSTOM' instead.")
+
         return self.find_element(by=MobileBy.CUSTOM, value=selector)
 
     def find_elements_by_custom(self: T, selector: str) -> List['WebElement']:
-        """Finds elements in conjunction with a custom element finding plugin
+        """
+        [Deprecated] Please use 'find_elements' with 'MobileBy.CUSTOM' instead.
+
+        Finds elements in conjunction with a custom element finding plugin
 
         Args:
             selector: a string of the form "module:selector", where "module" is
@@ -62,4 +72,7 @@ def find_elements_by_custom(self: T, selector: str) -> List['WebElement']:
         Returns:
             :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements
         """
+
+        logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.CUSTOM' instead.")
+
         return self.find_elements(by=MobileBy.CUSTOM, value=selector)
diff --git a/appium/webdriver/extensions/search_context/ios.py b/appium/webdriver/extensions/search_context/ios.py
@@ -16,6 +16,7 @@
 
 from typing import TYPE_CHECKING, List, TypeVar, Union
 
+from appium.common.logger import logger
 from appium.webdriver.common.mobileby import MobileBy
 
 from .base_search_context import BaseSearchContext
@@ -30,7 +31,10 @@ class iOSSearchContext(BaseSearchContext):
     """Define search context for iOS"""
 
     def find_element_by_ios_uiautomation(self: T, uia_string: str) -> 'WebElement':
-        """Finds an element by uiautomation in iOS.
+        """
+        [Deprecated] Please use 'find_element' with 'MobileBy.IOS_UIAUTOMATION' instead.
+
+        Finds an element by uiautomation in iOS.
 
         Args:
             uia_string: The element name in the iOS UIAutomation library
@@ -42,10 +46,16 @@ def find_element_by_ios_uiautomation(self: T, uia_string: str) -> 'WebElement':
             `appium.webdriver.webelement.WebElement`: The found element
 
         """
+
+        logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.IOS_UIAUTOMATION' instead.")
+
         return self.find_element(by=MobileBy.IOS_UIAUTOMATION, value=uia_string)
 
     def find_elements_by_ios_uiautomation(self: T, uia_string: str) -> List['WebElement']:
-        """Finds elements by uiautomation in iOS.
+        """
+        [Deprecated] Please use 'find_elements' with 'MobileBy.IOS_UIAUTOMATION' instead.
+
+        Finds elements by uiautomation in iOS.
 
         Args:
             uia_string: The element name in the iOS UIAutomation library
@@ -57,10 +67,16 @@ def find_elements_by_ios_uiautomation(self: T, uia_string: str) -> List['WebElem
             :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements
 
         """
+
+        logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.IOS_UIAUTOMATION' instead.")
+
         return self.find_elements(by=MobileBy.IOS_UIAUTOMATION, value=uia_string)
 
     def find_element_by_ios_predicate(self: T, predicate_string: str) -> 'WebElement':
-        """Find an element by ios predicate string.
+        """
+        [Deprecated] Please use 'find_element' with 'MobileBy.IOS_PREDICATE' instead.
+
+        Find an element by ios predicate string.
 
         Args:
             predicate_string: The predicate string
@@ -72,10 +88,16 @@ def find_element_by_ios_predicate(self: T, predicate_string: str) -> 'WebElement
             `appium.webdriver.webelement.WebElement`: The found element
 
         """
+
+        logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.IOS_PREDICATE' instead.")
+
         return self.find_element(by=MobileBy.IOS_PREDICATE, value=predicate_string)
 
     def find_elements_by_ios_predicate(self: T, predicate_string: str) -> List['WebElement']:
-        """Finds elements by ios predicate string.
+        """
+        [Deprecated] Please use 'find_elements' with 'MobileBy.IOS_PREDICATE' instead.
+
+        Finds elements by ios predicate string.
 
         Args:
             predicate_string: The predicate string
@@ -86,10 +108,16 @@ def find_elements_by_ios_predicate(self: T, predicate_string: str) -> List['WebE
         Returns:
             :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements
         """
+
+        logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.IOS_PREDICATE' instead.")
+
         return self.find_elements(by=MobileBy.IOS_PREDICATE, value=predicate_string)
 
     def find_element_by_ios_class_chain(self: T, class_chain_string: str) -> 'WebElement':
-        """Find an element by ios class chain string.
+        """
+        [Deprecated] Please use 'find_element' with 'MobileBy.IOS_CLASS_CHAIN' instead.
+
+        Find an element by ios class chain string.
 
         Args:
             class_chain_string: The class chain string
@@ -100,10 +128,16 @@ def find_element_by_ios_class_chain(self: T, class_chain_string: str) -> 'WebEle
         Returns:
             `appium.webdriver.webelement.WebElement`: The found element
         """
+
+        logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.IOS_CLASS_CHAIN' instead.")
+
         return self.find_element(by=MobileBy.IOS_CLASS_CHAIN, value=class_chain_string)
 
     def find_elements_by_ios_class_chain(self: T, class_chain_string: str) -> List['WebElement']:
-        """Finds elements by ios class chain string.
+        """
+        [Deprecated] Please use 'find_elements' with 'MobileBy.IOS_CLASS_CHAIN' instead.
+
+        Finds elements by ios class chain string.
 
         Args:
             class_chain_string: The class chain string
@@ -114,4 +148,7 @@ def find_elements_by_ios_class_chain(self: T, class_chain_string: str) -> List['
         Returns:
             :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements
         """
+
+        logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.IOS_CLASS_CHAIN' instead.")
+
         return self.find_elements(by=MobileBy.IOS_CLASS_CHAIN, value=class_chain_string)
diff --git a/appium/webdriver/extensions/search_context/mobile.py b/appium/webdriver/extensions/search_context/mobile.py
@@ -17,6 +17,7 @@
 import base64
 from typing import TYPE_CHECKING, List, TypeVar, Union
 
+from appium.common.logger import logger
 from appium.webdriver.common.mobileby import MobileBy
 
 from .base_search_context import BaseSearchContext
@@ -31,7 +32,10 @@ class MobileSearchContext(BaseSearchContext):
     """Define search context for Mobile(Android, iOS)"""
 
     def find_element_by_accessibility_id(self: T, accessibility_id: str) -> 'WebElement':
-        """Finds an element by accessibility id.
+        """
+        [Deprecated] Please use 'find_element' with 'MobileBy.ACCESSIBILITY_ID' instead.
+
+        Finds an element by accessibility id.
 
         Args:
             accessibility_id: A string corresponding to a recursive element search using the
@@ -44,10 +48,16 @@ def find_element_by_accessibility_id(self: T, accessibility_id: str) -> 'WebElem
             `appium.webdriver.webelement.WebElement`: The found element
 
         """
+
+        logger.warning("[Deprecated] Please use 'find_element' with 'MobileBy.ACCESSIBILITY_ID' instead.")
+
         return self.find_element(by=MobileBy.ACCESSIBILITY_ID, value=accessibility_id)
 
     def find_elements_by_accessibility_id(self: T, accessibility_id: str) -> List['WebElement']:
-        """Finds elements by accessibility id.
+        """
+        [Deprecated] Please use 'find_elements' with 'MobileBy.ACCESSIBILITY_ID' instead.
+
+        Finds elements by accessibility id.
 
         Args:
             accessibility_id: a string corresponding to a recursive element search using the
@@ -60,6 +70,9 @@ def find_elements_by_accessibility_id(self: T, accessibility_id: str) -> List['W
             :obj:`list` of :obj:`appium.webdriver.webelement.WebElement`: The found elements
 
         """
+
+        logger.warning("[Deprecated] Please use 'find_elements' with 'MobileBy.ACCESSIBILITY_ID' instead.")
+
         return self.find_elements(by=MobileBy.ACCESSIBILITY_ID, value=accessibility_id)
 
     def find_element_by_image(self: T, img_path: str) -> 'WebElement':
@@ -73,6 +86,7 @@ def find_element_by_image(self: T, img_path: str) -> 'WebElement':
         Returns:
             `appium.webdriver.webelement.WebElement`: The found element
         """
+
         with open(img_path, 'rb') as i_file:
             b64_data = base64.b64encode(i_file.read()).decode('UTF-8')