From 463633d553946c02d87ac90958d0970ea16463f1 Mon Sep 17 00:00:00 2001 From: g1879 Date: Mon, 7 Dec 2020 09:31:20 +0800 Subject: [PATCH] 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 *