UIWeb docs

2 years ago · 3adcc94cd1
parent 102704c75c
commit 3adcc94cd1
2 changed files with 170 additions and 67 deletions
--- a/Sources/pyOpenRPA/Robot/UIWeb.py
+++ b/Sources/pyOpenRPA/Robot/UIWeb.py
@ -15,17 +15,24 @@ UIO_WAIT_INTERVAL_SEC_FLOAT = 1.0
 gBrowser:webdriver.Chrome = None

 def BrowserChromeStart(inDriverExePathStr:str = None, inChromeExePathStr:str = None, inExtensionPathList:list = None, inProfilePathStr:str=None) -> webdriver.Chrome:
-    """_summary_
+    """L+,W+: Выполнить запуск браузера Chrome. Если вы скачали pyOpenRPA вместе с репозиторием, то будет использоваться встроенный браузер Google Chrome. Если установка pyOpenRPA производилась другим способом, то требуется указать расположение браузера Google Chrome и соответствующего WebDriver.
+
+    .. code-block:: python
+
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        UIWeb.BrowserChromeStart()
+        UIWeb.BrowserClose()

-    :param inDriverExePathStr: _description_, defaults to None
-    :type inDriverExePathStr: str, optional
-    :param inChromeExePathStr: _description_, defaults to None
-    :type inChromeExePathStr: str, optional
-    :param inExtensionPathList: _description_, defaults to None
-    :type inExtensionPathList: list, optional
-    :param inProfilePathStr: _description_, defaults to None
-    :type inProfilePathStr: str, optional
-    :return: _description_
+    :param inDriverExePathStr: _description_, по умолчанию None
+    :type inDriverExePathStr: str, опционально
+    :param inChromeExePathStr: _description_, по умолчанию None
+    :type inChromeExePathStr: str, опционально
+    :param inExtensionPathList: _description_, по умолчанию None
+    :type inExtensionPathList: list, опционально
+    :param inProfilePathStr: _description_, по умолчанию None
+    :type inProfilePathStr: str, опционально
+    :return: Объект браузера Google Chrome
    :rtype: webdriver.Chrome
    """
    global gBrowser
@ -65,19 +72,38 @@ def BrowserChromeStart(inDriverExePathStr:str = None, inChromeExePathStr:str = N
    return gBrowser

 def BrowserChange(inBrowser):
-    """_summary_
+    """L+,W+: Выполнить смену активного браузера (при необходимости).
+
+    .. code-block:: python
+
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        lBrowser1 = UIWeb.BrowserChromeStart()
+        UIWeb.BrowserChange(inBrowser=None)
+        lBrowser2 = UIWeb.BrowserChromeStart()
+        UIWeb.BrowserClose()
+        UIWeb.BrowserChange(inBrowser=lBrowser1)
+        UIWeb.BrowserClose()

-    :param inBrowser: _description_
-    :type inBrowser: _type_
+    :param inBrowser: Объект браузера
+    :type inBrowser: webdriver.Chrome
    """
    global gBrowser
    gBrowser = inBrowser

-def PageOpen(inURLStr):
-    """_summary_
+def PageOpen(inURLStr: str):
+    """L+,W+: Открыть страницу inURLStr в браузере и дождаться ее загрузки.
+
+    .. code-block:: python

-    :param inURLStr: _description_
-    :type inURLStr: _type_
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        UIWeb.BrowserChromeStart()
+        UIWeb.PageOpen("https://mail.ru")
+        UIWeb.BrowserClose()
+
+    :param inURLStr: URL адрес страницы
+    :type inURLStr: str
    """
    global gBrowser
    if gBrowser is not None: gBrowser.get(inURLStr)
@ -85,6 +111,15 @@ def PageOpen(inURLStr):
 def PageScrollTo(inVerticalPxInt=0, inHorizontalPxInt=0):
    """_summary_

