mirror of
https://gitee.com/g1879/DrissionPage.git
synced 2024-12-10 04:00:23 +08:00
486 lines
11 KiB
Markdown
486 lines
11 KiB
Markdown
本节介绍`SessionPage`的启动配置。
|
||
|
||
我们用`SessionOptions`对象管理`Session`对象初始配置。
|
||
|
||
!> **注意：** <br>`SessionOptions`仅用于管理启动配置，程序启动后再修改无效。
|
||
|
||
# ✔️ 创建对象
|
||
|
||
## 📍 导入
|
||
|
||
```python
|
||
from DrissionPage import SessionOptions
|
||
```
|
||
|
||
---
|
||
|
||
## 📍 `SessionOptions`
|
||
|
||
`SessionOptions`对象用于管理`Session`对象的初始化配置。可从配置文件中读取配置来进行初始化。
|
||
|
||
| 初始化参数 | 类型 | 默认值 | 说明 |
|
||
|:-----------:|:---------------:|:------:| ---------------------------------- |
|
||
| `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 | `dict` | 必填 | 完整的 headers 字典 |
|
||
|
||
| 返回类型 | 说明 |
|
||
| ---------------- | ------ |
|
||
| `SessionOptions` | 配置对象本身 |
|
||
|
||
**示例：**
|
||
|
||
```python
|
||
so.set_headers = {'user-agent': 'Mozilla/5.0 (Macint...', 'connection': 'keep-alive' ...}
|
||
```
|
||
|
||
---
|
||
|
||
## 📍 `set_a_header()`
|
||
|
||
该方法用于设置`headers`中的一个项。
|
||
|
||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||
|:-------:|:-----:|:---:| ---- |
|
||
| `attr` | `str` | 必填 | 设置名称 |
|
||
| `value` | `str` | 必填 | 设置值 |
|
||
|
||
| 返回类型 | 说明 |
|
||
| ---------------- | ------ |
|
||
| `SessionOptions` | 配置对象本身 |
|
||
|
||
**示例：**
|
||
|
||
```python
|
||
so.set_a_header('accept', 'text/html')
|
||
so.set_a_header('Accept-Charset', 'GB2312')
|
||
```
|
||
|
||
**输出：**
|
||
|
||
```
|
||
{'accept': 'text/html', 'accept-charset': 'GB2312'}
|
||
```
|
||
|
||
---
|
||
|
||
## 📍 `remove_a_header()`
|
||
|
||
此方法用于从`headers`中移除一个设置项。
|
||
|
||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||
|:------:|:-----:|:---:| ------ |
|
||
| `attr` | `str` | 必填 | 要删除的设置 |
|
||
|
||
| 返回类型 | 说明 |
|
||
| ---------------- | ------ |
|
||
| `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` | 必填 | 连接等待秒数 |
|
||
|
||
| 返回类型 | 说明 |
|
||
| ---------------- | ------ |
|
||
| `SessionOptions` | 配置对象本身 |
|
||
|
||
---
|
||
|
||
## 📍 `set_proxies()`
|
||
|
||
此方法用于设置代理信息。
|
||
|
||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||
|:-------:|:-----:|:------:| ------------------------------- |
|
||
| `http` | `str` | 必填 | http 代理地址 |
|
||
| `https` | `str` | `None` | https 代理地址，为`None`时使用`http`参数的值 |
|
||
|
||
| 返回类型 | 说明 |
|
||
| ---------------- | ------ |
|
||
| `SessionOptions` | 配置对象本身 |
|
||
|
||
**示例：**
|
||
|
||
```python
|
||
so.set_proxies('http://127.0.0.1:1080')
|
||
```
|
||
|
||
---
|
||
|
||
## 📍 `set_paths()`
|
||
|
||
此方法用于设置路径信息，目前只有`download_path`一种。
|
||
|
||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||
|:---------------:|:---------------:|:---:| -------- |
|
||
| `download_path` | `str`<br>`Path` | 必填 | 默认下载保存路径 |
|
||
|
||
| 返回类型 | 说明 |
|
||
| ---------------- | ------ |
|
||
| `SessionOptions` | 配置对象本身 |
|
||
|
||
---
|
||
|
||
## 📍 `set_auth()`
|
||
|
||
此方法用于设置认证元组信息。
|
||
|
||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||
|:------:|:--------------------------:|:---:| ------- |
|
||
| `auth` | `tuple`<br>`HTTPBasicAuth` | 必填 | 认证元组或对象 |
|
||
|
||
| 返回类型 | 说明 |
|
||
| ---------------- | ------ |
|
||
| `SessionOptions` | 配置对象本身 |
|
||
|
||
---
|
||
|
||
## 📍 `set_hooks()`
|
||
|
||
此方法用于设置回调方法。
|
||
|
||
| 参数名称 | 类型 | 默认值 | 说明 |
|
||
|:-------:|:------:|:---:| ---- |
|
||
| `hooks` | `dict` | 必填 | 回调方法 |
|
||
|
||
| 返回类型 | 说明 |
|
||
| ---------------- | ------ |
|
||
| `SessionOptions` | 配置对象本身 |
|
||
|
||
---
|
||
|
||
## 📍 `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`保存到当前读取的配置文件 |
|
||
|
||
| 返回类型 | 说明 |
|
||
| ----- | -------------- |
|
||
| `str` | 保存的 ini 文件绝对路径 |
|
||
|
||
**示例：**
|
||
|
||
```python
|
||
# 保存当前读取的ini文件
|
||
so.save()
|
||
|
||
# 把当前配置保存到指定的路径
|
||
so.save(path=r'D:\tmp\settings.ini')
|
||
```
|
||
|
||
---
|
||
|
||
## 📍 `save_to_default()`
|
||
|
||
此方法用于保存配置项到固定的默认 ini 文件。默认 ini 文件是指随 DrissionPage 内置的那个。
|
||
|
||
**参数：** 无
|
||
|
||
| 返回类型 | 说明 |
|
||
| ----- | -------------- |
|
||
| `str` | 保存的 ini 文件绝对路径 |
|
||
|
||
**示例：**
|
||
|
||
```python
|
||
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`
|