diff --git a/README.md b/README.md index 331481f..ab6f617 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ -# ✨️简洁！易用 ！方便！✨️ +# -DrissionPage，即 driver 和 session 组合而成的 page。 -是个基于 python 的 Web 自动化操作集成工具。 -它用 POM 模式封装了页面和元素常用的方法， -自带一套简洁直观优雅的元素定位语法， -实现了浏览器和 requests 之间的无缝切换， -可兼顾浏览器自动化的便利性和 requests 的高效率， -更棒的是，它的使用方式非常简洁和人性化，代码量少，对新手友好。 +DrissionPage 是一个基于 python 的网页自动化工具。 + +它既能控制浏览器，也能收发数据包，甚至能把两者合而为一， + +可兼顾浏览器自动化的便利性和 requests 的高效率。 + +它功能强大，内置无数人性化设计和便捷功能。 + +它的语法简洁而优雅，代码量少，对新手友好。 **使用文档：** 📒[点击打开](http://g1879.gitee.io/drissionpage) @@ -14,17 +16,26 @@ DrissionPage，即 driver 和 session 组合而成的 page。 **联系邮箱：** g1879@qq.com -## 📕 背景 +# 📕 背景 -用 requests 做数据采集面对要登录的网站时，要分析数据包、JS 源码，构造复杂的请求，往往还要应付验证码、JS 混淆、签名参数等反爬手段，门槛较高。若数据是由 JS 计算生成的，还须重现计算过程，体验不好，开发效率不高。 -使用浏览器，可以很大程度上绕过这些坑，但浏览器运行效率不高。因此，这个库将它们合而为一，不同须要时切换相应模式，并提供一种人性化的使用方法，提高开发和运行效率。 +用 requests 做数据采集面对要登录的网站时，要分析数据包、JS 源码，构造复杂的请求，往往还要应付验证码、JS 混淆、签名参数等反爬手段，门槛较高。若数据是由 JS 计算生成的，还须重现计算过程，体验不好，开发效率不高。 +使用浏览器，可以很大程度上绕过这些坑，但浏览器运行效率不高。 + +因此，这个库设计初衷，是将它们合而为一，能够在不同须要时切换相应模式，并提供一种人性化的使用方法，提高开发和运行效率。 除了合并两者，本库还以网页为单位封装了常用功能，提供非常简便的操作和语句，在用于网页自动化操作时，减少考虑细节，专注功能实现，使用更方便。 一切从简，尽量提供简单直接的使用方法，对新手更友好。 -# 🔆 3.0 版隆重推出 +# 💡 理念 -以前的版本是对 selenium 进行重新封装实现的。从 3.0 开始，作者另起炉灶，对底层进行了重新开发，摆脱对 selenium 的依赖，增强了功能，提升了运行效率。 -3.0 全新开发的页面对象是`WebPage`，支持 chromium 内核的浏览器（如 chrome 和 edge）。除了保持之前的功能，比依赖 selenium 的`MixPage`有以下优点： +简洁！易用 ！方便！ + +# ☀️ 特性和亮点 + +作者经过长期实践，踩过无数坑，总结出的经验全写到这个库里了。 + +## 🎇 强大的自研内核 + +本库采用全自研的内核，内置了 N 多实用功能，对常用功能作了整合和优化，对比 selenium，有以下优点： - 无 webdriver 特征，不会被网站识别 @@ -36,64 +47,34 @@ DrissionPage，即 driver 和 session 组合而成的 page。 - 把 iframe 看作普通元素，获取后可直接在其中查找元素，逻辑更清晰 -- 可以同时操作浏览器中的多个标签页，即使标签页为非激活状态 +- 可以同时操作浏览器中的多个标签页，即使标签页为非激活状态，无需切换 -- 可以直接读取浏览器缓存来保存图片，无需用 GUI 点击保存 +- 可以直接读取浏览器缓存来保存图片，无需用 GUI 点击另存 - 可以对整个网页截图，包括视口外的部分（90以上版本浏览器支持） -- 对 Linux 提供良好支持 - -新版是自己实现的功能，开发不会受太多限制，以后将主要对`WebPage`进行更新。 - -3.0 版已经发布，目前正在测试，欢迎试用并提出意见，让我做得更好。 - -# 💡 特性和亮点 - -作者踩过无数坑，总结出的经验全写到这个库里了。内置了 N 多实用功能，对常用功能作了整合和优化。 - -## 🎉 特性 - -- 代码高度集成，以简洁的代码为第一追求。 -- 页面对象可在浏览器和 requests 间任意切换，保留登录状态。 -- 极简单但强大的元素定位语法，支持链式操作，代码极其简洁。 -- 两种模式提供一致的 API，使用体验一致。 -- 人性化设计，集成众多实用功能，大大降低开发工作量。 - ## 🎇 亮点功能 -- 每次运行程序可以反复使用已经打开的浏览器。如手动设置网页到某个状态，再用程序接管，或手动处理登录，再用程序爬内容。无须每次运行从头启动浏览器，超级方便。 -- 使用 ini 文件保存常用配置，自动调用，也提供便捷的设置 API，远离繁杂的配置项。 -- 极致简明的定位语法，支持直接按文本定位元素，支持直接获取前后兄弟元素和父元素等。 -- 强大的下载工具，操作浏览器时也能享受快捷可靠的下载功能。 -- 下载工具支持多种方式处理文件名冲突、自动创建目标路径、断链重试等。 -- 访问网址带自动重试功能，可设置间隔和超时时间。 -- 访问网页能自动识别编码，无须手动设置。 -- 链接参数默认自动生成`Host`和`Referer`属性。 -- 可随时直接隐藏或显示浏览器进程窗口，非 headless 或最小化。 -- 可自动下载合适版本的 chromedriver，免去麻烦的配置。 -- d 模式查找元素内置等待，可任意设置全局等待时间或单次查找等待时间。 -- 点击元素集成 js 点击方式，一个参数即可切换点击方式。 -- 点击支持失败重试，可用于保证点击成功、判读网页遮罩层是否消失等。 -- 输入文本能自动判断是否成功并重试，避免某些情况下输入或清空失效的情况。 -- d 模式下支持全功能的 xpath，可直接获取元素的某个属性，selenium 原生无此功能。 -- 支持直接获取`shadow-root`，和普通元素一样操作其下的元素。 -- 支持直接获取`after`和`before`伪元素的内容。 -- 可以在元素下直接使用 > 以 css selector 方式获取当前元素直接子元素。原生不支持这种写法。 -- 可简单地使用 lxml 来解析 d 模式的页面或元素，爬取复杂页面数据时速度大幅提高。 -- 输出的数据均已转码及处理基本排版，减少重复劳动。 -- 可方便地与 selenium 或 requests 原生代码对接，便于项目迁移。 -- 使用 POM 模式封装，可直接用于测试，便于扩展。 -- d 模式配置可同时兼容`debugger_address`和其它参数，原生不能兼容。 -- 还有很多这里不一一列举………… +除了以上优点，本库还内置了无数人性化设计。 -# 🍀 简单演示 +- 极简的语法规则。集成大量常用功能，代码更优雅 +- 定位元素更加容易，功能更强大稳定 +- 无处不在的等待和自动重试功能。使不稳定的网络变得易于控制，程序更稳定，编写更省心 +- 提供强大的下载工具。操作浏览器时也能享受快捷可靠的下载功能 +- 允许反复使用已经打开的浏览器。无须每次运行从头启动浏览器，调试超方便 +- 使用 ini 文件保存常用配置，自动调用，提供便捷的设置，远离繁杂的配置项 +- 内置 lxml 作为解析引擎，解析速度成几个数量级提升 +- 使用 POM 模式封装，可直接用于测试，便于扩展 +- 高度集成的便利功能，从每个细节中体现 +- 还有很多细节，这里不一一列举，欢迎实际使用中体验：） -☘️ **与 selenium 代码对比** +# 🌟 简单演示 + +## ⭐ **与 selenium 代码对比** 以下代码实现一模一样的功能，对比两者的代码量： -🌿 用显性等待方式定位第一个文本包含`some text`的元素 +✨️ 用显性等待方式定位第一个文本包含`some text`的元素 ```python # 使用 selenium： @@ -103,17 +84,17 @@ element = WebDriverWait(driver).until(ec.presence_of_element_located((By.XPATH, element = page('some text') ``` -🌿 跳转到第一个标签页 +✨️ 跳转到第一个标签页 ```python # 使用 selenium： driver.switch_to.window(driver.window_handles[0]) # 使用 DrissionPage： -page.to_tab(0) +page.to_tab(page.tabs[0]) ``` -🌿 按文本选择下拉列表 +✨️ 按文本选择下拉列表 ```python # 使用 selenium： @@ -126,7 +107,7 @@ select_element.select_by_visible_text('text') element.select('text') ``` -🌿 拖拽一个元素 +✨️ 拖拽一个元素 ```python # 使用 selenium： @@ -136,7 +117,7 @@ ActionChains(driver).drag_and_drop(ele1, ele2).perform() ele1.drag_to(ele2) ``` -🌿 滚动窗口到底部（保持水平滚动条不变） +✨️ 滚动窗口到底部（保持水平滚动条不变） ```python # 使用 selenium： @@ -146,18 +127,7 @@ driver.execute_script("window.scrollTo(document.documentElement.scrollLeft, docu page.scroll.to_bottom() ``` -🌿 设置 headless 模式 - -```python -# 使用 selenium： -options = webdriver.ChromeOptions() -options.add_argument("--headless") - -# 使用 DrissionPage： -set_headless() -``` - -🌿 获取伪元素内容 +✨️ 获取伪元素内容 ```python # 使用 selenium： @@ -168,9 +138,7 @@ text = webdriver.execute_script('return window.getComputedStyle(arguments[0], ": text = element.pseudo_after ``` -🌿 shadow-root 操作 - -selenium 新增了`ShadowRoot`，但功能实在是太少。 +✨️ shadow-root 操作 ```python # 使用 selenium： @@ -184,17 +152,7 @@ ele = shadow_element.ele('tag:div') ele.click() ``` -🌿 用 xpath 直接获取属性或文本节点（返回文本） - -```python -# 使用 selenium 无此功能 - -# 使用 DrissionPage： -class_name = element('xpath://div[@id="div_id"]/@class') -text = element('xpath://div[@id="div_id"]/text()[2]') -``` - -🌿 随时让浏览器窗口消失和显示 +✨️ 随时让浏览器窗口消失和显示（Windows系统） ```python # selenium 无此功能 @@ -204,13 +162,11 @@ page.hide_browser() # 让浏览器窗口消失 page.show_browser() # 重新显示浏览器窗口 ``` -注：本功能只支持 Windows。 - -☘️ **与 requests 代码对比** +## ⭐ **与 requests 代码对比** 以下代码实现一模一样的功能，对比两者的代码量： -🌿 获取元素内容 +✨️ 获取元素内容 ```python url = 'https://baike.baidu.com/item/python' @@ -218,22 +174,21 @@ url = 'https://baike.baidu.com/item/python' # 使用 requests： from lxml import etree -headers = { - 'User-Agent': 'Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36'} +headers = {'User-Agent': 'Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36'} response = requests.get(url, headers=headers) html = etree.HTML(response.text) element = html.xpath('//h1')[0] title = element.text # 使用 DrissionPage： -page = MixPage('s') +page = WebPage('s') page.get(url) title = page('tag:h1').text ``` Tips: DrissionPage 自带默认`headers` -🌿 下载文件 +✨️ 下载文件 ```python url = 'https://www.baidu.com/img/flexible/logo/pc/result.png' @@ -249,9 +204,9 @@ with open(f'{save_path}\\img.png', 'wb') as fd: page.download(url, save_path, 'img') # 支持重命名，处理文件名冲突，自动创建目标文件夹 ``` -☘️ **模式切换** +## ⭐ **模式切换** -用 selenium 登录网站，然后切换到 requests 读取网页。两者会共享登录信息。 +用浏览器登录网站，然后切换到 requests 读取网页。两者会共享登录信息。 ```python page = WebPage() # 创建页面对象，默认 driver 模式 @@ -300,7 +255,7 @@ Git 命令学习 [点击跳转到使用文档](http://g1879.gitee.io/drissionpage) -# 🎯️ 版本历史 +# 🔖 版本历史 [点击查看版本历史](http://g1879.gitee.io/drissionpage/#/%E7%89%88%E6%9C%AC%E5%8E%86%E5%8F%B2) diff --git a/docs/README.md b/docs/README.md index d9b6181..608c3da 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,11 +21,11 @@ DrissionPage 是一个基于 python 的网页自动化工具。 除了合并两者，本库还以网页为单位封装了常用功能，提供非常简便的操作和语句，在用于网页自动化操作时，减少考虑细节，专注功能实现，使用更方便。 一切从简，尽量提供简单直接的使用方法，对新手更友好。 -# ✨️ 理念 +# 💡 理念 简洁！易用 ！方便！ -# 💡 特性和亮点 +# ☀️ 特性 作者经过长期实践，踩过无数坑，总结出的经验全写到这个库里了。 diff --git a/docs/WebPage使用方法/3.0概述.md b/docs/WebPage使用方法/3.0简介.md similarity index 100% rename from docs/WebPage使用方法/3.0概述.md rename to docs/WebPage使用方法/3.0简介.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index da1e201..a6b2ba9 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,66 +1,74 @@ -* [⭐️ 1 概述](README.md) +* [📣 1 概述](README.md) + +* [☀️ 2 特性和亮点](#) + + * [💖 2.1 贴心设计](特性和亮点\贴心设计.md) + * [🌟 2.2 特性演示](#) + * [⭐ 与 requests 对比](特性和亮点\特性演示\与requests代码对比.md) + * [⭐ 与 selenium 对比](特性和亮点\特性演示\与selenium代码对比.md) + * [⭐ 模式切换](特性和亮点\特性演示\模式切换.md) + * [⭐ 获取并打印元素属性](特性和亮点\特性演示\获取并打印元素属性.md) + * [⭐ 下载文件](特性和亮点\特性演示\下载文件.md) * [🧭 2 入门指南](#) - - * [🔥 2.1 基本概念](入门指南\基本概念.md) - * [👍 2.2 快速上手](入门指南\快速上手.md) - * [🍀 2.3 特性演示](#) - * [🌿 与 requests 对比](入门指南\特性演示\与requests代码对比.md) - * [🌿 与 selenium 对比](入门指南\特性演示\与selenium代码对比.md) - * [🌿 模式切换](入门指南\特性演示\模式切换.md) - * [🌿 获取并打印元素属性](入门指南\特性演示\获取并打印元素属性.md) - * [🌿 下载文件](入门指南\特性演示\下载文件.md) - * [💖 2.4 贴心设计](入门指南\贴心设计.md) -* [🛠 3 WebPage 使用方法](#) - - * [🔨 3.0 简介](WebPage使用方法\3.0概述.md) - * [🔨 3.1 创建页面对象](WebPage使用方法\3.1创建页面对象.md) - * [🔨 3.2 访问网页](WebPage使用方法\3.2访问网页.md) - * [🔨 3.3 查找元素](WebPage使用方法\3.3查找元素.md) - * [🔨 3.4 获取元素信息](WebPage使用方法\3.4获取元素信息.md) - * [🔨 3.5 元素操作](WebPage使用方法\3.5元素操作.md) - * [🔨 3.6 获取网页信息](WebPage使用方法\3.6获取网页信息.md) - * [🔨 3.7 页面操作](WebPage使用方法\3.7页面操作.md) - * [🔨 3.8 标签页操作](WebPage使用方法\3.8标签页操作.md) - * [🔨 3.9 iframe操作](WebPage使用方法\3.9iframe操作.md) - * [🔨 3.10 动作链](WebPage使用方法\3.10动作链.md) + * [🌏 2.1 基本概念](入门指南\基本概念.md) + * [🌏 2.2 安装和导入](入门指南\安装和导入.md) + * [🌏 2.3 准备工作](入门指南\准备工作.md) + * [🌏 2.4 上手示例](#) + * [🌐 控制浏览器](入门指南\上手示例\控制浏览器.md) + * [🌐 收发数据包](入门指南\上手示例\收发数据包.md) + * [🌐 模式切换](入门指南\上手示例\模式切换.md) -* [🛠 4 MixPage 使用方法](#) - - * [🔨 4.1 创建页面对象](MixPage使用方法\创建页面对象.md) - * [🔨 4.2 访问网页](MixPage使用方法\访问网页.md) - * [🔨 4.3 查找页面元素](MixPage使用方法\查找页面元素.md) - * [🔨 4.4 获取元素信息](MixPage使用方法\获取元素信息.md) - * [🔨 4.5 元素操作](MixPage使用方法\元素操作.md) - * [🔨 4.6 获取网页信息](MixPage使用方法\获取网页信息.md) - * [🔨 4.7 页面操作](MixPage使用方法\页面操作.md) - * [🔨 4.8 cookies 的使用](MixPage使用方法\cookies的使用.md) - * [🔨 4.9 Drission 对象](MixPage使用方法\Drission对象.md) - * [🔨 4.10 对接 selenium 及 requests 代码](MixPage使用方法\对接selenium及requests代码.md) - * [🔨 4.11 使用其它系统或浏览器](MixPage使用方法\使用其它系统或浏览器.md) - * [🔨 4.12 DriverPage 和 SessionPage](MixPage使用方法\DriverPage和SessionPage.md) +* [🛠 3 使用方法](#) -* [📝 5 启动配置](#) - - * [🗒️ 5.1 概述](启动配置\概述.md) - * [🗒️ 5.2 浏览器启动配置](启动配置\浏览器启动配置.md) - * [🗒️ 5.3 Session 启动配置](启动配置\Session启动配置.md) - * [🗒️ 5.4 使用配置文件](启动配置\使用配置文件.md) + * [🔨 3.0 简介](WebPage使用方法\3.0简介.md) + * [🔨 3.1 创建页面对象](WebPage使用方法\3.1创建页面对象.md) + * [🔨 3.2 访问网页](WebPage使用方法\3.2访问网页.md) + * [🔨 3.3 查找元素](WebPage使用方法\3.3查找元素.md) + * [🔨 3.4 获取元素信息](WebPage使用方法\3.4获取元素信息.md) + * [🔨 3.5 元素操作](WebPage使用方法\3.5元素操作.md) + * [🔨 3.6 获取网页信息](WebPage使用方法\3.6获取网页信息.md) + * [🔨 3.7 页面操作](WebPage使用方法\3.7页面操作.md) + * [🔨 3.8 标签页操作](WebPage使用方法\3.8标签页操作.md) + * [🔨 3.9 iframe操作](WebPage使用方法\3.9iframe操作.md) + * [🔨 3.10 动作链](WebPage使用方法\3.10动作链.md) -* [🧰 6 进阶使用](#) - - * [⚙️ 6.1 打包程序](进阶使用\打包程序.md) - * [⚙️ 6.2 监听浏览器网络](进阶使用\监听浏览器网络.md) - * [⚙️ 6.3 下载文件](进阶使用\下载文件.md) +* [📝 4 启动配置](#) + + * [🗒️ 4.1 概述](启动配置\概述.md) + * [🗒️ 4.2 浏览器启动配置](启动配置\浏览器启动配置.md) + * [🗒️ 4.3 Session 启动配置](启动配置\Session启动配置.md) + * [🗒️ 4.4 使用配置文件](启动配置\使用配置文件.md) + +* [🧰 5 进阶使用](#) + + * [⚙️ 5.1 打包程序](进阶使用\打包程序.md) + * [⚙️ 5.2 监听浏览器网络](进阶使用\监听浏览器网络.md) + * [⚙️ 5.3 下载文件](进阶使用\下载文件.md) + +* [🛠 6 旧版使用方法](#) + + * [🔨 6.1 创建页面对象](MixPage使用方法\创建页面对象.md) + * [🔨 6.2 访问网页](MixPage使用方法\访问网页.md) + * [🔨 6.3 查找页面元素](MixPage使用方法\查找页面元素.md) + * [🔨 6.4 获取元素信息](MixPage使用方法\获取元素信息.md) + * [🔨 6.5 元素操作](MixPage使用方法\元素操作.md) + * [🔨 6.6 获取网页信息](MixPage使用方法\获取网页信息.md) + * [🔨 6.7 页面操作](MixPage使用方法\页面操作.md) + * [🔨 6.8 cookies 的使用](MixPage使用方法\cookies的使用.md) + * [🔨 6.9 Drission 对象](MixPage使用方法\Drission对象.md) + * [🔨 6.10 对接 selenium 及 requests 代码](MixPage使用方法\对接selenium及requests代码.md) + * [🔨 6.11 使用其它系统或浏览器](MixPage使用方法\使用其它系统或浏览器.md) + * [🔨 6.12 DriverPage 和 SessionPage](MixPage使用方法\DriverPage和SessionPage.md) * [⚡️ 7 示例和技巧](#) - - * [🌠 自动登录码云](示例和技巧\自动登录码云.md) - * [🌠 采集猫眼电影TOP100榜](示例和技巧\采集猫眼电影TOP100榜.md) - * [🌠 下载星巴克产品图片](示例和技巧\下载星巴克产品图片.md) - * [🌠 下载豆瓣图书封面图片](示例和技巧\下载豆瓣图书封面图片.md) - * [🌠 多线程操作多标签页](示例和技巧\多线程操作多标签页.md) + + * [🌠 自动登录码云](示例和技巧\自动登录码云.md) + * [🌠 采集猫眼电影TOP100榜](示例和技巧\采集猫眼电影TOP100榜.md) + * [🌠 下载星巴克产品图片](示例和技巧\下载星巴克产品图片.md) + * [🌠 下载豆瓣图书封面图片](示例和技巧\下载豆瓣图书封面图片.md) + * [🌠 多线程操作多标签页](示例和技巧\多线程操作多标签页.md) * [🔖 9 版本历史](版本历史.md) diff --git a/docs/入门指南/上手示例/gitee_1.jpg b/docs/入门指南/上手示例/gitee_1.jpg new file mode 100644 index 0000000..8b11878 Binary files /dev/null and b/docs/入门指南/上手示例/gitee_1.jpg differ diff --git a/docs/入门指南/上手示例/gitee_2.jpg b/docs/入门指南/上手示例/gitee_2.jpg new file mode 100644 index 0000000..69c11ed Binary files /dev/null and b/docs/入门指南/上手示例/gitee_2.jpg differ diff --git a/docs/入门指南/上手示例/控制浏览器.md b/docs/入门指南/上手示例/控制浏览器.md new file mode 100644 index 0000000..af1d91d --- /dev/null +++ b/docs/入门指南/上手示例/控制浏览器.md @@ -0,0 +1,89 @@ +现在，我们通过一些例子，来直观感受一下 DrissionPage 的工作方式。 + +本示例演示使用`ChromiumPage`控制浏览器登录 gitee 网站。 + +# ✔️ 页面分析 + +网址：[https://gitee.com/login](https://gitee.com/login) + +打开网址，按`F12`，我们可以看到页面元素如下： + +![](gitee_1.jpg) + +用户名输入框`id`为`'user_login'`，密码输入框`id`为`'user_password'`，登录按钮`value`为`'登 录'`。 + +我们可以用这三个属性定位这三个元素，然后对其输入数据和点击。 + +# ✔️ 示例代码 + +您可以把以下代码复制到编辑器，把账号和密码改为您自己的，可直接执行看到运行结果。 + +```python +from DrissionPage import ChromiumPage + +# 创建页面对象，并启动或接管浏览器 +page = ChroiumPage() +# 跳转到登录页面 +page.get('https://gitee.com/login') + +# 定位到账号文本框，获取文本框元素 +ele = page.ele('#user_login') +# 输入对文本框输入账号 +ele.input('你的账号') +# 定位到密码文本框并输入密码 +page.ele('#user_password').input('你的密码') +# 点击登录按钮 +page.ele('@value=登 录').click() +``` + +# ✔️ 示例详解 + +首先，我们导入用于控制浏览器的类`ChromiumPage`。 + +```python +from DrissionPage import ChromiumPage +``` + +接下来，我们创建一个`ChromiumPage`对象。 + +```python +page = ChromiumPage() +``` + +`get()`方法用于访问参数中的网址。它会等待页面完全加载，再继续执行后面的代码。您也可以修改等待策略，如等待 DOM 加载而不等待资源下载，就停止加载，这将在后面的章节说明。 + +```python +page.get('https://gitee.com/login') +``` + +`ele()`方法用于查找元素，它返回一个`ChromiumElement`元素对象，可用于对元素的操作。 + +`'#user_login'`是定位符文本，`#`意思是按`id`属性查找元素。 + +值得一提的是，`ele()`内置了等待，如果元素未加载，它会执行等待，直到元素出现或到达时限。默认超时时间 10 秒。 + +```python +ele = page.ele('#user_login') +``` + +`input()`方法用于对元素输入文本。 + +```python +ele.input('你的账号') +``` + +我们也可以进行链式操作。 + +```python +page.ele('#user_password').input('你的密码') +``` + +输入账号密码后，以相同的方法获取按钮元素，并对其执行点击操作。 + +不同的是，这次通过其`value`属性作为查找条件。`@`表示按属性名查找。 + +```python +page.ele('@value=登 录').click() +``` + +到这里，我们已完成了自动登录 gitee 网站的操作。 diff --git a/docs/入门指南/上手示例/收发数据包.md b/docs/入门指南/上手示例/收发数据包.md new file mode 100644 index 0000000..9d49219 --- /dev/null +++ b/docs/入门指南/上手示例/收发数据包.md @@ -0,0 +1,90 @@ +本示例演示用`SessionPage`已收发数据包的方式采集 gitee 网站数据。 + +本示例不使用浏览器。 + +# ✔️ 页面分析 + +网址：[https://gitee.com/explore/all](https://gitee.com/explore/all) + +这个示例的目标，要获取所有库的名称和链接，为避免对网站造成压力，我们只采集 3 页。 + +打开网址，按`F12`，我们可以看到页面元素如下： + +![](gitee_2.jpg) + +从 html 代码中可以看到，所有开源项目的标题都是`class`属性为`'title project-namespace-path'`的``元素。我们可以遍历这些``元素，获取它们的信息。 + +同时，我们观察到，列表页网址是以页数为参数访问的，如第一页 url 为`https://gitee.com/explore/all?page=1`，页数就是`page`参数。因此我们可以通过修改这个参数访问不同的页面。 + +# ✔️ 示例代码 + +以下代码可直接运行并查看结果： + +```python +from DrissionPage import SessionPage + +# 创建页面对象 +page = SessionPage() + +# 爬取3页 +for i in range(1, 4): + # 访问某一页的网页 + p.get(f'https://gitee.com/explore/all?page={i}') + # 获取所有开源库元素列表 + links = p.eles('.title project-namespace-path') + # 遍历所有元素 + for link in links: + # 打印链接信息 + print(link.text, link.link) +``` + +输出： + +``` +小熊派开源社区/BearPi-HM_Nano https://gitee.com/bearpi/bearpi-hm_nano +明月心/PaddleSegSharp https://gitee.com/raoyutian/PaddleSegSharp +RockChin/QChatGPT https://gitee.com/RockChin/QChatGPT +TopIAM/eiam https://gitee.com/topiam/eiam + +以下省略。。。 +``` + +# ✔️ 示例详解 + +首先，我们导入用于收发数据包的类`SessionPage`。 + +```python +from DrissionPage import SessionPage +``` + +接下来，我们创建一个`SessionPage`对象。 + +```python +page = SessionPage() +``` + +然后我们循环 3 次，以构造每页的 url，每次都用`get()`方法访问该页网址。 + +```python +for i in ranage(1, 4): +    p.get(f'https://gitee.com/explore/all?page={i}') +``` + +访问网址后，我们用页面对象的`eles()`获取页面中所有`class`属性为`'title project-namespace-path'`的元素对象。 + +`eles()`方法用于查找多个符合条件的元素，返回由它们组成的`list`。 + +这里查找的条件是`class`属性，`.`表示按`class`属性查找元素。 + +```python +links = p.eles('.title project-namespace-path') +``` + +最后，我们遍历获取到的元素列表，获取每个元素的属性并打印出来。 + +`.text`获取元素的文本，`.link`获取元素的`href`或`src`属性。 + +```python +for link in links: +print(link.text, link.link) +``` diff --git a/docs/入门指南/上手示例/模式切换.md b/docs/入门指南/上手示例/模式切换.md new file mode 100644 index 0000000..d3aced8 --- /dev/null +++ b/docs/入门指南/上手示例/模式切换.md @@ -0,0 +1 @@ +# 施工中。。。 diff --git a/docs/入门指南/准备工作.md b/docs/入门指南/准备工作.md new file mode 100644 index 0000000..4c4356b --- /dev/null +++ b/docs/入门指南/准备工作.md @@ -0,0 +1,43 @@ +在开始之前，我们先进行一些简单设置。 + +如果只使用收发数据包功能，无须任何准备工作。 + +如果要控制浏览器，须设置浏览器路径。以下用 Chrome 作为演示。其它 Chromium 内核浏览器设置方法是一样的。 + +# ✔️ 执行步骤 + +## 📍 关闭已打开的 Chrome + +多个 Chrome 会造成冲突，如果已有打开的 Chrome 浏览器，请关闭。 + +后面在"创建页面对象"章节再介绍多 Chrome 浏览器共存的方法。 + +## 📍 尝试启动浏览器 + +执行以下代码，如果正常启动了浏览器并且访问了百度，则可跳过后面的步骤。 + +```python +from DrissionPage import ChromiumPage + +page = ChromiumPage() +page.get('https://www.baidu.com') +``` + +## 📍 设置路径 + +如果上面的步骤成功访问了百度，可跳过本条。 +如果提示出错，请新建一个临时 py 文件，并输入以下代码，填入您电脑里的 Chrome 浏览器 exe 文件路径，然后执行。 + +!>**注意：**
这段代码只要运行一次即可，不要写到正式程序里。 + +```python +from DrissionPage.easy_set import set_paths + +set_paths(chrome_path=r'这里修改为您的Chrome浏览器exe文件路径', check_version=False) +``` + +执行这段代码会记录您电脑的 Chrome 浏览器路径到配置文件。现在，请重新执行上一步的代码，如果正确访问了百度，说明已经设置完成。 + +# ✔️ 说明 + +当您完成准备工作后，无须关闭浏览器，后面的上手示例可继续使用当前浏览器。 diff --git a/docs/入门指南/安装和导入.md b/docs/入门指南/安装和导入.md new file mode 100644 index 0000000..fc7c4d4 --- /dev/null +++ b/docs/入门指南/安装和导入.md @@ -0,0 +1,42 @@ +# ✔️ 安装 + +## 📍 安装 + +请使用 pip 安装 DrissionPage： + +```shell +pip install DrissionPage +``` + +## 📍 升级 + +```shell +pip install DrissionPage --upgrade +``` + +# ✔️ 导入 + +`WebPage`是功能最全面的页面类，既可控制浏览器，也可收发数据包。通常程序从导入它开始。 + +```python +from DrissionPage import WebPage +``` + +也可以根据具体需要，导入相应的类： + +```python +# ChromiumPage 只控制浏览器，不能收发数据包 +from DrissionPage import ChromiumPage + +# SessionPage 只用于收发数据包，不能控制浏览器 +from DrissionPage import SessionPage + +# 浏览启动参数管理器，用于控制浏览器启动参数 +from DrissionPage import DriverOptions + +# Session对象启动参数管理器，用于控制Session对象启动参数 +from DrissionPage import SessionOptions + +# 动作链类，用于模拟一连串鼠标键盘动作 +from DrissionPage import ActionChains +``` diff --git a/docs/入门指南/快速上手.md b/docs/入门指南/快速上手.md deleted file mode 100644 index 97bde19..0000000 --- a/docs/入门指南/快速上手.md +++ /dev/null @@ -1,122 +0,0 @@ -# ✔️ 安装 - -```shell -pip install DrissionPage -``` - -升级： - -```shell -pip install DrissionPage --upgrade -``` - -# ✔️ 导入 - -根据实际须要导入相应对象： - -```python -from DrissionPage import WebPage # 集成两种模式，推荐使用 -from DrissionPage import MixPage # 集成两种模式，基于selenium -from DrissionPage import ChromiumPage # 只控制浏览器，无须切换s模式 -from DrissionPage import SessionPage # 只收发数据包，无须使用浏览器 -from DrissionPage import DriverOptions # 浏览启动参数管理器 -from DrissionPage import SessionOptions # Session对象启动参数管理器 -``` - -# ✔️ 第一次使用 - -如果只使用 s 模式是无须初始化的，导入后就可以直接使用。 -如果使用 d 模式，`WebPage`须指定浏览器执行文件路径。`MixPage`还须下载与浏览器版本匹配的 driver 文件。这里只介绍`WebPage`需要的设置。 - -多数情况下，如果系统内安装了 Chrome 浏览器，或在系统路径中指定了 Chrome 执行文件，DrissionPage 运行时会自动从系统路径和注册表（Windows）中寻找路径，可直接运行，无须设置。 - -如果程序没有找到路径，或需要手动设置，可使用以下方法： - -新建一个**临时文件** ，修改并运行以下代码，作用是手动指定 Chrome 路径，记录到配置文件，以后程序会自动读取其中的配置，无须再写。 - -```python -from DrissionPage.easy_set import set_paths - -# 请将以下路径修改为本机实际路径 -set_paths(chrome_path=r"D:\chrome\chrome.exe") # 浏览器执行文件路径 -``` - -!> **注意：**
这段代码只用于设置配置文件中的路径信息，**运行一次即可**，勿写到正式程序里 。 - -除了把配置信息写在配置文件，还能把信息直接写在代码里，后面章节再详细叙述。 - -# ✔️ 上手示例 - -现在，我们通过一些例子，来直观感受一下 DrissionPage 的工作方式。 - -## 📍 用 d 模式登录 gitee 网站 - -网址：https://gitee.com/login -此示例演示使用控制浏览器的方式自动登录 gitee 网站。 - -!> **注意：**
如果您有已打开的 Chrome 浏览器，请先关闭，否则会造成冲突。后面在 [创建页面对象](%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95%5C%E4%BD%BF%E5%88%9B%E5%BB%BA%E9%A1%B5%E9%9D%A2%E5%AF%B9%E8%B1%A1.md) 章节再介绍多 Chrome 浏览器共存的方法。 - -```python -from DrissionPage import WebPage - -# 用 d 模式创建页面对象（默认模式） -page = WebPage() -# 跳转到登录页面 -page.get('https://gitee.com/login') - -# 定位到账号文本框并输入账号 -page.ele('#user_login').input('你的账号') -# 定位到密码文本框并输入密码 -page.ele('#user_password').input('你的密码') -# 点击登录按钮 -page.ele('@value=登 录').click() -``` - -## 📍 用 s 模式爬取 gitee 网站开源列表 - -以下代码可直接运行： - -```python -from DrissionPage import WebPge - -# 用 s 模式创建页面对象 -page = WebPage('s') - -for i in range(1, 4):# 爬取3页 - # 跳转到第几页 - p.get(f'https://gitee.com/explore/all?page={i}') - # 遍历所有库链接并打印 - for link in p.eles('.title project-namespace-path'): - print(link.text, link.link) -``` - -结果： - -``` -小熊派开源社区/BearPi-HM_Nano https://gitee.com/bearpi/bearpi-hm_nano -明月心/PaddleSegSharp https://gitee.com/raoyutian/PaddleSegSharp -RockChin/QChatGPT https://gitee.com/RockChin/QChatGPT -TopIAM/eiam https://gitee.com/topiam/eiam - -以下省略。。。 -``` - -## 📍 `ChromiumPage`和`SessionPage` - -上面两个例子都不用转换模式，可以不需要用`WebPage`，而使用对应模式的页面对象也可以，使用方法是一样的。 - -```python -from DrissionPage import ChromiumPage -from DrissionPage import SessionPage - -d_page = ChromiumPage() # 用于控制浏览器 -s_page = SessionPage() # 用于收发数据包 - -# 以下省略…… -``` - -# ✔️ 说明 - -无论电脑安装的 Chrome 能否正常使用，都建议使用绿色版 Chrome，并且设置`user_data_path`。 - -如果计划程序打包成 exe 文件，就不能使用默认配置文件记录配置，具体方法请查看“使用方法->打包程序”章节。 diff --git a/docs/入门指南/特性演示/下载文件.md b/docs/特性和亮点/特性演示/下载文件.md similarity index 100% rename from docs/入门指南/特性演示/下载文件.md rename to docs/特性和亮点/特性演示/下载文件.md diff --git a/docs/入门指南/特性演示/与requests代码对比.md b/docs/特性和亮点/特性演示/与requests代码对比.md similarity index 100% rename from docs/入门指南/特性演示/与requests代码对比.md rename to docs/特性和亮点/特性演示/与requests代码对比.md diff --git a/docs/入门指南/特性演示/与selenium代码对比.md b/docs/特性和亮点/特性演示/与selenium代码对比.md similarity index 100% rename from docs/入门指南/特性演示/与selenium代码对比.md rename to docs/特性和亮点/特性演示/与selenium代码对比.md diff --git a/docs/入门指南/特性演示/模式切换.md b/docs/特性和亮点/特性演示/模式切换.md similarity index 100% rename from docs/入门指南/特性演示/模式切换.md rename to docs/特性和亮点/特性演示/模式切换.md diff --git a/docs/入门指南/特性演示/获取并打印元素属性.md b/docs/特性和亮点/特性演示/获取并打印元素属性.md similarity index 100% rename from docs/入门指南/特性演示/获取并打印元素属性.md rename to docs/特性和亮点/特性演示/获取并打印元素属性.md diff --git a/docs/入门指南/贴心设计.md b/docs/特性和亮点/贴心设计.md similarity index 96% rename from docs/入门指南/贴心设计.md rename to docs/特性和亮点/贴心设计.md index 5f27d33..f18f632 100644 --- a/docs/入门指南/贴心设计.md +++ b/docs/特性和亮点/贴心设计.md @@ -42,7 +42,8 @@ element = page('some text', timeout=10) # ✔️ 无需切入切出，逻辑清晰 -使用过 selenium 的人都知道，selenium 同一时间只能操作一个标签页或`