+    .. code-block:: python
+
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        UIWeb.BrowserChromeStart()
+        UIWeb.PageOpen("https://mail.ru")
+        UIWeb.PageJSExecute(alert('arguments[0]);", "hello world!")
+        UIWeb.BrowserClose()
+
    :param inVerticalPxInt: _description_, defaults to 0
    :type inVerticalPxInt: int, optional
    :param inHorizontalPxInt: _description_, defaults to 0
@ -93,31 +128,63 @@ def PageScrollTo(inVerticalPxInt=0, inHorizontalPxInt=0):
    PageJSExecute(inJSStr=f"scroll({inHorizontalPxInt},{inVerticalPxInt})")

 def PageJSExecute(inJSStr, *inArgList):
-    """_summary_
+    """L+,W+: Отправить на выполнение на сторону браузера код JavaScript.
+
+    !ВНИМАНИЕ! Данная функция поддерживает передачу переменных в область кода JavaScript (*inArgList). Обратиться к переданным переменным из JavaScript можно с помощью ключевого слова: arguments[i], где i - это порядковый номер переданной переменной

-    :param inJSStr: _description_
-    :type inJSStr: _type_
-    :return: _description_
-    :rtype: _type_
+    .. code-block:: python
+
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        UIWeb.BrowserChromeStart()
+        UIWeb.PageOpen("https://mail.ru")
+        UIWeb.PageJSExecute(alert('arguments[0]);", "hello world!")
+        UIWeb.BrowserClose()
+
+    :param inJSStr: Код JavaScript, отправляемый на сторону браузера
+    :type inJSStr: str
+    :param *inArgList: Перечисление аргументов, отправляемых на сторону браузера
+    :type *inArgList: str
+    :return: Результат отработки кода JavaScript, если он заканчивался оператором "return"
+    :rtype: str | int | bool | float
    """
    # arguments[0], arguments[1] etc
    global gBrowser
    if gBrowser is not None: return gBrowser.execute_script(inJSStr, *inArgList)
    
 def BrowserClose():
-    """_summary_
+    """L+,W+: Закрыть браузер
+
+    .. code-block:: python
+
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        UIWeb.BrowserChromeStart()
+        UIWeb.PageOpen("https://mail.ru")
+        UIWeb.BrowserClose()
+
    """
    global gBrowser
    if gBrowser is not None: gBrowser.quit()

 def UIOSelectorList(inUIOSelectorStr, inUIO=None) -> list:
-    """_summary_
+    """L+,W+: Получить список UIO объектов по UIO селектору.

-    :param inUIOSelectorStr: _description_
-    :type inUIOSelectorStr: _type_
-    :param inUIO: _description_, defaults to None
-    :type inUIO: _type_, optional
-    :return: _description_
+    .. code-block:: python
+
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        UIWeb.BrowserChromeStart()
+        UIWeb.PageOpen("https://mail.ru")
+        lUIOSelectorStr = "//*[@id=\"grid\"]/div[2]/div[2]/div[3]/div[1]/ul/li[5]/div/a"
+        lUIOList = UIOSelectorList(inUIOSelectorStr = lUIOSelectorStr)
+        UIWeb.BrowserClose()
+
+    :param inUIOSelectorStr: XPATH или CSS селектор UI объекта на web странице. Подсказки по CSS: https://devhints.io/css Подсказки по XPath: https://devhints.io/xpath 
+    :type inUIOSelectorStr: str
+    :param inUIO: Объект UIO, от которого выполнить поиск UIO объектов по селектору, по умолчанию None
+    :type inUIO: WebElement, опционально
+    :return: Список UIO объектов
    :rtype: list
    """
    lResultList = []
@ -136,14 +203,24 @@ def UIOSelectorList(inUIOSelectorStr, inUIO=None) -> list:
    return lResultList

 def UIOSelectorFirst(inUIOSelectorStr, inUIO=None) -> list:
-    """_summary_
+    """L+,W+: Получить UIO объект по UIO селектору.

-    :param inUIOSelectorStr: _description_
-    :type inUIOSelectorStr: _type_
-    :param inUIO: _description_, defaults to None
-    :type inUIO: _type_, optional
-    :return: _description_
-    :rtype: list
+    .. code-block:: python
+
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        UIWeb.BrowserChromeStart()
+        UIWeb.PageOpen("https://mail.ru")
+        lUIOSelectorStr = "//*[@id=\"grid\"]/div[2]/div[2]/div[3]/div[1]/ul/li[5]/div/a"
+        lUIO = UIOSelectorFirst(inUIOSelectorStr = lUIOSelectorStr)
+        UIWeb.BrowserClose()
+
+    :param inUIOSelectorStr: XPATH или CSS селектор UI объекта на web странице. Подсказки по CSS: https://devhints.io/css Подсказки по XPath: https://devhints.io/xpath 
+    :type inUIOSelectorStr: str
+    :param inUIO: Объект UIO, от которого выполнить поиск UIO объектов по селектору, по умолчанию None
+    :type inUIO: WebElement, опционально
+    :return: Первый подходящий UIO объект
+    :rtype: UIO объект
    """
    lResult = None
    lUIOList = UIOSelectorList(inUIOSelectorStr=inUIOSelectorStr, inUIO=inUIO)
@ -151,35 +228,68 @@ def UIOSelectorFirst(inUIOSelectorStr, inUIO=None) -> list:
    return lResult

 def UIOTextGet(inUIO) -> str:
-    """_summary_
+    """L+,W+: Получить текст UI элемента.
+
+    .. code-block:: python

-    :param inUIO: _description_
-    :type inUIO: _type_
-    :return: _description_
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        UIWeb.BrowserChromeStart()
+        UIWeb.PageOpen("https://mail.ru")
+        lUIOSelectorStr = "//*[@id=\"grid\"]/div[2]/div[2]/div[3]/div[1]/ul/li[5]/div/a"
+        lUIO = UIOSelectorList(inUIOSelectorStr = lUIOSelectorStr)[0]
+        lTextStr = UIWeb.UIOTextGet(inUIO=lUIO)
+        UIWeb.BrowserClose()
+
+    :param inUIO: UIO элемент. Получить его можно с помощью функций UIOSelectorList или UIOSelectorFirst
+    :type inUIO: WebElement
+    :return: Текст UI элемента
    :rtype: str
    """
    return inUIO.text

 def UIOAttributeGet(inUIO, inAttributeStr) -> str:
-    """_summary_
+    """L+,W+: Получить обычный (нестилевой) атрибут у UI элемента.
+
+    .. code-block:: python

-    :param inUIO: _description_
-    :type inUIO: _type_
-    :param inAttributeStr: _description_
-    :type inAttributeStr: _type_
-    :return: _description_
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        UIWeb.BrowserChromeStart()
+        UIWeb.PageOpen("https://mail.ru")
+        lUIOSelectorStr = "//*[@id=\"grid\"]/div[2]/div[2]/div[3]/div[1]/ul/li[5]/div/a"
+        lUIO = UIOSelectorList(inUIOSelectorStr = lUIOSelectorStr)[0]
+        UIWeb.UIOAttributeGet(inUIO=lUIO, inAttributeStr = "href")
+        UIWeb.BrowserClose()
+
+    :param inUIO: UIO элемент. Получить его можно с помощью функций UIOSelectorList или UIOSelectorFirst
+    :type inUIO: WebElement
+    :param inAttributeStr: Наименование обычного (нестилевого) атрибута
+    :type inAttributeStr: str
+    :return: Значение обычного (нестилевого) атрибута
    :rtype: str
    """
    return inUIO.get_attribute(inAttributeStr)

 def UIOAttributeStyleGet(inUIO, inAttributeStr) -> str:
-    """_summary_
+    """L+,W+: Получить стилевой атрибут у UI элемента.
+
+    .. code-block:: python

-    :param inUIO: _description_
-    :type inUIO: _type_
-    :param inAttributeStr: _description_
-    :type inAttributeStr: _type_
-    :return: _description_
+        # UIWeb: Взаимодействие с ui web
+        from pyOpenRPA.Robot import UIWeb
+        UIWeb.BrowserChromeStart()
+        UIWeb.PageOpen("https://mail.ru")
+        lUIOSelectorStr = "//*[@id=\"grid\"]/div[2]/div[2]/div[3]/div[1]/ul/li[5]/div/a"
+        lUIO = UIOSelectorList(inUIOSelectorStr = lUIOSelectorStr)[0]
+        UIWeb.UIOAttributeStyleGet(inUIO=lUIO, inAttributeStr = "href")
+        UIWeb.BrowserClose()
+
+    :param inUIO: UIO элемент. Получить его можно с помощью функций UIOSelectorList или UIOSelectorFirst
+    :type inUIO: WebElement
+    :param inAttributeStr: Наименование стилевого атрибута
+    :type inAttributeStr: str
+    :return: Значение стилевого атрибута
    :rtype: str
    """
    return inUIO.value_of_css_property(inAttributeStr)
--- a/Utils/Jupyter-notebooks/Web.ipynb
+++ b/Utils/Jupyter-notebooks/Web.ipynb
@ -29,7 +29,7 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
@ -38,22 +38,15 @@
  },
  {
   "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 4,
   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "<selenium.webdriver.remote.webelement.WebElement (session=\"2d9c81f94cb903caaa62936fe795b5ba\", element=\"e826bde4-71c0-4245-b08d-7f4af5564c43\")>"
-      ]
-     },
-     "execution_count": 3,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
+   "outputs": [],
   "source": [
-    "lUIO"
+    "        # UIWeb: Взаимодействие с ui web\n",
+    "        from pyOpenRPA.Robot import UIWeb\n",
+    "        #UIWeb.BrowserChromeStart()\n",
+    "        #UIWeb.PageOpen(\"https://mail.ru\")\n",
+    "        UIWeb.PageJSExecute(\"alert(arguments[0]);\", \"hello world!\")"
   ]
  },
  {