Skip to content

Commit d679ed8

Browse files
ki4070maki4070ma
authored
Use the same format for docstring (appium#395)
* Update docstring * Update docstring * Update docstring * tweak * tweak * tweak * tweak * tweak * Update docstring * Update docstring * Update docstring * Update docstring * tweak * Update
1 parent 1ddff24 commit d679ed8

30 files changed

Lines changed: 958 additions & 620 deletions

‎appium/common/exceptions.py‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,7 @@
1616

1717

1818
class NoSuchContextException(InvalidSwitchToTargetException):
19-
"""
20-
Thrown when context target to be switched doesn't exist.
19+
"""Thrown when context target to be switched doesn't exist.
2120
2221
To find the current set of active contexts, you can get a list
2322
of the active contexts in the following way:

‎appium/common/helper.py‎

Lines changed: 13 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,16 @@
1818

1919

2020
def appium_bytes(value, encoding):
21-
"""
22-
Return a bytes-like object. Has _appium_ prefix to avoid overriding built-in bytes.
21+
"""Return a bytes-like object
2322
24-
:param value: A value to convert
25-
:type value: string
23+
Has _appium_ prefix to avoid overriding built-in bytes.
2624
27-
:param encoding: A encoding which will convert to
28-
:type encoding: string
25+
Args:
26+
value (str): A value to convert
27+
encoding (str): A encoding which will convert to
2928
30-
:return: A bytes-like object
31-
:rtype: string
29+
Returns:
30+
str: A bytes-like object
3231
"""
3332

3433
try:
@@ -38,22 +37,20 @@ def appium_bytes(value, encoding):
3837

3938

4039
def extract_const_attributes(cls):
41-
"""
42-
Return dict with constants attributes and values in the class (e.g. {'VAL1': 1, 'VAL2': 2})
40+
"""Return dict with constants attributes and values in the class(e.g. {'VAL1': 1, 'VAL2': 2})
4341
44-
:param cls: Class to be extracted constants
45-
:type cls: type
42+
Args:
43+
cls (type): Class to be extracted constants
4644
47-
:return: dict with constants attributes and values in the class
48-
:rtype: OrderedDict
45+
Returns:
46+
OrderedDict: dict with constants attributes and values in the class
4947
"""
5048
return OrderedDict(
5149
[(attr, value) for attr, value in vars(cls).items() if not callable(getattr(cls, attr)) and attr.isupper()])
5250

5351

5452
def library_version():
55-
"""
56-
Return a version of this python library
53+
"""Return a version of this python library
5754
"""
5855

5956
return appium_version.version

‎appium/webdriver/appium_service.py‎

Lines changed: 37 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -120,34 +120,34 @@ def _parse_host(args):
120120
return DEFAULT_HOST
121121

122122
def start(self, **kwargs):
123-
"""
124-
Starts Appium service with given arguments.
123+
"""Starts Appium service with given arguments.
124+
125125
The service will be forcefully restarted if it is already running.
126126
127-
:param kwargs:
128-
`env` - Environment variables mapping. The default system environment,
129-
which is inherited from the parent process is assigned by default.
130-
`node` - The full path to the main NodeJS executable. The service will try
131-
to retrieve it automatically by default.
132-
`stdout` - Check on the documentation for subprocess.Popen for more details.
133-
The default value is subprocess.PIPE.
134-
`stderr` - Check on the documentation for subprocess.Popen for more details.
135-
The default value is subprocess.PIPE.
136-
`timeout_ms` - The maximum time to wait until Appium process starts listening
137-
for HTTP connections. If set to zero or a negative number then no wait will be applied.
138-
60000 ms by default
139-
`main_script` - The full path to the main Appium executable
140-
(usually located this is build/lib/main.js). If this is not set
141-
then the service tries to detect the path automatically.
142-
`args` - List of Appium arguments (all must be strings). Check on
143-
https://appium.io/docs/en/writing-running-appium/server-args/ for more details
144-
about possible arguments and their values.
145-
146-
:return:
147-
subprocess.Popen instance. You can use Popen.communicate interface
148-
or stderr/stdout properties of the instance
149-
(stdout/stderr must not be set to None in such case)
150-
in order to retrieve the actual process output.
127+
Keyword Args:
128+
env (dict): Environment variables mapping. The default system environment,
129+
which is inherited from the parent process is assigned by default.
130+
node (str): The full path to the main NodeJS executable. The service will try
131+
to retrieve it automatically by default.
132+
stdout: Check on the documentation for subprocess.Popen for more details.
133+
The default value is subprocess.PIPE.
134+
stderr: Check on the documentation for subprocess.Popen for more details.
135+
The default value is subprocess.PIPE.
136+
timeout_ms (int): The maximum time to wait until Appium process starts listening
137+
for HTTP connections. If set to zero or a negative number then no wait will be applied.
138+
60000 ms by default
139+
main_script (str): The full path to the main Appium executable
140+
(usually located this is build/lib/main.js). If this is not set
141+
then the service tries to detect the path automatically.
142+
args (str): List of Appium arguments (all must be strings). Check on
143+
https://appium.io/docs/en/writing-running-appium/server-args/ for more details
144+
about possible arguments and their values.
145+
146+
Returns:
147+
subprocess.Popen instance: You can use Popen.communicate interface
148+
or stderr/stdout properties of the instance
149+
(stdout/stderr must not be set to None in such case)
150+
in order to retrieve the actual process output.
151151
"""
152152
self.stop()
153153

@@ -178,13 +178,13 @@ def start(self, **kwargs):
178178
return self._process
179179

180180
def stop(self):
181-
"""
182-
Stops Appium service if it is running.
181+
"""Stops Appium service if it is running.
182+
183183
The call will be ignored if the service is not running
184184
or has been already stopped.
185185
186-
:return:
187-
`True` if the service was running before being stopped
186+
Returns:
187+
bool: `True` if the service was running before being stopped
188188
"""
189189
is_terminated = False
190190
if self.is_running:
@@ -196,24 +196,23 @@ def stop(self):
196196

197197
@property
198198
def is_running(self):
199-
"""
200-
Check if the service is running.
199+
"""Check if the service is running.
201200
202-
:return:
203-
`True` or `False`
201+
Returns:
202+
bool: `True` or `False`
204203
"""
205204
return self._process is not None and self._process.poll() is None
206205

207206
@property
208207
def is_listening(self):
209-
"""
210-
Check if the service is listening on the given/default host/port.
208+
"""Check if the service is listening on the given/default host/port.
209+
211210
The fact, that the service is running, does not always mean it is listening.
212211
the default host/port values can be customized by providing --address/--port
213212
command line arguments while starting the service.
214213
215-
:return:
216-
`True` if the service is running and listening on the given/default host/port
214+
Returns:
215+
bool: `True` if the service is running and listening on the given/default host/port
217216
"""
218217
if not self.is_running or self._cmd is None:
219218
return False

‎appium/webdriver/common/multi_action.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,10 @@ def __init__(self, driver, element=None):
3232
def add(self, *touch_actions):
3333
"""Add TouchAction objects to the MultiAction, to be performed later.
3434
35-
:Args:
36-
- touch_actions - one or more TouchAction objects describing a chain of actions to be performed by one finger
35+
Args:
36+
touch_actions (`TouchAction`): one or more TouchAction objects describing a chain of actions to be performed by one finger
3737
38-
:Usage:
38+
Usage:
3939
a1 = TouchAction(driver)
4040
a1.press(el1).move_to(el2).release()
4141
a2 = TouchAction(driver)
@@ -52,7 +52,7 @@ def add(self, *touch_actions):
5252
def perform(self):
5353
"""Perform the actions stored in the object.
5454
55-
:Usage:
55+
Usage:
5656
a1 = TouchAction(driver)
5757
a1.press(el1).move_to(el2).release()
5858
a2 = TouchAction(driver)

‎appium/webdriver/common/touch_action.py‎

Lines changed: 43 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,13 @@ def __init__(self, driver=None):
3636
def tap(self, element=None, x=None, y=None, count=1):
3737
"""Perform a tap action on the element
3838
39-
:Args:
40-
- element - the element to tap
41-
- x - (optional) x coordinate to tap, relative to the top left corner of the element.
42-
- y - (optional) y coordinate. If y is used, x must also be set, and vice versa
39+
Args:
40+
element (`WebElement`): the element to tap
41+
x (:obj:`int`, optional): x coordinate to tap, relative to the top left corner of the element.
42+
y (:obj:`int`, optional): y coordinate. If y is used, x must also be set, and vice versa
4343
44-
:Usage:
44+
Returns:
45+
`TouchAction`: self instance
4546
"""
4647
opts = self._get_opts(element, x, y)
4748
opts['count'] = count
@@ -52,26 +53,44 @@ def tap(self, element=None, x=None, y=None, count=1):
5253
def press(self, el=None, x=None, y=None, pressure=None):
5354
"""Begin a chain with a press down action at a particular element or point
5455
55-
:Args:
56-
- el - (optional) the element to press
57-
- x - (optional) x coordiate to press. If y is used, x must also be set
58-
- y - (optional) y coordiate to press. If x is used, y must also be set
59-
- pressure - (optional) [iOS Only] press as force touch. Read the description of `force` property on Apple's UITouch class
56+
Args:
57+
el (:obj:`WebElement`, optional): the element to press
58+
x (:obj:`int`, optional): x coordiate to press. If y is used, x must also be set
59+
y (:obj:`int`, optional): y coordiate to press. If x is used, y must also be set
60+
pressure (:obj:`float`, optional): [iOS Only] press as force touch. Read the description of `force` property on Apple's UITouch class
6061
(https://developer.apple.com/documentation/uikit/uitouch?language=objc) for more details on possible value ranges.
62+
63+
Returns:
64+
`TouchAction`: self instance
6165
"""
6266
self._add_action('press', self._get_opts(el, x, y, pressure=pressure))
6367

6468
return self
6569

6670
def long_press(self, el=None, x=None, y=None, duration=1000):
6771
"""Begin a chain with a press down that lasts `duration` milliseconds
72+
73+
Args:
74+
el (:obj:`WebElement`, optional): the element to press
75+
x (:obj:`int`, optional): x coordiate to press. If y is used, x must also be set
76+
y (:obj:`int`, optional): y coordiate to press. If x is used, y must also be set
77+
duration (:obj:`int`, optional): Duration to press
78+
79+
Returns:
80+
`TouchAction`: self instance
6881
"""
6982
self._add_action('longPress', self._get_opts(el, x, y, duration))
7083

7184
return self
7285

7386
def wait(self, ms=0):
7487
"""Pause for `ms` milliseconds.
88+
89+
Args:
90+
ms (int): The time to pause
91+
92+
Returns:
93+
`TouchAction`: self instance
7594
"""
7695
if ms is None:
7796
ms = 0
@@ -84,20 +103,34 @@ def wait(self, ms=0):
84103

85104
def move_to(self, el=None, x=None, y=None):
86105
"""Move the pointer from the previous point to the element or point specified
106+
107+
Args:
108+
el (:obj:`WebElement`, optional): the element to be moved to
109+
x (:obj:`int`, optional): x coordiate to be moved to. If y is used, x must also be set
110+
y (:obj:`int`, optional): y coordiate to be moved to. If x is used, y must also be set
111+
112+
Returns:
113+
`TouchAction`: self instance
87114
"""
88115
self._add_action('moveTo', self._get_opts(el, x, y))
89116

90117
return self
91118

92119
def release(self):
93120
"""End the action by lifting the pointer off the screen
121+
122+
Returns:
123+
`TouchAction`: self instance
94124
"""
95125
self._add_action('release', {})
96126

97127
return self
98128

99129
def perform(self):
100130
"""Perform the action by sending the commands to the server to be operated upon
131+
132+
Returns:
133+
`TouchAction`: self instance
101134
"""
102135
params = {'actions': self._actions}
103136
self._driver.execute(Command.TOUCH_ACTION, params)

0 commit comments

Comments
 (0)