From 5bce92551659a41bd5c05f11e4a3328433af525a Mon Sep 17 00:00:00 2001 From: Tatu Aalto Date: Fri, 10 Nov 2017 00:05:34 +0200 Subject: [PATCH 1/2] Adds sphix style definitions to important methods. --- src/SeleniumLibrary/__init__.py | 46 +++++++++++++++++++++-------- src/SeleniumLibrary/base/context.py | 14 +++++++-- 2 files changed, 46 insertions(+), 14 deletions(-) diff --git a/src/SeleniumLibrary/__init__.py b/src/SeleniumLibrary/__init__.py index 17321ec1a..05fe78827 100644 --- a/src/SeleniumLibrary/__init__.py +++ b/src/SeleniumLibrary/__init__.py @@ -363,6 +363,15 @@ def run_keyword(self, name, args, kwargs): raise def register_driver(self, driver, alias): + """Add's a `driver` to the library WebDriverCache. + + :param driver: Instance of the Selenium `WebDriver`. + :param alias: Alias given for this `WebDriver` instance. + :type driver: selenium.webdriver.remote.webdriver.WebDriver + :type alias: intger or string + :return: The index of the `WebDriver` instance. + :rtype: int + """ return self._drivers.register(driver, alias) def failure_occurred(self): @@ -402,26 +411,39 @@ def browser(self): return self.driver def find_element(self, locator, parent=None): - """Find element matching ``locator``. - - This method and :meth:`find_elements` form the recommended - public API for external tools to get elements via SeleniumLibrary. + """Find element matching `locator`. :param locator: Locator to use when searching the element. See library documentation for the supported locator syntax. - :param parent: Optional parent ``WebElememt`` to search child elements - from. By default search starts from the root using ``WebDriver``. + :param tag: Limit searching only to these elements. + :param required: Raise `ElementNotFound` if element not found when + true, return `None` otherwise. + :param parent: Optional parent `WebElememt` to search child elements + from. By default search starts from the root using `WebDriver`. + :type parent: selenium.webdriver.remote.webelement.WebElement + :return: Found `WebElement` or `None` if element not found and + `required` is false. :rtype: selenium.webdriver.remote.webelement.WebElement - :raises SeleniumLibrary.errors.ElementNotFound: If element not found. + :raises SeleniumLibrary.errors.ElementNotFound: If element not found + and `required` is true. """ return self._element_finder.find(locator, parent=parent) def find_elements(self, locator, parent=None): - """Find all elements matching ``locator``. + """Find all elements matching `locator`. - Returns a list of ``WebElement`` objects. If no matching elements - are found, the list is empty. Otherwise semantics are exactly same - as with the :meth:`find_element` method. + :param locator: Locator to use when searching the element. + See library documentation for the supported locator syntax. + :param tag: Limit searching only to these elements. + :param parent: Optional parent `WebElememt` to search child elements + from. By default search starts from the root using `WebDriver`. + :type parent: selenium.webdriver.remote.webelement.WebElement + :return: list of found `WebElement` or `[]` if element not found. + :rtype: list[selenium.webdriver.remote.webelement.WebElement] + + Always returns a list of `WebElement` objects. If no matching element + is found, the list is empty. Otherwise semantics are exactly same + as with :meth:`find_element`. """ return self._element_finder.find(locator, first_only=False, required=False, parent=parent) @@ -430,7 +452,7 @@ def find_elements(self, locator, parent=None): def _cache(self): warnings.warn('"SeleniumLibrary._cache" is deprecated, ' 'use public API instead.', DeprecationWarning) - return self._browsers + return self._drivers def _current_browser(self): warnings.warn('"SeleniumLibrary._current_browser" is deprecated, ' diff --git a/src/SeleniumLibrary/base/context.py b/src/SeleniumLibrary/base/context.py index 266959462..c39c142cd 100644 --- a/src/SeleniumLibrary/base/context.py +++ b/src/SeleniumLibrary/base/context.py @@ -22,8 +22,8 @@ class ContextAware(object): def __init__(self, ctx): """Base class exposing attributes from the common context. - :param SeleniumLibrary.SeleniumLibrary ctx: - The library itself as a context object. + :param ctx: The library itself as a context object. + :type ctx: SeleniumLibrary.SeleniumLibrary """ self.ctx = ctx @@ -49,6 +49,7 @@ def find_element(self, locator, tag=None, required=True, parent=None): true, return `None` otherwise. :param parent: Optional parent `WebElememt` to search child elements from. By default search starts from the root using `WebDriver`. + :type parent: selenium.webdriver.remote.webelement.WebElement :return: Found `WebElement` or `None` if element not found and `required` is false. :rtype: selenium.webdriver.remote.webelement.WebElement @@ -60,6 +61,15 @@ def find_element(self, locator, tag=None, required=True, parent=None): def find_elements(self, locator, tag=None, parent=None): """Find all elements matching `locator`. + :param locator: Locator to use when searching the element. + See library documentation for the supported locator syntax. + :param tag: Limit searching only to these elements. + :param parent: Optional parent `WebElememt` to search child elements + from. By default search starts from the root using `WebDriver`. + :type parent: selenium.webdriver.remote.webelement.WebElement + :return: list of found `WebElement` or `[]` if element not found. + :rtype: list[selenium.webdriver.remote.webelement.WebElement] + Always returns a list of `WebElement` objects. If no matching element is found, the list is empty. Otherwise semantics are exactly same as with :meth:`find_element`. From fb963b021f4aa044f78de07727dff0e0ee23c6a1 Mon Sep 17 00:00:00 2001 From: Tatu Aalto Date: Tue, 14 Nov 2017 22:16:14 +0200 Subject: [PATCH 2/2] Fixes based on comments --- src/SeleniumLibrary/__init__.py | 22 +++++++--------------- src/SeleniumLibrary/base/context.py | 11 ++++++----- 2 files changed, 13 insertions(+), 20 deletions(-) diff --git a/src/SeleniumLibrary/__init__.py b/src/SeleniumLibrary/__init__.py index 05fe78827..8884818e6 100644 --- a/src/SeleniumLibrary/__init__.py +++ b/src/SeleniumLibrary/__init__.py @@ -366,9 +366,9 @@ def register_driver(self, driver, alias): """Add's a `driver` to the library WebDriverCache. :param driver: Instance of the Selenium `WebDriver`. - :param alias: Alias given for this `WebDriver` instance. :type driver: selenium.webdriver.remote.webdriver.WebDriver - :type alias: intger or string + :param alias: Alias given for this `WebDriver` instance. + :type alias: str :return: The index of the `WebDriver` instance. :rtype: int """ @@ -415,17 +415,13 @@ def find_element(self, locator, parent=None): :param locator: Locator to use when searching the element. See library documentation for the supported locator syntax. - :param tag: Limit searching only to these elements. - :param required: Raise `ElementNotFound` if element not found when - true, return `None` otherwise. + :type locator: str or selenium.webdriver.remote.webelement.WebElement :param parent: Optional parent `WebElememt` to search child elements from. By default search starts from the root using `WebDriver`. :type parent: selenium.webdriver.remote.webelement.WebElement - :return: Found `WebElement` or `None` if element not found and - `required` is false. + :return: Found `WebElement`. :rtype: selenium.webdriver.remote.webelement.WebElement - :raises SeleniumLibrary.errors.ElementNotFound: If element not found - and `required` is true. + :raises SeleniumLibrary.errors.ElementNotFound: If element not found. """ return self._element_finder.find(locator, parent=parent) @@ -434,16 +430,12 @@ def find_elements(self, locator, parent=None): :param locator: Locator to use when searching the element. See library documentation for the supported locator syntax. - :param tag: Limit searching only to these elements. + :type locator: str or selenium.webdriver.remote.webelement.WebElement :param parent: Optional parent `WebElememt` to search child elements from. By default search starts from the root using `WebDriver`. :type parent: selenium.webdriver.remote.webelement.WebElement - :return: list of found `WebElement` or `[]` if element not found. + :return: list of found `WebElement` or e,mpty if elements are not found. :rtype: list[selenium.webdriver.remote.webelement.WebElement] - - Always returns a list of `WebElement` objects. If no matching element - is found, the list is empty. Otherwise semantics are exactly same - as with :meth:`find_element`. """ return self._element_finder.find(locator, first_only=False, required=False, parent=parent) diff --git a/src/SeleniumLibrary/base/context.py b/src/SeleniumLibrary/base/context.py index c39c142cd..e210d6606 100644 --- a/src/SeleniumLibrary/base/context.py +++ b/src/SeleniumLibrary/base/context.py @@ -44,9 +44,12 @@ def find_element(self, locator, tag=None, required=True, parent=None): :param locator: Locator to use when searching the element. See library documentation for the supported locator syntax. + :type locator: str or selenium.webdriver.remote.webelement.WebElement :param tag: Limit searching only to these elements. + :type tag: str :param required: Raise `ElementNotFound` if element not found when true, return `None` otherwise. + :type required: True or False :param parent: Optional parent `WebElememt` to search child elements from. By default search starts from the root using `WebDriver`. :type parent: selenium.webdriver.remote.webelement.WebElement @@ -63,16 +66,14 @@ def find_elements(self, locator, tag=None, parent=None): :param locator: Locator to use when searching the element. See library documentation for the supported locator syntax. + :type locator: str or selenium.webdriver.remote.webelement.WebElement :param tag: Limit searching only to these elements. + :type tag: str :param parent: Optional parent `WebElememt` to search child elements from. By default search starts from the root using `WebDriver`. :type parent: selenium.webdriver.remote.webelement.WebElement - :return: list of found `WebElement` or `[]` if element not found. + :return: list of found `WebElement` or empty if elements are not found. :rtype: list[selenium.webdriver.remote.webelement.WebElement] - - Always returns a list of `WebElement` objects. If no matching element - is found, the list is empty. Otherwise semantics are exactly same - as with :meth:`find_element`. """ return self.element_finder.find(locator, tag, False, False, parent)