From 3a0c7153dbee0ed1919d53930ddb5289fb174721 Mon Sep 17 00:00:00 2001 From: g1879 Date: Fri, 4 Dec 2020 22:32:06 +0800 Subject: [PATCH 1/5] 1.7.0 --- README.en.md | 20 ++++++++++++++++++-- README.zh-cn.md | 18 ++++++++++++++++-- 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/README.en.md b/README.en.md index d124a59..bc0c904 100644 --- a/README.en.md +++ b/README.en.md @@ -581,12 +581,28 @@ page.chrome_downloading() # Get the list of files that chrome is downloading page.process_alert(mode, text) # Process the prompt box ``` +### Use of cookies +MixPage supports obtaining and setting cookies. The specific usage methods are as follows: + +```python +page.cookies # Return cookies in dictionary form, only cookies available for the current domain name will be returned +page.get_cookies(as_dict=False) # Return the cookies available for the current domain name in the form of a list, each cookie contains all the detailed information +page.get_cookies(all_domains=True) # Return all cookies in list form, only s mode is valid +page.set_cookies(cookies) # Set cookies, you can pass in RequestsCookieJar, list, tuple, str, dict +``` + +Tips: + +- After setting cookies in d mode, you must refresh the page to see the effect. + +- The s mode can set cookies in the ini file, SessionOptions, and configuration dictionary, which can be passed in when + MixPage is initialized. The d mode can only be set with the set_cookies() function. ## Find element -ele() returns the first eligible element, and eles() returns a list of all eligible elements. -You can use these two functions under the page object or element object to find subordinate elements. +ele() returns the first eligible element, and eles() returns a list of all eligible elements. You can use these two +functions under the page object or element object to find subordinate elements. page.eles() and element.eles() search and return a list of all elements that meet the conditions. diff --git a/README.zh-cn.md b/README.zh-cn.md index 195f1d0..bbf3db8 100644 --- a/README.zh-cn.md +++ b/README.zh-cn.md @@ -585,14 +585,28 @@ page.chrome_downloading() # 获取 chrome 正在下载的文件列表 page.process_alert(mode, text) # 处理提示框 ``` +### cookies 的使用 +MixPage 支持获取和设置 cookies，具体使用方法如下： + +```python +page.cookies # 以字典形式返回 cookies，只会返回当前域名可用的 cookies +page.get_cookies(as_dict=False) # 以列表形式返回当前域名可用 cookies，每个 cookie 包含所有详细信息 +page.get_cookies(all_domains=True) # 以列表形式返回所有 cookies，只有 s 模式有效 +page.set_cookies(cookies) # 设置 cookies，可传入 RequestsCookieJar, list, tuple, str, dict +``` + +Tips: + +- d 模式设置 cookies 后要刷新页面才能看到效果。 +- s 模式可在 ini 文件、SessionOptions、配置字典中设置 cookies，在 MixPage 初始化时即可传入，d 模式只能用 set_cookies() 函数设置。 ## 查找元素 ele() 返回第一个符合条件的元素，eles() 返回所有符合条件的元素列表。 -你可在页面对象或元素对象下使用这两个函数，以查找下级元素。 +你可在页面对象或元素对象下使用这两个函数，以查找下级元素。 -page.eles() 和 element.eles() 查找返回符合条件的所有元素列表。 +page.eles() 和 element.eles() 查找返回符合条件的所有元素列表。 说明： From 0d98abf5a0f005f6f77999ce0adc8e3239669e42 Mon Sep 17 00:00:00 2001 From: g1879 Date: Sun, 6 Dec 2020 21:29:58 +0800 Subject: [PATCH 2/5] =?UTF-8?q?=E4=BF=AE=E6=94=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.zh-cn.md | 2062 +---------------------------------------------- 1 file changed, 42 insertions(+), 2020 deletions(-) diff --git a/README.zh-cn.md b/README.zh-cn.md index bbf3db8..7e225fb 100644 --- a/README.zh-cn.md +++ b/README.zh-cn.md @@ -2,13 +2,15 @@ *** -DrissionPage，即 driver 和 session 的合体。 +## 项目介绍 + +DrissionPage，即 driver 和 session 组合而成的 page。 是个基于 python 的 Web 自动化操作集成工具。 它实现了 selenium 和 requests 之间的无缝切换。 -因此可以兼顾 selenium 的便利性和 requests 的高效率。 +可以兼顾 selenium 的便利性和 requests 的高效率。 它集成了页面常用功能，两种模式系统一致的 API，使用便捷。 -它用 POM 模式封装了页面元素常用的方法，很适合自动化操作功能扩展。 -更棒的是，它的使用方式非常简洁和人性化，代码量少，对新手友好。 +它用 POM 模式封装了页面元素常用的方法，适合自动化操作功能扩展。 +更棒的是，它的使用方式非常简洁和人性化，代码量少，对新手友好。 **项目地址：** @@ -21,9 +23,7 @@ DrissionPage，即 driver 和 session 的合体。 **交流QQ群：** 897838127 -# 理念及背景 -*** ## 理念 @@ -49,29 +49,30 @@ requests 爬虫面对要登录的网站时，要分析数据包、JS 源码， - 对常用功能作了整合和优化，更符合实际使用需要。 - 兼容 selenium 代码，便于项目迁移。 - 使用 POM 模式封装，便于扩展。 -- 统一的文件下载方法，弥补浏览器下载的不足。 +- 统一的文件下载方法，弥补浏览器下载的不足。 - 简易的配置方法，摆脱繁琐的浏览器配置。 # 项目结构 *** -## 结构图 + +**结构图** ![](https://gitee.com/g1879/DrissionPage-demos/raw/master/pics/20201118170751.jpg) -## Drission 类 +**Drission 类** 管理负责与网页通讯的 WebDriver 对象和 Session 对象，相当于驱动器的角色。 -## MixPage 类 +**MixPage 类** -MixPage 封装了页面操作的常用功能，它调用 Drission 类中管理的驱动器，对页面进行访问、操作。可在 driver 和 session 模式间切换。切换的时候会自动同步登录状态。 +MixPage 封装了页面操作的常用功能，它调用 Drission 类中管理的驱动器，对页面进行访问、操作。可在 driver 和 session 模式间切换。切换的时候会自动同步登录状态。 -## DriverElement 类 +**DriverElement 类** -driver 模式下的页面元素类，可对元素进行点击、输入文本、修改属性、运行 js 等操作，也可在其下级搜索后代元素。 +driver 模式下的页面元素类，可对元素进行点击、输入文本、修改属性、运行 js 等操作，也可在其下级搜索后代元素。 -## SessionElement 类 +**SessionElement 类** session 模式下的页面元素类，可获取元素属性值，也可在其下级搜索后代元素。 @@ -299,23 +300,20 @@ save_path = r'C:\download' page.download(url, save_path) ``` - - -# 安装 +# 使用方法 *** +## 安装 + ``` pip install DrissionPage ``` -只支持 python3.6 及以上版本，driver 模式目前只支持 chrome，目前只在 Windows 环境下作了测试。。 + +只支持 python3.6 及以上版本，driver 模式目前只支持 chrome，目前只在 Windows 环境下作了测试。 若要使用 driver 模式，须配置 chrome 和 **对应版本** 的 chromedriver。[[chromedriver下载]](http://npm.taobao.org/mirrors/chromedriver) easy_set 工具中的 get_match_driver() 方法可自动识别 chrome 版本并下载匹配的 driver 。 -# 使用方法 - -*** - ## 导入模块 ```python @@ -326,7 +324,7 @@ from DrissionPage import MixPage ## 初始化 -如果你只使用 session 模式，可跳过本节。 +> 如果你只使用 session 模式，可跳过本节。 使用 selenium 前，必须配置 chrome.exe 和 chromedriver.exe 的路径，并确保它们版本匹配。 @@ -430,7 +428,7 @@ Tips： ## 创建驱动器对象 Drission -创建的步骤不是必须，若想快速上手，可跳过本节。MixPage 会自动创建该对象。 +> 创建的步骤不是必须，若想快速上手，可跳过本节。MixPage 会自动创建该对象。 Drission 对象用于管理 driver 和 session 对象。在多个页面协同工作时，Drission 对象用于传递驱动器，使多个页面类可控制同一个浏览器或 Session 对象。 可直接读取 ini 文件配置信息创建，也可以在初始化时传入配置信息。 @@ -737,7 +735,7 @@ element.hover() # 在元素上悬停鼠标 ## shadow-dom 操作 -支持获取 shadow-root 及内部元素，获取到的 shadow-root 元素类型为 ShadowRootElement，用法和正常元素类似，但功能有所简化。 +d 模式独有，支持获取 shadow-root 及内部元素，获取到的 shadow-root 元素类型为 ShadowRootElement，用法和正常元素类似，但功能有所简化。 **注意：** @@ -766,11 +764,9 @@ shadow_root_element.is_enabled() # 返回元素是否可用 shadow_root_element.is_valid() # 返回元素是否还在 dom 内 ``` -**Tips：**以上属性或方法获取到的元素是普通的 DriverElement，用法参考上文所述。 +**Tips:** 以上属性或方法获取到的元素是普通的 DriverElement，用法参考上文所述。 - - -## 与 selenium 及 requests 代码对接 +## 对接 selenium 及 requests DrissionPage 代码可与 selenium 及 requests 代码无缝拼接。既可直接使用 selenium 的 WebDriver 对象，也可导出自身的 WebDriver 给 selenium 代码使用。requests 的 Session 对象也可直接传递。使已有项目的迁移非常方便。 @@ -1077,11 +1073,9 @@ set_argument(arg, value) # 设置属性，若属性无值（如'zh_CN.UTF-8'） check_driver_version() # 检查chrome和chromedriver版本是否匹配 ``` -# POM 模式 +## POM 模式 -*** - -MixPage 封装了常用的页面操作，可方便地用于扩展。 +MixPage 封装了常用的页面操作，可方便地用于扩展。 例：扩展一个列表页面读取类 @@ -1148,9 +1142,7 @@ class ListPage(MixPage): return 列表 ``` -# 其它 -*** ## DriverPage 和 SessionPage @@ -1171,2032 +1163,62 @@ page.get('http://www.baidu.com') print(page.ele('@id:su').text) # 输出：百度一下 ``` +# 版本历史 + +*** + +点击查看：[https://gitee.com/g1879/DrissionPage/wikis/%E7%89%88%E6%9C%AC%E5%8E%86%E5%8F%B2?sort_id=3201403](https://gitee.com/g1879/DrissionPage/wikis/%E7%89%88%E6%9C%AC%E5%8E%86%E5%8F%B2?sort_id=3201403) + # APIs *** ## Drission 类 -### class Drission() - -Drission 类用于管理 WebDriver 对象和 Session 对象，是驱动器的角色。 - -参数说明： - -- driver_or_options: [WebDriver, dict, Options, DriverOptions] - WebDriver 对象或 chrome 配置参数。 -- session_or_options: [Session, dict] - Session 对象配置参数 -- ini_path: str - ini 文件路径，默认为 DrissionPage 文件夹下的ini文件 -- proxy: dict - 代理设置 - - - -### session - -返回 Session 对象，自动按配置信息初始化。 - -返回： Session - 管理的 Session 对象 - - - -### driver - -返回 WebDriver 对象，自动按配置信息初始化。 - -返回： WebDriver - 管理的 WebDriver 对象 - - - -### driver_options - -返回或设置 driver 配置。 - -返回： dict - - - -### session_options - -返回 session 配置。 - -返回： dict - - - -### session_options() - -设置 session 配置。 - -返回： None - - - -### proxy - -返回代理配置。 - -返回： dict - - - -### set_cookies() - -设置 cookies。 - -参数说明： - -- cookies: Union[RequestsCookieJar, list, tuple, str, dict] - cookies 信息，可为CookieJar, list, tuple, str, dict -- set_session: bool - 是否设置 session 的 cookies -- set_driver: bool - 是否设置 driver 的 cookies - -返回： None - - - -### cookies_to_session() - -把 driver 对象的 cookies 复制到 session 对象。 - -参数说明： - -- copy_user_agent: bool - 是否复制 user_agent 到 session - -返回： None - - - -### cookies_to_driver() - -把 cookies 从 session 复制到 driver。 - -参数说明： - -- url: str - cookies 的域 - -返回： None - - - -### user_agent_to_session() - -把 user agent 从 driver 复制到 session。 - -参数说明： - -- driver: WebDriver - WebDriver 对象，复制 user agent -- session: Session - Session 对象，接收 user agent - -返回： None - - - -### close_driver() - -关闭浏览器，driver 置为 None。 - -返回： None - - - -### close_session() - -关闭 session 并置为 None。 - -返回： None - - - -### close() - -关闭 driver 和 session。 - -返回： None - - +点击查看：[https://gitee.com/g1879/DrissionPage/wikis/Drission%20%E7%B1%BB?sort_id=3159323](https://gitee.com/g1879/DrissionPage/wikis/Drission%20%E7%B1%BB?sort_id=3159323) ## MixPage 类 -### class MixPage() - -MixPage 封装了页面操作的常用功能，可在 driver 和 session 模式间无缝切换。切换的时候会自动同步 cookies。 -获取信息功能为两种模式共有，操作页面元素功能只有 d 模式有。调用某种模式独有的功能，会自动切换到该模式。 -它继承自 DriverPage 和 SessionPage 类，这些功能由这两个类实现，MixPage 作为调度的角色存在。 - -参数说明： - -- drission: Drission - Drission 对象，如没传入则创建一个。传入 's' 或 'd' 时快速配置相应模式 -- mode: str - 模式，可选 'd' 或 's'，默认为'd' -- timeout: float - 超时时间，driver 模式为查找元素时间，session 模式为连接等待时间 - - - -### url - -返回 MixPage 对象当前访问的 url。 - -返回： str - - - -### mode - -返回当前模式（ 's' 或 'd' ）。 - -返回： str - - - -### drission - -返回当前使用的 Dirssion 对象。 - -返回： Drission - - - -### driver - -返回driver对象，如没有则创建，调用时会切换到 driver 模式。 - -返回： WebDriver - - - -### session - -返回 session 对象，如没有则创建。 - -返回： Session - - - -### response - -返回s模式获取到的 Response 对象，调用时会切换到s模式。 - -返回： Response - - - -### cookies - -返回 cookies，从当前模式获取。 - -返回： [dict, list] - - - -### html - -返回页面 html 文本。 - -返回： str - - - -### title - -返回页面 title。 - -返回： str - - - -### url_available - -返回当前 url 有效性。 - -返回： bool - - - -### set_cookies() - -设置 cookies。 - -参数说明： - -- cookies: Union[RequestsCookieJar, list, tuple, str, dict] - cookies 信息，可为CookieJar, list, tuple, str, dict - -返回： None - - - -### get_cookies() - -返回 cookies。 - -参数说明： - -- as_dict: bool - 是否以 dict 方式返回，默认以 list 返回完整的 cookies -- all_domains: bool - 是否返回所有域名的 cookies，只有 s 模式下生效 - -返回：cookies 字典或列表 - - - -### change_mode() - -切换模式，'d' 或 's'。切换时会把当前模式的 cookies 复制到目标模式。 - -参数说明： - -- mode: str - 指定目标模式，'d' 或 's'。 -- go: bool - 切换模式后是否跳转到当前 url - -返回： None - - - -### ele() - -返回页面中符合条件的元素，默认返回第一个。 -​如查询参数是字符串，可选 '@属性名:'、'tag:'、'text:'、'css:'、'xpath:'、'.'、'#' 方式。无控制方式时默认用 text 方式查找。 -​如是loc，直接按照内容查询。 - -参数说明： - -- loc_or_str: [Tuple[str, str], str, DriverElement, SessionElement, WebElement] - 元素的定位信息，可以是元素对象，loc 元组，或查询字符串 -- mode: str - 'single' 或 'all‘，对应查找一个或全部 -- timeout: float - 查找元素超时时间，driver 模式下有效 - -示例： - -- 接收到元素对象时：返回元素对象对象 - -- 用loc元组查找： - - - ele.ele((By.CLASS_NAME, 'ele_class')) - 返回第一个class为 ele_class 的子元素 - -- 用查询字符串查找： - - 属性、tag name 和属性、文本、xpath、css selector、id、class。 - - @ 表示属性，. 表示 class，# 表示 id，= 表示精确匹配，: 表示模糊匹配，无控制字符串时默认搜索该字符串。 - - - page.ele('.ele_class') - 返回第一个 class 为 ele_class 的元素 - - page.ele('.:ele_class') - 返回第一个 class 中含有 ele_class 的元素 - - page.ele('#ele_id') - 返回第一个 id 为 ele_id 的元素 - - page.ele('#:ele_id') - 返回第一个 id 中含有 ele_id 的元素 - - page.ele('@class:ele_class') - 返回第一个 class 含有 ele_class 的元素 - - page.ele('@name=ele_name') - 返回第一个 name 等于 ele_name 的元素 - - page.ele('@placeholder') - 返回第一个带 placeholder 属性的元素 - - page.ele('tag:p') - 返回第一个 p 元素 - - page.ele('tag:div@class:ele_class') - 返回第一个 class 含有 ele_class 的 div 元素 - - page.ele('tag:div@class=ele_class') - 返回第一个 class 等于 ele_class 的 div 元素 - - page.ele('tag:div@text():some_text') - 返回第一个文本含有 some_text 的 div 元素 - - page.ele('tag:div@text()=some_text') - 返回第一个文本等于 some_text 的 div 元素 - - page.ele('text:some_text') - 返回第一个文本含有 some_text 的元素 - - page.ele('some_text') - 返回第一个文本含有 some_text 的元素（等价于上一行） - - page.ele('text=some_text') - 返回第一个文本等于 some_text 的元素 - - page.ele('xpath://div[@class="ele_class"]') - 返回第一个符合 xpath 的元素 - - page.ele('css:div.ele_class') - 返回第一个符合 css selector 的元素 - -返回： [DriverElement, SessionElement, str] - 元素对象或属性、文本节点文本 - - - -### eles() - -根据查询参数获取符合条件的元素列表。查询参数使用方法和 ele 方法一致。 - -参数说明： - -- loc_or_str: [Tuple[str, str], str] - 查询条件参数 -- timeout: float - 查找元素超时时间，driver 模式下有效 - -返回： [List[DriverElement or str], List[SessionElement or str]] - 元素对象或属性、文本节点文本组成的列表 - - - -### cookies_to_session() - -从 WebDriver 对象复制 cookies 到 Session 对象。 - -参数说明： - -- copy_user_agent: bool - 是否同时复制 user agent - -返回： None - - - -### cookies_to_driver() - -从 Session 对象复制 cookies 到 WebDriver 对象。 - -参数说明： - -- url: str - cookies 的域或 url - -返回： None - - - -### get() - -跳转到一个url，跳转前先同步 cookies，跳转后返回目标 url 是否可用。 - -参数说明： - -- url: str - 目标 url -- go_anyway: bool - 是否强制跳转。若目标 url 和当前 url 一致，默认不跳转。 -- show_errmsg: bool - 是否显示和抛出异常 -- retry: int - 连接出错时重试次数 -- interval: float - 重试间隔（秒） -- **kwargs - 用于 requests 的连接参数 - -返回： [bool, None] - url 是否可用 - - - -### post() - -以 post 方式跳转，调用时自动切换到 session 模式。 - -参数说明： - -- url: str - 目标 url -- data: dict - 提交的数据 -- go_anyway: bool - 是否强制跳转。若目标 url 和当前 url 一致，默认不跳转。 -- show_errmsg: bool - 是否显示和抛出异常 -- retry: int - 连接出错时重试次数 -- interval: float - 重试间隔（秒） -- **kwargs - 用于 requests 的连接参数 - -返回： [bool, None] - url 是否可用 - - - -### download() - -下载一个文件，返回是否成功和下载信息字符串。改方法会自动避免和目标路径现有文件重名。 - -参数说明： - -- file_url: str - 文件 url -- goal_path: str - 存放路径，默认为 ini 文件中指定的临时文件夹 -- rename: str - 重命名文件，不改变扩展名 -- file_exists: str - 若存在同名文件，可选择 'rename', 'overwrite', 'skip' 方式处理 -- post_data: dict - post 方式时提交的数据 -- show_msg: bool - 是否显示下载信息 -- show_errmsg: bool - 是否显示和抛出异常 -- **kwargs - 用于 requests 的连接参数 - -返回： Tuple[bool, str] - 下载是否成功（bool）和状态信息（成功时信息为文件路径）的元组 - - - -以下方法和属性只有 driver 模式下生效，调用时会自动切换到 driver 模式 - -*** - -### tabs_count - -返回标签页数量。 - -返回： int - - - -### tab_handles - -返回所有标签页 handle 列表。 - -返回： list - - - -### current_tab_num - -返回当前标签页序号。 - -返回： int - - - -### current_tab_handle - -返回当前标签页 handle。 - -返回： str - - - -### wait_ele() - -等待元素从 dom 删除、显示、隐藏。 - -参数说明： - -- loc_or_ele: [str, tuple, DriverElement, WebElement] - 元素查找方式，与ele()相同 -- mode: str - 等待方式，可选：'del', 'display', 'hidden' -- timeout: float - 等待超时时间 - -返回： bool - 等待是否成功 - - - -### check_page() - -d 模式时检查网页是否符合预期。默认由 response 状态检查，可重载实现针对性检查。 - -参数说明： - -- by_requests:bool - 强制使用内置 response 进行检查 - -返回： [bool, None] - bool 为是否可用，None 为未知 - - - -### run_script() - -执行JavaScript代码。 - -参数说明： - -- script: str - JavaScript 代码文本 -- *args - 传入的参数 - -返回： Any - - - -### create_tab() - -新建并定位到一个标签页,该标签页在最后面。 - -参数说明： - -- url: str - 新标签页跳转到的网址 - -返回： None - - - -### close_current_tab() - -关闭当前标签页。 - -返回： None - - - -### close_other_tabs() - -关闭传入的标签页以外标签页，默认保留当前页。可传入列表或元组。 - -参数说明： - -- num_or_handles:[int, str] - 要保留的标签页序号或 handle，可传入 handle 组成的列表或元组 - -返回： None - - - -### to_tab() - -跳转到标签页。 - -参数说明： - -- num_or_handle:[int, str] - 标签页序号或handle字符串，序号第一个为0，最后为-1 - -返回： None - - - -### to_iframe() - -跳转到 iframe，默认跳转到最高层级，兼容 selenium 原生参数。 - -参数说明： - -- loc_or_ele: [int, str, tuple, WebElement, DriverElement] - 查找 iframe 元素的条件，可接收 iframe 序号（0开始）、id 或 name、查询字符串、loc参数、WebElement对象、DriverElement 对象，传入 'main' 跳到最高层，传入 'parent' 跳到上一层 - -示例： -- to_iframe('tag:iframe') - 通过传入 iframe 的查询字符串定位 -- to_iframe('iframe_id') - 通过 iframe 的 id 属性定位 -- to_iframe('iframe_name') - 通过 iframe 的 name 属性定位 -- to_iframe(iframe_element) - 通过传入元素对象定位 -- to_iframe(0) - 通过 iframe 的序号定位 -- to_iframe('main') - 跳到最高层 -- to_iframe('parent') - 跳到上一层 - -返回： None - - - -### scroll_to_see() - -滚动直到元素可见。 - -参数说明： - -- loc_or_ele: [str, tuple, WebElement, DriverElement] - 查找元素的条件，和 ele() 方法的查找条件一致。 - -返回： None - - - -### scroll_to() - -滚动页面，按照参数决定如何滚动。 - -参数说明： - -- mode: str - 滚动的方向，top、bottom、rightmost、leftmost、up、down、left、right -- pixel: int - 滚动的像素 - -返回： None - - - -### refresh() - -刷新页面。 - -返回： None - - - -### back() - -页面后退。 - -返回： None - - - -### set_window_size() - -设置窗口大小，默认最大化。 - -参数说明： - -- x: int - 目标宽度 -- y: int - 目标高度 - -返回： None - - - -### screenshot() - -网页截图，返回截图文件路径。 - -参数说明： - -- path: str - 截图保存路径，默认为 ini 文件中指定的临时文件夹 -- filename: str - 截图文件名，默认为页面 title 为文件名 - -返回： str - - - -### chrome_downloading() - -返回浏览器下载中的文件列表。 - -参数说明： - -- download_path: str - 下载文件夹路径 - -返回：list - - - -### process_alert() - -处理提示框。 - -参数说明： - -- mode: str - 'ok' 或 'cancel'，若输入其它值，不会按按钮但依然返回文本值 -- text: str - 处理 prompt 提示框时可输入文本 - -返回： [str, None] - 提示框内容文本 - - - -### close_driver() - -关闭 driver 及浏览器。 - -返回： None - - - -### close_session() - -关闭 session。 - -返回： None +点击查看：[https://gitee.com/g1879/DrissionPage/wikis/MixPage%20%E7%B1%BB?sort_id=3195973](https://gitee.com/g1879/DrissionPage/wikis/MixPage%20%E7%B1%BB?sort_id=3195973) ## DriverElement 类 -### class DriverElement() - -driver 模式的元素对象，包装了一个 WebElement 对象，并封装了常用功能。 - -参数说明： - -- ele: WebElement - WebElement 对象 -- page: DriverPage - 元素所在的页面对象 -- timeout: float - 查找元素超时时间（每次查找元素时还可单独设置） - - - -### inner_ele - -被包装的 WebElement 对象。 - -返回： WebElement - - - -### html - -返回元素 outerHTML 文本。 - -返回： str - - - -### inner_html - -返回元素 innerHTML 文本。 - -返回： str - - - -### tag - -返回元素标签名。 - -返回： str - - - -### attrs - -以字典方式返回元素所有属性及值。 - -返回： dict - - - -### text - -返回元素内的文本。 - -返回： str - - - -### link - -返回元素 href 或 src 绝对 url。 - -返回： str - - - -### css_path - -返回元素 css selector 绝对路径。 - -返回： str - - - -### xpath - -返回元素 xpath 绝对路径。 - -返回： str - - - -### parent - -返回父级元素对象。 - -返回： DriverElement - - - -### next - -返回下一个兄弟元素对象。 - -返回： DriverElement - - - -### prev - -返回上一个兄弟元素对象。 - -返回： DriverElement - - - -### size - -以字典方式返回元素大小。 - -返回： dict - - - -### location - -以字典方式放回元素坐标。 - -返回： dict - - - -### shadow_root - -返回当前元素的 shadow_root 元素对象 - -返回： ShadowRoot - - - -### before - -返回当前元素的 ::before 伪元素内容 - -返回： str - - - -### after - -返回当前元素的 ::after 伪元素内容 - -返回： str - - - -### texts() - -返回元素内所有直接子节点的文本，包括元素和文本节点 - -参数说明： - -- text_node_only:bool - 是否只返回文本节点 - -返回： List[str] - - - -### parents() - -返回第 N 层父级元素对象。 - -参数说明： - -- num: int - 第几层父元素 - -返回： DriverElement - - - -### nexts() - -返回后面第 num 个兄弟元素或节点文本。 - -参数说明： - -- num: int - 后面第几个兄弟元素或节点 -- mode: str - 'ele', 'node' 或 'text'，匹配元素、节点、或文本节点 - -返回： [DriverElement, str] - - - -### prevs() - -返回前面第 num 个兄弟元素或节点文本。 - -参数说明： - -- num: int - 前面第几个兄弟元素或节点 -- mode: str - 'ele', 'node' 或 'text'，匹配元素、节点、或文本节点 - -返回： [DriverElement, str] - - - -### attr() - -获取元素某个属性的值。 - -参数说明： - -- attr: str - 属性名称 - -返回： str - - - -### ele() - -返回当前元素下级符合条件的子元素、属性或节点文本。 -如查询参数是字符串，可选 '@属性名:'、'tag:'、'text:'、'css:'、'xpath:'、'.'、'#' 方式。无控制方式时默认用 text 方式查找。 -如是loc，直接按照内容查询。 - -参数说明： - -- loc_or_str: [Tuple[str, str], str] - 元素的定位信息，可以是 loc 元组，或查询字符串 -- mode: str - 'single' 或 'all'，对应查找一个或全部 -- timeout: float - 查找元素超时时间 - -示例： - -- 用loc元组查找： - - - ele.ele((By.CLASS_NAME, 'ele_class')) - 返回第一个class为 ele_class 的子元素 - -- 用查询字符串查找： - - 属性、tag name和属性、文本、xpath、css selector、id、class。 - - @ 表示属性，. 表示 class，# 表示 id，= 表示精确匹配，: 表示模糊匹配，无控制字符串时默认搜索该字符串。 - - - ele.ele('.ele_class') - 返回第一个 class 为 ele_class 的子元素 - - ele.ele('.:ele_class') - 返回第一个 class 中含有 ele_class 的子元素 - - ele.ele('#ele_id') - 返回第一个 id 为 ele_id 的子元素 - - ele.ele('#:ele_id') - 返回第一个 id 中含有 ele_id 的子元素 - - ele.ele('@class:ele_class') - 返回第一个 class 含有e le_class 的子元素 - - ele.ele('@name=ele_name') - 返回第一个 name 等于 ele_name 的子元素 - - ele.ele('@placeholder') - 返回第一个带 placeholder 属性的子元素 - - ele.ele('tag:p') - 返回第一个 p 子元素 - - ele.ele('tag:div@class:ele_class') - 返回第一个 class 含有 ele_class 的 div 子元素 - - ele.ele('tag:div@class=ele_class') - 返回第一个 class 等于 ele_class 的 div 子元素 - - ele.ele('tag:div@text():some_text') - 返回第一个文本含有 some_text 的 div 子元素 - - ele.ele('tag:div@text()=some_text') - 返回第一个文本等于 some_tex t的 div 子元素 - - ele.ele('text:some_text') - 返回第一个文本含有 some_text 的子元素 - - ele.ele('some_text') - 返回第一个文本含有 some_text 的子元素（等价于上一行） - - ele.ele('text=some_text') - 返回第一个文本等于 some_text 的子元素 - - ele.ele('xpath://div[@class="ele_class"]') - 返回第一个符合 xpath 的子元素 - - ele.ele('css:div.ele_class') - 返回第一个符合 css selector 的子元素 - -返回： [DriverElement, str] - - - -### eles() - -根据查询参数获取符合条件的元素列表。查询参数使用方法和 ele 方法一致。 - -参数说明： - -- loc_or_str: [Tuple[str, str], str] - 查询条件参数 -- timeout: float - 查找元素超时时间 - -返回： List[DriverElement or str] - - - -### get_style_property() - -返回元素样式属性值。 - -参数说明： - -- style: str - 样式属性名称 -- pseudo_ele: str - 伪元素名称 - -返回： str - - - -### click() - -点击元素，如不成功则用 js 方式点击，可指定是否用 js 方式点击。 - -参数说明： - -- by_js: bool - 是否用js方式点击 - -返回： bool - - - -### input() - -输入文本，返回是否成功。 - -参数说明： - -- value: str - 文本值 -- clear: bool - 输入前是否清除文本框 - -返回： bool - - - -### run_script() - -执行 js 代码，传入自己为第一个参数。 - -参数说明： - -- script: str - JavaScript文本 -- *args - 传入的参数 - -返回： Any - - - -### submit() - -提交表单。 - -返回： None - - - -### clear() - -清空文本框。 - -返回： None - - - -### is_selected() - -元素是否被选中。 - -返回： bool - - - -### is_enabled() - -元素在页面中是否可用。 - -返回： bool - - - -### is_displayed() - -元素是否可见。 - -返回： bool - - - -### is_valid() - -元素是否还在 DOM 内。该方法用于判断页面跳转元素不能用的情况 - -返回： bool - - - -### screenshot() - -网页截图，返回截图文件路径。 - -参数说明： - -- path: str - 截图保存路径，默认为 ini 文件中指定的临时文件夹 -- filename: str - 截图文件名，默认为页面 title 为文件名 - -返回： str - - - -### select() - -在下拉列表中选择。 - -参数说明： - -- text: str - 选项文本 - -返回： bool - 是否成功 - - - -### set_attr() - -设置元素属性。 - -参数说明： - -- attr: str - 参数名 -- value: str - 参数值 - -返回： bool -是否成功 - - - -### remove_attr() - -删除元素属性。 - -参数说明： - -- attr: str - 参数名 - -返回： bool -是否成功 - - - -### drag() - -拖拽当前元素一段距离，返回是否拖拽成功。 - -参数说明： - -- x: int - 拖拽x方向距离 -- y: int - 拖拽y方向距离 -- speed: int - 拖拽速度 -- shake: bool - 是否随机抖动 - -返回： bool - - - -### drag_to() - -拖拽当前元素，目标为另一个元素或坐标元组，返回是否拖拽成功。 - -参数说明： - -- ele_or_loc[tuple, WebElement, DrissionElement] - 另一个元素或相对当前位置，坐标为元素中点坐标。 -- speed: int - 拖拽速度 -- shake: bool - 是否随机抖动 - -返回： bool - - - -### hover() - -在元素上悬停鼠标。 - -返回： None +点击查看：[https://gitee.com/g1879/DrissionPage/wikis/DriverElement%20%E7%B1%BB?sort_id=3195974](https://gitee.com/g1879/DrissionPage/wikis/DriverElement%20%E7%B1%BB?sort_id=3195974) ## SessionElement 类 -### class SessionElement() - -session 模式的元素对象，包装了一个Element对象，并封装了常用功能。 - -参数说明： - -- ele: HtmlElement - lxml 库的 HtmlElement 对象 -- page: SessionPage - 元素所在页面对象 - - - -### inner_ele - -被包装的 HTMLElement 对象。 - -返回： HtmlElement - - - -### html - -返回元素 outerHTML 文本。 - -返回： str - - - -### inner_html - -返回元素 innerHTML 文本。 - -返回： str - - - -### tag - -返回元素标签名。 - -返回： srt - - - -### attrs - -以字典格式返回元素所有属性的名称和值。 - -返回： dict - - - -### text - -返回元素内的文本，即 innerText。 - -返回： str - - - -### link - -返回元素 href 或 src 绝对 url。 - -返回： str - - - -### css_path - -返回元素 css selector 绝对路径。 - -返回： srt - - - -### xpath - -返回元素 xpath 绝对路径。 - -返回： srt - - - -### parent - -返回父级元素对象。 - -返回： SessionElement - - - -### next - -返回下一个兄弟元素对象。 - -返回： SessionElement - - - -### prev - -返回上一个兄弟元素对象。 - -返回： SessionElement - - - -### parents() - -返回第N层父级元素对象。 - -参数说明： - -- num:int - 第几层父元素 - -返回： SessionElement - - - -### nexts() - -返回后面第 num 个兄弟元素或节点文本。 - -参数说明： - -- num - 后面第几个兄弟元素 -- mode: str - 'ele', 'node' 或 'text'，匹配元素、节点、或文本节点 - -返回： [SessionElement, str] - - - -### prevs() - -返回前 N 个兄弟元素对象。 - -参数说明： - -- num - 前面第几个兄弟元素 -- mode: str - 'ele', 'node' 或 'text'，匹配元素、节点、或文本节点 - -返回： [SessionElement, str] - - - -### attr() - -获取元素某个属性的值。 - -参数说明： - -- attr: str - 属性名称 - -返回： str - - - -### ele() - -根据查询参数获取元素。 -如查询参数是字符串，可选 '@属性名:'、'tag:'、'text:'、'css:'、'xpath:'、'.'、'#' 方式。无控制方式时默认用 text 方式查找。 -如是loc，直接按照内容查询。 - -参数说明： - -- loc_or_str:[Tuple[str, str], str] - 查询条件参数 - -- mode: str - 查找一个或多个，传入 'single' 或 'all' - - -示例： - -- 用loc元组查找： - -- ele.ele((By.CLASS_NAME, 'ele_class')) - 返回第一个class为 ele_class 的子元素 - -- 用查询字符串查找： - -属性、tag name和属性、文本、xpath、css selector、id、class。 - -@ 表示属性，. 表示 class，# 表示 id，= 表示精确匹配，: 表示模糊匹配，无控制字符串时默认搜索该字符串。 - -- ele.ele('.ele_class') - 返回第一个 class 为 ele_class 的子元素 -- ele.ele('.:ele_class') - 返回第一个 class 中含有 ele_class 的子元素 -- ele.ele('#ele_id') - 返回第一个 id 为 ele_id 的子元素 -- ele.ele('#:ele_id') - 返回第一个 id 中含有 ele_id 的子元素 -- ele.ele('@class:ele_class') - 返回第一个 class 含有e le_class 的子元素 -- ele.ele('@name=ele_name') - 返回第一个 name 等于 ele_name 的子元素 -- ele.ele('@placeholder') - 返回第一个带 placeholder 属性的子元素 -- ele.ele('tag:p') - 返回第一个 p 子元素 -- ele.ele('tag:div@class:ele_class') - 返回第一个 class 含有 ele_class 的 div 子元素 -- ele.ele('tag:div@class=ele_class') - 返回第一个 class 等于 ele_class 的 div 子元素 -- ele.ele('tag:div@text():some_text') - 返回第一个文本含有 some_text 的 div 子元素 -- ele.ele('tag:div@text()=some_text') - 返回第一个文本等于 some_tex t的 div 子元素 -- ele.ele('text:some_text') - 返回第一个文本含有 some_text 的子元素 -- ele.ele('some_text') - 返回第一个文本含有 some_text 的子元素（等价于上一行） -- ele.ele('text=some_text') - 返回第一个文本等于 some_text 的子元素 -- ele.ele('xpath://div[@class="ele_class"]') - 返回第一个符合 xpath 的子元素 -- ele.ele('css:div.ele_class') - 返回第一个符合 css selector 的子元素 - -返回： [SessionElement, str] - - - -### eles() - -根据查询参数获取符合条件的元素列表。查询参数使用方法和ele方法一致。 - -参数说明： - -- loc_or_str: [Tuple[str, str], str] - 查询条件参数 - -返回： List[SessionElement or str] +点击查看：[https://gitee.com/g1879/DrissionPage/wikis/SessionElement%20%E7%B1%BB?sort_id=3195975](https://gitee.com/g1879/DrissionPage/wikis/SessionElement%20%E7%B1%BB?sort_id=3195975) ## ShadowRootElement 类 -### class ShadowRootElement() - -元素内 shadow-root 元素。 - -参数说明： - -- inner_ele: WebElement - selenium 获取到的 shadow-root 元素 -- parent_ele: DriverElement - shadow-root 所依附的元素 -- timeout: float - 超时时间 - - - -### tag - -元素标签名。 - -返回：'shadow-root' 字符串。 - - - -### html - -内部html文本。 - -返回：str - - - -### parent - -shadow-root 所依赖的父元素。 - -返回：DriverElement - - - -### next - -返回后一个兄弟元素。 - -返回：DriverElement - - - -### parents() - -返回上面第 num 级父元素 - -参数说明： - -- num: int - 第几层父元素 - -返回：DriverElement - - - -### nexts() - -返回后面第 num 个兄弟元素 - -参数说明： - -- num: int - 第几个兄弟元素 - -返回：DriverElement - - - -### ele() - -返回第一个符合条件的子元素。 - -参数说明： - -- loc_or_str: Union[Tuple[str, str], str] - 元素定位条件 -- mode: str - 'single' 或 'all'，对应获取一个和全部 -- timeout: float - 超时时间 - -返回：DriverElement - 第一个符合条件的元素 - - - -### eles() - -返回所有符合条件的子元素。 - -参数说明： - -- loc_or_str: Union[Tuple[str, str], str] - 元素定位条件 -- timeout: float - 超时时间 - -返回：List[DriverElement] - 所有符合条件的元素组成的列表 - - - -### run_script() - -对元素执行 js 代码。 - -参数说明： - -- scrpit: str - js 代码 -- *args - 传入的对象 - - - -### is_enabled() - -返回元素是否可用。 - -返回：bool - - - -### is_valid() - -返回元素是否仍在 dom 内。 - -返回：bool +点击查看：[https://gitee.com/g1879/DrissionPage/wikis/ShadowRootElement%20%E7%B1%BB?sort_id=3195976](https://gitee.com/g1879/DrissionPage/wikis/ShadowRootElement%20%E7%B1%BB?sort_id=3195976) ## OptionsManager 类 -### class OptionsManager() - -管理配置文件内容的类。 - -参数说明： - -- path: str - ini文件路径，不传入则默认读取当前文件夹下的 configs.ini 文件 - - - -### paths - -返回 paths 设置信息。 - -返回： dict - - - -### chrome_options - -返回 chrome 设置信息。 - -返回： dict - - - -### session_options - -返回 session 设置信息。 - -返回： dict - - - -### get_value() - -获取配置的值。 - -参数说明： - -- section: str - 段落名称 -- item: str - 配置项名称 - -返回： Any - - - -### get_option() - -以字典的格式返回整个段落的配置信息。 - -参数说明： - -- section: str - 段落名称 - -返回： dict - - - -### set_item() - -设置配置值，返回自己，用于链式操作。 - -参数说明： - -- section: str - 段落名称 -- item: str - 配置项名称 -- value: Any - 值内容 - -返回： OptionsManager - 返回自己 - - - -### save() - -保存设置到文件，返回自己，用于链式操作。 - -参数说明： - -- path: str - ini 文件的路径，传入 'default' 保存到默认ini文件 - -返回： OptionsManager - 返回自己 +点击查看：[https://gitee.com/g1879/DrissionPage/wikis/OptionsManager%20%E7%B1%BB?sort_id=3195977](https://gitee.com/g1879/DrissionPage/wikis/OptionsManager%20%E7%B1%BB?sort_id=3195977) ## SessionOptions 类 -### class SessionOptions() - -Session 对象配置类。 - -参数说明： - -- read_file: bool - 创建时是否从 ini 文件读取配置信息 -- ini_path: str - ini 文件路径，为None则读取默认 ini 文件 - - - -### headers - -headers 配置信息。 - -返回： dict - - - -### cookies - -cookies 配置信息。 - -返回： list - - - -### auth - -auth 配置信息。 - -返回： tuple - - - -### proxies - -proxies 配置信息。 - -返回： dict - - - -### hooks - -hooks 配置信息。 - -返回： dict - - - -### params - -params 配置信息。 - -返回： dict - - - -### verify - -verify 配置信息。 - -返回： bool - - - -### cert - -cert 配置信息。 - -返回： [str, tuple] - - - -### adapters - -adapters 配置信息。 - -返回： adapters - - - -### stream - -stream 配置信息。 - -返回： bool - - - -### trust_env - -srust_env 配置信息。 - -返回： bool - - - -### max_redirects - -max_redirect 配置信息。 - -返回： int - - - -### set_a_header() - -设置 headers 中一个项。 - -参数说明： - -- attr: str - 配置项名称 -- value: str - 配置的值 - -返回： 当前对象 - - - -### remove_a_header() - -从 headers 中删除一个设置。 - -参数说明： - -- attr: str - 要删除的配置名称 - -返回：当前对象 - - - -### save() - -保存设置到文件。 - -参数说明： - -- path: str - ini文件的路径，传入 'default' 保存到默认ini文件 - -返回：当前对象 - - - -### as_dict() - -以字典形式返回当前对象。 - -返回： dict +点击查看：[https://gitee.com/g1879/DrissionPage/wikis/SessionOptions%20%E7%B1%BB?sort_id=3195978](https://gitee.com/g1879/DrissionPage/wikis/SessionOptions%20%E7%B1%BB?sort_id=3195978) ## DriverOptions 类 -### class DriverOptions() - -chrome 浏览器配置类，继承自 selenium.webdriver.chrome.options 的 Options 类，增加了删除配置和保存到文件方法。 - -参数说明： - -- read_file: bool - 创建时是否从 ini 文件读取配置信息 -- ini_path: str - ini 文件路径，为None则读取默认 ini 文件 - - - -### driver_path - -chromedriver.exe 的路径。 - -返回： str - - - -### chrome_path - -chrome.exe 的路径 - -返回： str - - - -### save() - -保存设置到文件，返回自己，用于链式操作。 - -参数说明： - -- path: str - ini 文件的路径，传入 'default' 保存到默认ini文件 - -返回： DriverOptions - 返回自己 - - - -### remove_argument() - -移除一个设置。 - -参数说明： - -- value: str - 要移除的属性值 - -返回： DriverOptions - 返回自己 - - - -### remove_experimental_option() - -移除一个实验设置，传入 key 值删除。 - -参数说明： - -- key: str - 要移除的实验设置 key 值 - -返回： DriverOptions - 返回自己 - - - -### remove_all_extensions() - -移除所有插件，因插件是以整个文件储存，难以移除其中一个，故如须设置则全部移除再重设。 - -返回： DriverOptions - 返回自己 - - - -### set_argument() - -设置 chrome 属性，无值的属性可设置开关，有值的属性可设置属性的值。 - -参数说明： - -- arg: str - 属性名 -- value[bool, str] - 属性值，有值的属性传入值，没有的传入 bool - -返回： DriverOptions - 返回自己 - - - -### set_headless() - -打开或关闭无界面模式。 - -参数说明： - -on_off: bool - 打开或关闭 - -返回： DriverOptions - 返回自己 - - - -### set_no_imgs() - -是否加载图片。 - -参数说明： - -on_off: bool - 打开或关闭 - -返回： DriverOptions - 返回自己 - - - -### set_no_js() - -是否禁用 js。 - -参数说明： - -on_off: bool - 打开或关闭 - -返回： DriverOptions - 返回自己 - - - -### set_mute() - -是否静音。 - -参数说明： - -on_off: bool - 打开或关闭 - -返回： DriverOptions - 返回自己 - - - -### set_user_agent() - -设置浏览器 user agent。 - -参数说明： - -- user_agent: str - user agent 字符串 - -返回： DriverOptions - 返回自己 - - - -### set_proxy() - -设置代理。 - -参数说明： - -- proxy: str - 代理地址 - -返回： DriverOptions - 返回自己 - - - -### set_paths() - -设置浏览器相关的路径。 - -参数说明： - -- driver_path: str - chromedriver.exe 的路径 -- chrome_path: str - chrome.exe 的路径 -- debugger_address: str - 调试浏览器地址，例：127.0.0.1:9222 -- download_path: str - 下载文件路径 -- user_data_path: str - 用户数据路径 -- cache_path: str - 缓存路径 - -返回： DriverOptions - 返回自己 +点击查看：[https://gitee.com/g1879/DrissionPage/wikis/DriverOptions%20%E7%B1%BB?sort_id=3195979](https://gitee.com/g1879/DrissionPage/wikis/DriverOptions%20%E7%B1%BB?sort_id=3195979) ## easy_set 方法 -chrome 配置太复杂，所以把常用的配置写成简单的方法，调用会修改 ini 文件相关内容。 - -### get_match_driver() - -自动识别 chrome 版本并下载匹配的driver。获取 ini 文件记录的 chrome.exe 路径，若没有则获取系统变量中的。 - -参数说明： - -- ini_path: str - 要读取和修改的 ini 文件路径 -- save_path: str - chromedriver 保存路径 - -返回： None - - - -### show_settings() - -打印 ini 文件中所有配置信息。 - -参数说明： - -- ini_path: str - ini 文件路径，为 None 则读取默认 ini 文件 - -返回： None - - - -### set_paths() - -便捷的设置路径方法，把传入的路径保存到 ini 文件，并检查 chrome 和 chromedriver 版本是否匹配。 - -参数说明： - -- driver_path: str - chromedriver.exe 路径 -- chrome_path: str - chrome.exe 路径 -- debugger_address: str - 调试浏览器地址，例：127.0.0.1:9222 -- download_path: str - 下载文件路径 -- tmp_path: str - 临时文件夹路径 -- user_data_path: str - 用户数据路径 -- cache_path: str - 缓存路径 -- ini_path: str - ini 文件路径，为 None 则保存到默认 ini 文件 -- check_version: bool - 是否检查 chromedriver 和 chrome 是否匹配 - -返回： None - - - -### set_argument() - -设置属性。若属性无值（如 'zh_CN.UTF-8' ），value 传入 bool 表示开关；否则把 value 赋值给属性，当 value 为 '' 或 False，删除该属性项。 - -参数说明： - -- arg: str - 属性名 -- value: [bool, str] - 属性值，有值的属性传入值，没有的传入 bool -- ini_path: str - ini 文件路径，为 None 则保存到默认 ini 文件 - -返回： None - - - -### set_headless() - -开启或关闭 headless 模式。 - -参数说明： - -- on_off: bool - 是否开启 headless 模式 -- ini_path: str - ini 文件路径，为 None 则保存到默认 ini 文件 - -返回： None - - - -### set_no_imgs() - -开启或关闭图片显示。 - -参数说明： - -- on_off: bool - 是否开启无图模式 -- ini_path: str - ini 文件路径，为 None 则保存到默认 ini 文件 - -返回： None - - - -### set_no_js() - -开启或关闭禁用 JS 模式。 - -参数说明： - -- on_off: bool - 是否开启禁用 JS 模式 -- ini_path: str - ini 文件路径，为 None 则保存到默认 ini 文件 - -返回： None - - - -### set_mute() - -开启或关闭静音模式。 - -参数说明： - -- on_off: bool - 是否开启静音模式 -- ini_path: str - ini 文件路径，为 None 则保存到默认 ini 文件 - -返回： None - - - -### set_user_agent() - -设置 user_agent。 - -参数说明： - -- user_agent: str - user_agent 值 -- ini_path: str - ini 文件路径，为 None 则保存到默认 ini 文件 - -返回： None - - - -### set_proxy() - -设置代理。 - -参数说明： - -- proxy: str - 代理值 -- ini_path: str - ini 文件路径，为 None 则保存到默认 ini 文件 - -返回： None - - - -### check_driver_version() - -检查 chrome 与 chromedriver 版本是否匹配。 - -参数说明： - -- driver_path: bool - chromedriver.exe 路径 -- chrome_path: bool - chrome.exe 路径 - -返回： bool \ No newline at end of file +点击查看：[https://gitee.com/g1879/DrissionPage/wikis/easy_set%20%E6%96%B9%E6%B3%95?sort_id=3195980](https://gitee.com/g1879/DrissionPage/wikis/easy_set%20%E6%96%B9%E6%B3%95?sort_id=3195980) \ No newline at end of file From 463633d553946c02d87ac90958d0970ea16463f1 Mon Sep 17 00:00:00 2001 From: g1879 Date: Mon, 7 Dec 2020 09:31:20 +0800 Subject: [PATCH 3/5] 1.7.0 --- README.zh-cn.md | 119 +++++++++++++++++------------------------------- 1 file changed, 43 insertions(+), 76 deletions(-) diff --git a/README.zh-cn.md b/README.zh-cn.md index 7e225fb..fbf2d2f 100644 --- a/README.zh-cn.md +++ b/README.zh-cn.md @@ -2,8 +2,6 @@ *** -## 项目介绍 - DrissionPage，即 driver 和 session 组合而成的 page。 是个基于 python 的 Web 自动化操作集成工具。 它实现了 selenium 和 requests 之间的无缝切换。 @@ -23,15 +21,11 @@ DrissionPage，即 driver 和 session 组合而成的 page。 **交流QQ群：** 897838127 - - -## 理念 +**理念** **简洁、易用 、可扩展** - - -## 背景 +**背景** requests 爬虫面对要登录的网站时，要分析数据包、JS 源码，构造复杂的请求，往往还要应付验证码、JS 混淆、签名参数等反爬手段，门槛较高。若数据是由 JS 计算生成的，还须重现计算过程，体验不好，开发效率不高。 使用 selenium，可以很大程度上绕过这些坑，但 selenium 效率不高。因此，这个库将 selenium 和 requests 合而为一，不同须要时切换相应模式，并提供一种人性化的使用方法，提高开发和运行效率。 @@ -80,7 +74,7 @@ session 模式下的页面元素类，可获取元素属性值，也可在其下 *** -## 与 selenium 代码对比 +**与 selenium 代码对比** 以下代码实现一模一样的功能，对比两者的代码量： @@ -194,9 +188,7 @@ class_name = element('xpath://div[@id="div_id"]/@class') text = element('xpath://div[@id="div_id"]/text()[2]') ``` - - -## 与 requests 代码对比 +**与 requests 代码对比** 以下代码实现一模一样的功能，对比两者的代码量： @@ -239,9 +231,7 @@ with open(f'{save_path}\\img.png', 'wb') as fd: page.download(url, save_path, 'img') # 支持重命名，处理文件名冲突 ``` - - -## 模式切换 +**模式切换** 用 selenium 登录网站，然后切换到 requests 读取网页。两者会共享登录信息。 @@ -263,9 +253,7 @@ print('登录后title：', page.title, '\n') # 登录后 session 模式的输 登录后title： 个人资料 - 码云 Gitee.com ``` - - -## 获取并打印元素属性 +**获取并打印元素属性** ```python # 接上段代码 @@ -290,9 +278,7 @@ Git 命令学习 https://oschina.gitee.io/learn-git-branching/ Git 命令学习 ``` - - -## 下载文件 +**下载文件** ```python url = 'https://www.baidu.com/img/flexible/logo/pc/result.png' @@ -304,7 +290,9 @@ page.download(url, save_path) *** -## 安装 +## 安装及导入 + +**安装** ``` pip install DrissionPage @@ -314,7 +302,7 @@ pip install DrissionPage 若要使用 driver 模式，须配置 chrome 和 **对应版本** 的 chromedriver。[[chromedriver下载]](http://npm.taobao.org/mirrors/chromedriver) easy_set 工具中的 get_match_driver() 方法可自动识别 chrome 版本并下载匹配的 driver 。 -## 导入模块 +**导入模块** ```python from DrissionPage import MixPage @@ -334,7 +322,7 @@ from DrissionPage import MixPage - 将两个路径写入系统变量 - 在代码中填写路径 -### 使用 get_match_driver() 方法 +**使用 get_match_driver() 方法** 若你选择第一种方式，请在第一次使用前，运行以下代码，程序会自动检测电脑安装的 chrome 版本，下载对应 driver，并记录到 ini 文件。 @@ -370,9 +358,7 @@ get_match_driver(ini_path='ini文件路径', save_path='保存路径', chrome_pa Tips：当指定 chrome_path 时，检测成功后程序会把这个路径写进 ini 文件。 - - -### 使用 set_paths() 方法 +**使用 set_paths() 方法** 若上一种方法失败，可自行下载 chromedriver.exe，然后运行以下代码，把路径记录到 ini 文件中。 @@ -418,15 +404,11 @@ Tips： - 推荐使用绿色版 chrome，并手动设置路径，避免浏览器升级造成与 chromedriver 版本不匹配。 - 调试项目时推荐设置 debugger_address，使用手动打开的浏览器，再用程序接管，好处多多。 - - -### 其它方法 +**其它方法** 若你不想使用 ini 文件（如要打包项目时），可在系统路径写入以上两个路径，或在程序中填写。后者的使用方法见下一节。 - - -## 创建驱动器对象 Drission +## Drission 对象 > 创建的步骤不是必须，若想快速上手，可跳过本节。MixPage 会自动创建该对象。 @@ -468,16 +450,14 @@ drission = Drission(driver_options, session_options, proxy=proxy) DriverOptions 和 SessionOptions 用法详见下文。 - - -## 使用页面对象 MixPage +## MixPage 对象 MixPage 页面对象封装了常用的网页操作，并实现 driver 和 session 模式之间的切换。 MixPage 须控制一个 Drission 对象并使用其中的 driver 或 session，如没有传入，MixPage 会自己创建一个（使用传入的配置信息或从默认 ini 文件读取）。 Tips: 多对象协同工作时，可将一个 MixPage 中的 Drission 对象传递给另一个，使多个对象共享登录信息或操作同一个页面。 -### 创建对象 +**创建对象** 创建对象方式有3种：简易、传入 Drission 对象、传入配置。可根据实际需要选择。 @@ -494,9 +474,7 @@ page = MixPage(drission, mode='s', timeout=5) # session 模式，等待时间5 page = MixPage(driver_options=do, session_options=so) # 默认 d 模式 ``` - - -### 访问网页 +**访问网页** ```python # 默认方式 @@ -509,9 +487,7 @@ page.get(url, retry=5, interval=0.5) Tips：若连接出错，程序会自动重试2次，可指定重试次数和等待间隔。 - - -### 切换模式 +**切换模式** 在 s 和 d 模式之间切换，切换时会自动同步 cookies 和正在访问的 url。 @@ -521,9 +497,7 @@ page.change_mode(go=False) # go 为 False 表示不跳转 url Tips：使用某种模式独有的方法时会自动跳转到该模式。 - - -### 页面属性 +**页面属性** ```python page.url # 当前访问的 url @@ -542,9 +516,7 @@ page.current_tab_num # 返回当前标签页序号 page.current_tab_handle # 返回当前标签页 handle ``` - - -### 页面操作 +**页面操作** 调用只属于 d 模式的方法，会自动切换到 d 模式。详细用法见 APIs。 @@ -583,7 +555,7 @@ page.chrome_downloading() # 获取 chrome 正在下载的文件列表 page.process_alert(mode, text) # 处理提示框 ``` -### cookies 的使用 +**cookies 的使用** MixPage 支持获取和设置 cookies，具体使用方法如下： @@ -599,6 +571,8 @@ Tips: - d 模式设置 cookies 后要刷新页面才能看到效果。 - s 模式可在 ini 文件、SessionOptions、配置字典中设置 cookies，在 MixPage 初始化时即可传入，d 模式只能用 set_cookies() 函数设置。 + + ## 查找元素 ele() 返回第一个符合条件的元素，eles() 返回所有符合条件的元素列表。 @@ -766,11 +740,14 @@ shadow_root_element.is_valid() # 返回元素是否还在 dom 内 **Tips:** 以上属性或方法获取到的元素是普通的 DriverElement，用法参考上文所述。 + + ## 对接 selenium 及 requests -DrissionPage 代码可与 selenium 及 requests 代码无缝拼接。既可直接使用 selenium 的 WebDriver 对象，也可导出自身的 WebDriver 给 selenium 代码使用。requests 的 Session 对象也可直接传递。使已有项目的迁移非常方便。 +DrissionPage 代码可与 selenium 及 requests 代码无缝拼接。既可直接使用 selenium 的 WebDriver 对象，也可导出自身的 WebDriver 给 selenium 代码使用。requests 的 +Session 对象也可直接传递。使已有项目的迁移非常方便。 -### selenium 转 DrissionPage +**selenium 转 DrissionPage** ```python driver = webdriver.Chrome() @@ -780,7 +757,7 @@ page = MixPage(Drission(driver)) # 把 driver 传递给 Drission，创建 MixPa print(page.title) # 打印结果：百度一下，你就知道 ``` -### DrissionPage 转 selenium +**DrissionPage 转 selenium** ```python page = MixPage() @@ -791,7 +768,7 @@ print(driver.title) # 打印结果：百度一下，你就知道 element = driver.find_element_by_xpath('//div') # 使用 selenium 原生功能 ``` -### requests 转 DrissionPage +**requests 转 DrissionPage** ``` python session = requets.Session() @@ -801,7 +778,7 @@ page = MixPage(drission, mode='s') page.get('https://www.baidu.com') ``` -### DrissionPage 转 requests +**DrissionPage 转 requests** ```python page = MixPage('s') @@ -814,7 +791,7 @@ response = session.get('https://www.baidu.com') ## requests 功能使用 -### 连接参数 +**连接参数** 除了在创建时传入配置信息及连接参数，如有必要，s 模式下也可在每次访问网址时设置连接参数。 @@ -830,9 +807,7 @@ Tips： - 如果连接参数内没有指定，s 模式会根据当前域名自动填写 Host 和 Referer 属性 - 在创建 MixPage 时传入的 Session 配置是全局有效的 - - -### Response 对象 +**Response 对象** requests 获取到的 Response 对象存放在 page.response，可直接使用。如： @@ -850,7 +825,7 @@ selenium 缺乏对浏览器下载文件的有效管理，难以进行检测下 因此 DrissionPage 封装了 download 方法，整合了两者优点，可从 selenium 获取登录信息，用 requests 进行下载。 弥补了 selenium 的不足，使下载简洁高效。 -### 功能 +**功能** - 指定下载路径 - 重命名文件，可不填写扩展名，程序自动补充 @@ -859,7 +834,7 @@ selenium 缺乏对浏览器下载文件的有效管理，难以进行检测下 - 支持 post 方式 - 支持自定义连接参数 -### 演示 +**演示** ```python url = 'https://www.baidu.com/img/flexible/logo/pc/result.png' # 文件 url @@ -876,7 +851,7 @@ page.download(url, save_path, 'img', 'rename', show_msg=True) chrome 的配置很繁琐，为简化使用，本库提供了常用配置的设置方法。 -### DriverOptions 对象 +**DriverOptions 对象** DriverOptions 对象继承自 selenium.webdriver.chrome.options 的 Options 对象，在其基础上增加了以下方法： @@ -897,9 +872,7 @@ options.set_proxy(proxy) # 设置代理地址 options.set_paths(driver_path, chrome_path, debugger_address, download_path, user_data_path, cache_path) # 设置浏览器相关的路径 ``` - - -### 使用方法 +**使用方法** ```python do = DriverOptions() # 读取默认 ini 文件创建 DriverOptions 对象 @@ -923,7 +896,7 @@ do.save('default') # 保存当前设置到默认 ini 文件 ## Session 设置 -### SessionOPtions 对象 +**SessionOPtions 对象** SessionOptions 对象用于管理 Session 的配置信息。它创建时默认读取默认 ini 文件配置信息，也可手动设置所需信息。 @@ -933,9 +906,7 @@ headers、cookies、auth、proxies、hooks、params、verify、cert、adapters **Tips:** cookies 可接收 dict、list、tuple、str、RequestsCookieJar 等格式的信息。 - - -### 使用方法 +**使用方法** ```python so = SessionOptions() # 读取默认 ini 文件创建 SessionOptions 对象 @@ -964,7 +935,7 @@ so.save('default') # 保存当前设置到默认 ini 文件 Tips：建议把常用配置文件保存到别的路径，以防本库升级时配置被重置。 -### ini 文件内容 +**ini 文件内容** ini 文件默认拥有三部分配置：paths、chrome_options、session_options，初始内容如下。 @@ -1019,9 +990,7 @@ headers = { } ``` - - -### OptionsManager 对象 +**OptionsManager 对象** OptionsManager 对象用于读取、设置和保存配置。 @@ -1037,9 +1006,7 @@ manager.save('D:\\settings.ini') # 保存到指定路径 ini 文件 manager.save('default') # 保存当前设置到默认 ini 文件 ``` - - -### 使用示例 +**使用示例** ```python from DrissionPage.configs import * From fb8e666b922daf4d1c770610fb528b8773a6f9b1 Mon Sep 17 00:00:00 2001 From: g1879 Date: Mon, 7 Dec 2020 09:35:02 +0800 Subject: [PATCH 4/5] 1.7.0 --- README.zh-cn.md | 51 +++---------------------------------------------- 1 file changed, 3 insertions(+), 48 deletions(-) diff --git a/README.zh-cn.md b/README.zh-cn.md index fbf2d2f..d11b4ae 100644 --- a/README.zh-cn.md +++ b/README.zh-cn.md @@ -1140,52 +1140,7 @@ print(page.ele('@id:su').text) # 输出：百度一下 *** -## Drission 类 +请在 Wiki中查看：[[Drission 类 - Wiki - Gitee.com](https://gitee.com/g1879/DrissionPage/wikis/Drission +类?sort_id=3159323)]([Drission 类 - Wiki - Gitee.com](https://gitee.com/g1879/DrissionPage/wikis/Drission +类?sort_id=3159323)) -点击查看：[https://gitee.com/g1879/DrissionPage/wikis/Drission%20%E7%B1%BB?sort_id=3159323](https://gitee.com/g1879/DrissionPage/wikis/Drission%20%E7%B1%BB?sort_id=3159323) - -## MixPage 类 - -点击查看：[https://gitee.com/g1879/DrissionPage/wikis/MixPage%20%E7%B1%BB?sort_id=3195973](https://gitee.com/g1879/DrissionPage/wikis/MixPage%20%E7%B1%BB?sort_id=3195973) - - - -## DriverElement 类 - -点击查看：[https://gitee.com/g1879/DrissionPage/wikis/DriverElement%20%E7%B1%BB?sort_id=3195974](https://gitee.com/g1879/DrissionPage/wikis/DriverElement%20%E7%B1%BB?sort_id=3195974) - - - -## SessionElement 类 - -点击查看：[https://gitee.com/g1879/DrissionPage/wikis/SessionElement%20%E7%B1%BB?sort_id=3195975](https://gitee.com/g1879/DrissionPage/wikis/SessionElement%20%E7%B1%BB?sort_id=3195975) - - - -## ShadowRootElement 类 - -点击查看：[https://gitee.com/g1879/DrissionPage/wikis/ShadowRootElement%20%E7%B1%BB?sort_id=3195976](https://gitee.com/g1879/DrissionPage/wikis/ShadowRootElement%20%E7%B1%BB?sort_id=3195976) - - - -## OptionsManager 类 - -点击查看：[https://gitee.com/g1879/DrissionPage/wikis/OptionsManager%20%E7%B1%BB?sort_id=3195977](https://gitee.com/g1879/DrissionPage/wikis/OptionsManager%20%E7%B1%BB?sort_id=3195977) - - - -## SessionOptions 类 - -点击查看：[https://gitee.com/g1879/DrissionPage/wikis/SessionOptions%20%E7%B1%BB?sort_id=3195978](https://gitee.com/g1879/DrissionPage/wikis/SessionOptions%20%E7%B1%BB?sort_id=3195978) - - - -## DriverOptions 类 - -点击查看：[https://gitee.com/g1879/DrissionPage/wikis/DriverOptions%20%E7%B1%BB?sort_id=3195979](https://gitee.com/g1879/DrissionPage/wikis/DriverOptions%20%E7%B1%BB?sort_id=3195979) - - - -## easy_set 方法 - -点击查看：[https://gitee.com/g1879/DrissionPage/wikis/easy_set%20%E6%96%B9%E6%B3%95?sort_id=3195980](https://gitee.com/g1879/DrissionPage/wikis/easy_set%20%E6%96%B9%E6%B3%95?sort_id=3195980) \ No newline at end of file From 79859193651ad4fe0769250efac58ecb215c67a4 Mon Sep 17 00:00:00 2001 From: g1879 Date: Mon, 7 Dec 2020 13:58:25 +0800 Subject: [PATCH 5/5] =?UTF-8?q?=E5=88=9B=E5=BB=BAdriver=E6=97=B6=EF=BC=8C?= =?UTF-8?q?=E5=A6=82=E6=8C=87=E5=AE=9A=E4=BA=86=E6=9C=AC=E5=9C=B0=E8=B0=83?= =?UTF-8?q?=E8=AF=95=E6=B5=8F=E8=A7=88=E5=99=A8=EF=BC=8C=E5=8F=AF=E8=87=AA?= =?UTF-8?q?=E5=8A=A8=E6=8E=A5=E5=85=A5=E6=88=96=E5=88=9B=E5=BB=BA=E6=B5=8F?= =?UTF-8?q?=E8=A7=88=E5=99=A8=E8=BF=9B=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DrissionPage/drission.py | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/DrissionPage/drission.py b/DrissionPage/drission.py index 8be5cc6..e305a54 100644 --- a/DrissionPage/drission.py +++ b/DrissionPage/drission.py @@ -79,7 +79,9 @@ class Drission(object): @property def driver(self) -> WebDriver: - """返回WebDriver对象，如未初始化则按配置信息创建""" + """返回WebDriver对象，如未初始化则按配置信息创建。 \n + 如设置了本地调试浏览器，可自动接入或打开浏览器进程。 + """ if self._driver is None: if isinstance(self._driver_options, dict): options = _dict_to_chrome_options(self._driver_options) @@ -92,7 +94,14 @@ class Drission(object): driver_path = self._driver_options.get('driver_path', None) or 'chromedriver' try: + if options.debugger_address and _check_port(options.debugger_address) is False: + from subprocess import Popen + port = options.debugger_address.split(':')[-1] + chrome_path = self._driver_options.get('binary_location', None) or 'chrome.exe' + Popen(f'{chrome_path} --remote-debugging-port={port}', shell=False) + self._driver = webdriver.Chrome(driver_path, options=options) + except SessionNotCreatedException: print('Chrome版本与chromedriver版本不匹配，可执行easy_set.get_match_driver()自动下载匹配的版本。') exit(0) @@ -279,3 +288,25 @@ class Drission(object): self.close() except ImportError: pass + + +def _check_port(debugger_address: str) -> Union[bool, None]: + """检查端口是否可用 \n + :param debugger_address: 浏览器地址及端口 + :return: bool + """ + import socket + + ip, port = debugger_address.split(':') + + if ip not in ('127.0.0.1', 'localhost'): + return + + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + + try: + s.connect((ip, int(port))) + s.shutdown(2) + return True + except socket.error: + return False