mirror of
https://gitee.com/g1879/DrissionPage.git
synced 2024-11-29 18:47:34 +08:00
微调注释，修改文档
This commit is contained in:
g1879
parent
d0ed2a7767
commit
ed8debe630
@ -22,7 +22,7 @@ from .configs.driver_options import DriverOptions
|
||||
class ChromiumPage(ChromiumBase):
|
||||
|
||||
def __init__(self,
|
||||
addr_driver_opts: Union[str, ChromiumOptions, DriverOptions] = None,
|
||||
addr_driver_opts: Union[str, ChromiumOptions, ChromiumDriver, DriverOptions] = None,
|
||||
tab_id: str = None,
|
||||
timeout: float = None):
|
||||
self._driver_options: [ChromiumDriver, DriverOptions] = ...
|
||||
|
||||
@ -91,7 +91,7 @@ class ChromiumOptions(object):
|
||||
|
||||
@property
|
||||
def page_load_strategy(self):
|
||||
"""返回页面加载策略设置"""
|
||||
"""返回页面加载策略，'normal', 'eager', 'none'"""
|
||||
return self._page_load_strategy
|
||||
|
||||
@property
|
||||
|
||||
@ -181,7 +181,7 @@ class SessionOptions(object):
|
||||
|
||||
@property
|
||||
def auth(self):
|
||||
"""返回auth设置信息"""
|
||||
"""返回认证设置信息"""
|
||||
return self._auth
|
||||
|
||||
def set_auth(self, auth):
|
||||
@ -201,7 +201,7 @@ class SessionOptions(object):
|
||||
|
||||
def set_hooks(self, hooks):
|
||||
"""设置回调方法
|
||||
:param hooks:
|
||||
:param hooks: 回调方法
|
||||
:return: 返回当前对象
|
||||
"""
|
||||
self._hooks = hooks
|
||||
@ -209,7 +209,7 @@ class SessionOptions(object):
|
||||
|
||||
@property
|
||||
def params(self):
|
||||
"""返回params设置信息"""
|
||||
"""返回连接参数设置信息"""
|
||||
if self._params is None:
|
||||
self._params = {}
|
||||
return self._params
|
||||
@ -237,7 +237,7 @@ class SessionOptions(object):
|
||||
|
||||
@property
|
||||
def cert(self):
|
||||
"""返回cert设置信息"""
|
||||
"""返回SSL证书设置信息"""
|
||||
return self._cert
|
||||
|
||||
def set_cert(self, cert):
|
||||
@ -266,7 +266,7 @@ class SessionOptions(object):
|
||||
|
||||
@property
|
||||
def stream(self):
|
||||
"""返回stream设置信息"""
|
||||
"""返回是否使用流式响应内容设置信息"""
|
||||
return self._stream
|
||||
|
||||
def set_stream(self, on_off):
|
||||
@ -279,7 +279,7 @@ class SessionOptions(object):
|
||||
|
||||
@property
|
||||
def trust_env(self):
|
||||
"""返回trust_env设置信息"""
|
||||
"""返回是否信任环境设置信息"""
|
||||
return self._trust_env
|
||||
|
||||
def set_trust_env(self, on_off):
|
||||
@ -387,7 +387,7 @@ def session_options_to_dict(options):
|
||||
return options
|
||||
|
||||
re_dict = dict()
|
||||
attrs = ['headers', 'cookies', 'proxies', 'params', 'verify', 'stream', 'trust_env',
|
||||
attrs = ['headers', 'cookies', 'proxies', 'params', 'verify', 'stream', 'trust_env', 'cert',
|
||||
'max_redirects', 'timeout', 'download_path']
|
||||
|
||||
for attr in attrs:
|
||||
|
||||
24
README.md
24
README.md
@ -1,3 +1,5 @@
|
||||
# ✨️ 概述
|
||||
|
||||
DrissionPage 是一个基于 python 的网页自动化工具。
|
||||
|
||||
它既能控制浏览器，也能收发数据包，甚至能把两者合而为一，
|
||||
@ -14,7 +16,7 @@ DrissionPage 是一个基于 python 的网页自动化工具。
|
||||
|
||||
python 版本：3.6 及以上
|
||||
|
||||
支持浏览器：Chromium 内核浏览器（如 Chrome 和 edge）
|
||||
支持浏览器：Chromium 内核浏览器（如 Chrome 和 Edge）
|
||||
|
||||
***
|
||||
|
||||
@ -96,7 +98,7 @@ python 版本：3.6 及以上
|
||||
|
||||
以下代码实现一模一样的功能，对比两者的代码量：
|
||||
|
||||
✨️ 用显性等待方式定位第一个文本包含`some text`的元素
|
||||
🔸 用显性等待方式定位第一个文本包含`some text`的元素
|
||||
|
||||
```python
|
||||
# 使用 selenium：
|
||||
@ -106,7 +108,7 @@ element = WebDriverWait(driver).until(ec.presence_of_element_located((By.XPATH,
|
||||
element = page('some text')
|
||||
```
|
||||
|
||||
✨️ 跳转到第一个标签页
|
||||
🔸 跳转到第一个标签页
|
||||
|
||||
```python
|
||||
# 使用 selenium：
|
||||
@ -116,7 +118,7 @@ driver.switch_to.window(driver.window_handles[0])
|
||||
page.to_tab(page.tabs[0])
|
||||
```
|
||||
|
||||
✨️ 按文本选择下拉列表
|
||||
🔸 按文本选择下拉列表
|
||||
|
||||
```python
|
||||
# 使用 selenium：
|
||||
@ -129,7 +131,7 @@ select_element.select_by_visible_text('text')
|
||||
element.select('text')
|
||||
```
|
||||
|
||||
✨️ 拖拽一个元素
|
||||
🔸 拖拽一个元素
|
||||
|
||||
```python
|
||||
# 使用 selenium：
|
||||
@ -139,7 +141,7 @@ ActionChains(driver).drag_and_drop(ele1, ele2).perform()
|
||||
ele1.drag_to(ele2)
|
||||
```
|
||||
|
||||
✨️ 滚动窗口到底部（保持水平滚动条不变）
|
||||
🔸 滚动窗口到底部（保持水平滚动条不变）
|
||||
|
||||
```python
|
||||
# 使用 selenium：
|
||||
@ -149,7 +151,7 @@ driver.execute_script("window.scrollTo(document.documentElement.scrollLeft, docu
|
||||
page.scroll.to_bottom()
|
||||
```
|
||||
|
||||
✨️ 获取伪元素内容
|
||||
🔸 获取伪元素内容
|
||||
|
||||
```python
|
||||
# 使用 selenium：
|
||||
@ -160,7 +162,7 @@ text = webdriver.execute_script('return window.getComputedStyle(arguments[0], ":
|
||||
text = element.pseudo_after
|
||||
```
|
||||
|
||||
✨️ shadow-root 操作
|
||||
🔸 shadow-root 操作
|
||||
|
||||
```python
|
||||
# 使用 selenium：
|
||||
@ -174,7 +176,7 @@ ele = shadow_element.ele('tag:div')
|
||||
ele.click()
|
||||
```
|
||||
|
||||
✨️ 随时让浏览器窗口消失和显示（Windows系统）
|
||||
🔸 随时让浏览器窗口消失和显示（Windows系统）
|
||||
|
||||
```python
|
||||
# selenium 无此功能
|
||||
@ -188,7 +190,7 @@ page.show_browser() # 重新显示浏览器窗口
|
||||
|
||||
以下代码实现一模一样的功能，对比两者的代码量：
|
||||
|
||||
✨️ 获取元素内容
|
||||
🔸 获取元素内容
|
||||
|
||||
```python
|
||||
url = 'https://baike.baidu.com/item/python'
|
||||
@ -210,7 +212,7 @@ title = page('tag:h1').text
|
||||
|
||||
Tips: DrissionPage 自带默认`headers`
|
||||
|
||||
✨️ 下载文件
|
||||
🔸 下载文件
|
||||
|
||||
```python
|
||||
url = 'https://www.baidu.com/img/flexible/logo/pc/result.png'
|
||||
|
||||
@ -16,7 +16,7 @@ DrissionPage 是一个基于 python 的网页自动化工具。
|
||||
|
||||
python 版本：3.6 及以上
|
||||
|
||||
支持浏览器：Chromium 内核（如 Chrome 和 edge）
|
||||
支持浏览器：Chromium 内核（如 Chrome 和 Edge）
|
||||
|
||||
***
|
||||
|
||||
|
||||
@ -1,22 +0,0 @@
|
||||
以前的版本是对 selenium 进行重新封装实现的。从 3.0 开始，作者另起炉灶，对底层进行了重新开发，摆脱对 selenium 的依赖，增强了功能，提升了运行效率。
|
||||
3.0 全新开发的页面对象是`WebPage`，支持 chromium 内核的浏览器（如 chrome 和 edge）。除了保持之前的功能，比依赖 selenium 的`MixPage`有以下优点：
|
||||
|
||||
- 无 webdriver 特征，不会被网站识别
|
||||
|
||||
- 无需为不同版本的浏览器下载不同的驱动
|
||||
|
||||
- 运行速度更快
|
||||
|
||||
- 可以跨 iframe 查找元素，无需切入切出
|
||||
|
||||
- 把 iframe 看作普通元素，获取后可直接在其中查找元素，逻辑更清晰
|
||||
|
||||
- 可以同时操作浏览器中的多个标签页，即使标签页为非激活状态，无需切换
|
||||
|
||||
- 可以直接读取浏览器缓存来保存图片，无需用 GUI 点击另存
|
||||
|
||||
- 可以对整个网页截图，包括视口外的部分（90以上版本浏览器支持）
|
||||
|
||||
- 对 Linux 提供良好支持
|
||||
|
||||
新版是自己实现的功能，开发不会受太多限制，以后将主要对`WebPage`进行更新。旧版只会修 bug。
|
||||
@ -22,7 +22,6 @@
|
||||
|
||||
* [🛠 4 使用方法](#)
|
||||
|
||||
* [🔨 4.0 简介](WebPage使用方法\3.0简介.md)
|
||||
* [🔨 4.1 创建页面对象](WebPage使用方法\3.1创建页面对象.md)
|
||||
* [🔨 4.2 访问网页](WebPage使用方法\3.2访问网页.md)
|
||||
* [🔨 4.3 查找元素](WebPage使用方法\3.3查找元素.md)
|
||||
@ -41,6 +40,7 @@
|
||||
* [🗒️ 5.2 浏览器启动配置](启动配置\浏览器启动配置.md)
|
||||
* [🗒️ 5.3 Session 启动配置](启动配置\Session启动配置.md)
|
||||
* [🗒️ 5.4 使用配置文件](启动配置\使用配置文件.md)
|
||||
* [🗒️ 5.5 easy_set 方法](启动配置\easy_set方法.md)
|
||||
|
||||
* [🧰 6 进阶使用](#)
|
||||
|
||||
|
||||
File diff suppressed because one or more lines are too long
@ -31,61 +31,63 @@ page.get('https://gitee.com/login')
|
||||
# 定位到账号文本框，获取文本框元素
|
||||
ele = page.ele('#user_login')
|
||||
# 输入对文本框输入账号
|
||||
ele.input('你的账号')
|
||||
ele.input('您的账号')
|
||||
# 定位到密码文本框并输入密码
|
||||
page.ele('#user_password').input('你的密码')
|
||||
page.ele('#user_password').input('您的密码')
|
||||
# 点击登录按钮
|
||||
page.ele('@value=登 录').click()
|
||||
```
|
||||
|
||||
# ✔️ 示例详解
|
||||
|
||||
首先，我们导入用于控制浏览器的类`ChromiumPage`。
|
||||
我们逐行解读代码：
|
||||
|
||||
```python
|
||||
from DrissionPage import ChromiumPage
|
||||
```
|
||||
|
||||
接下来，我们创建一个`ChromiumPage`对象。
|
||||
↑ 首先，我们导入用于控制浏览器的类`ChromiumPage`。
|
||||
|
||||
```python
|
||||
page = ChromiumPage()
|
||||
```
|
||||
|
||||
`get()`方法用于访问参数中的网址。它会等待页面完全加载，再继续执行后面的代码。您也可以修改等待策略，如等待 DOM 加载而不等待资源下载，就停止加载，这将在后面的章节说明。
|
||||
↑ 接下来，我们创建一个`ChromiumPage`对象。
|
||||
|
||||
```python
|
||||
page.get('https://gitee.com/login')
|
||||
```
|
||||
|
||||
`ele()`方法用于查找元素，它返回一个`ChromiumElement`元素对象，可用于对元素的操作。
|
||||
↑ `get()`方法用于访问参数中的网址。它会等待页面完全加载，再继续执行后面的代码。您也可以修改等待策略，如等待 DOM 加载而不等待资源下载，就停止加载，这将在后面的章节说明。
|
||||
|
||||
```python
|
||||
ele = page.ele('#user_login')
|
||||
```
|
||||
|
||||
↑ `ele()`方法用于查找元素，它返回一个`ChromiumElement`对象，用于操作元素。
|
||||
|
||||
`'#user_login'`是定位符文本，`#`意思是按`id`属性查找元素。
|
||||
|
||||
值得一提的是，`ele()`内置了等待，如果元素未加载，它会执行等待，直到元素出现或到达时限。默认超时时间 10 秒。
|
||||
|
||||
```python
|
||||
ele = page.ele('#user_login')
|
||||
ele.input('您的账号')
|
||||
```
|
||||
|
||||
`input()`方法用于对元素输入文本。
|
||||
↑ `input()`方法用于对元素输入文本。
|
||||
|
||||
```python
|
||||
ele.input('你的账号')
|
||||
page.ele('#user_password').input('您的密码')
|
||||
```
|
||||
|
||||
我们也可以进行链式操作。
|
||||
|
||||
```python
|
||||
page.ele('#user_password').input('你的密码')
|
||||
```
|
||||
|
||||
输入账号密码后，以相同的方法获取按钮元素，并对其执行点击操作。
|
||||
|
||||
不同的是，这次通过其`value`属性作为查找条件。`@`表示按属性名查找。
|
||||
↑ 我们也可以进行链式操作，获取元素后直接输入文本。
|
||||
|
||||
```python
|
||||
page.ele('@value=登 录').click()
|
||||
```
|
||||
|
||||
↑ 输入账号密码后，以相同的方法获取按钮元素，并对其执行点击操作。
|
||||
|
||||
不同的是，这次通过其`value`属性作为查找条件。`@`表示按属性名查找。
|
||||
|
||||
到这里，我们已完成了自动登录 gitee 网站的操作。
|
||||
|
||||
@ -53,40 +53,42 @@ TopIAM/eiam https://gitee.com/topiam/eiam
|
||||
|
||||
# ✔️ 示例详解
|
||||
|
||||
首先，我们导入用于收发数据包的类`SessionPage`。
|
||||
我们逐行解读代码：
|
||||
|
||||
```python
|
||||
from DrissionPage import SessionPage
|
||||
```
|
||||
|
||||
接下来，我们创建一个`SessionPage`对象。
|
||||
↑ 首先，我们导入用于收发数据包的页面类`SessionPage`。
|
||||
|
||||
```python
|
||||
page = SessionPage()
|
||||
```
|
||||
|
||||
然后我们循环 3 次，以构造每页的 url，每次都用`get()`方法访问该页网址。
|
||||
↑ 接下来，我们创建一个`SessionPage`对象。
|
||||
|
||||
```python
|
||||
for i in ranage(1, 4):
|
||||
p.get(f'https://gitee.com/explore/all?page={i}')
|
||||
```
|
||||
|
||||
访问网址后，我们用页面对象的`eles()`获取页面中所有`class`属性为`'title project-namespace-path'`的元素对象。
|
||||
↑ 然后我们循环 3 次，以构造每页的 url，每次都用`get()`方法访问该页网址。
|
||||
|
||||
```python
|
||||
links = p.eles('.title project-namespace-path')
|
||||
```
|
||||
|
||||
↑ 访问网址后，我们用页面对象的`eles()`获取页面中所有`class`属性为`'title project-namespace-path'`的元素对象。
|
||||
|
||||
`eles()`方法用于查找多个符合条件的元素，返回由它们组成的`list`。
|
||||
|
||||
这里查找的条件是`class`属性，`.`表示按`class`属性查找元素。
|
||||
|
||||
```python
|
||||
links = p.eles('.title project-namespace-path')
|
||||
for link in links:
|
||||
print(link.text, link.link)
|
||||
```
|
||||
|
||||
最后，我们遍历获取到的元素列表，获取每个元素的属性并打印出来。
|
||||
↑ 最后，我们遍历获取到的元素列表，获取每个元素的属性并打印出来。
|
||||
|
||||
`.text`获取元素的文本，`.link`获取元素的`href`或`src`属性。
|
||||
|
||||
```python
|
||||
for link in links:
|
||||
print(link.text, link.link)
|
||||
```
|
||||
|
||||
@ -66,52 +66,54 @@ DrissionPagev2.2.1 发布,WEB 自动化测试集成工具
|
||||
|
||||
# ✔️ 示例详解
|
||||
|
||||
首先，我们导入页面对象`WebPage`类。
|
||||
我们逐行解读代码：
|
||||
|
||||
```python
|
||||
from DrissionPage import WebPage
|
||||
```
|
||||
|
||||
接下来，我们创建一个`WebPage`对象。
|
||||
↑ 首先，我们导入页面对象`WebPage`类。
|
||||
|
||||
```python
|
||||
page = WebPage()
|
||||
```
|
||||
|
||||
然后控制浏览器访问百度。
|
||||
↑ 接下来，我们创建一个`WebPage`对象。
|
||||
|
||||
```python
|
||||
page.get('https://www.baidu.com')
|
||||
```
|
||||
|
||||
再通过模拟输入的方式输入关键词，模拟点击搜索按钮。
|
||||
|
||||
这里查找元素的方法上两个示例已经讲过，不再细说。
|
||||
|
||||
`click()`方法里面的`wait_loading`参数用于等待页面进入加载状态，避免操作过快出现异常。
|
||||
↑ 然后控制浏览器访问百度。
|
||||
|
||||
```python
|
||||
page('#kw').input('DrissionPage')
|
||||
page('#su').click(wait_loading=True)
|
||||
```
|
||||
|
||||
`change_mode()`方法用于切换工作模式，从当前控制浏览器的模式切换到收发数据包模式。
|
||||
↑ 再通过模拟输入的方式输入关键词，模拟点击搜索按钮。
|
||||
|
||||
切换的时候程序会在新模式重新访问当前 url。
|
||||
这里查找元素的方法上两个示例已经讲过，不再细说。
|
||||
|
||||
`click()`方法里面的`wait_loading`参数用于等待页面进入加载状态，避免操作过快出现异常。
|
||||
|
||||
```python
|
||||
page.change_mode()
|
||||
```
|
||||
|
||||
切换后，我们可以用与控制浏览器一致的语法，获取页面元素，这里`eles()`方法是获取页面中所有`<h3>`元素，它返回这些元素对象组成的列表。`tag:`是查找条件，表示查找某种类型的元素。
|
||||
↑ `change_mode()`方法用于切换工作模式，从当前控制浏览器的模式切换到收发数据包模式。
|
||||
|
||||
切换的时候程序会在新模式重新访问当前 url。
|
||||
|
||||
```python
|
||||
links = page.eles('tag:h3')
|
||||
```
|
||||
|
||||
最后，我们遍历这些元素，并逐个打印它们包含的文本。
|
||||
↑ 切换后，我们可以用与控制浏览器一致的语法，获取页面元素，这里`eles()`方法是获取页面中所有`<h3>`元素，它返回这些元素对象组成的列表。`tag:`是查找条件，表示查找某种类型的元素。
|
||||
|
||||
```python
|
||||
for link in links:
|
||||
print(link.text)
|
||||
```
|
||||
|
||||
↑ 最后，我们遍历这些元素，并逐个打印它们包含的文本。
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
如果只使用收发数据包功能，无须任何准备工作。
|
||||
|
||||
如果要控制浏览器，须设置浏览器路径。程序默认设置控制 Chrome，所以以下用 Chrome 作为演示。如果要使用 edge 或其它 Chromium 内核浏览器，设置方法是一样的。
|
||||
如果要控制浏览器，须设置浏览器路径。程序默认设置控制 Chrome，所以以下用 Chrome 作为演示。如果要使用 Edge 或其它 Chromium 内核浏览器，设置方法是一样的。
|
||||
|
||||
# ✔️ 执行步骤
|
||||
|
||||
@ -12,11 +12,11 @@
|
||||
|
||||
后面在"创建页面对象"章节再介绍多 Chrome 浏览器共存的方法。
|
||||
|
||||
!>**注意：**<br>如果您使用的是 edge 浏览器，直接关闭不能清干净进程，请打开任务管理器手动关闭进程。
|
||||
!>**注意：**<br>如果您使用的是 Edge 浏览器，直接关闭不能清干净进程，请打开任务管理器手动关闭进程。
|
||||
|
||||
## 📍 尝试启动浏览器
|
||||
|
||||
执行以下代码，如果正常启动了浏览器并且访问了百度，则可跳过后面的步骤。
|
||||
执行以下代码，如果正常启动了浏览器并且访问了百度，说明可直接使用，跳过后面的步骤即可。
|
||||
|
||||
```python
|
||||
from DrissionPage import ChromiumPage
|
||||
@ -27,8 +27,7 @@ page.get('https://www.baidu.com')
|
||||
|
||||
## 📍 设置路径
|
||||
|
||||
如果上面的步骤成功访问了百度，可跳过本条。
|
||||
如果提示出错，请新建一个临时 py 文件，并输入以下代码，填入您电脑里的 Chrome 浏览器 exe 文件路径，然后执行。
|
||||
如果上面的步骤提示出错，请新建一个临时 py 文件，并输入以下代码，填入您电脑里的 Chrome 浏览器 exe 文件路径，然后执行。
|
||||
|
||||
!>**注意：**<br>这段代码只要运行一次即可，不要写到正式程序里。
|
||||
|
||||
@ -38,7 +37,7 @@ from DrissionPage.easy_set import set_paths
|
||||
set_paths(browser_path=r'这里修改为您的Chrome浏览器exe文件路径')
|
||||
```
|
||||
|
||||
执行这段代码会记录您电脑的 Chrome 浏览器路径到配置文件。
|
||||
这段代码会记录 Chrome 浏览器路径到配置文件。
|
||||
|
||||
## 📍 重试控制浏览器
|
||||
|
||||
|
||||
@ -9,16 +9,14 @@
|
||||
- 直接向服务器发送数据包，获取需要的数据
|
||||
- 控制浏览器跟网页进行交互
|
||||
|
||||
前者轻量级，速度快，便于多线程、分布式部署，如 requests 库。但当数据包机构复杂，甚至加入加密技术时，开发过程烧脑程度直线上升。
|
||||
前者轻量级，速度快，便于多线程、分布式部署，如 requests 库。但当数据包构成复杂，甚至加入加密技术时，开发过程烧脑程度直线上升。
|
||||
|
||||
后者使用浏览器模拟人的行为，如 selenium。写起来简单得多，免去复杂的分析过程，但速度非常慢，占用资源巨大。
|
||||
|
||||
鉴于此，DrissionPage 以页面为单位将两者整合，对 chromium 协议 和 requests 进行了重新封装，实现两种模式的互通，并加入常用的页面和元素控制功能，可大幅降低开发难度和代码量。
|
||||
用于操作浏览器的对象叫 Driver，requests 用于管理连接的对象叫 Session，Drission 就是它们两者的合体。
|
||||
鉴于此，DrissionPage 以页面为单位将两者整合，对 Chromium 协议 和 requests 进行了重新封装，实现两种模式的互通，并加入常用的页面和元素控制功能，可大幅降低开发难度和代码量。
|
||||
用于操作浏览器的对象叫 Driver，requests 用于管理连接的对象叫 Session，Drission 就是它们两者的合体。Page 表示以 POM 模式封装。
|
||||
在旧版本，本库是通过对 selenium 和 requests 的重新封装实现的。
|
||||
从 3.0 版开始，作者另起炉灶，用 chromium 协议自行实现了 selenium 全部功能，从而摆脱了对 selenium 的依赖，功能更多更强，运行效率更高，开发更灵活。
|
||||
|
||||
本节只介绍新版的内容，如果您想了解旧版，请查阅“`MixPage`使用方法”章节。
|
||||
如果您想了解旧版，请查阅“旧版使用方法”章节。
|
||||
|
||||
# ✔️ 主要对象
|
||||
|
||||
@ -26,9 +24,9 @@
|
||||
|
||||
## 📍 `ChromiumPage`
|
||||
|
||||
`ChromiumPage`是用于操作浏览器的页面对象，它仅用于操作浏览器，而不能收发数据包。支持 chroium 内核浏览器，如 chrome、edge 等。创建页面对象时，程序会自动启动浏览器，如果指定端口已存在浏览器，就接管该浏览器。
|
||||
`ChromiumPage`是用于操作浏览器的页面对象，它仅用于操作浏览器，而不能收发数据包。支持 Chroium 内核浏览器，如 Chrome、Edge 等。创建页面对象时，程序会自动启动浏览器，如果指定端口已存在浏览器，就接管该浏览器。
|
||||
|
||||
!>**注意：**<br>尝试以下代码前，请先关闭已经打开的 Chrome 浏览器。<br>如果启动失败，请查看“快速上手”一节配置浏览器路径。
|
||||
!>**注意：**<br>尝试以下代码前，请先关闭已经打开的 Chrome 浏览器。<br>如果启动失败，请查看“入门指南”里“准备工作”一节配置浏览器路径。
|
||||
|
||||
```python
|
||||
from DrissionPage import ChromiumPage
|
||||
@ -62,7 +60,7 @@ ele.set_attr('style', 'display:none;')
|
||||
links = ele.eles('tag:a')
|
||||
```
|
||||
|
||||
除了最常用的`ChromiumElement`对象，浏览器还会产生`ChromiumFrame`、`ChromiumShadowRootElement`等对象，详细使用方法见“使用方法”中相关章节。
|
||||
除了最常用的`ChromiumElement`对象，浏览器还会产生`ChromiumFrame`、`ChromiumShadowRootElement`、`ChromiumTab`对象，详细用法见相关章节。
|
||||
|
||||
## 📍 `SessionPage`
|
||||
|
||||
@ -194,12 +192,12 @@ rows = ele.eles('tag:tr')
|
||||
|
||||
# ✔️ 配置管理
|
||||
|
||||
无论 requests 还是浏览器，都通常须要一些配置信息才能正常工作，如长长的`user_agent`、driver 路径、浏览器配置等。这些代码往往是繁琐而重复的，不利于代码的简洁。
|
||||
无论 requests 还是浏览器，都通常须要一些配置信息才能正常工作，如长长的`user_agent`、浏览器 exe 文件路径、浏览器配置等。这些代码往往是繁琐而重复的，不利于代码的简洁。
|
||||
因此，DrissionPage 使用配置文件记录常用配置信息，程序会自动读取默认配置文件里的内容。所以，在示例中，通常看不见配置信息的代码。
|
||||
|
||||
这个功能支持用户保存不同的配置文件，按情况调研，也可以支持直接把配置写在代码里面，屏蔽读取配置文件。
|
||||
|
||||
?> **Tips：** <br>当须要打包程序时，必须把配置写到代码里，或打包后手动复制配置文件到运行路径，否则会报错。详见“”章节。
|
||||
?> **Tips：** <br>当须要打包程序时，必须把配置写到代码里，或打包后手动复制配置文件到运行路径，否则会报错。详见相关章节。
|
||||
|
||||
# ✔️ 定位符
|
||||
|
||||
@ -239,4 +237,4 @@ ele1 = ele.find_element(By.XPATH, './/following-sibling::*') # 获取有i一个
|
||||
ele1 = ele.find_element(By.XPATH, './/preceding-sibling::*[2]') # 获取前面第二个元素
|
||||
```
|
||||
|
||||
显然，本库的定位语句更简洁易懂，还有很多灵活好用的方法，详见“使用方法”里“查找元素章节”。
|
||||
显然，本库的定位语句更简洁易懂，还有很多灵活好用的方法，详见“查找元素”章节。
|
||||
@ -1,10 +1,10 @@
|
||||
# ✔️运行环境
|
||||
# ✔️ 运行环境
|
||||
|
||||
操作系统：Windows、Linux 或 Mac。
|
||||
|
||||
python 版本：3.6 及以上
|
||||
|
||||
支持浏览器：Chromium 内核（如 Chrome 和 edge）
|
||||
支持浏览器：Chromium 内核（如 Chrome 和 Edge）
|
||||
|
||||
# ✔️ 安装
|
||||
|
||||
@ -22,27 +22,62 @@ pip install DrissionPage --upgrade
|
||||
|
||||
# ✔️ 导入
|
||||
|
||||
`WebPage`是功能最全面的页面类，既可控制浏览器，也可收发数据包。通常程序从导入它开始。
|
||||
## 📍 页面类
|
||||
|
||||
页面类用于控制浏览器，或收发数据包，是最主要的工具。`DrissionPage`包含三种主要页面类。根据须要在其中选择使用。
|
||||
|
||||
`WebPage`是功能最全面的页面类，既可控制浏览器，也可收发数据包：
|
||||
|
||||
```python
|
||||
from DrissionPage import WebPage
|
||||
```
|
||||
|
||||
也可以根据具体需要，导入相应的类：
|
||||
如果只要控制浏览器，导入`ChromiumPage`：
|
||||
|
||||
```python
|
||||
# ChromiumPage 只控制浏览器，不能收发数据包
|
||||
from DrissionPage import ChromiumPage
|
||||
```
|
||||
|
||||
# SessionPage 只用于收发数据包，不能控制浏览器
|
||||
如果只要收发数据包，导入`SessionPage`：
|
||||
|
||||
```python
|
||||
from DrissionPage import SessionPage
|
||||
```
|
||||
|
||||
# 浏览启动参数管理器，用于控制浏览器启动参数
|
||||
## 📍 配置类
|
||||
|
||||
很多时候我们须要设置启动参数，可导入以下两个类，但不是必须的。
|
||||
|
||||
`ChromiumOptions`类用于设置浏览器启动参数：
|
||||
|
||||
```python
|
||||
from DrissionPage import ChromiumOptions
|
||||
```
|
||||
|
||||
# Session对象启动参数管理器，用于控制Session对象启动参数
|
||||
`SessionOptions`类用于设置`Session`对象启动参数：
|
||||
|
||||
```
|
||||
from DrissionPage import SessionOptions
|
||||
```
|
||||
|
||||
# 动作链类，用于模拟一连串鼠标键盘动作
|
||||
## 📍 其它工具
|
||||
|
||||
有两个我们可能须要用到的工具，需要时可以导入。
|
||||
|
||||
动作链，用于模拟一系列键盘和鼠标的操作：
|
||||
|
||||
```python
|
||||
from DrissionPage import ActionChains
|
||||
```
|
||||
|
||||
键盘按键类，用于键入 ctrl、alt 等按键：
|
||||
|
||||
```python
|
||||
from DrissionPage import Keys
|
||||
```
|
||||
|
||||
`easy_set`里保存了一些便捷的 ini 文件设置方法，可选择使用：
|
||||
|
||||
```python
|
||||
from DrissionPage.easy_set import *
|
||||
```
|
||||
|
||||
@ -3,49 +3,100 @@
|
||||
|
||||
!> **注意：** <br>`SessionOptions`仅用于管理启动配置，程序启动后再修改无效。
|
||||
|
||||
# ✔️ `SessionOptions`类
|
||||
# ✔️ 创建对象
|
||||
|
||||
`SessionOptions`对象创建时默认读取默认 ini 文件配置信息，也可手动设置所需信息。
|
||||
该类的方法支持链式操作。
|
||||
## 📍 导入
|
||||
|
||||
**初始化参数：**
|
||||
```python
|
||||
from DrissionPage import SessionOptions
|
||||
```
|
||||
|
||||
- `read_file`：是否从默认 ini 文件中读取配置信息
|
||||
- `ini_path`：ini 文件路径，为`None`则读取默认 ini 文件
|
||||
## 📍 `SessionOptions`
|
||||
|
||||
## 📍 `headers`
|
||||
`SessionOptions`对象用于管理 Session 对象的初始化配置。可从配置文件中读取配置来进行初始化。
|
||||
|
||||
该属性返回`headers`设置信息，可传入字典赋值。
|
||||
| 初始化参数 | 类型 | 默认值 | 说明 |
|
||||
|:-----------:|:---------------:|:------:| ---------------------------------- |
|
||||
| `read_file` | `bool` | `True` | 是否从 ini 文件中读取配置信息，为`False`则用默认配置创建 |
|
||||
| `ini_path` | `Path`<br>`str` | `None` | 指定 ini 文件路径，为`None`则读取内置 ini 文件 |
|
||||
|
||||
创建配置对象：
|
||||
|
||||
```python
|
||||
from DrissionPage import SessionOptions
|
||||
|
||||
so = SessionOptions()
|
||||
```
|
||||
|
||||
默认情况下，`SessionOptions`对象会从 ini 文件中读取配置信息，当指定`read_file`参数为`False`时，则以默认配置创建。
|
||||
|
||||
***
|
||||
|
||||
# ✔️ 使用方法
|
||||
|
||||
创建配置对象后，可调整配置内容，然后在页面对象创建时以参数形式把配置对象传递进去。
|
||||
|
||||
```python
|
||||
from DrissionPage import SessionPage, SessionOptions
|
||||
|
||||
# 创建配置对象（默认从 ini 文件中读取配置）
|
||||
so = SessionOptions()
|
||||
# 设置代理
|
||||
so.set_proxies('http://localhost:1080')
|
||||
# 设置 cookies
|
||||
cookies = ['key1=val1; domain=xxxx', 'key2=val2; domain=xxxx']
|
||||
so.set_cookies(cookies)
|
||||
|
||||
# 以该配置创建页面对象
|
||||
page = SessionPage(session_or_options=so)
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
# ✔️ 设置方法
|
||||
|
||||
## 📍 `set_headers()`
|
||||
|
||||
该方法与`headers`参数赋值功能一致。
|
||||
该方法用于设置整个 headers 参数，传入值会覆盖原来的 headers。
|
||||
|
||||
**参数：**
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:--------:|:------:|:---:| -------------- |
|
||||
| `headers | `dict` | 无 | 完整的 headers 字典 |
|
||||
|
||||
- `headers`：`headers`字典
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
**返回：** 当前对象
|
||||
**示例：**
|
||||
|
||||
```python
|
||||
so.set_headers = {'user-agent': 'Mozilla/5.0 (Macint...', 'connection': 'keep-alive' ...}
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 📍 `set_a_header()`
|
||||
|
||||
该方法用于设置`headers`中的一个项。
|
||||
|
||||
**参数：**
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:-------:|:-----:|:---:| ---- |
|
||||
| `attr` | `str` | 无 | 设置名称 |
|
||||
| `value` | `str` | 无 | 设置值 |
|
||||
|
||||
- `attr`：设置项名称
|
||||
- `value`：设置值
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
**返回：** 当前对象
|
||||
**示例：**
|
||||
|
||||
```python
|
||||
so = SessionOptions()
|
||||
so.set_a_header('accept', 'text/html')
|
||||
so.set_a_header('Accept-Charset', 'GB2312')
|
||||
|
||||
print(so.headers)
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
输出：
|
||||
|
||||
```
|
||||
@ -56,116 +107,376 @@ print(so.headers)
|
||||
|
||||
此方法用于从`headers`中移除一个设置项。
|
||||
|
||||
**参数：**
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:------:|:-----:|:---:| ------ |
|
||||
| `attr` | `str` | 无 | 要删除的设置 |
|
||||
|
||||
- `attr`：要删除的设置名称
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
**返回：** 当前对象
|
||||
**示例：**
|
||||
|
||||
```python
|
||||
so.remove_a_header('accept')
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 📍 `set_cookies()`
|
||||
|
||||
此方法用于设置 cookies 信息，每次设置会覆盖之前所有 cookies 信息。
|
||||
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:---------:|:-----------------------------------------------------------:|:---:| ------- |
|
||||
| `cookies` | `RequestsCookieJar`<br>`list`<br>`tuple`<br>`str`<br>`dict` | 无 | cookies |
|
||||
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
**示例：**
|
||||
|
||||
```python
|
||||
cookies = ['key1=val1; domain=xxxx', 'key2=val2; domain=xxxx']
|
||||
so.set_cookies(cookies)
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 📍 `set_timeout()`
|
||||
|
||||
此方法用于设置超时属性。
|
||||
此方法用于设置连接超时属性。
|
||||
|
||||
**参数：**
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:--------:|:----------------:|:---:| ------ |
|
||||
| `second` | `int`<br>`float` | 无 | 连接等待秒数 |
|
||||
|
||||
- `second`：秒数
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
**返回：** 当前对象
|
||||
|
||||
## 📍 `cookies`
|
||||
|
||||
此属性返回`cookies`设置信息，可赋值。
|
||||
可接收`dict`、`list`、`tuple`、`str`、`RequestsCookieJar`等格式的信息。
|
||||
|
||||
## 📍 `proxies`
|
||||
|
||||
此属性返回代理信息，可赋值。可传入字典类型。
|
||||
**格式：**{'http': 'http://xx.xx.xx.xx:xxxx', 'https': 'http://xx.xx.xx.xx:xxxx'}
|
||||
***
|
||||
|
||||
## 📍 `set_proxies()`
|
||||
|
||||
此方法与`proxies`属性赋值功能一致。
|
||||
此方法用于设置代理信息。
|
||||
|
||||
**参数：**
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:-------:|:-----:|:------:| ------------------------------- |
|
||||
| `http` | `str` | 无 | http 代理地址 |
|
||||
| `https` | `str` | `None` | https 代理地址，为`None`时使用`http`参数的值 |
|
||||
|
||||
- `proxies`：`dict`格式的代理参数
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
**返回：** 当前对象
|
||||
**示例：**
|
||||
|
||||
## 📍 `auth`
|
||||
```python
|
||||
so.set_proxies('http://127.0.0.1:1080')
|
||||
```
|
||||
|
||||
此属性用于返回和设置`auth`参数，接收`tuple`类型参数。
|
||||
***
|
||||
|
||||
## 📍 `hooks`
|
||||
## 📍 `set_paths()`
|
||||
|
||||
此属性用于返回和设置`hooks`参数，接收`dict`类型参数。
|
||||
此方法用于设置路径信息，目前只有`download_path`一种。
|
||||
|
||||
## 📍 `params`
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:---------------:|:---------------:|:---:| -------- |
|
||||
| `download_path` | `str`<br>`Path` | 无 | 默认下载保存路径 |
|
||||
|
||||
此属性用于返回和设置`params`参数，接收`dict`类型参数。
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
## 📍 `verify`
|
||||
***
|
||||
|
||||
此属性用于返回和设置`verify`参数，接收`bool`类型参数。
|
||||
## 📍 `set_auth()`
|
||||
|
||||
## 📍 `cert`
|
||||
此方法用于设置认证元组信息。
|
||||
|
||||
此属性用于返回和设置`cert`参数，接收`str`或`tuple`类型参数。
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:------:|:--------------------------:|:---:| ------- |
|
||||
| `auth` | `tuple`<br>`HTTPBasicAuth` | 无 | 认证元组或对象 |
|
||||
|
||||
## 📍 `adapters`
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
此属性用于返回和设置`adapters`参数。
|
||||
***
|
||||
|
||||
## 📍 `stream`
|
||||
## 📍 `set_hooks()`
|
||||
|
||||
此属性用于返回和设置`stream`参数，接收`bool`类型参数。
|
||||
此方法用于设置回调方法。
|
||||
|
||||
## 📍 `trust_env`
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:-------:|:------:|:---:| ---- |
|
||||
| `hooks` | `dict` | 无 | 回调方法 |
|
||||
|
||||
此属性用于返回和设置`trust_env`参数，接收`bool`类型参数。
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
## 📍 `max_redirects`
|
||||
***
|
||||
|
||||
此属性用于返回和设置`max_redirects`参数，接收`int`类型参数。
|
||||
## 📍 `set_params()`
|
||||
|
||||
此方法用于设置查询参数。
|
||||
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:--------:|:------:|:---:| ------ |
|
||||
| `params` | `dict` | 无 | 查询参数字典 |
|
||||
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
***
|
||||
|
||||
## 📍 `set_cert()`
|
||||
|
||||
此方法用于设置 SSL 客户端证书文件的路径（.pem格式），或 ('cert', 'key') 元组。
|
||||
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:------:|:----------------:|:---:| ------- |
|
||||
| `cert` | `str`<br>`tuple` | 无 | 证书路径或元组 |
|
||||
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
***
|
||||
|
||||
## 📍 `set_verify()`
|
||||
|
||||
此方法用于设置是否验证SSL证书。
|
||||
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:--------:|:------:|:---:| ----------- |
|
||||
| `on_off` | `bool` | 无 | `bool`表示开或关 |
|
||||
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
***
|
||||
|
||||
## 📍 `add_adapter()`
|
||||
|
||||
此方法用于添加适配器。
|
||||
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:---------:|:-------------:|:---:| --------- |
|
||||
| `url` | `str` | 无 | 适配器对应 url |
|
||||
| `adapter` | `HTTPAdapter` | 无 | 适配器对象 |
|
||||
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
***
|
||||
|
||||
## 📍 `set_stream()`
|
||||
|
||||
此方法用于设置是否使用流式响应内容。
|
||||
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:--------:|:------:|:---:| ----------- |
|
||||
| `on_off` | `bool` | 无 | `bool`表示开或关 |
|
||||
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
***
|
||||
|
||||
## 📍 `set_trust_env()`
|
||||
|
||||
此方法用于设置是否信任环境。
|
||||
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:--------:|:------:|:---:| ----------- |
|
||||
| `on_off` | `bool` | 无 | `bool`表示开或关 |
|
||||
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
***
|
||||
|
||||
## 📍 `set_max_redirects()`
|
||||
|
||||
此方法用于设置最大重定向次数。
|
||||
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:-------:|:-----:|:---:| ------- |
|
||||
| `times` | `int` | 无 | 最大重定向次数 |
|
||||
|
||||
| 返回类型 | 说明 |
|
||||
| ---------------- | ------ |
|
||||
| `SessionOptions` | 配置对象本身 |
|
||||
|
||||
***
|
||||
|
||||
# ✔️ 保存设置到文件
|
||||
|
||||
您可以把不同的配置保存到各自的 ini 文件，以便适应不同的场景。
|
||||
|
||||
!>**注意：**<br>`hooks`和`adapters`配置是不会保存到文件中的。
|
||||
|
||||
## 📍 `save()`
|
||||
|
||||
此方法用于保存当前配置对象的信息到配置文件。
|
||||
此方法用于保存配置项到一个 ini 文件。
|
||||
|
||||
**参数：**
|
||||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||||
|:------:|:---------------:|:------:| ------------------------------- |
|
||||
| `path` | `str`<br>`Path` | `None` | ini 文件的路径， 传入`None`保存到当前读取的配置文件 |
|
||||
|
||||
- `path`：配置文件的路径，默认保存到当前读取的配置文件，传入`'default'`保存到默认 ini 文件
|
||||
| 返回类型 | 说明 |
|
||||
| ----- | -------------- |
|
||||
| `str` | 保存的 ini 文件绝对路径 |
|
||||
|
||||
**返回：** 配置文件绝对路径
|
||||
**示例：**
|
||||
|
||||
```python
|
||||
# 保存当前读取的ini文件
|
||||
so.save()
|
||||
|
||||
# 把当前配置保存到指定的路径
|
||||
so.save(path=r'D:\tmp\settings.ini')
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 📍 `save_to_default()`
|
||||
|
||||
此方法用于保存当前配置对象的信息到默认 ini 文件。
|
||||
此方法用于保存配置项到固定的默认 ini 文件。默认 ini 文件是指随`DrissionPage`内置的那个。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 配置文件绝对路径
|
||||
| 返回类型 | 说明 |
|
||||
| ----- | -------------- |
|
||||
| `str` | 保存的 ini 文件绝对路径 |
|
||||
|
||||
## 📍 `as_dict()`
|
||||
|
||||
该方法以`dict`方式返回所有配置信息。
|
||||
|
||||
**参数：** 无
|
||||
|
||||
**返回：** 配置信息
|
||||
|
||||
# ✔️ 简单示例
|
||||
**示例：**
|
||||
|
||||
```python
|
||||
from DrissionPage import WebPage, SessionOptions
|
||||
|
||||
# 创建配置对象（默认从 ini 文件中读取配置）
|
||||
so = SessionOptions()
|
||||
# 设置 cookies
|
||||
so.cookies = ['key1=val1; domain=xxxx', 'key2=val2; domain=xxxx']
|
||||
# 设置 headers 一个参数
|
||||
so.set_a_header('Connection', 'keep-alive')
|
||||
|
||||
# 以该配置创建页面对象
|
||||
page = WenPage(mode='s', session_or_options=so)
|
||||
so.save_to_default()
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
# ✔️ `SessionOptions`属性
|
||||
|
||||
## 📍 `headers`
|
||||
|
||||
该属性返回 headers 设置信息。
|
||||
|
||||
**类型：**`dict`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `cookies`
|
||||
|
||||
此属性以`list`方式返回 cookies 设置信息。
|
||||
|
||||
**类型：**`list`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `proxies`
|
||||
|
||||
此属性返回代理信息。
|
||||
|
||||
**类型：**`dict`
|
||||
**格式：**{'http': 'http://xx.xx.xx.xx:xxxx', 'https': 'http://xx.xx.xx.xx:xxxx'}
|
||||
|
||||
***
|
||||
|
||||
## 📍 `auth`
|
||||
|
||||
此属性返回认证设置。
|
||||
|
||||
**类型：**`tuple`、`HTTPBasicAuth`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `hooks`
|
||||
|
||||
此属性返回回调方法设置。
|
||||
|
||||
**类型：**`dict`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `params`
|
||||
|
||||
此属性返回查询参数设置。
|
||||
|
||||
**类型：**`dict`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `verify`
|
||||
|
||||
此属性返回是否验证 SSL 证书设置。
|
||||
|
||||
**类型：**`bool`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `cert`
|
||||
|
||||
此属性返回 SSL 证书设置。
|
||||
|
||||
**类型：**`str`、`tuple`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `adapters`
|
||||
|
||||
此属性返回适配器设置。
|
||||
|
||||
**类型：**`List[HTTPAdapter]`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `stream`
|
||||
|
||||
此属性返回是否使用流式响应设置。
|
||||
|
||||
**类型：**`bool`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `trust_env`
|
||||
|
||||
此属性返回是否信任环境设置。
|
||||
|
||||
**类型：**`bool`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `max_redirects`
|
||||
|
||||
此属性返回`max_redirects`设置。
|
||||
|
||||
**类型：**`int`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `timeout`
|
||||
|
||||
此属性返回连接超时设置。
|
||||
|
||||
**类型：**`int`、`float`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `download_path`
|
||||
|
||||
此属性返回默认下载路径设置。
|
||||
|
||||
**类型：**`str`
|
||||
|
||||
134
docs/启动配置/easy_set方法.md
Normal file
134
docs/启动配置/easy_set方法.md
Normal file
@ -0,0 +1,134 @@
|
||||
Chrome 浏览器的配置繁琐且难以记忆，本库提供一些常用功能的快速设置方法，调用即可修改 ini 文件中该部分内容。
|
||||
|
||||
!> **注意：** <br>easy_set 方法仅用于设置 ini 文件，浏览器或 Session 创建后再调用没有效果的。 <br>如果是接管已打开的浏览器，这些设置也没有用。<br>这些方法只是便于修改 ini 文件，不要写在正式代码中。
|
||||
|
||||
## 📍 简单示例
|
||||
|
||||
```python
|
||||
# 导入
|
||||
from DrissionPage.easy_set import set_headless
|
||||
|
||||
# 设置无头模式
|
||||
set_headless(True)
|
||||
```
|
||||
|
||||
## 📍 `show_settings()`
|
||||
|
||||
该方法用于打印 ini 文件内容。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `ini_path`：ini 文件路径，默认读取默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_paths()`
|
||||
|
||||
该方法用于设置浏览器用到的几种路径信息，设置后可检查 driver 是否和浏览器匹配。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `driver_path`：chromedriver.exe 路径
|
||||
- `chrome_path`：chrome.exe 路径
|
||||
- `local_port`：本地端口号
|
||||
- `debugger_address`：调试浏览器地址，会覆盖 local_port 设置，例：127.0.0.1:9222
|
||||
- `download_path`：下载文件路径
|
||||
- `tmp_path`：临时文件夹路径，暂时没有作用
|
||||
- `user_data_path`：用户数据路径
|
||||
- `cache_path`：缓存路径
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
- `check_version`：是否检查 chromedriver 和 Chrome 是否匹配
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_headless()`
|
||||
|
||||
该方法用于设置是否已无头模式启动浏览器。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `on_off`：`bool`类型，表示开或关
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_no_imgs()`
|
||||
|
||||
该方法用于设置是否禁止加载图片。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `on_off`：`bool`类型，表示开或关
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_mute()`
|
||||
|
||||
该方法用于设置是否静音。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `on_off`：`bool`类型，表示开或关
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_proxy()`
|
||||
|
||||
该方法用于设置代理。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `proxy`: 代理网址和端口，如 127.0.0.1:1080
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_user_agent()`
|
||||
|
||||
该方法用于设置 user agent。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `user_agent`：user agent 文本
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_argument()`
|
||||
|
||||
该方法用于设置浏览器配置 argument 属性。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `arg`：属性名
|
||||
- `value`：属性值，有值的属性传入值。没有的传入`bool`表示开或关
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `check_driver_version()`
|
||||
|
||||
该方法用于检查传入的 chrome 和 chromedriver 是否匹配。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `driver_path`：chromedriver.exe 路径
|
||||
- `chrome_path`：chrome.exe 路径
|
||||
|
||||
**返回：**`bool`类型，表示是否匹配
|
||||
|
||||
## 📍 `get_match_drive()`
|
||||
|
||||
该方法用于自动识别 chrome 版本并下载匹配的 driver。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `ini_path`：要读取和修改的 ini 文件路径
|
||||
- `save_path`：chromedriver 保存路径
|
||||
- `chrome_path`：指定 chrome.exe 位置，不指定会自动依次在 ini 文件、注册表、系统路径中查找
|
||||
- `show_msg`：是否打印信息
|
||||
- `check_version`：是否检查版本匹配
|
||||
|
||||
**返回：** 成功返回 driver 路径，失败返回`None`
|
||||
@ -7,71 +7,34 @@
|
||||
|
||||
# ✔️ ini 文件内容
|
||||
|
||||
ini 文件默认拥有三部分配置：`paths`、`chrome_options`、`session_options`，初始内容如下。
|
||||
ini 文件初始内容如下。
|
||||
|
||||
```
|
||||
[paths]
|
||||
; chromedriver.exe路径
|
||||
chromedriver_path =
|
||||
|
||||
; 临时文件夹路径，暂时没有实际作用
|
||||
tmp_path =
|
||||
chromedriver_path =
|
||||
download_path =
|
||||
|
||||
[chrome_options]
|
||||
; 浏览器默认地址和端口，程序会启动或接管这个端口的浏览器进程
|
||||
debugger_address = 127.0.0.1:9222
|
||||
|
||||
; 浏览器可执行文件路径
|
||||
binary_location = chrome
|
||||
|
||||
; 配置信息
|
||||
arguments = [
|
||||
; 屏蔽欢迎页面
|
||||
'--no-first-run',
|
||||
; 不使用沙盒
|
||||
'--no-sandbox',
|
||||
; 谷歌文档提到需要加上这个属性来规避bug
|
||||
'--disable-gpu',
|
||||
; 忽略链接不安全页面提示
|
||||
'--ignore-certificate-errors',
|
||||
; 不显示信息栏
|
||||
'--disable-infobars',
|
||||
; 允许弹窗
|
||||
'--disable-popup-blocking'
|
||||
]
|
||||
|
||||
; 插件
|
||||
arguments = ['--no-first-run', '--no-sandbox', '--disable-gpu', '--ignore-certificate-errors', '--disable-infobars', '--disable-popup-blocking']
|
||||
extensions = []
|
||||
|
||||
; 实验性配置
|
||||
experimental_options = {
|
||||
'prefs': {
|
||||
; 下载不弹出窗口
|
||||
'profile.default_content_settings.popups': 0,
|
||||
; 无弹窗
|
||||
'profile.default_content_setting_values': {'notifications': 2},
|
||||
; 禁用PDF插件
|
||||
'plugins.plugins_list': [{"enabled": False, "name": "Chrome PDF Viewer"}]
|
||||
},
|
||||
; 设置为开发者模式
|
||||
'excludeSwitches': ["enable-automation"],
|
||||
'useAutomationExtension': False
|
||||
}
|
||||
|
||||
; 超时设置
|
||||
timeouts = {'implicit': 10.0, 'pageLoad': 30.0, 'script': 30.0}
|
||||
|
||||
; 页面加载策略
|
||||
experimental_options = {'prefs': {'profile.default_content_settings.popups': 0, 'profile.default_content_setting_values': {'notifications': 2}, 'plugins.plugins_list': [{'enabled': False, 'name': 'Chrome PDF Viewer'}]}, 'useAutomationExtension': False, 'excludeSwitches': ['enable-automation']}
|
||||
page_load_strategy = normal
|
||||
user = Default
|
||||
auto_port = False
|
||||
|
||||
[session_options]
|
||||
headers = {
|
||||
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/603.3.8 (KHTML, like Gecko) Version/10.1.2 Safari/603.3.8",
|
||||
"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
|
||||
"Connection": "keep-alive",
|
||||
"Accept-Charset": "utf-8;q=0.7,*;q=0.7"
|
||||
}
|
||||
timeout = 10
|
||||
headers = {'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/603.3.8 (KHTML, like Gecko) Version/10.1.2 Safari/603.3.8', 'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8', 'connection': 'keep-alive', 'accept-charset': 'GB2312,utf-8;q=0.7,*;q=0.7'}
|
||||
|
||||
[timeouts]
|
||||
implicit = 10
|
||||
page_load = 30
|
||||
script = 30
|
||||
|
||||
[proxies]
|
||||
http =
|
||||
https =
|
||||
```
|
||||
|
||||
# ✔️ 文件位置
|
||||
@ -98,8 +61,8 @@ page = WebPage()
|
||||
```python
|
||||
from DrissionPage import ChromiumOptions, SessionOptions, WebPage
|
||||
|
||||
do = ChromiumOptions(ini_path='D:\\setting.ini')
|
||||
so = SessionOptions(ini_path='D:\\setting.ini')
|
||||
do = ChromiumOptions(ini_path=r'D:\setting.ini')
|
||||
so = SessionOptions(ini_path=r'D:\setting.ini')
|
||||
|
||||
page = WebPage(driver_or_options=do, session_or_options=so)
|
||||
```
|
||||
@ -122,150 +85,15 @@ page = MixPage(drission=ds)
|
||||
```python
|
||||
from DrissionPage import ChromiumOptions
|
||||
|
||||
do = ChromiumOptions()
|
||||
# 设置不加载图片
|
||||
do.set_no_imgs()
|
||||
co = ChromiumOptions()
|
||||
|
||||
# 保存到默认 ini 文件
|
||||
do.save()
|
||||
# 修改一些设置
|
||||
co.set_no_imgs()
|
||||
|
||||
# 保存到其它位置的配置文件
|
||||
do.save(r'D:\config1.ini')
|
||||
# 保存到当前打开的ini文件
|
||||
co.save()
|
||||
# 保存到指定位置的配置文件
|
||||
co.save(r'D:\config1.ini')
|
||||
# 保存到默认配置文件
|
||||
co.save_to_default()
|
||||
```
|
||||
|
||||
# ✔️ easy_set 方法
|
||||
|
||||
Chrome 浏览器的配置繁琐且难以记忆，本库提供一些常用功能的快速设置方法，调用即可修改 ini 文件中该部分内容。
|
||||
|
||||
!> **注意：** <br>easy_set 方法仅用于设置 ini 文件，浏览器或 Session 创建后再调用没有效果的。 <br>如果是接管已打开的浏览器，这些设置也没有用。<br>这些方法只是便于修改 ini 文件，不要写在正式代码中。
|
||||
|
||||
## 📍 简单示例
|
||||
|
||||
```python
|
||||
# 导入
|
||||
from DrissionPage.easy_set import set_headless
|
||||
|
||||
# 设置无头模式
|
||||
set_headless(True)
|
||||
```
|
||||
|
||||
## 📍 `show_settings()`
|
||||
|
||||
该方法用于打印 ini 文件内容。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `ini_path`：ini 文件路径，默认读取默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_paths()`
|
||||
|
||||
该方法用于设置浏览器用到的几种路径信息，设置后可检查 driver 是否和浏览器匹配。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `driver_path`：chromedriver.exe 路径
|
||||
- `chrome_path`：chrome.exe 路径
|
||||
- `local_port`：本地端口号
|
||||
- `debugger_address`：调试浏览器地址，会覆盖 local_port 设置，例：127.0.0.1:9222
|
||||
- `download_path`：下载文件路径
|
||||
- `tmp_path`：临时文件夹路径，暂时没有作用
|
||||
- `user_data_path`：用户数据路径
|
||||
- `cache_path`：缓存路径
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
- `check_version`：是否检查 chromedriver 和 Chrome 是否匹配
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_headless()`
|
||||
|
||||
该方法用于设置是否已无头模式启动浏览器。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `on_off`：`bool`类型，表示开或关
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_no_imgs()`
|
||||
|
||||
该方法用于设置是否禁止加载图片。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `on_off`：`bool`类型，表示开或关
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_mute()`
|
||||
|
||||
该方法用于设置是否静音。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `on_off`：`bool`类型，表示开或关
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_proxy()`
|
||||
|
||||
该方法用于设置代理。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `proxy`: 代理网址和端口，如 127.0.0.1:1080
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_user_agent()`
|
||||
|
||||
该方法用于设置 user agent。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `user_agent`：user agent 文本
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `set_argument()`
|
||||
|
||||
该方法用于设置浏览器配置 argument 属性。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `arg`：属性名
|
||||
- `value`：属性值，有值的属性传入值。没有的传入`bool`表示开或关
|
||||
- `ini_path`：要修改的 ini 文件路径，默认设置默认 ini 文件
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
## 📍 `check_driver_version()`
|
||||
|
||||
该方法用于检查传入的 chrome 和 chromedriver 是否匹配。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `driver_path`：chromedriver.exe 路径
|
||||
- `chrome_path`：chrome.exe 路径
|
||||
|
||||
**返回：**`bool`类型，表示是否匹配
|
||||
|
||||
## 📍 `get_match_drive()`
|
||||
|
||||
该方法用于自动识别 chrome 版本并下载匹配的 driver。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `ini_path`：要读取和修改的 ini 文件路径
|
||||
- `save_path`：chromedriver 保存路径
|
||||
- `chrome_path`：指定 chrome.exe 位置，不指定会自动依次在 ini 文件、注册表、系统路径中查找
|
||||
- `show_msg`：是否打印信息
|
||||
- `check_version`：是否检查版本匹配
|
||||
|
||||
**返回：** 成功返回 driver 路径，失败返回`None`
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
浏览器的启动配置非常繁杂，本库使用`ChromiumOptions`类管理启动配置，并且内置了常用配置的设置接口。
|
||||
|
||||
需要注意的是，该对象只能用于浏览器的启动，浏览器启动后，再修改该配置没有任何效果。接管已打开的浏览器时，启动配置也是无效的。
|
||||
!> **注意：** <br>该对象只能用于浏览器的启动，浏览器启动后，再修改该配置没有任何效果。接管已打开的浏览器时，启动配置也是无效的。
|
||||
|
||||
# ✔️ 创建对象
|
||||
|
||||
@ -49,18 +49,6 @@ page = WebPage(driver_or_options=co)
|
||||
|
||||
***
|
||||
|
||||
# ✔️ 浏览器地址
|
||||
|
||||
## 📍 `debugger_address`
|
||||
|
||||
该属性为要控制的浏览器地址，格式为 ip:port，默认为`'127.0.0.0:9222'`。可对其赋值进行设置。也可以用后文介绍的`set_paths()`方法设置。
|
||||
|
||||
```python
|
||||
co.debugger_address = 'localhost:9333'
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
# ✔️ 启动参数配置
|
||||
|
||||
Chromium 内核浏览器有一系列的启动配置，以`--`开头，可在浏览器创建时传入。如`--headless`无界面模式，`--disable-images`禁用图像等。有些参数只有参数名，有些会带有值。
|
||||
@ -501,7 +489,7 @@ co.set_user_agent(user_agent='Mozilla/5.0 (Macintos.....')
|
||||
co.save()
|
||||
|
||||
# 把当前配置保存到指定的路径
|
||||
co.save(path=r'D:\tmp')
|
||||
co.save(path=r'D:\tmp\settings.ini')
|
||||
```
|
||||
|
||||
***
|
||||
@ -521,3 +509,113 @@ co.save(path=r'D:\tmp')
|
||||
```python
|
||||
co.save_to_default()
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
# ✔️ `ChromiumOptions`属性
|
||||
|
||||
## 📍 `debugger_address`
|
||||
|
||||
该属性为要控制的浏览器地址，格式为 ip:port，默认为`'127.0.0.0:9222'`。可对其赋值进行设置。也可以用后文介绍的`set_paths()`方法设置。
|
||||
|
||||
**类型：**`str`
|
||||
|
||||
```python
|
||||
co.debugger_address = 'localhost:9333'
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 📍 `browser_path`
|
||||
|
||||
该属性返回浏览器可执行文件的路径。
|
||||
|
||||
**类型：**`str`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `user_data_path`
|
||||
|
||||
该属性返回用户数据文件夹路径。
|
||||
|
||||
**类型：**`str`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `download_path`
|
||||
|
||||
该属性返回默认下载路径文件路径。
|
||||
|
||||
**类型：**`str`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `user`
|
||||
|
||||
该属性返回用户配置文件夹名称。
|
||||
|
||||
**类型：**`str`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `page_load_strategy`
|
||||
|
||||
该属性返回页面加载策略。有`'normal'`、`'eager'`、`'none'`三种
|
||||
|
||||
**类型：**`str`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `timeouts`
|
||||
|
||||
该属性返回超时设置。包括三种：`'implicit'`、`'pageLoad'`、`'script'`。
|
||||
|
||||
**类型：**`dict`
|
||||
|
||||
```python
|
||||
print(co.timeouts)
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```console
|
||||
{
|
||||
'implicit': 10,
|
||||
'pageLoad': 30,
|
||||
'script': 30
|
||||
}
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 📍 `proxy`
|
||||
|
||||
该属性返回代理设置。
|
||||
|
||||
**类型：**`str`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `arguments`
|
||||
|
||||
该属性以`list`形式返回浏览器启动参数。
|
||||
|
||||
**类型：**`list`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `extensions`
|
||||
|
||||
该属性以`list`形式返回要加载的插件路径。
|
||||
|
||||
**类型：**`list`
|
||||
|
||||
***
|
||||
|
||||
## 📍 `preferences`
|
||||
|
||||
该属性返回用户首选项配置。
|
||||
|
||||
**类型：**`dict`
|
||||
|
||||
***
|
||||
|
||||
@ -28,9 +28,9 @@ page = ChromiumPage()
|
||||
page.get('https://gitee.com/login')
|
||||
|
||||
# 定位到账号文本框并输入账号
|
||||
page.ele('#user_login').input('你的账号')
|
||||
page.ele('#user_login').input('您的账号')
|
||||
# 定位到密码文本框并输入密码
|
||||
page.ele('#user_password').input('你的密码')
|
||||
page.ele('#user_password').input('您的密码')
|
||||
|
||||
# 点击登录按钮
|
||||
page.ele('@value=登 录').click()
|
||||
|
||||
@ -1,220 +0,0 @@
|
||||
浏览器缺乏对下载文件的有效管理，难以进行检测下载状态、重命名、失败管理。
|
||||
使用 requests 下载文件能较好实现以上功能，但代码较为繁琐。
|
||||
因此 DrissionPage 提供了高效可靠的下载工具，整合了两者优点，可从浏览器获取登录信息，用 requests 进行下载。弥补了浏览器对下载支持的不足，使下载简洁高效。
|
||||
|
||||
?> 为了增强灵活性，该工具现在独立打包成一个库，叫 DownloadKit，详细用法见：[DownloadKit](https://gitee.com/g1879/DownloadKit)
|
||||
|
||||
# ✔️ 功能
|
||||
|
||||
- 支持多线程同时下载多个文件
|
||||
- 大文件自动分块使用多线程下载
|
||||
- 自动任务调度，简易的任务添加方式
|
||||
- 支持 d 模式下用 requests 下载文件
|
||||
- 自动创建目标路径
|
||||
- 自动去除路径中的非法字符
|
||||
- 下载时支持文件重命名
|
||||
- 自动处理文件名冲突
|
||||
- 显示下载进度
|
||||
- 支持 post 方式
|
||||
- 支持自定义连接参数
|
||||
- 任务失败自动重试
|
||||
|
||||
# ✔️ 单线程下载方式
|
||||
|
||||
页面对象的`download`属性是一个`DownloadKit`对象，为尽量与旧版兼容，该属性可直接调用。如`page.download(url, save_path)`
|
||||
?> 使用这个方式时效果与旧版一致，下载一个文件时会阻塞程序，因此更加建议用后文讲述的多线程方法。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `file_ur`：文件 url
|
||||
- `goal_path`：存放路径，填写到文件夹，不填写文件名
|
||||
- `rename`：重命名文件，可不写扩展名，不输入则用网络文件原名
|
||||
- `file_exists`：若存在同名文件，可选择`'rename'`,`'overwrite'`,`'skip'`方式处理，若选择重命名，会在文件名后面添加序号
|
||||
- `post_data`：post 方式的数据，这个参数不为`None`时自动转成 post 方式
|
||||
- `show_msg`：是否显示下载信息和进度
|
||||
- `**kwargs`：连接参数，与 requests 的一致
|
||||
|
||||
**返回：** 下载是否成功和状态信息的元组。
|
||||
|
||||
```python
|
||||
from DrissionPage import WebPage
|
||||
|
||||
page = WebPage()
|
||||
# 文件 url
|
||||
url = 'https://www.baidu.com/img/flexible/logo/pc/result.png'
|
||||
# 存放路径
|
||||
save_path = r'C:\download'
|
||||
|
||||
# 重命名为img.png，存在重名时自动在文件名末尾加上序号，显示下载进度
|
||||
res = page.download(url, save_path, 'img', 'rename', show_msg=True)
|
||||
# 打印结果
|
||||
print(res)
|
||||
```
|
||||
|
||||
显示：
|
||||
|
||||
```shell
|
||||
url：https://www.baidu.com/img/flexible/logo/pc/result.png
|
||||
文件名：img.png
|
||||
目标路径：C:\download
|
||||
100% 下载完成 C:\download\img.png
|
||||
|
||||
(True, 'C:\\download\\img.png')
|
||||
```
|
||||
|
||||
# ✔️ 多线程并发下载方式
|
||||
|
||||
你可以往`DownloadKit`对象添加个数不限的下载任务，它会自动调配线程去完成这些任务。
|
||||
默认为 10 个线程。
|
||||
|
||||
## 📍 添加任务
|
||||
|
||||
使用`add()`方法添加任务
|
||||
|
||||
**参数：**
|
||||
|
||||
- `file_ur`：文件 url
|
||||
- `goal_path`：存放路径，填写到文件夹，不填写文件名
|
||||
- `session`：可指定使用的`Session`对象，默认使用`MixPage`内置的`Session`对象
|
||||
- `rename`：重命名文件，可不写扩展名，不输入则用网络文件原名
|
||||
- `file_exists`：若存在同名文件，可选择`'rename'`,`'overwrite'`,`'skip'`方式处理，若选择重命名，会在文件名后面添加序号
|
||||
- `post_data`：post 方式的数据，这个参数不为`None`时自动转成 post 方式
|
||||
- `**kwargs`：连接参数，与 requests 的一致
|
||||
|
||||
**返回：** 任务对象，可通过任务对象查看任务状态和结果
|
||||
|
||||
```python
|
||||
from DrissionPage import WebPage
|
||||
|
||||
page = WebPage('s')
|
||||
# 文件 url
|
||||
url = 'https://www.baidu.com/img/flexible/logo/pc/result.png'
|
||||
# 存放路径
|
||||
save_path = r'C:\download'
|
||||
|
||||
# 返回一个任务对象
|
||||
mission = page.download.add(url, save_path)
|
||||
|
||||
# 通过任务对象查看状态
|
||||
print(mission.rate, mission.info)
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```shell
|
||||
90% '下载中'
|
||||
```
|
||||
|
||||
## 📍 实时查看所有线程进度
|
||||
|
||||
多线程方式不会实时显示下载进度，可用`show()`方法把下载进度打印出来。
|
||||
|
||||
!> **注意：** <br>若使用 pyCharm 运行，须在运行配置里勾选“模拟输出控制台中的终端”才能正常显示输出。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `asyn`：是否异步进行
|
||||
- `keep`：任务全部完成后是否保持显示
|
||||
|
||||
**返回：**`None`
|
||||
|
||||
```python
|
||||
url = 'https://example.com/file/abc.zip'
|
||||
mission = page.download.add(url, r'.\files')
|
||||
page.download.show()
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```shell
|
||||
等待任务数：0
|
||||
线程0：97.41% D:\files\abc.zip
|
||||
线程1：空闲
|
||||
线程2：空闲
|
||||
.....
|
||||
```
|
||||
|
||||
?> **Tips：** <br> `keep`参数为`True`时，即使所有任务都已结束仍会一直打印进度，可以按`enter`结束。
|
||||
|
||||
## 📍 等待任务结束
|
||||
|
||||
有时须要等待任务结束，以便获取结果，可用`wait()`方法。 当传入任务时，等待该任务结束并返回结果。不传入参数时等待所有任务结束，与`show()`方法一致。
|
||||
|
||||
**参数：**
|
||||
|
||||
- `mission`：任务对象或任务 id，为`None`时等待所有任务结束
|
||||
- `show`：是否显示进度
|
||||
|
||||
**返回：**
|
||||
|
||||
- 指定任务时，返回任务结果和信息组成的两位 tuple。`True`表示成功，`False`表示失败，`None`表示跳过。
|
||||
- 不指定任务时，返回`None`
|
||||
|
||||
!> **注意：** <br>若使用 pyCharm 运行，须在运行配置里勾选“模拟输出控制台中的终端”才能正常显示输出。
|
||||
|
||||
```python
|
||||
url = 'https://www.baidu.com/img/PCfb_5bf082d29588c07f842ccde3f97243ea.png'
|
||||
mission = page.download.add(url, save_path)
|
||||
page.download.wait(mission)
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```shell
|
||||
url：https://www.baidu.com/img/PCfb_5bf082d29588c07f842ccde3f97243ea.png
|
||||
文件名：PCfb_5bf082d29588c07f842ccde3f97243ea_4.png
|
||||
目标路径：D:\files
|
||||
100% 下载完成 D:\files\PCfb_5bf082d29588c07f842ccde3f97243ea_4.png
|
||||
```
|
||||
|
||||
## 📍 获取某个任务结果
|
||||
|
||||
从`add()`方法返回的`Mission`对象，可查看该任务执行情况。
|
||||
|
||||
`Mission`对象属性：
|
||||
|
||||
- `id`：任务 id
|
||||
- `file_name`：要保存的文件名
|
||||
- `path`：要保存的路径
|
||||
- `data`：任务数据
|
||||
- `state`：任务状态，有`'waiting'`、`'running'`、`'done'`三种
|
||||
- `rate`：任务进度，以百分比显示
|
||||
- `info`：任务信息，成功会返回文件绝对路径，失败会显示原因
|
||||
- `result`：任务结果，`True`表示成功，`False`表示失败，`None`表示跳过
|
||||
|
||||
```python
|
||||
mission = page.download.add(url)
|
||||
print(mission.state)
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```python
|
||||
running
|
||||
```
|
||||
|
||||
## 📍 下载设置
|
||||
|
||||
可使用以下属性进行配置：
|
||||
|
||||
```python
|
||||
# 设置线程数，只能在没有任务在运行的时候进行
|
||||
page.download.roads = 20
|
||||
|
||||
# 大文件分块大小，默认 20MB
|
||||
page.downloadd.block_size = '50M'
|
||||
|
||||
# 设置保存路径，设置后每个任务会使用这个路径，也可添加任务时单独设置
|
||||
page.download.goal_path = r'D:\tmp'
|
||||
|
||||
# 设置重试次数，初始为继承 page 的 retry_times 属性
|
||||
page.download.retry = 5
|
||||
|
||||
# 设置失败重试间隔，初始为继承 page 的 retry_interval 属性
|
||||
page.download.interval = 2
|
||||
|
||||
# 设置存在文件名冲突时的处理方式，可选 'skip', 'overwrite', 'rename'
|
||||
page.download.file_exists = 'skip'
|
||||
```
|
||||
|
||||
?> **Tips：**<br> 重试次数和间隔在初始化时继承页面对象的`retry_times`和`retry_interval`属性，可用上面例子的方法对下载的重试次数和间隔进行设置，设置后不会影响页面对象的设置。
|
||||
Loading…
Reference in New Issue
Block a user