From 3a6e8aca9e208e36721df6a005ff8bbcae5d162d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Francis=20Qin=28=E7=A7=A6=E5=BD=AC=E6=B4=B2=29?= Date: Thu, 16 Feb 2023 17:18:01 +0800 Subject: [PATCH 1/6] check wiki --- teedoc_with_qpydoc | 1 + 1 file changed, 1 insertion(+) create mode 160000 teedoc_with_qpydoc diff --git a/teedoc_with_qpydoc b/teedoc_with_qpydoc new file mode 160000 index 00000000..ac4665f0 --- /dev/null +++ b/teedoc_with_qpydoc @@ -0,0 +1 @@ +Subproject commit ac4665f07f03f90f6c51b44896dae690bb1bc6f2 -- Gitee From 664ffdf16db2e40867fe3d471c73ac24f3e5be5f Mon Sep 17 00:00:00 2001 From: "Francis.Qin" <1371316129@qq.com> Date: Thu, 16 Feb 2023 20:10:45 +0800 Subject: [PATCH 2/6] check wiki --- .../ucollections.md" | 95 +++++++ .../ustruct.md" | 161 +++++++++++ .../WLAN.ESP8266.md" | 251 ++++++++++++++++++ .../WLAN.md" | 115 ++++++++ teedoc_with_qpydoc | 1 - 5 files changed, 622 insertions(+), 1 deletion(-) create mode 100644 "docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" create mode 100644 "docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.ESP8266.md" create mode 100644 "docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.md" delete mode 160000 teedoc_with_qpydoc diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" index e69de29b..1d4ab162 100644 --- "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" @@ -0,0 +1,95 @@ + +# `ucollections` - 集合和容器类型 + +模块功能：ucollections 模块可以创建一个新的容器类型，用于保存各种对象。该模块实现了CPython模块相应模块的子集。更多信息请参阅阅CPython文档：[collections](https://docs.python.org/3/library/collections.html) + +## `ucollections`方法 +### `ucollections.namedtuple` + +```python +mytuple = ucollections.namedtuple(name, fields) +``` + +创建一个具有特定名称和一组字段的新`namedtuple`容器类型，`namedtuple`是元组的子类，允许通过索引来访问它的字段。 + +**参数描述：** + +- `name` - str类型，表示新建容器的类型名称 +- `fields` - tuple类型，表示新创建容器类型包含子类型的字段 + +**示例：** + +```python +>>> import ucollections +>>> mytuple = ucollections.namedtuple("mytuple", ("id", "name")) +>>> t1 = mytuple(1, "foo") +>>> t2 = mytuple(2, "bar") +>>> print(t1.name) +foo +``` + +### `ucollections.deque` + +```python +ucollections.deque(iterable, maxlen, flag) +``` + +创建`deque`双向队列 + +**参数描述：** + +- `iterable` - tuple类型，必须是一个空元组 +- `maxlen` - int类型，表示指定maxlen并将双端队列限制为此最大长度 +- `flag` - int类型，可选参数；0(默认)：不检查队列是否溢出，达到最大长度时继续append会丢弃之前的值 ，1：当队列达到最大设定长度会抛出IndexError: full + +**返回值：** + +- deque对象 + + + +## deque对象方法 + +### `deque.append` + +```python +deque.append(data) +``` + +往队列中插入值。 + +**参数描述：** + +- `data` - 基本数据类型，表示需要添加到队列的数值 + + + +### `deque.popleft` + +```python +deque.popleft() +``` + +从`deque`的左侧移除并返回移除的数据。如果`deque`为空，会引起索引错误 + +**返回值：** + +- 返回pop出的值 + +**使用示例** + +```python +from ucollections import deque + +>>> dq = deque((),5) +>>> dq.append(1) +>>> dq.append(['a']) +>>> dq.append('a') + +>>> dq.popleft() +1 +>>> dq.popleft() +['a'] +>>> dq.popleft() +'a' +``` \ No newline at end of file diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" new file mode 100644 index 00000000..b3cb0dc2 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" @@ -0,0 +1,161 @@ + +# `ustruct` - 打包和解压原始数据类型 + +模块功能：`ustruct`模块实现相应CPython模块的子集。更多信息请参阅阅CPython文档：[struct](https://docs.python.org/3/library/struct.html) + + +## 格式字符串 + +格式字符串是用来在打包和解包数据时指定预期布局的机制。 其使用指定被打包/解包数据类型的`格式字符`进行构建。 此外，还有一些特殊字符用来控制`字节顺序`，`大小`和`对齐方式`。 + + +### **字节顺序，大小和对齐方式** + +默认情况下，C类型以机器的本机格式和字节顺序表示，并在必要时通过跳过填充字节来正确对齐（根据C编译器使用的规则）。根据下表，格式字符串的第一个字符可用于指示打包数据的字节顺序，大小和对齐方式： + +| Character | Byte order | Size | Alignment | +| --------- | ---------------------- | -------- | --------- | +| `@` | native | native | native | +| `=` | native | standard | none | +| `<` | little-endian | standard | none | +| `>` | big-endian | standard | none | +| `!` | network (= big-endian) | standard | none | + +> 如果第一个字符不是其中之一，则假定为 '@' 。 + + +### **格式化字符表** + +| Format | C Type | Python type | Standard size | +| ------ | -------------------- | ----------- | ------------- | +| `x` | `pad byte` | no value | | +| `c` | `char` | bytes of length 1 | 1 | +| `b` | `signed char` | integer | 1 | +| `B` | `unsigned char` | integer | 1 | +| `?` | `_Bool` | bool | 1 | +| `h` | `short` | integer | 2 | +| `H` | `unsigned short` | integer | 2 | +| `i` | `int` | integer | 4 | +| `I` | `unsigned int` | integer | 4 | +| `l` | `long` | integer | 4 | +| `L` | `unsigned long` | integer | 4 | +| `q` | `long long` | integer | 8 | +| `Q` | `unsigned long long` | integer | 8 | +| `n` | `ssize_t` | integer | | +| `N` | `size_t` | integer | | +| `e` | `` | float | 2 | +| `f` | `float` | float | 4 | +| `d` | `double` | float | 8 | +| `s` | `char[]` | bytes | | +| `p` | `char[]` | bytes | | +| `P` | `void *` | integer | 4 | + + +## `ustruct`方法 + +### `ustruct.calcsize` + +```python +ustruct.calcsize(fmt) +``` + +返回存放 `fmt` 需要的字节数。 + +**参数描述：** + +- `fmt` - 格式字符的类型，详情见上文格化式字符表 + +**示例：** + +```python +>>> import ustruct +>>> ustruct.calcsize('i') +4 +>>> ustruct.calcsize('f') +4 +>>> ustruct.calcsize('d') +8 +``` + + + +### `ustruct.pack` + +```python +ustruct.pack(fmt, v1, v2, ...) +``` + +按照格式字符串 `fmt` 压缩参数v1、 v2、…。 + +**参数描述：** + +- `fmt` - 格式字符的类型，详情见上文格化式字符表 + +**返回值描述：** + +- 返回参数编码后的字节对象。 + + + +### `ustruct.unpack` + +```python +ustruct.unpack(fmt, data) +``` + +根据格式化字符串 `fmt` 对数据进行解压，返回值为一个元组。 + +**参数描述：** + +- `fmt` - 格式字符的类型，详情见上文格化式字符表 +- `data` - 要进行解压的数据 + +**返回值描述：** + +- 返回包含解压值的元组(即使只包含一个项)。 + +**示例：** + +```python +>>> import ustruct +>>> ustruct.pack('ii', 7, 9) #打包两个整数 +b'\x07\x00\x00\x00\t\x00\x00\x00' +>>> ustruct.unpack('ii', b'\x07\x00\x00\x00\t\x00\x00\x00') #解压两个整数 +(7, 9) +``` + + + +### `ustruct.pack_into` + +```python +ustruct.pack_into(fmt, buffer, offset, v1, v2, ...) +``` + +根据格式字符串`fmt`将值v1、v2、 …打包到从`offset`开始的缓冲区中。从缓冲区的末尾算起，`offset`可能为负。 + +**参数描述：** + +- `fmt` - 格式字符的类型，详情见上文格化式字符表 +- `buffer` - 可写数据缓冲区 +- `offset` - 写入的起始位置 + + + +### `ustruct.unpack_from` + +```python +ustruct.unpack_from(fmt, data, offset=0) +``` + +根据格式化字符串 `fmt` 解析从 `offest` 开始的数据解压，从缓冲区末尾开始计数的偏移量可能为负值。 + +**参数描述：** + +- `fmt` - 格式字符的类型，详情见上文格化式字符表 +- `data` - 数据缓冲区(缓冲区大小以字节为单位) +- `offset` - 解压的起始位置 + +**返回值描述：** + +- 返回解压值的元组(即使只包含一个项)。 diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.ESP8266.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.ESP8266.md" new file mode 100644 index 00000000..58d0d839 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.ESP8266.md" @@ -0,0 +1,251 @@ + +# `class ESP8266` - ESP8266无线网络控制 + +该类用于控制`ESP8266`型号无线网卡设备。 + +## 构造函数 + +### `ESP8266` + +```python +class ESP8266(uart=UART.UART1, mod=ESP8266.STA， callback=None) +``` + +加载ESP8266驱动，初始化虚拟网卡，并返回ESP8266对象。 + +**参数描述：** +- `uart` - 模组UART口选择，表示模组与ESP8266所连接的`串口号`，默认使用`UART1`。 +- `mode` - 无线网卡工作模式配置，用来指定ESP8266的`工作模式`，STA客户端模式为ESP8266.STA，AP接入点模式为ESP8266.AP，默认使用`STA客户端`模式。 +- `callback` - 设置回调函数，用于`网络变化`以及`ota升级`通知，默认为未开启。 + +**callback参数描述：** +- `content` - 用户回调，表示上报消息内容 + +**上报消息内容描述：** +- `ota`信息上报： + - `ota,begin` - ota升级开始 + - `ota,downloading,xx` - ota升级下载百分比 + - `ota,restart` - ota升级下载完成进行重启 + - `ota,err_code,1` - ota升级错误码 +- `station`网络连接变化上报： + - `station, connected` - wifi已连接 + - `station, disconnected` - wifi未连接 + + + +## 方法 + +### `ESP8266.status` + +```python +ESP8266.status() +``` + +获取无线网卡状态信息，用以判断无线网卡当前工作模式。 + +**返回值描述：** +- `0` - esp8266 设备不存在 +- `1` - esp8266 station模式已连接 +- `2` - esp8266 station模式未连接 +- `3` - esp8266 web配网模式 +- `4` - esp8266 ap模式 +- `5` - esp8266 ota升级中 + + + + +### `ESP8266.version` + +```python +ESP8266.version() +``` + +获取无线网卡当前固件版本信息 + +**返回值描述：** + +- 返回字符串，格式为(sdk, model, version, time),具体描述如下： + - `sdk` - sdk信息 + - `model` - 无线网卡型号 + - `version` - 版本号 + - `time` - 版本时间 + + + +### `ESP8266.ipconfig` + +```python +ESP8266.ipconfig() +``` + +获取网卡当前网络配置信息(IP地址、DNS服务器等信息) + +**返回值描述：** + + - 返回tuple类型，格式为 (ip, subnet, gateway, mtu, primary_dns, secondary_dns)，具体描述如下： + + - `ip` - ip地址 + - `subnet` - 子网掩码 + - `gateway` - 网关 + - `mtu` - 最大传输单元 + - `primary_dns` - DNS服务器主地址 + - `secondary_dns` - DNS服务器辅地址 + + + +### `ESP8266.station` + +```python +ESP8266.station(username，password) +``` + +使无线网卡以`station`工作模式启动，连接指定wifi。 + +**参数描述：** + +- `username` - 填写所要连接的 `WiFi` 的名称（1~32 个字符） +- `password` - 填写所要连接的 `WiFi` 的密码（8~64 个字符） + +**返回值描述：** + +- 配置成功返回`0`，配置失败返回其他值。 + + + +### `ESP8266.ap` + +```python +ESP8266.ap(username，password) +``` + +使无线网卡以`ap`工作模式启动，作为无线热点。 + +**参数描述：** + +- `username` - 配置 `WiFi热点` 的名称（1~32 个字符） +- `password` - 配置 `WiFi热点` 的密码（8~64 个字符） + +**返回值描述：** + +- 配置成功返回`0`，配置失败返回其他值。 + + + +### `ESP8266.web_config` + +```python +ESP8266.web_config(username，password) +``` + +使无线网卡以`web 配网`工作模式启动，用户可通过web页面进行网络配置。 + +> 提示：启用配网功能后，需使用手机/电脑等终端设备通过无线网络连接至无线网卡(用户自定义名称和密码)，然后通过浏览器输入192.168.4.1进入配网页面。 + +**参数描述：** + +- `username` - 配置 `配网热点` 的名称（1~32 个字符） +- `password` - 配置 `配网热点` 的密码（8~64 个字符） + +**返回值描述：** + +- 配置成功返回`0`，配置失败返回其他值。 + + + +### `ESP8266.ota` + +```python +ESP8266.ota(url) +``` + +开启`ota`后，网卡将更新新版本固件 + +> 注意：升级过程中只可查询当前状态，不可进行其他操作 + +**参数描述：** + +- `url` - 填写网址地址，表示固件下载地址，当前仅支持 http 协议，最长 256 字节。 + +**返回值描述：** + +- 执行成功返回`0`，执行失败返回其他值。 + +**示例：** + +```python + +url='http://www.example.com/fota.bin' + +esp8266.ota(url) + +``` + + + +### `ESP8266.stop` + +```python +ESP8266.stop() +``` + +释放掉为无线网卡所配置的虚拟网卡 + +**返回值描述：** + +- 释放成功返回`0`，释放失败返回其他值。 + + + +### `ESP8266.set_default_NIC` + +```python +ESP8266.set_default_NIC(ip_str) +``` + +指定网卡进行网络转发 + +**参数描述：** + +- `ip_str` - 所要设置默认转发网卡的网卡 ip 地址，如：'192.168.1.100' + +**返回值描述：** + +- 配置成功返回`0`，配置失败返回其他值。 + + + +### `ESP8266.set_dns` + +```python +ESP8266.set_dns(pri_dns, sec_dns) +``` + +指定无线网卡的`dns`服务器进行地址解析 + +**参数描述：** + +- `pri_dns` - 设置无线网卡的`首选 dns` 服务器，默认为 `8.8.8.8` +- `sec_dns` - 设置无线网卡的`备选 dns` 服务器，默认为 `114.114.114.114` + +**返回值描述：** + +- 配置成功返回`0`，配置失败返回其他值。 + + + +### `ESP8266.router_add` + +```python +ESP8266.router_add(ip, mask) +``` + +设置无线网卡路由转发规则 + +**参数描述：** + +- `ip` - 设置 `ap` 模式的网段，默认为 192.168.4.1 +- `mask` - 设置子网掩码，默认为 255.255.255.0 + +**返回值描述：** + +- 配置成功返回`0`，配置失败返回其他值。 diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.md" new file mode 100644 index 00000000..677c1099 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.md" @@ -0,0 +1,115 @@ + +# `WLAN` - 无线局域网相关功能 + +`WLAN`模块包含无线局域网控制及网络配置功能。主要是针对不同类型无线网卡提供统一的管理方式。 + +> 当前仅支持ESP8266无线网卡 + +**示例：** + +以ESP8266为例，根据不同应用场景，分别展示以`station`模式、`ap`模式、`web配网`模式下无线网卡初始化使用过程。 + +**station客户端模式：** +```python +# 在station工作模式下，无线网卡连接路由器的WiFi，由路由器分配IP等信息，使模组通过无线网卡连接外部网络。 +>>> from usr.WLAN import ESP8266 +>>> from machine import UART + + +# 加载ESP8266网卡驱动，并初始化网卡相关配置 +>>> ESP8266 = ESP8266(UART.UART2, ESP8266.STA) + +# 配置无线网卡以station模式启动并连接WiFi热点 +>>> ESP8266.station('wifiname','wifipassword') +0 + +# 查看无线网卡的IP信息 +>>> ESP8266.ipconfig() + ('172.16.1.2', '255.255.255.0', '172.16.1.1', 1500, '0.0.0.0', +'0.0.0.0') + +# 配置DNS服务器 +>>> ESP8266.set_dns('8.8.8.8','114.114.114.114') +0 + +# 查看无线网卡的IP信息，可以看到DNS已被配置成功 +>>> ESP8266.ipconfig() +('172.16.1.2', '255.255.255.0', '172.16.1.1', 1500, '8.8.8.8', +'114.114.114.114') + +# 设置无线网卡作为默认网卡，使用无线网卡进行网络通信 +>>> ESP8266.set_default_NIC('172.16.1.2') +0 + +# 获取当前网卡状态 返回“1”说明无线网卡已连接WiFi，返回“2”说明未连接WiFi +>>> ESP8266.status() +1 + +# 此时可以启动其他网络服务，并通过无线网络进行网络访问 +``` + + + +**AP接入点模式：** +```python +# 在ap工作模式下，无线网卡开启ap热点，使用模组的4G网络 连接外网，并为连接到热点的终端设备分配IP信息，其他终端设备即可连接外部网络。 +>>> from usr.WLAN import ESP8266 +>>> from machine import UART +>>> import dataCall + + +# 加载ESP8266网卡驱动，并初始化网卡相关配置 +>>> ESP8266 = ESP8266(UART.UART2, ESP8266.AP) + +# 配置无线网卡以ap模式启动WiFi热点 +>>> ESP8266.ap('wifiname','wifipassword') +0 + +#获取拨号信息 +>>> Info = dataCall.getInfo(1,0) + +#设置默认网卡，ap模式下设置4G为默认网卡 +>>> ESP8266.set_default_NIC(Info[2][2]) +0 + +#添加路由信息，设置网卡转发规则 +>>> ESP8266.router_add('192.168.4.0', '255.255.255.0') +0 + +# 获取当前网卡状态 返回“4”说明无线网卡已启用ap热点模式 +>>> ESP8266.status() +4 + +# 此时可用其他终端设备连接ap热点，进行网络访问 +``` + + + +**web配网模式：** +```python +# 在web配网模式下，可以使用手机等设备连接无线网卡的WiFi热点，通过浏览器进入web页面，配置无线网卡的网络信息。 +>>> from usr.WLAN import ESP8266 +>>> from machine import UART + + +# 初始化网卡，若使用web配置ap模式，需把模式字段设置为ESP8266.AP +>>> ESP8266 = ESP8266(UART.UART2, ESP8266.STA) + +# 获取当前网卡状态 +>>> ESP8266.status() +1 + +# 配置web配网模式热点的信息 +>>> ESP8266.web_config('admin','adminpwd') +0 + +# 获取当前网卡状态 返回“3”表示web配网已启用，可以使用web配网模式 +>>> ESP8266.status() +3 + +# 此时可用其他终端设备连接热点，登录web界面进行网络配置 +``` + + +## Classes +- [class ESP8266 – ESP8266驱动](./WLAN.ESP8266.md) \ No newline at end of file diff --git a/teedoc_with_qpydoc b/teedoc_with_qpydoc deleted file mode 160000 index ac4665f0..00000000 --- a/teedoc_with_qpydoc +++ /dev/null @@ -1 +0,0 @@ -Subproject commit ac4665f07f03f90f6c51b44896dae690bb1bc6f2 -- Gitee From 827f3c52b40543affdf1ba80324d93d0611b4805 Mon Sep 17 00:00:00 2001 From: "Francis.Qin" <1371316129@qq.com> Date: Thu, 16 Feb 2023 20:12:36 +0800 Subject: [PATCH 3/6] check wiki --- README | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 README diff --git a/README b/README new file mode 100644 index 00000000..e69de29b -- Gitee From e4ce8b6fcb0c4d86aa38c70bfbd0c753be1335ed Mon Sep 17 00:00:00 2001 From: "Francis.Qin" <1371316129@qq.com> Date: Thu, 16 Feb 2023 20:19:18 +0800 Subject: [PATCH 4/6] check wiki --- .../ucollections.md" | 95 ----------- .../ustruct.md" | 161 ------------------ 2 files changed, 256 deletions(-) delete mode 100644 "docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" delete mode 100644 "docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" deleted file mode 100644 index 1d4ab162..00000000 --- "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" +++ /dev/null @@ -1,95 +0,0 @@ - -# `ucollections` - 集合和容器类型 - -模块功能：ucollections 模块可以创建一个新的容器类型，用于保存各种对象。该模块实现了CPython模块相应模块的子集。更多信息请参阅阅CPython文档：[collections](https://docs.python.org/3/library/collections.html) - -## `ucollections`方法 -### `ucollections.namedtuple` - -```python -mytuple = ucollections.namedtuple(name, fields) -``` - -创建一个具有特定名称和一组字段的新`namedtuple`容器类型，`namedtuple`是元组的子类，允许通过索引来访问它的字段。 - -**参数描述：** - -- `name` - str类型，表示新建容器的类型名称 -- `fields` - tuple类型，表示新创建容器类型包含子类型的字段 - -**示例：** - -```python ->>> import ucollections ->>> mytuple = ucollections.namedtuple("mytuple", ("id", "name")) ->>> t1 = mytuple(1, "foo") ->>> t2 = mytuple(2, "bar") ->>> print(t1.name) -foo -``` - -### `ucollections.deque` - -```python -ucollections.deque(iterable, maxlen, flag) -``` - -创建`deque`双向队列 - -**参数描述：** - -- `iterable` - tuple类型，必须是一个空元组 -- `maxlen` - int类型，表示指定maxlen并将双端队列限制为此最大长度 -- `flag` - int类型，可选参数；0(默认)：不检查队列是否溢出，达到最大长度时继续append会丢弃之前的值 ，1：当队列达到最大设定长度会抛出IndexError: full - -**返回值：** - -- deque对象 - - - -## deque对象方法 - -### `deque.append` - -```python -deque.append(data) -``` - -往队列中插入值。 - -**参数描述：** - -- `data` - 基本数据类型，表示需要添加到队列的数值 - - - -### `deque.popleft` - -```python -deque.popleft() -``` - -从`deque`的左侧移除并返回移除的数据。如果`deque`为空，会引起索引错误 - -**返回值：** - -- 返回pop出的值 - -**使用示例** - -```python -from ucollections import deque - ->>> dq = deque((),5) ->>> dq.append(1) ->>> dq.append(['a']) ->>> dq.append('a') - ->>> dq.popleft() -1 ->>> dq.popleft() -['a'] ->>> dq.popleft() -'a' -``` \ No newline at end of file diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" deleted file mode 100644 index b3cb0dc2..00000000 --- "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" +++ /dev/null @@ -1,161 +0,0 @@ - -# `ustruct` - 打包和解压原始数据类型 - -模块功能：`ustruct`模块实现相应CPython模块的子集。更多信息请参阅阅CPython文档：[struct](https://docs.python.org/3/library/struct.html) - - -## 格式字符串 - -格式字符串是用来在打包和解包数据时指定预期布局的机制。 其使用指定被打包/解包数据类型的`格式字符`进行构建。 此外，还有一些特殊字符用来控制`字节顺序`，`大小`和`对齐方式`。 - - -### **字节顺序，大小和对齐方式** - -默认情况下，C类型以机器的本机格式和字节顺序表示，并在必要时通过跳过填充字节来正确对齐（根据C编译器使用的规则）。根据下表，格式字符串的第一个字符可用于指示打包数据的字节顺序，大小和对齐方式： - -| Character | Byte order | Size | Alignment | -| --------- | ---------------------- | -------- | --------- | -| `@` | native | native | native | -| `=` | native | standard | none | -| `<` | little-endian | standard | none | -| `>` | big-endian | standard | none | -| `!` | network (= big-endian) | standard | none | - -> 如果第一个字符不是其中之一，则假定为 '@' 。 - - -### **格式化字符表** - -| Format | C Type | Python type | Standard size | -| ------ | -------------------- | ----------- | ------------- | -| `x` | `pad byte` | no value | | -| `c` | `char` | bytes of length 1 | 1 | -| `b` | `signed char` | integer | 1 | -| `B` | `unsigned char` | integer | 1 | -| `?` | `_Bool` | bool | 1 | -| `h` | `short` | integer | 2 | -| `H` | `unsigned short` | integer | 2 | -| `i` | `int` | integer | 4 | -| `I` | `unsigned int` | integer | 4 | -| `l` | `long` | integer | 4 | -| `L` | `unsigned long` | integer | 4 | -| `q` | `long long` | integer | 8 | -| `Q` | `unsigned long long` | integer | 8 | -| `n` | `ssize_t` | integer | | -| `N` | `size_t` | integer | | -| `e` | `` | float | 2 | -| `f` | `float` | float | 4 | -| `d` | `double` | float | 8 | -| `s` | `char[]` | bytes | | -| `p` | `char[]` | bytes | | -| `P` | `void *` | integer | 4 | - - -## `ustruct`方法 - -### `ustruct.calcsize` - -```python -ustruct.calcsize(fmt) -``` - -返回存放 `fmt` 需要的字节数。 - -**参数描述：** - -- `fmt` - 格式字符的类型，详情见上文格化式字符表 - -**示例：** - -```python ->>> import ustruct ->>> ustruct.calcsize('i') -4 ->>> ustruct.calcsize('f') -4 ->>> ustruct.calcsize('d') -8 -``` - - - -### `ustruct.pack` - -```python -ustruct.pack(fmt, v1, v2, ...) -``` - -按照格式字符串 `fmt` 压缩参数v1、 v2、…。 - -**参数描述：** - -- `fmt` - 格式字符的类型，详情见上文格化式字符表 - -**返回值描述：** - -- 返回参数编码后的字节对象。 - - - -### `ustruct.unpack` - -```python -ustruct.unpack(fmt, data) -``` - -根据格式化字符串 `fmt` 对数据进行解压，返回值为一个元组。 - -**参数描述：** - -- `fmt` - 格式字符的类型，详情见上文格化式字符表 -- `data` - 要进行解压的数据 - -**返回值描述：** - -- 返回包含解压值的元组(即使只包含一个项)。 - -**示例：** - -```python ->>> import ustruct ->>> ustruct.pack('ii', 7, 9) #打包两个整数 -b'\x07\x00\x00\x00\t\x00\x00\x00' ->>> ustruct.unpack('ii', b'\x07\x00\x00\x00\t\x00\x00\x00') #解压两个整数 -(7, 9) -``` - - - -### `ustruct.pack_into` - -```python -ustruct.pack_into(fmt, buffer, offset, v1, v2, ...) -``` - -根据格式字符串`fmt`将值v1、v2、 …打包到从`offset`开始的缓冲区中。从缓冲区的末尾算起，`offset`可能为负。 - -**参数描述：** - -- `fmt` - 格式字符的类型，详情见上文格化式字符表 -- `buffer` - 可写数据缓冲区 -- `offset` - 写入的起始位置 - - - -### `ustruct.unpack_from` - -```python -ustruct.unpack_from(fmt, data, offset=0) -``` - -根据格式化字符串 `fmt` 解析从 `offest` 开始的数据解压，从缓冲区末尾开始计数的偏移量可能为负值。 - -**参数描述：** - -- `fmt` - 格式字符的类型，详情见上文格化式字符表 -- `data` - 数据缓冲区(缓冲区大小以字节为单位) -- `offset` - 解压的起始位置 - -**返回值描述：** - -- 返回解压值的元组(即使只包含一个项)。 -- Gitee From 5a32ba5f6f4ec69135e581e6f3a219318ceb41eb Mon Sep 17 00:00:00 2001 From: "Francis.Qin" <1371316129@qq.com> Date: Thu, 16 Feb 2023 20:21:38 +0800 Subject: [PATCH 5/6] check wiki --- README | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 README diff --git a/README b/README deleted file mode 100644 index e69de29b..00000000 -- Gitee From 5c9c4f8a04d9a4dfb58145e922bce45283596463 Mon Sep 17 00:00:00 2001 From: "Francis.Qin" <1371316129@qq.com> Date: Fri, 17 Feb 2023 09:42:34 +0800 Subject: [PATCH 6/6] check wiki --- .../ucollections.md" | 95 +++++++++++ .../ustruct.md" | 161 ++++++++++++++++++ 2 files changed, 256 insertions(+) create mode 100644 "docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" create mode 100644 "docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" new file mode 100644 index 00000000..1d4ab162 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" @@ -0,0 +1,95 @@ + +# `ucollections` - 集合和容器类型 + +模块功能：ucollections 模块可以创建一个新的容器类型，用于保存各种对象。该模块实现了CPython模块相应模块的子集。更多信息请参阅阅CPython文档：[collections](https://docs.python.org/3/library/collections.html) + +## `ucollections`方法 +### `ucollections.namedtuple` + +```python +mytuple = ucollections.namedtuple(name, fields) +``` + +创建一个具有特定名称和一组字段的新`namedtuple`容器类型，`namedtuple`是元组的子类，允许通过索引来访问它的字段。 + +**参数描述：** + +- `name` - str类型，表示新建容器的类型名称 +- `fields` - tuple类型，表示新创建容器类型包含子类型的字段 + +**示例：** + +```python +>>> import ucollections +>>> mytuple = ucollections.namedtuple("mytuple", ("id", "name")) +>>> t1 = mytuple(1, "foo") +>>> t2 = mytuple(2, "bar") +>>> print(t1.name) +foo +``` + +### `ucollections.deque` + +```python +ucollections.deque(iterable, maxlen, flag) +``` + +创建`deque`双向队列 + +**参数描述：** + +- `iterable` - tuple类型，必须是一个空元组 +- `maxlen` - int类型，表示指定maxlen并将双端队列限制为此最大长度 +- `flag` - int类型，可选参数；0(默认)：不检查队列是否溢出，达到最大长度时继续append会丢弃之前的值 ，1：当队列达到最大设定长度会抛出IndexError: full + +**返回值：** + +- deque对象 + + + +## deque对象方法 + +### `deque.append` + +```python +deque.append(data) +``` + +往队列中插入值。 + +**参数描述：** + +- `data` - 基本数据类型，表示需要添加到队列的数值 + + + +### `deque.popleft` + +```python +deque.popleft() +``` + +从`deque`的左侧移除并返回移除的数据。如果`deque`为空，会引起索引错误 + +**返回值：** + +- 返回pop出的值 + +**使用示例** + +```python +from ucollections import deque + +>>> dq = deque((),5) +>>> dq.append(1) +>>> dq.append(['a']) +>>> dq.append('a') + +>>> dq.popleft() +1 +>>> dq.popleft() +['a'] +>>> dq.popleft() +'a' +``` \ No newline at end of file diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" new file mode 100644 index 00000000..b3cb0dc2 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" @@ -0,0 +1,161 @@ + +# `ustruct` - 打包和解压原始数据类型 + +模块功能：`ustruct`模块实现相应CPython模块的子集。更多信息请参阅阅CPython文档：[struct](https://docs.python.org/3/library/struct.html) + + +## 格式字符串 + +格式字符串是用来在打包和解包数据时指定预期布局的机制。 其使用指定被打包/解包数据类型的`格式字符`进行构建。 此外，还有一些特殊字符用来控制`字节顺序`，`大小`和`对齐方式`。 + + +### **字节顺序，大小和对齐方式** + +默认情况下，C类型以机器的本机格式和字节顺序表示，并在必要时通过跳过填充字节来正确对齐（根据C编译器使用的规则）。根据下表，格式字符串的第一个字符可用于指示打包数据的字节顺序，大小和对齐方式： + +| Character | Byte order | Size | Alignment | +| --------- | ---------------------- | -------- | --------- | +| `@` | native | native | native | +| `=` | native | standard | none | +| `<` | little-endian | standard | none | +| `>` | big-endian | standard | none | +| `!` | network (= big-endian) | standard | none | + +> 如果第一个字符不是其中之一，则假定为 '@' 。 + + +### **格式化字符表** + +| Format | C Type | Python type | Standard size | +| ------ | -------------------- | ----------- | ------------- | +| `x` | `pad byte` | no value | | +| `c` | `char` | bytes of length 1 | 1 | +| `b` | `signed char` | integer | 1 | +| `B` | `unsigned char` | integer | 1 | +| `?` | `_Bool` | bool | 1 | +| `h` | `short` | integer | 2 | +| `H` | `unsigned short` | integer | 2 | +| `i` | `int` | integer | 4 | +| `I` | `unsigned int` | integer | 4 | +| `l` | `long` | integer | 4 | +| `L` | `unsigned long` | integer | 4 | +| `q` | `long long` | integer | 8 | +| `Q` | `unsigned long long` | integer | 8 | +| `n` | `ssize_t` | integer | | +| `N` | `size_t` | integer | | +| `e` | `` | float | 2 | +| `f` | `float` | float | 4 | +| `d` | `double` | float | 8 | +| `s` | `char[]` | bytes | | +| `p` | `char[]` | bytes | | +| `P` | `void *` | integer | 4 | + + +## `ustruct`方法 + +### `ustruct.calcsize` + +```python +ustruct.calcsize(fmt) +``` + +返回存放 `fmt` 需要的字节数。 + +**参数描述：** + +- `fmt` - 格式字符的类型，详情见上文格化式字符表 + +**示例：** + +```python +>>> import ustruct +>>> ustruct.calcsize('i') +4 +>>> ustruct.calcsize('f') +4 +>>> ustruct.calcsize('d') +8 +``` + + + +### `ustruct.pack` + +```python +ustruct.pack(fmt, v1, v2, ...) +``` + +按照格式字符串 `fmt` 压缩参数v1、 v2、…。 + +**参数描述：** + +- `fmt` - 格式字符的类型，详情见上文格化式字符表 + +**返回值描述：** + +- 返回参数编码后的字节对象。 + + + +### `ustruct.unpack` + +```python +ustruct.unpack(fmt, data) +``` + +根据格式化字符串 `fmt` 对数据进行解压，返回值为一个元组。 + +**参数描述：** + +- `fmt` - 格式字符的类型，详情见上文格化式字符表 +- `data` - 要进行解压的数据 + +**返回值描述：** + +- 返回包含解压值的元组(即使只包含一个项)。 + +**示例：** + +```python +>>> import ustruct +>>> ustruct.pack('ii', 7, 9) #打包两个整数 +b'\x07\x00\x00\x00\t\x00\x00\x00' +>>> ustruct.unpack('ii', b'\x07\x00\x00\x00\t\x00\x00\x00') #解压两个整数 +(7, 9) +``` + + + +### `ustruct.pack_into` + +```python +ustruct.pack_into(fmt, buffer, offset, v1, v2, ...) +``` + +根据格式字符串`fmt`将值v1、v2、 …打包到从`offset`开始的缓冲区中。从缓冲区的末尾算起，`offset`可能为负。 + +**参数描述：** + +- `fmt` - 格式字符的类型，详情见上文格化式字符表 +- `buffer` - 可写数据缓冲区 +- `offset` - 写入的起始位置 + + + +### `ustruct.unpack_from` + +```python +ustruct.unpack_from(fmt, data, offset=0) +``` + +根据格式化字符串 `fmt` 解析从 `offest` 开始的数据解压，从缓冲区末尾开始计数的偏移量可能为负值。 + +**参数描述：** + +- `fmt` - 格式字符的类型，详情见上文格化式字符表 +- `data` - 数据缓冲区(缓冲区大小以字节为单位) +- `offset` - 解压的起始位置 + +**返回值描述：** + +- 返回解压值的元组(即使只包含一个项)。 -- Gitee