Skip to content

Commit 084c3b1

Browse files
symonksymonk
committed
[py]: PEP257 compliant consistent docstrings throughout. Include in linting recipe
1 parent 3152c96 commit 084c3b1

60 files changed

Lines changed: 773 additions & 1129 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎py/selenium/common/exceptions.py‎

Lines changed: 66 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,14 @@
1515
# specific language governing permissions and limitations
1616
# under the License.
1717

18-
"""
19-
Exceptions that may happen in all the webdriver code.
20-
"""
18+
"""Exceptions that may happen in all the webdriver code."""
2119

2220
from typing import Optional
2321
from typing import Sequence
2422

2523

2624
class WebDriverException(Exception):
27-
"""
28-
Base webdriver exception.
29-
"""
25+
"""Base webdriver exception."""
3026

3127
def __init__(
3228
self, msg: Optional[str] = None, screen: Optional[str] = None, stacktrace: Optional[Sequence[str]] = None
@@ -47,32 +43,25 @@ def __str__(self) -> str:
4743

4844

4945
class InvalidSwitchToTargetException(WebDriverException):
50-
"""
51-
Thrown when frame or window target to be switched doesn't exist.
52-
"""
46+
"""Thrown when frame or window target to be switched doesn't exist."""
5347

5448

5549
class NoSuchFrameException(InvalidSwitchToTargetException):
56-
"""
57-
Thrown when frame target to be switched doesn't exist.
58-
"""
50+
"""Thrown when frame target to be switched doesn't exist."""
5951

6052

6153
class NoSuchWindowException(InvalidSwitchToTargetException):
62-
"""
63-
Thrown when window target to be switched doesn't exist.
54+
"""Thrown when window target to be switched doesn't exist.
6455
6556
To find the current set of active window handles, you can get a list
6657
of the active window handles in the following way::
6758
6859
print driver.window_handles
69-
7060
"""
7161

7262

7363
class NoSuchElementException(WebDriverException):
74-
"""
75-
Thrown when element could not be found.
64+
"""Thrown when element could not be found.
7665
7766
If you encounter this exception, you may want to check the following:
7867
* Check your selector used in your find_by...
@@ -83,25 +72,22 @@ class NoSuchElementException(WebDriverException):
8372

8473

8574
class NoSuchAttributeException(WebDriverException):
86-
"""
87-
Thrown when the attribute of element could not be found.
75+
"""Thrown when the attribute of element could not be found.
8876
89-
You may want to check if the attribute exists in the particular browser you are
90-
testing against. Some browsers may have different property names for the same
91-
property. (IE8's .innerText vs. Firefox .textContent)
77+
You may want to check if the attribute exists in the particular
78+
browser you are testing against. Some browsers may have different
79+
property names for the same property. (IE8's .innerText vs. Firefox
80+
.textContent)
9281
"""
9382

9483

9584
class NoSuchShadowRootException(WebDriverException):
96-
"""
97-
Thrown when trying to access the shadow root of an element when it does not
98-
have a shadow root attached.
99-
"""
85+
"""Thrown when trying to access the shadow root of an element when it does
86+
not have a shadow root attached."""
10087

10188

10289
class StaleElementReferenceException(WebDriverException):
103-
"""
104-
Thrown when a reference to an element is now "stale".
90+
"""Thrown when a reference to an element is now "stale".
10591
10692
Stale means the element no longer appears on the DOM of the page.
10793
@@ -118,19 +104,19 @@ class StaleElementReferenceException(WebDriverException):
118104

119105

120106
class InvalidElementStateException(WebDriverException):
121-
"""
122-
Thrown when a command could not be completed because the element is in an invalid state.
107+
"""Thrown when a command could not be completed because the element is in
108+
an invalid state.
123109
124-
This can be caused by attempting to clear an element that isn't both editable and resettable.
110+
This can be caused by attempting to clear an element that isn't both
111+
editable and resettable.
125112
"""
126113

127114

128115
class UnexpectedAlertPresentException(WebDriverException):
129-
"""
130-
Thrown when an unexpected alert has appeared.
116+
"""Thrown when an unexpected alert has appeared.
131117
132-
Usually raised when an unexpected modal is blocking the webdriver from executing
133-
commands.
118+
Usually raised when an unexpected modal is blocking the webdriver
119+
from executing commands.
134120
"""
135121

136122
def __init__(
@@ -148,156 +134,123 @@ def __str__(self) -> str:
148134

149135

150136
class NoAlertPresentException(WebDriverException):
151-
"""
152-
Thrown when switching to no presented alert.
137+
"""Thrown when switching to no presented alert.
153138
154-
This can be caused by calling an operation on the Alert() class when an alert is
155-
not yet on the screen.
139+
This can be caused by calling an operation on the Alert() class when
140+
an alert is not yet on the screen.
156141
"""
157142

158143

159144
class ElementNotVisibleException(InvalidElementStateException):
160-
"""
161-
Thrown when an element is present on the DOM, but
162-
it is not visible, and so is not able to be interacted with.
145+
"""Thrown when an element is present on the DOM, but it is not visible, and
146+
so is not able to be interacted with.
163147
164-
Most commonly encountered when trying to click or read text
165-
of an element that is hidden from view.
148+
Most commonly encountered when trying to click or read text of an
149+
element that is hidden from view.
166150
"""
167151

168152

169153
class ElementNotInteractableException(InvalidElementStateException):
170-
"""
171-
Thrown when an element is present in the DOM but interactions
172-
with that element will hit another element due to paint order
173-
"""
154+
"""Thrown when an element is present in the DOM but interactions with that
155+
element will hit another element due to paint order."""
174156

175157

176158
class ElementNotSelectableException(InvalidElementStateException):
177-
"""
178-
Thrown when trying to select an unselectable element.
159+
"""Thrown when trying to select an unselectable element.
179160
180161
For example, selecting a 'script' element.
181162
"""
182163

183164

184165
class InvalidCookieDomainException(WebDriverException):
185-
"""
186-
Thrown when attempting to add a cookie under a different domain
187-
than the current URL.
188-
"""
166+
"""Thrown when attempting to add a cookie under a different domain than the
167+
current URL."""
189168

190169

191170
class UnableToSetCookieException(WebDriverException):
192-
"""
193-
Thrown when a driver fails to set a cookie.
194-
"""
171+
"""Thrown when a driver fails to set a cookie."""
195172

196173

197174
class TimeoutException(WebDriverException):
198-
"""
199-
Thrown when a command does not complete in enough time.
200-
"""
175+
"""Thrown when a command does not complete in enough time."""
201176

202177

203178
class MoveTargetOutOfBoundsException(WebDriverException):
204-
"""
205-
Thrown when the target provided to the `ActionsChains` move()
206-
method is invalid, i.e. out of document.
207-
"""
179+
"""Thrown when the target provided to the `ActionsChains` move() method is
180+
invalid, i.e. out of document."""
208181

209182

210183
class UnexpectedTagNameException(WebDriverException):
211-
"""
212-
Thrown when a support class did not get an expected web element.
213-
"""
184+
"""Thrown when a support class did not get an expected web element."""
214185

215186

216187
class InvalidSelectorException(WebDriverException):
217-
"""
218-
Thrown when the selector which is used to find an element does not return
219-
a WebElement. Currently this only happens when the selector is an xpath
220-
expression and it is either syntactically invalid (i.e. it is not a
221-
xpath expression) or the expression does not select WebElements
222-
(e.g. "count(//input)").
188+
"""Thrown when the selector which is used to find an element does not
189+
return a WebElement.
190+
191+
Currently this only happens when the selector is an xpath expression
192+
and it is either syntactically invalid (i.e. it is not a xpath
193+
expression) or the expression does not select WebElements (e.g.
194+
"count(//input)").
223195
"""
224196

225197

226198
class ImeNotAvailableException(WebDriverException):
227-
"""
228-
Thrown when IME support is not available. This exception is thrown for every IME-related
229-
method call if IME support is not available on the machine.
199+
"""Thrown when IME support is not available.
200+
201+
This exception is thrown for every IME-related method call if IME
202+
support is not available on the machine.
230203
"""
231204

232205

233206
class ImeActivationFailedException(WebDriverException):
234-
"""
235-
Thrown when activating an IME engine has failed.
236-
"""
207+
"""Thrown when activating an IME engine has failed."""
237208

238209

239210
class InvalidArgumentException(WebDriverException):
240-
"""
241-
The arguments passed to a command are either invalid or malformed.
242-
"""
211+
"""The arguments passed to a command are either invalid or malformed."""
243212

244213

245214
class JavascriptException(WebDriverException):
246-
"""
247-
An error occurred while executing JavaScript supplied by the user.
248-
"""
215+
"""An error occurred while executing JavaScript supplied by the user."""
249216

250217

251218
class NoSuchCookieException(WebDriverException):
252-
"""
253-
No cookie matching the given path name was found amongst the associated cookies of the
254-
current browsing context's active document.
255-
"""
219+
"""No cookie matching the given path name was found amongst the associated
220+
cookies of the current browsing context's active document."""
256221

257222

258223
class ScreenshotException(WebDriverException):
259-
"""
260-
A screen capture was made impossible.
261-
"""
224+
"""A screen capture was made impossible."""
262225

263226

264227
class ElementClickInterceptedException(WebDriverException):
265-
"""
266-
The Element Click command could not be completed because the element receiving the events
267-
is obscuring the element that was requested to be clicked.
268-
"""
228+
"""The Element Click command could not be completed because the element
229+
receiving the events is obscuring the element that was requested to be
230+
clicked."""
269231

270232

271233
class InsecureCertificateException(WebDriverException):
272-
"""
273-
Navigation caused the user agent to hit a certificate warning, which is usually the result
274-
of an expired or invalid TLS certificate.
275-
"""
234+
"""Navigation caused the user agent to hit a certificate warning, which is
235+
usually the result of an expired or invalid TLS certificate."""
276236

277237

278238
class InvalidCoordinatesException(WebDriverException):
279-
"""
280-
The coordinates provided to an interaction's operation are invalid.
281-
"""
239+
"""The coordinates provided to an interaction's operation are invalid."""
282240

283241

284242
class InvalidSessionIdException(WebDriverException):
285-
"""
286-
Occurs if the given session id is not in the list of active sessions, meaning the session
287-
either does not exist or that it's not active.
288-
"""
243+
"""Occurs if the given session id is not in the list of active sessions,
244+
meaning the session either does not exist or that it's not active."""
289245

290246

291247
class SessionNotCreatedException(WebDriverException):
292-
"""
293-
A new session could not be created.
294-
"""
248+
"""A new session could not be created."""
295249

296250

297251
class UnknownMethodException(WebDriverException):
298-
"""
299-
The requested command matched a known URL but did not match any methods for that URL.
300-
"""
252+
"""The requested command matched a known URL but did not match any methods
253+
for that URL."""
301254

302255

303256
class SeleniumManagerException(WebDriverException):

‎py/selenium/webdriver/chrome/service.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@
2222

2323

2424
class Service(service.ChromiumService):
25-
"""A Service class that is responsible for the starting and stopping
26-
of `chromedriver`.
25+
"""A Service class that is responsible for the starting and stopping of
26+
`chromedriver`.
2727
2828
:param executable_path: install path of the chromedriver executable, defaults to `chromedriver`.
2929
:param port: Port for the service to run on, defaults to 0 where the operating system will decide.

‎py/selenium/webdriver/chrome/webdriver.py‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,8 @@
2929

3030

3131
class WebDriver(ChromiumDriver):
32-
"""
33-
Controls the ChromeDriver and allows you to drive the browser.
32+
"""Controls the ChromeDriver and allows you to drive the browser.
33+
3434
You will need to download the ChromeDriver executable from
3535
http://chromedriver.storage.googleapis.com/index.html
3636
"""
@@ -47,9 +47,8 @@ def __init__(
4747
service: Service = None,
4848
keep_alive=DEFAULT_KEEP_ALIVE,
4949
) -> None:
50-
"""
51-
Creates a new instance of the chrome driver.
52-
Starts the service and then creates new instance of chrome driver.
50+
"""Creates a new instance of the chrome driver. Starts the service and
51+
then creates new instance of chrome driver.
5352
5453
:Args:
5554
- executable_path - Deprecated: path to the executable. If the default is used it assumes the executable is in the $PATH

‎py/selenium/webdriver/chromium/options.py‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,8 @@ def _decode(file_data: BinaryIO) -> str:
9191
return encoded_extensions + self._extensions
9292

9393
def add_extension(self, extension: str) -> None:
94-
"""
95-
Adds the path to the extension to a list that will be used to extract it
96-
to the ChromeDriver
94+
"""Adds the path to the extension to a list that will be used to
95+
extract it to the ChromeDriver.
9796
9897
:Args:
9998
- extension: path to the \\*.crx file
@@ -108,9 +107,8 @@ def add_extension(self, extension: str) -> None:
108107
raise ValueError("argument can not be null")
109108

110109
def add_encoded_extension(self, extension: str) -> None:
111-
"""
112-
Adds Base64 encoded string with extension data to a list that will be used to extract it
113-
to the ChromeDriver
110+
"""Adds Base64 encoded string with extension data to a list that will
111+
be used to extract it to the ChromeDriver.
114112
115113
:Args:
116114
- extension: Base64 encoded string with extension data
@@ -128,8 +126,7 @@ def experimental_options(self) -> dict:
128126
return self._experimental_options
129127

130128
def add_experimental_option(self, name: str, value: Union[str, int, dict, List[str]]) -> None:
131-
"""
132-
Adds an experimental option which is passed to chromium.
129+
"""Adds an experimental option which is passed to chromium.
133130
134131
:Args:
135132
name: The experimental option name.

‎py/selenium/webdriver/chromium/service.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@
2020

2121

2222
class ChromiumService(service.Service):
23-
"""A Service class that is responsible for the starting and stopping
24-
the WebDriver instance of the ChromiumDriver.
23+
"""A Service class that is responsible for the starting and stopping the
24+
WebDriver instance of the ChromiumDriver.
2525
2626
:param executable_path: install path of the executable.
2727
:param port: Port for the service to run on, defaults to 0 where the operating system will decide.

0 commit comments

Comments
 (0)