chore: Updates docstring (appium#533)

* Updates docstring * Add description to Returns field * Remove type from docstring Since type hint already added to args * Set default lang to en * Change usage style in docstring * Updates * Remove rtype unnecessary anymore since type hint works for auto completion * tweak * Update return type * Restore types for keyword args * Remove types from Return field Except for property and TypeVar

Author: ki4070ma

appium/common/exceptions.py

@@ -21,7 +21,7 @@ class NoSuchContextException(InvalidSwitchToTargetException):
  To find the current set of active contexts, you can get a list
  of the active contexts in the following way:
 
- print driver.contexts
+ print(driver.contexts)
 
  """
  pass

appium/common/helper.py

@@ -21,10 +21,10 @@ def extract_const_attributes(cls: type) -> Dict[str, Any]:
  """Return dict with constants attributes and values in the class(e.g. {'VAL1': 1, 'VAL2': 2})
 
  Args:
- cls (type): Class to be extracted constants
+ cls: Class to be extracted constants
 
  Returns:
- dict: dict with constants attributes and values in the class
+ dict with constants attributes and values in the class
  """
  return dict([(attr, value) for attr, value in vars(cls).items()
  if not callable(getattr(cls, attr)) and attr.isupper()])

appium/webdriver/appium_service.py

@@ -128,9 +128,9 @@ def start(self, **kwargs: Any) -> sp.Popen:
  which is inherited from the parent process is assigned by default.
  node (str): The full path to the main NodeJS executable. The service will try
  to retrieve it automatically by default.
- stdout: Check on the documentation for subprocess.Popen for more details.
+ stdout (int): Check on the documentation for subprocess.Popen for more details.
  The default value is subprocess.PIPE.
- stderr: Check on the documentation for subprocess.Popen for more details.
+ stderr (int): Check on the documentation for subprocess.Popen for more details.
  The default value is subprocess.PIPE.
  timeout_ms (int): The maximum time to wait until Appium process starts listening
  for HTTP connections. If set to zero or a negative number then no wait will be applied.
@@ -143,10 +143,8 @@ def start(self, **kwargs: Any) -> sp.Popen:
  about possible arguments and their values.
 
  Returns:
- subprocess.Popen instance: You can use Popen.communicate interface
- or stderr/stdout properties of the instance
- (stdout/stderr must not be set to None in such case)
- in order to retrieve the actual process output.
+ You can use Popen.communicate interface or stderr/stdout properties
+ of the instance (stdout/stderr must not be set to None in such case) in order to retrieve the actual process output.
  """
  self.stop()
 
@@ -182,7 +180,7 @@ def stop(self) -> bool:
  or has been already stopped.
 
  Returns:
- bool: `True` if the service was running before being stopped
+ `True` if the service was running before being stopped
  """
  is_terminated = False
  if self.is_running:
@@ -197,7 +195,7 @@ def is_running(self) -> bool:
  """Check if the service is running.
 
  Returns:
- bool: `True` or `False`
+ bool: `True` if the service is running
  """
  return self._process is not None and self._process.poll() is None
 

appium/webdriver/common/multi_action.py

@@ -41,18 +41,17 @@ def add(self, *touch_actions: 'TouchAction') -> None:
  """Add TouchAction objects to the MultiAction, to be performed later.
 
  Args:
- touch_actions (`TouchAction`): one or more TouchAction objects describing a chain of actions to be performed by one finger
+ touch_actions: one or more TouchAction objects describing a chain of actions to be performed by one finger
 
  Usage:
- a1 = TouchAction(driver)
-
- a1.press(el1).move_to(el2).release()
-
- a2 = TouchAction(driver)
-
- a2.press(el2).move_to(el1).release()
-
- MultiAction(driver).add(a1, a2)
+ | a1 = TouchAction(driver)
+ | a1.press(el1).move_to(el2).release()
+ | a2 = TouchAction(driver)
+ | a2.press(el2).move_to(el1).release()
+ | MultiAction(driver).add(a1, a2)
+
+ Returns:
+ `MultiAction`: Self instance
  """
  for touch_action in touch_actions:
  if self._touch_actions is None:
@@ -64,15 +63,14 @@ def perform(self: T) -> T:
  """Perform the actions stored in the object.
 
  Usage:
- a1 = TouchAction(driver)
-
- a1.press(el1).move_to(el2).release()
-
- a2 = TouchAction(driver)
-
- a2.press(el2).move_to(el1).release()
-
- MultiAction(driver).add(a1, a2).perform()
+ | a1 = TouchAction(driver)
+ | a1.press(el1).move_to(el2).release()
+ | a2 = TouchAction(driver)
+ | a2.press(el2).move_to(el1).release()
+ | MultiAction(driver).add(a1, a2).perform()
+
+ Returns:
+ `MultiAction`: Self instance
  """
  self._driver.execute(Command.MULTI_ACTION, self.json_wire_gestures)
 

appium/webdriver/common/touch_action.py

@@ -46,12 +46,12 @@ def tap(self: T, element: Optional['WebElement'] = None, x: Optional[int]
  """Perform a tap action on the element
 
  Args:
- element (`appium.webdriver.webelement.WebElement`): the element to tap
- x (:obj:`int`, optional): x coordinate to tap, relative to the top left corner of the element.
- y (:obj:`int`, optional): y coordinate. If y is used, x must also be set, and vice versa
+ element: the element to tap
+ x : x coordinate to tap, relative to the top left corner of the element.
+ y : y coordinate. If y is used, x must also be set, and vice versa
 
  Returns:
- `TouchAction`: self instance
+ `TouchAction`: Self instance
  """
  opts = self._get_opts(element, x, y)
  opts['count'] = count
@@ -64,14 +64,14 @@ def press(self: T, el: Optional['WebElement'] = None, x: Optional[int] = None,
  """Begin a chain with a press down action at a particular element or point
 
  Args:
- el (:obj:`appium.webdriver.webelement.WebElement`, optional): the element to press
- x (:obj:`int`, optional): x coordiate to press. If y is used, x must also be set
- y (:obj:`int`, optional): y coordiate to press. If x is used, y must also be set
- pressure (:obj:`float`, optional): [iOS Only] press as force touch. Read the description of `force` property on Apple's UITouch class
+ el: the element to press
+ x: x coordiate to press. If y is used, x must also be set
+ y: y coordiate to press. If x is used, y must also be set
+ pressure: [iOS Only] press as force touch. Read the description of `force` property on Apple's UITouch class
  (https://developer.apple.com/documentation/uikit/uitouch?language=objc) for more details on possible value ranges.
 
  Returns:
- `TouchAction`: self instance
+ `TouchAction`: Self instance
  """
  self._add_action('press', self._get_opts(el, x, y, pressure=pressure))
 
@@ -82,13 +82,13 @@ def long_press(self: T, el: Optional['WebElement'] = None, x: Optional[int]
  """Begin a chain with a press down that lasts `duration` milliseconds
 
  Args:
- el (:obj:`appium.webdriver.webelement.WebElement`, optional): the element to press
- x (:obj:`int`, optional): x coordiate to press. If y is used, x must also be set
- y (:obj:`int`, optional): y coordiate to press. If x is used, y must also be set
- duration (:obj:`int`, optional): Duration to press
+ el: the element to press
+ x: x coordiate to press. If y is used, x must also be set
+ y: y coordiate to press. If x is used, y must also be set
+ duration: Duration to press
 
  Returns:
- `TouchAction`: self instance
+ `TouchAction`: Self instance
  """
  self._add_action('longPress', self._get_opts(el, x, y, duration))
 
@@ -98,10 +98,10 @@ def wait(self: T, ms: int = 0) -> T:
  """Pause for `ms` milliseconds.
 
  Args:
- ms (int): The time to pause
+ ms: The time to pause
 
  Returns:
- `TouchAction`: self instance
+ `TouchAction`: Self instance
  """
  if ms is None:
  ms = 0
@@ -116,12 +116,12 @@ def move_to(self: T, el: Optional['WebElement'] = None, x: Optional[int] = None,
  """Move the pointer from the previous point to the element or point specified
 
  Args:
- el (:obj:`appium.webdriver.webelement.WebElement`, optional): the element to be moved to
- x (:obj:`int`, optional): x coordiate to be moved to. If y is used, x must also be set
- y (:obj:`int`, optional): y coordiate to be moved to. If x is used, y must also be set
+ el: the element to be moved to
+ x: x coordiate to be moved to. If y is used, x must also be set
+ y: y coordiate to be moved to. If x is used, y must also be set
 
  Returns:
- `TouchAction`: self instance
+ `TouchAction`: Self instance
  """
  self._add_action('moveTo', self._get_opts(el, x, y))
 
@@ -131,7 +131,7 @@ def release(self: T) -> T:
  """End the action by lifting the pointer off the screen
 
  Returns:
- `TouchAction`: self instance
+ `TouchAction`: Self instance
  """
  self._add_action('release', {})
 
@@ -141,7 +141,7 @@ def perform(self: T) -> T:
  """Perform the action by sending the commands to the server to be operated upon
 
  Returns:
- `TouchAction`: self instance
+ `TouchAction`: Self instance
  """
  if self._driver is None:
  raise ValueError('Set driver to constructor as a argument when to create the instance.')

appium/webdriver/extensions/action_helpers.py

@@ -42,7 +42,7 @@ def scroll(self: T, origin_el: WebElement, destination_el: WebElement, duration:
  driver.scroll(el1, el2)
 
  Returns:
- `appium.webdriver.webelement.WebElement`
+ Union['WebDriver', 'ActionHelpers']: Self instance
  """
 
  # XCUITest x W3C spec has no duration by default in server side
@@ -64,7 +64,7 @@ def drag_and_drop(self: T, origin_el: WebElement, destination_el: WebElement) ->
  destination_el: the element to drag to
 
  Returns:
- `appium.webdriver.webelement.WebElement`
+ Union['WebDriver', 'ActionHelpers']: Self instance
  """
  action = TouchAction(self)
  action.long_press(origin_el).move_to(destination_el).release().perform()
@@ -75,15 +75,15 @@ def tap(self: T, positions: List[Tuple[int, int]], duration: Optional[int] = Non
  certain time
 
  Args:
- positions (:obj:`list` of :obj:`tuple`): an array of tuples representing the x/y coordinates of
+ positions: an array of tuples representing the x/y coordinates of
  the fingers to tap. Length can be up to five.
- duration (:obj:`int`, optional): length of time to tap, in ms
+ duration: length of time to tap, in ms
 
  Usage:
  driver.tap([(100, 20), (100, 60), (100, 100)], 500)
 
  Returns:
- `appium.webdriver.webelement.WebElement`
+ Union['WebDriver', 'ActionHelpers']: Self instance
  """
  if len(positions) == 1:
  action = TouchAction(self)
@@ -113,17 +113,17 @@ def swipe(self: T, start_x: int, start_y: int, end_x: int, end_y: int, duration:
  """Swipe from one point to another point, for an optional duration.
 
  Args:
- start_x (int): x-coordinate at which to start
- start_y (int): y-coordinate at which to start
- end_x (int): x-coordinate at which to stop
- end_y (int): y-coordinate at which to stop
- duration (:obj:`int`, optional): time to take the swipe, in ms.
+ start_x: x-coordinate at which to start
+ start_y: y-coordinate at which to start
+ end_x: x-coordinate at which to stop
+ end_y: y-coordinate at which to stop
+ duration: time to take the swipe, in ms.
 
  Usage:
  driver.swipe(100, 100, 100, 400)
 
  Returns:
- `appium.webdriver.webelement.WebElement`
+ Union['WebDriver', 'ActionHelpers']: Self instance
  """
  # `swipe` is something like press-wait-move_to-release, which the server
  # will translate into the correct action
@@ -140,16 +140,16 @@ def flick(self: T, start_x: int, start_y: int, end_x: int, end_y: int) -> T:
  """Flick from one point to another point.
 
  Args:
- start_x (int): x-coordinate at which to start
- start_y (int): y-coordinate at which to start
- end_x (int): x-coordinate at which to stop
- end_y (int): y-coordinate at which to stop
+ start_x: x-coordinate at which to start
+ start_y: y-coordinate at which to start
+ end_x: x-coordinate at which to stop
+ end_y: y-coordinate at which to stop
 
  Usage:
  driver.flick(100, 100, 100, 400)
 
  Returns:
- `appium.webdriver.webelement.WebElement`
+ Union['WebDriver', 'ActionHelpers']: Self instance
  """
  action = TouchAction(self)
  action \

appium/webdriver/extensions/android/activities.py

@@ -35,8 +35,8 @@ def start_activity(self: T, app_package: str, app_activity: str, **opts: str) ->
  This is an Android-only method.
 
  Args:
- app_package (str): The package containing the activity to start.
- app_activity (str): The activity to start.
+ app_package: The package containing the activity to start.
+ app_activity: The activity to start.
 
  Keyword Args:
  app_wait_package (str): Begin automation after this package starts.
@@ -81,12 +81,12 @@ def wait_activity(self: T, activity: str, timeout: int, interval: int = 1) -> bo
  This is an Android-only method.
 
  Args:
- activity (str): target activity
- timeout (int): max wait time, in seconds
- interval (int): sleep interval between retries, in seconds
+ activity: target activity
+ timeout: max wait time, in seconds
+ interval: sleep interval between retries, in seconds
 
  Returns:
- bool: `True` if the target activity is shown
+ `True` if the target activity is shown
  """
  try:
  WebDriverWait(self, timeout, interval).until(

appium/webdriver/extensions/android/common.py

@@ -34,8 +34,8 @@ def end_test_coverage(self: T, intent: str, path: str) -> Any: # TODO Check ret
  See https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/android/android-coverage.md
 
  Args:
- intent (str): description of operation to be performed
- path (str): path to coverage.ec file to be pulled from the device
+ intent: description of operation to be performed
+ path: path to coverage.ec file to be pulled from the device
 
  Returns:
  TODO
@@ -50,7 +50,7 @@ def open_notifications(self: T) -> T:
  """Open notification shade in Android (API Level 18 and above)
 
  Returns:
- `appium.webdriver.webdriver.WebDriver`
+ Union['WebDriver', 'Common']: Self instance
  """
  self.execute(Command.OPEN_NOTIFICATIONS, {})
  return self

appium/webdriver/extensions/android/display.py

@@ -31,10 +31,13 @@ def get_display_density(self: T) -> int:
  """Get the display density, Android only
 
  Returns:
- int: The display density of the Android device(dpi)
+ The display density of the Android device(dpi)
 
  Usage:
  self.driver.get_display_density()
+
+ Return:
+ int: The display density
  """
  return self.execute(Command.GET_DISPLAY_DENSITY)['value']