From d975e5c8125afd8b59ea45ead1ecae60d9973a6d Mon Sep 17 00:00:00 2001 From: g1879 Date: Mon, 17 Jan 2022 23:55:54 +0800 Subject: [PATCH] 2.4.0 --- README.md | 52 ++++++++++++----------- docs/README.md | 32 +++++++------- docs/_sidebar.md | 7 +++- docs/index.html | 7 +++- docs/使用方法/获取网页信息.md | 32 +++++++------- docs/使用方法/访问网页.md | 18 ++++---- docs/入门指南/基本概念.md | 20 ++++----- docs/入门指南/快速上手.md | 6 +++ docs/实用示例/下载星巴克产品图片.md | 65 +++++++++++++++++++++++++++++ docs/实用示例/同时操作多个浏览器.md | 27 ++++++++++++ docs/版本历史.md | 6 +++ docs/简介.md | 64 ---------------------------- setup.py | 2 +- 13 files changed, 194 insertions(+), 144 deletions(-) create mode 100644 docs/实用示例/下载星巴克产品图片.md create mode 100644 docs/实用示例/同时操作多个浏览器.md delete mode 100644 docs/简介.md diff --git a/README.md b/README.md index 9dce982..2bfb809 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# 简洁！易用 ！方便！ +# ✨️简洁！易用 ！方便！✨️ -# 简介 +# ⭐️ 简介 DrissionPage，即 driver 和 session 组合而成的 page。 是个基于 python 的 Web 自动化操作集成工具。 @@ -10,22 +10,24 @@ DrissionPage，即 driver 和 session 组合而成的 page。 可兼顾 selenium 的便利性和 requests 的高效率， 更棒的是，它的使用方式非常简洁和人性化，代码量少，对新手友好。 -点击打开：[使用文档](http://g1879.gitee.io/drissionpage) +点击打开：📒[使用文档](http://g1879.gitee.io/drissionpage) -**交流QQ群：** 897838127 **联系邮箱：** g1879@qq.com +**交流QQ群：** 897838127 -## 背景 +**联系邮箱：** g1879@qq.com + +## 📔 背景 requests 爬虫面对要登录的网站时，要分析数据包、JS 源码，构造复杂的请求，往往还要应付验证码、JS 混淆、签名参数等反爬手段，门槛较高。若数据是由 JS 计算生成的，还须重现计算过程，体验不好，开发效率不高。 使用 selenium，可以很大程度上绕过这些坑，但 selenium 效率不高。因此，这个库将 selenium 和 requests 合而为一，不同须要时切换相应模式，并提供一种人性化的使用方法，提高开发和运行效率。 除了合并两者，本库还以网页为单位封装了常用功能，简化了 selenium 的操作和语句，在用于网页自动化操作时，减少考虑细节，专注功能实现，使用更方便。 一切从简，尽量提供简单直接的使用方法，对新手更友好。 -# 特性和亮点 +# 💡 特性和亮点 -作者有多年自动化和爬虫经验，踩过无数坑，总结出的经验全写到这个库里了。内置了N多实用功能，对常用功能作了整合和优化。 +作者有多年自动化和爬虫经验，踩过无数坑，总结出的经验全写到这个库里了。内置了 N 多实用功能，对常用功能作了整合和优化。 -## 特性 +## 🔮 特性 - 代码高度集成，以简洁的代码为第一追求。 - 页面对象可在 selenium 和 requests 模式间任意切换，保留登录状态。 @@ -33,16 +35,16 @@ requests 爬虫面对要登录的网站时，要分析数据包、JS 源码， - 两种模式提供一致的 API，使用体验一致。 - 人性化设计，集成众多实用功能，大大降低开发工作量。 -## 亮点功能 +## 🎇 亮点功能 - 每次运行程序可以反复使用已经打开的浏览器。如手动设置网页到某个状态，再用程序接管，或手动处理登录，再用程序爬内容。无须每次运行从头启动浏览器，超级方便。 -- 使用 ini 文件保存常用配置，自动调用，也提供便捷的设置api，远离繁杂的配置项。 +- 使用 ini 文件保存常用配置，自动调用，也提供便捷的设置 API，远离繁杂的配置项。 - 极致简明的定位语法，支持直接按文本定位元素，支持直接获取前后兄弟元素和父元素等。 - 强大的下载工具，操作浏览器时也能享受快捷可靠的下载功能。 - 下载工具支持多种方式处理文件名冲突、自动创建目标路径、断链重试等。 - 访问网址带自动重试功能，可设置间隔和超时时间。 - 访问网页能自动识别编码，无须手动设置。 -- 链接参数默认自动生成 Host 和 Referer 属性。 +- 链接参数默认自动生成`Host`和`Referer`属性。 - 可随时直接隐藏或显示浏览器进程窗口，非 headless 或最小化。 - 可自动下载合适版本的 chromedriver，免去麻烦的配置。 - d 模式查找元素内置等待，可任意设置全局等待时间或单次查找等待时间。 @@ -50,23 +52,23 @@ requests 爬虫面对要登录的网站时，要分析数据包、JS 源码， - 点击支持失败重试，可用于保证点击成功、判读网页遮罩层是否消失等。 - 输入文本能自动判断是否成功并重试，避免某些情况下输入或清空失效的情况。 - d 模式下支持全功能的 xpath，可直接获取元素的某个属性，selenium 原生无此功能。 -- 支持直接获取 shadow-root，和普通元素一样操作其下的元素。 -- 支持直接获取 after 和 before 伪元素的内容。 +- 支持直接获取`shadow-root`，和普通元素一样操作其下的元素。 +- 支持直接获取`after`和`before`伪元素的内容。 - 可以在元素下直接使用 > 以 css selector 方式获取当前元素直接子元素。原生不支持这种写法。 - 可简单地使用 lxml 来解析 d 模式的页面或元素，爬取复杂页面数据时速度大幅提高。 - 输出的数据均已转码及处理基本排版，减少重复劳动。 - 可方便地与 selenium 或 requests 原生代码对接，便于项目迁移。 - 使用 POM 模式封装，可直接用于测试，便于扩展。 -- d 模式配置可同时兼容 debugger 和其它参数，原生不能兼容。 +- d 模式配置可同时兼容`debugger_address`和其它参数，原生不能兼容。 - 还有很多这里不一一列举………… -# 简单演示 +# 🪄 简单演示 **与 selenium 代码对比** 以下代码实现一模一样的功能，对比两者的代码量： -- 用显性等待方式定位第一个文本包含 some text 的元素 +- 用显性等待方式定位第一个文本包含`some text`的元素 ```python # 使用 selenium： @@ -115,7 +117,7 @@ ele1.drag_to(ele2) driver.execute_script("window.scrollTo(document.documentElement.scrollLeft, document.body.scrollHeight);") # 使用 DrissionPage： -page.scroll_to('bottom') +page.scroll.to_bottom() ``` - 设置 headless 模式 @@ -141,7 +143,7 @@ text = element.pseudo_after - shadow-root 操作 -selenium 新增了 ShadowRoot，但功能实在是太少。 +selenium 新增了`ShadowRoot`，但功能实在是太少。 ```python # 使用 selenium： shadow_element = webdriver.execute_script('return arguments[0].shadowRoot', element) @@ -168,14 +170,14 @@ text = element('xpath://div[@id="div_id"]/text()[2]') - 随时让浏览器窗口消失和显示 ```python -# selenium无此功能 +# selenium 无此功能 # 使用 DrissionPage page.hide_browser() # 让浏览器窗口消失 page.show_browser() # 重新显示浏览器窗口 ``` -注：本功能只支持 Windows，且须设置了 debugger_address 参数时才能生效 +注：本功能只支持 Windows，且须设置了`local_port`或`debugger_address`参数时才能生效。 **与 requests 代码对比** @@ -200,7 +202,7 @@ page.get(url) title = page('tag:h1').text ``` -Tips: DrissionPage 自带默认 headers +Tips: DrissionPage 自带默认`headers` - 下载文件 @@ -265,18 +267,18 @@ Git 命令学习 https://oschina.gitee.io/learn-git-branching/ Git 命令学习 ``` -# 使用方法 +# 🔠 使用方法 [点击跳转到使用文档](http://g1879.gitee.io/drissionpage) -# 版本历史 +# 🎯️ 版本历史 [点击查看版本历史](http://g1879.gitee.io/drissionpage/#/%E7%89%88%E6%9C%AC%E5%8E%86%E5%8F%B2) -# 免责声明 +# 🖐🏻 免责声明 请勿将 DrissionPage 应用到任何可能会违反法律规定和道德约束的工作中,请友善使用 DrissionPage，遵守蜘蛛协议，不要将 DrissionPage 用于任何非法用途。如您选择使用 DrissionPage 即代表您遵守此协议，作者不承担任何由于您违反此协议带来任何的法律风险和损失，一切后果由您承担。 -# 请我喝咖啡 +# ☕ 请我喝咖啡 如果本项目对您有所帮助，不妨请作者我喝杯咖啡 ：） diff --git a/docs/README.md b/docs/README.md index 47048e0..a50a4b2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,4 @@ -# 简洁！易用 ！方便！ - -# 简介 +# ✨️简洁！易用 ！方便！✨️ DrissionPage，即 driver 和 session 组合而成的 page。 是个基于 python 的 Web 自动化操作集成工具。 @@ -10,20 +8,24 @@ DrissionPage，即 driver 和 session 组合而成的 page。 可兼顾 selenium 的便利性和 requests 的高效率， 更棒的是，它的使用方式非常简洁和人性化，代码量少，对新手友好。 -**交流QQ群：** 897838127 **联系邮箱：** g1879@qq.com +点击打开：📒[使用文档](http://g1879.gitee.io/drissionpage) -## 背景 +**交流QQ群：** 897838127 + +**联系邮箱：** g1879@qq.com + +## 📕 背景 requests 爬虫面对要登录的网站时，要分析数据包、JS 源码，构造复杂的请求，往往还要应付验证码、JS 混淆、签名参数等反爬手段，门槛较高。若数据是由 JS 计算生成的，还须重现计算过程，体验不好，开发效率不高。 使用 selenium，可以很大程度上绕过这些坑，但 selenium 效率不高。因此，这个库将 selenium 和 requests 合而为一，不同须要时切换相应模式，并提供一种人性化的使用方法，提高开发和运行效率。 除了合并两者，本库还以网页为单位封装了常用功能，简化了 selenium 的操作和语句，在用于网页自动化操作时，减少考虑细节，专注功能实现，使用更方便。 一切从简，尽量提供简单直接的使用方法，对新手更友好。 -# 特性和亮点 +# 🍀 特性和亮点 作者有多年自动化和爬虫经验，踩过无数坑，总结出的经验全写到这个库里了。内置了 N 多实用功能，对常用功能作了整合和优化。 -## 特性 +## 🎉 特性 - 代码高度集成，以简洁的代码为第一追求。 - 页面对象可在 selenium 和 requests 模式间任意切换，保留登录状态。 @@ -31,16 +33,16 @@ requests 爬虫面对要登录的网站时，要分析数据包、JS 源码， - 两种模式提供一致的 API，使用体验一致。 - 人性化设计，集成众多实用功能，大大降低开发工作量。 -## 亮点功能 +## 💡 亮点功能 - 每次运行程序可以反复使用已经打开的浏览器。如手动设置网页到某个状态，再用程序接管，或手动处理登录，再用程序爬内容。无须每次运行从头启动浏览器，超级方便。 -- 使用 ini 文件保存常用配置，自动调用，也提供便捷的设置 api，远离繁杂的配置项。 +- 使用 ini 文件保存常用配置，自动调用，也提供便捷的设置 API，远离繁杂的配置项。 - 极致简明的定位语法，支持直接按文本定位元素，支持直接获取前后兄弟元素和父元素等。 - 强大的下载工具，操作浏览器时也能享受快捷可靠的下载功能。 - 下载工具支持多种方式处理文件名冲突、自动创建目标路径、断链重试等。 - 访问网址带自动重试功能，可设置间隔和超时时间。 - 访问网页能自动识别编码，无须手动设置。 -- 链接参数默认自动生成 Host 和 Referer 属性。 +- 链接参数默认自动生成`Host`和`Referer`属性。 - 可随时直接隐藏或显示浏览器进程窗口，非 headless 或最小化。 - 可自动下载合适版本的 chromedriver，免去麻烦的配置。 - d 模式查找元素内置等待，可任意设置全局等待时间或单次查找等待时间。 @@ -48,22 +50,22 @@ requests 爬虫面对要登录的网站时，要分析数据包、JS 源码， - 点击支持失败重试，可用于保证点击成功、判读网页遮罩层是否消失等。 - 输入文本能自动判断是否成功并重试，避免某些情况下输入或清空失效的情况。 - d 模式下支持全功能的 xpath，可直接获取元素的某个属性，selenium 原生无此功能。 -- 支持直接获取 shadow-root，和普通元素一样操作其下的元素。 -- 支持直接获取 after 和 before 伪元素的内容。 +- 支持直接获取`shadow-root`，和普通元素一样操作其下的元素。 +- 支持直接获取`after`和`before`伪元素的内容。 - 可以在元素下直接使用 > 以 css selector 方式获取当前元素直接子元素。原生不支持这种写法。 - 可简单地使用 lxml 来解析 d 模式的页面或元素，爬取复杂页面数据时速度大幅提高。 - 输出的数据均已转码及处理基本排版，减少重复劳动。 - 可方便地与 selenium 或 requests 原生代码对接，便于项目迁移。 - 使用 POM 模式封装，可直接用于测试，便于扩展。 -- d 模式配置可同时兼容 debugger 和其它参数，原生不能兼容。 +- d 模式配置可同时兼容`debugger_address`和其它参数，原生不能兼容。 - 还有很多这里不一一列举………… -# 免责声明 +# 🖐🏻 免责声明 请勿将 DrissionPage 应用到任何可能会违反法律规定和道德约束的工作中,请友善使用 DrissionPage，遵守蜘蛛协议，不要将 DrissionPage 用于任何非法用途。如您选择使用 DrissionPage 即代表您遵守此协议，作者不承担任何由于您违反此协议带来任何的法律风险和损失，一切后果由您承担。 -# 请我喝咖啡 +# ☕ 请我喝咖啡 如果本项目对您有所帮助，不妨请作者我喝杯咖啡 ：） diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 85a0301..bea2eec 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,7 +1,7 @@ -* [⭐️ 简介](简介.md) +* [⭐️ 简介](README.md) * 🧭入门指南 - * [💡 基本概念](入门指南\基本概念.md) + * [🪄 基本概念](入门指南\基本概念.md) * [🖐🏻 快速上手](入门指南\快速上手.md) * 🎭 特性演示 * [🐙 与 requests 对比](入门指南\特性演示\与requests代码对比.md) @@ -31,6 +31,9 @@ * [🦒 DriverPage 和 SessionPage](使用方法\DriverPage和SessionPage.md) * [🐭 打包程序](使用方法\打包程序.md) +* 💖 实用示例 + * [🧡 同时操作多个浏览器](实用示例\同时操作多个浏览器.md) + * [✨️ Tips大集合](Tips大集合.md) * [🎯️ 版本历史](版本历史.md) * [💐 鸣谢](鸣谢.md) diff --git a/docs/index.html b/docs/index.html index 6321ff9..bd026e0 100644 --- a/docs/index.html +++ b/docs/index.html @@ -8,12 +8,15 @@ - + + + + --> diff --git a/docs/使用方法/获取网页信息.md b/docs/使用方法/获取网页信息.md index 9ef6219..5b02b2b 100644 --- a/docs/使用方法/获取网页信息.md +++ b/docs/使用方法/获取网页信息.md @@ -8,35 +8,35 @@ ## mode -此属性返回当前页面对象的模式，'s' 或 'd'。 +此属性返回当前页面对象的模式，`'s'`或`'d'`。 ## drission -此属性返回当前页面对象使用的 Drission 对象。 +此属性返回当前页面对象使用的`Drission`对象。 ## driver -此属性返回当前页面对象使用的 WebDriver 对象。访问时会自动切换到 d 模式。 +此属性返回当前页面对象使用的`WebDriver`对象。访问时会自动切换到 d 模式。 ## session -此属性返回当前页面对象使用的 Session 对象。访问时不会切换模式。 +此属性返回当前页面对象使用的`Session`对象。访问时不会切换模式。 ## cookies -此属性以 dict 方式返回当前页面所使用的 cookies。 -d 模式只返回当前标签页的 cookies，s 模式则只返回当前访问的 url 的cookies。 +此属性以`dict`方式返回当前页面所使用的 cookies。 +d 模式只返回当前标签页的 cookies，s 模式则只返回当前访问的 url 的 cookies。 ## get_cookies() -此方法获取 cookies 并以 cookie 组成的 list 形式返回。 +此方法获取 cookies 并以 cookie 组成的`list`形式返回。 参数： -- as_dict：是否以字典方式返回，为 False 返回 cookie 组成的 list +- as_dict：是否以字典方式返回，为`False`返回 cookie 组成的`list` - all_domains：是否返回所有域的 cookies，只有 s 模式下生效 -返回：cookies信息 +返回：cookies 信息 ```python from DrissionPage import MixPage @@ -64,7 +64,7 @@ for i in p.get_cookies(as_dict=False, all_domains=True): ## title -此属性返回当前页面 title 文本。 +此属性返回当前页面`title`文本。 ## timeout @@ -101,8 +101,8 @@ page.retry_interval = 1.5 ## url_available 此属性以布尔值返回当前链接是否可用。 -s 模式下根据 Response 对象的 status_code 判断。 -d 模式根据 check_page() 方法返回值判断。 +s 模式下根据 Response 对象的`status_code`判断。 +d 模式根据`check_page()`方法返回值判断。 # s 模式独有属性 @@ -127,9 +127,9 @@ print(r.status_code) ## timeouts 此属性以字典方式返回三种超时时间，selenium 4 以上版本可用。 -'implicit' 用于元素查找、点击重试、输入文本重试、处理弹出框重试等； -'pageLoad' 用于等待页面加载； -'script' 用于等待脚本执行。 +`'implicit'`用于元素查找、点击重试、输入文本重试、处理弹出框重试等； +`'pageLoad'`用于等待页面加载； +`'script'`用于等待脚本执行。 ```python print(page.timeouts) @@ -160,7 +160,7 @@ print(page.timeouts) ## active_ele -此属性返回当前页面上焦点所在元素。类型为 DriverElement。 +此属性返回当前页面上焦点所在元素。类型为`DriverElement`。 ## wait_obj diff --git a/docs/使用方法/访问网页.md b/docs/使用方法/访问网页.md index 0757928..fb9d6e8 100644 --- a/docs/使用方法/访问网页.md +++ b/docs/使用方法/访问网页.md @@ -1,23 +1,23 @@ -操作页面前通常要先跳转到目标 url（接管现有浏览器除外），本库访问网页主要支持 get() 和 post() 两种方式，还支持自动重试。 +操作页面前通常要先跳转到目标 url（接管现有浏览器除外），本库访问网页主要支持`get()`和`post()`两种方式，还支持自动重试。 # get() 该方法在 d 模式和 s 模式下都可用，用于跳转到一个网址。 当连接失败时，程序默认重试 3 次，每次间隔 2 秒，也可以通过参数设置重试次数和间隔。 如果目标 url 和当前 url 一致，程序默认不跳转，可通过参数强制跳转。 -在 s 模式下，可传入连接参数，语法与 requests 的 get() 方法一致。 -方法返回是否连接成功的布尔值，s 模式下根据 Response 对象的 status_code 参数决定，d 模式下根据浏览器的状态，还可以通过重写 check_page() 方法实现自定义检查方式。 +在 s 模式下，可传入连接参数，语法与 requests 的`get()`方法一致。 +方法返回是否连接成功的布尔值，s 模式下根据 Response 对象的`status_code`参数决定，d 模式下根据浏览器的状态，还可以通过重写`check_page()`方法实现自定义检查方式。 参数： - url：目标 url - go_anyway：若目标 url 与当前 url 一致，是否强制跳转 -- show_errmsg：是否显示和抛出异常，默认不抛出，连接错误会返回 None +- show_errmsg：是否显示和抛出异常，默认不抛出，连接错误会返回`None` - retry：重试次数，与页面对象的设置一致，默认 3 次 - interval：重试间隔（秒），与页面对象的设置一致，默认 2 秒 - **kwargs：连接参数，s 模式专用，与 requests 的使用方法一致 -返回：是否连接成功 +返回：`bool`类型，表示是否连接成功 ## d 模式 @@ -30,14 +30,14 @@ page.get('https://www.baidu.com') ## s 模式 -s 模式的 **kwargs 参数与 requests 中该参数使用方法一致，但有一个特点，如果该参数中设置了某一项（如 headers），该项中的每个项会覆盖从配置中读取的同名项，而不会整个覆盖。 -就是说，如果想继续使用配置中的 headers 信息，而只想修改其中一项，只需要传入该项的值即可。这样可以简化代码逻辑。 +s 模式的`**kwargs`参数与 requests 中该参数使用方法一致，但有一个特点，如果该参数中设置了某一项（如`headers`），该项中的每个项会覆盖从配置中读取的同名项，而不会整个覆盖。 +就是说，如果想继续使用配置中的`headers`信息，而只想修改其中一项，只需要传入该项的值即可。这样可以简化代码逻辑。 实用功能： -- 程序会根据要访问的网址自动在 headers 中加入 Host 和 Referer 项。 +- 程序会根据要访问的网址自动在`headers`中加入`Host`和`Referer`项。 - 程序会自动从返回内容中确定编码，一般情况无须手动设置。 -- s 模式下页面对象的 timeout 属性是指连接超时时间，不是查找元素超时时间。 +- s 模式下页面对象的`timeout`属性是指连接超时时间，不是查找元素超时时间。 ```python from DrissionPage import MixPage diff --git a/docs/入门指南/基本概念.md b/docs/入门指南/基本概念.md index 613d253..e8961e8 100644 --- a/docs/入门指南/基本概念.md +++ b/docs/入门指南/基本概念.md @@ -60,7 +60,7 @@ rows = ele.eles('tag:tr') ## MixPage -顾名思义，MixPage 对象是整合了两种模式的页面对象，所有页面的跳转、读取、操作、标签页控制都由该对象进行。 +顾名思义，`MixPage`对象是整合了两种模式的页面对象，所有页面的跳转、读取、操作、标签页控制都由该对象进行。 ```python # 创建页面对象 @@ -77,7 +77,7 @@ page.ele('@value=百度一下').click() ## DriverElement -DriverElemnet 对象是 d 模式所产生的页面元素对象，用于可对其进行点击、文本输入、拖拽、运行 js 脚本等操作，也可以基于这个元素查找其下级或周围的元素。 +`DriverElemnet`对象是 d 模式所产生的页面元素对象，用于可对其进行点击、文本输入、拖拽、运行 js 脚本等操作，也可以基于这个元素查找其下级或周围的元素。 ```python # 点击一个元素 @@ -96,8 +96,8 @@ links = ele1.eles('tag:a') ## SessionElement -SessionElement 对象是 s 模式所产生的页面元素对象，可以读取元素信息，或基于它进行下级元素查找、相对定位其它元素，但不能执行点击等操作。 -这种对象解析效率很高，当 d 模式页面太复杂时，可把 d 模式的元素转换为 SessionElement 进行解析，提高速度。转换的同时可以执行下级元素的查找。 +`SessionElement`对象是 s 模式所产生的页面元素对象，可以读取元素信息，或基于它进行下级元素查找、相对定位其它元素，但不能执行点击等操作。 +这种对象解析效率很高，当 d 模式页面太复杂时，可把 d 模式的元素转换为`SessionElement`进行解析，提高速度。转换的同时可以执行下级元素的查找。 ```python # 获取元素 tag 属性 @@ -111,7 +111,7 @@ ele2 = d_ele.s_ele('@name=name1') ## Drission -Drission 对象用于管理与网页通讯的 WebDriver 对象和 Session 对象，相当于驱动器的角色。能实现这两个对象间的登录状态传递等。但它提供的功能往往通过 MixPage 调用，所以出场几率并不高。 +`Drission`对象用于管理与网页通讯的`WebDriver`对象和`Session`对象，相当于驱动器的角色。能实现这两个对象间的登录状态传递等。但它提供的功能往往通过`MixPage`调用，所以出场几率并不高。 ```python from DrissionPage import Drission @@ -122,7 +122,7 @@ d = Drission() page = MixPage(drission=d) ``` -实际上，如果创建时不传入 Drission 对象，MixPage 会自动根据配置信息创建一个。 +实际上，如果创建时不传入`Drission`对象，`MixPage`会自动根据配置信息创建一个。 ```python from DrissionPage import MixPage @@ -133,15 +133,15 @@ page = MixPage() # 结构图 -如图所示，Drission 对象负责链接的创建、共享登录状态等工作，类似 selenium 中 driver 的概念。 -MixPage 对象负责对获取到的页面进行解析、操作。 -DriverElement 和 SessionElement 则是从页面对象中获取到的元素对象。负责对元素进行解析和操作。 +如图所示，`Drission`对象负责链接的创建、共享登录状态等工作，类似 selenium 中 driver 的概念。 +`MixPage`对象负责对获取到的页面进行解析、操作。 +`DriverElement`和`SessionElement`则是从页面对象中获取到的元素对象。负责对元素进行解析和操作。 ![](https://gitee.com/g1879/DrissionPage-demos/raw/master/pics/20201118170751.jpg) # 配置管理 -无论 requests 还是 selenium，都通常须要一些配置信息才能正常工作，如长长的 user_agent、driver 路径、浏览器配置等。这些代码往往是繁琐而重复的，不利于代码的简洁。 +无论 requests 还是 selenium，都通常须要一些配置信息才能正常工作，如长长的`user_agent`、driver 路径、浏览器配置等。这些代码往往是繁琐而重复的，不利于代码的简洁。 因此，DrissionPage 使用配置文件记录常用配置信息，程序会自动读取默认配置文件里的内容。所以，在示例中，通常看不见配置信息的代码。 这个功能支持用户保存不同的配置文件，按情况调研，也可以支持直接把配置写在代码里面，屏蔽读取配置文件。 diff --git a/docs/入门指南/快速上手.md b/docs/入门指南/快速上手.md index af78960..1734031 100644 --- a/docs/入门指南/快速上手.md +++ b/docs/入门指南/快速上手.md @@ -4,6 +4,12 @@ pip install DrissionPage ``` +升级： + +```python +pip install DrissionPage --upgrade +``` + # 导入 ```python diff --git a/docs/实用示例/下载星巴克产品图片.md b/docs/实用示例/下载星巴克产品图片.md new file mode 100644 index 0000000..a34e0de --- /dev/null +++ b/docs/实用示例/下载星巴克产品图片.md @@ -0,0 +1,65 @@ +这个示例用于演示`download()`方法的功能。 + +# 页面分析 + +目标网址：https://www.starbucks.com.cn/menu/ + +采集目标：下载所有产品图片，并以产品名称命名。 + +如图所示： + +![](https://gitee.com/g1879/DrissionPage-demos/raw/master/pics/QQ%E6%88%AA%E5%9B%BE20220117233111.jpg) + +按 F12 查看页面代码，可以发现每个产品图片都是一个`div`元素，`class`属性都为`preview circle`。且图片网址藏在其`style`属性中。而产品名称则在这个`div`元素后面一个元素中。 + +如图所示： + +![](https://gitee.com/g1879/DrissionPage-demos/raw/master/pics/QQ%E6%88%AA%E5%9B%BE20220117233229.jpg) + +# 编码思路 + +按照页面规律，我们可以获取所有`class`属性为`preview circle`的元素，然后遍历它们，逐个获取图片路径，以及在后面一个元素中获取产品名称。再将其下载。 + +# 示例代码 + +```python +from DrissionPage import MixPage +from re import search + +# 以s模式创建页面对象 +page = MixPage('s') +# 访问目标网页 +page.get('https://www.starbucks.com.cn/menu/') + +# 获取所有class属性为preview circle的元素 +divs = page.eles('.preview circle') +# 遍历这些元素 +for div in divs: + # 用相对定位获取当前div元素后一个兄弟元素，并获取其文本 + name = div.next().text + + # 在div元素的style属性中提取图片网址并进行拼接 + img_url = div.attr('style') + img_url = search(r'"(.*)"', img_url).group(1) + img_url = f'https://www.starbucks.com.cn{img_url}' + + # 执行下载 + page.download(img_url, r'.\imgs', rename=name) +``` + +?> **Tips：** 程序中无须创建`imgs`文件夹，`download()`方法会自动创建。 + +# 结果 + +![](https://gitee.com/g1879/DrissionPage-demos/raw/master/pics/QQ%E6%88%AA%E5%9B%BE20220117234300.jpg) + +程序执行的时候，默认会把下载进度打印出来。 + +![](https://gitee.com/g1879/DrissionPage-demos/raw/master/pics/QQ%E6%88%AA%E5%9B%BE20220117234232.jpg) + +我们注意到有些产品名称是带有`/`的，这是系统路径的非法字符。一般下载方法须程序员自行处理。 +但 DrissionPage 的`download()`方法自带去除非法字符功能，保证文件能成功保存。 +除此以外，遇到保存路径有重名文件时，该方法也能自动对新文件进行重命名（添加序号），避免路径冲突。 +该方法会返回已下载文件的绝对路径，方便程序进一步使用。 + +?> **Tips：** 遇到重名时，`download()`方法可选择`skip`、`overwrite`、`rename`三种方式处理。 \ No newline at end of file diff --git a/docs/实用示例/同时操作多个浏览器.md b/docs/实用示例/同时操作多个浏览器.md new file mode 100644 index 0000000..d48e33c --- /dev/null +++ b/docs/实用示例/同时操作多个浏览器.md @@ -0,0 +1,27 @@ +在 selenium 中，一个`WebDriver`对象操作一个浏览器进程。 +对应地，DrissionPage 中一个`Drission`对象控制一个浏览器进程。 +当须要控制多个浏览器时，只需创建多个`Drission`对象即可。 + +实际上，因为`MixPage`会自动根据传入配置创建`Drission`对象，因此只需设置不同的`DriverOptions`和`MixPage`对象即可。 + +!> **注意：** 这些对象必须设置不同的`local_port`和`user_data_path`参数，否则会造成冲突。 + +```python +from DrissionPage.config import DriverOptions +from DrissionPage import MixPage + +# 创建两个配置对象指向不同端口和数据文件夹 +do1 = DriverOptions().set_paths(local_port=9222, + user_data_path=r'D:\data1') +do2 = DriverOptions().set_paths(local_port=9333, + user_data_path=r'D:\data2') + +# 通过两个配置对象创建两个页面对象 +page1 = MixPage(driver_options=do1) +page2 = MixPage(driver_options=do2) + +# 两个页面对象分别操作自己的浏览器 +page1.get('https://www.baidu.com') +page2.get('http://www.163.com') +``` + diff --git a/docs/版本历史.md b/docs/版本历史.md index af6e678..0274534 100644 --- a/docs/版本历史.md +++ b/docs/版本历史.md @@ -1,3 +1,9 @@ +# v2.4.0 + +- wait_ele()、to_frame()、scroll_to()改用类的方式，避免使用字符串方式选择功能 +- scroll_to()方法改为scroll属性 +- 滚动页面或元素增加to_location()方式 + # v2.3.0 - DriverPage 添加 forward() 方法 diff --git a/docs/简介.md b/docs/简介.md deleted file mode 100644 index adaefbc..0000000 --- a/docs/简介.md +++ /dev/null @@ -1,64 +0,0 @@ -DrissionPage，即 driver 和 session 组合而成的 page。 -是个基于 python 的 Web 自动化操作集成工具。 -它用 POM 模式封装了页面和元素常用的方法， -自带一套简洁直观优雅的元素定位语法， -实现了 selenium 和 requests 之间的无缝切换， -可兼顾 selenium 的便利性和 requests 的高效率， -更棒的是，它的使用方式非常简洁和人性化，代码量少，对新手友好。 - -**项目地址：** - -- https://github.com/g1879/DrissionPage -- https://gitee.com/g1879/DrissionPage - -**联系邮箱：** g1879@qq.com **QQ交流群：** 897838127 - -# 背景 - -requests 爬虫面对要登录的网站时，要分析数据包、JS 源码，构造复杂的请求，往往还要应付验证码、JS 混淆、签名参数等反爬手段，门槛较高。若数据是由 JS 计算生成的，还须重现计算过程，体验不好，开发效率不高。 -使用 selenium，可以很大程度上绕过这些坑，但 selenium 效率不高。因此，这个库将 selenium 和 requests 合而为一，不同须要时切换相应模式，并提供一种人性化的使用方法，提高开发和运行效率。 -除了合并两者，本库还以网页为单位封装了常用功能，简化了 selenium 的操作和语句，在用于网页自动化操作时，减少考虑细节，专注功能实现，使用更方便。 - -# 特性 - -- 代码高度集成，以简洁的代码为第一追求。 -- 页面对象可在 selenium 和 requests 模式间任意切换，保留登录状态。 -- 极简单但强大的元素定位语法，支持链式操作，代码极其简洁。 -- 两种模式提供一致的 API，使用体验一致。 -- 使用 POM 模式封装，便于扩展。 -- 兼容 selenium 代码，便于项目迁移。 -- 人性化设计，集成众多实用功能，大大降低开发工作量。 - -# 亮点功能 - -作者有多年自动化和爬虫经验，踩过无数坑，总结出的经验全写到这个库里。内置了N多实用功能，对常用功能作了整合和优化。使用时可以更专注业务逻辑，减少重复操作。大概罗列一下： - -- 每次运行程序可以反复使用已经打开的浏览器。如手动设置网页到某个状态，再用程序接管，或手动处理登录，再用程序爬内容。无须每次运行从头启动浏览器，超级方便。 -- 使用 ini 文件保存常用配置，自动调用，也提供便捷的设置api，远离繁杂的配置项。 -- 极致简明的定位语法，支持直接按文本定位元素，支持极其灵活的相对定位方法。 -- 强大的下载工具，操作浏览器时也能享受快捷可靠的下载功能。 -- 下载工具支持多种方式处理文件名冲突、自动创建目标路径、断链重试等。 -- 访问网址带自动重试功能，可设置间隔和超时时间。 -- 访问网页能自动识别编码，无须手动设置。 -- 链接参数默认自动生成 Host 和 Referer 属性。 -- 可随时直接隐藏或显示浏览器进程窗口，非 headless 或最小化。 -- 可自动下载合适版本的 chromedriver，免去麻烦的配置。 -- d 模式查找元素内置等待，可任意设置全局等待时间或单次查找等待时间。 -- 点击元素集成 js 点击方式，一个参数即可切换点击方式。 -- 点击支持失败重试，可用于保证点击成功、判读网页遮罩层是否消失等。 -- 输入文本能自动判断是否成功并重试，避免某些情况下输入或清空失效的情况。 -- d 模式下支持全功能的 xpath，可直接获取元素的某个属性，selenium 原生无此功能。 -- 支持直接获取 shadow-root，和普通元素一样操作其下的元素。 -- 支持直接获取 after 和 before 伪元素的内容。 -- 可以在元素下直接使用 > 以 css selector 方式获取当前元素直接子元素。原生不支持这种写法。 -- 可简单地使用 lxml 来解析 d 模式的页面或元素，爬取复杂页面数据时速度大幅提高。 -- 输出的数据均已转码及处理基本排版，减少重复劳动。 -- 可方便地与 selenium 或 requests 原生代码对接，便于项目迁移。 -- 使用 POM 模式封装，可直接用于测试，便于扩展。 -- d 模式配置可同时兼容 debugger 和其它参数，原生不能兼容。 -- 还有很多这里不一一列举………… - -# 免责声明 - -请勿将 DrissionPage 应用到任何可能会违反法律规定和道德约束的工作中，请友善使用 DrissionPage，遵守蜘蛛协议，不要将 DrissionPage 用于任何非法用途。如您选择使用 DrissionPage -即代表您遵守此协议，作者不承担任何由于您违反此协议带来任何的法律风险和损失，一切后果由您承担。 diff --git a/setup.py b/setup.py index b1d9589..4566153 100644 --- a/setup.py +++ b/setup.py @@ -6,7 +6,7 @@ with open("README.md", "r", encoding='utf-8') as fh: setup( name="DrissionPage", - version="2.3.3", + version="2.4.0", author="g1879", author_email="g1879@qq.com", description="A module that integrates selenium and requests session, encapsulates common page operations.",