python脚本使用指南

金山文档的表格产品中引入了执行 Python 脚本能力，以期为用户提供一种更加灵活、高效的数据处理方式。

## **1\.**   **主要特点**

### **1\.**    **脚本内嵌在文档中**

与表格文档数据无缝结合，跟随文档一同分享协作

### **2\. 云端工作**

云端编码，云端执行，无需本地开发环境

### **3\. 使用python脚本完成数据分析全链路**

a.      **数据连接**

n  支持从工作表、数据表中获取数据写入到表格

n  将两张表以主键列联表，为数据分析提供基础

n  同时还可以利用开源库从第三方应用获取数据，比如利用python获取数据库数据

b.      **数据清洗**

n  在获取数据函数中支持过滤参数，可以实现数据清洗

c.      **数据可视化**

利用丰富的第三方库，轻松实现数据分析可视化

n  **数据操作与分析：** Pandas、NumPy

n  **数据可视化：** pyecharts

n  **金融数据：** akshare、tushare、baostock 等等

d.      **将结果导入到表格**

n  python脚本输出的结果可以写入到表格

n  python脚本输出的结果也可以导出为图片

 

 

## **2\.**   **开始使用**

使用 Python脚本编辑器前，请先在金山文档上新建或打开一个已有的智能表格或表格或多维表格文件

 

| 智能表格/表格文件中使用py脚本 | 多维表格文件中使用py脚本 |
| :---- | :---- |
| 在智能表格/表格文件中顶部信息区，选择效率 \> PY脚本 l  打开PY脚本功能的侧边栏后，可以看到文档内已经存在的Python文件和模板 l  点击新建脚本，创建Python文件，进入Python编辑栏，进行代码编辑 l  开始之前，也可以点击模板示例参考模板示例，了解表格中Python的使用   | 在多维表格顶部标题栏右侧区域，选择脚本 \> PY脚本 l  打开PY脚本功能弹窗后，可以看到文档内已经存在的Python文件和模板 l  点击新建脚本，创建Python脚本，进入Python编辑器，进行代码编辑 l  开始之前，也可以点击模板示例参考模板示例，了解表格中Python的使用   |

 

## **3\.**   **使用Python访问表格里的数据**

| 金山文档的表格类产品中有工作表ET和数据表DB的区别，不同的表格类型，读取/写入数据要使用的函数是不同的，下面展开说一下～ |
| :---- |

 

### **3.1使用python访问工作表里的数据**

#### **1\.**     **xl() 函数**

##### ¢  **函数签名**

         1  def xl(range: str \= "",

         2         headers: bool \= False,

         3         sheet\_name: str | list\[str\] \= "",

         4         book\_url: str \= "",

         5         start\_row: int | None \= None,

         6         start\_column: int | None \= None,

         7         end\_row: int | None \= None,

         8         end\_column: int | None \= None,

         9         formula: bool \= False) \-\> \_\_pd.DataFrame | dict\[str, \_\_pd.DataFrame\]: ...

##### ¢  **参数列表**

| 参数 | 类型 | 默认值 | 说明 |
| :---- | :---- | :---- | :---- |
| range | str | 空字符串 | 工作表中的选区描述。 默认为工作表中已经使用的区域。 |
| headers | bool | False | 是否将当前选区第一行处理为表头。 |
| sheet\_name | str or list | 空字符串 | 选区所在的工作表名称，可为多个。 默认为当前激活的工作表。 如果为None则返回全部工作表数据。 |
| book\_url | str | 空字符串 | 选区所在的表格文件地址。 必须为金山文档云文档地址。 默认当前表格。 |
| start\_row | int | None | 选区左上单元格的行，从0开始 |
| start\_column | int | None | 选区左上单元格的列，从0开始 |
| end\_row | int | 空值 | 选区右下单元格的行，从0开始 |
| end\_column | int | 空值 | 选区右下单元格的列，从0开始 |
| formula | bool | False | 是否返回单元格内的公式内容 |

 

##### ¢  **示例**

以下示例会使用到如下虚拟的进销存表格，并假设当前正在打开的是工作表1（激活状态）

|  |
| ----- |
| 表格中的数据均虚构，仅做示例使用 |

 

###### **a.**      **获取当前工作表（**工作表1**）中的所有数据，无表头**

         1  \# 相当于 df \= pandas.DataFrame(columns=None, data={全部数据})

         2  df1 \= xl()

         3   

         4  \# 由于无表头，只能按照索引访问 df 中的数据

         5  \# 下边这条语句会输出“产品名称”

         6  print(df1\[0\]\[0\])

 

###### **b.**     **获取当前工作表（**工作表1**）中的所有数据，无表头**

         1  \# 相当于 df \= pandas.DataFrame(columns=\[A1:C1\], data=\[A2:C5\])

         2  df2 \= xl("A1:C5", headers=True)

         3   

         4  \# 可以通过列名来索引 df 中的数据

         5  df2\_subset \= df\[\['产品名称', '发货日期'\]\]

 

###### **c.**      **获取**工作表2**（当前激活为**工作表1**）中，**A1:G10**区域的数据，将第一行处理为表头**

         1  \# 相当于 df \= pandas.DataFrame(columns=\[A1:G1\], data=\[A2:G10\])

         2  df3 \= xl("A1:G10", headers=True, sheet\_name="工作表2")

###### **d.**     **获取其它表格文档（**[https://kdocs.cn/l/foo](https://kdocs.cn/l/foo)**）中，**工作表3**的前10行数据，第一行作为表头**

         1  df4 \= xl(

         2      range="1:10",

         3      headers=True,

         4      sheet\_name="工作表3",

         5      book\_url="https://kdocs.cn/l/foo",

         6  )

###### **e.**      **获取当前表格中，所有工作表数据。**

         1  \# 此时将返回一个 dict\[str, pandas.DataFrame\] 类型的 ds

         2  \# ds 的 key 为工作表名称

         3  ds \= xl(

         4      headers=True,

         5      sheet\_name=None,

         6  )

         7   

         8  df5 \= ds\['工作表1'\]

 

###### **f.**       **获取当前表格（**工作表1**）中所有售价及发货日期数据**

         1  df6 \= xl(

         2      start\_row=0,

         3      start\_column=1,

         4  )

 

#### **2\.**     **write\_xl() 函数**

通过 write\_xl 函数将数据回写到工作表。

##### ¢  **函数签名**

         1  def write\_xl(data: object,

         2               range: str \= "",

         3               new\_sheet: bool \= False,

         4               sheet\_name: str \= "",

         5               overfill: bool \= True,

         6               book\_url: str \= "",

         7               start\_row: int | None \= None,

         8               start\_column: int | None \= None,

         9               write\_df\_index: bool \= False) \-\> None:

 

##### ¢  **参数列表**

| 参数 | 类型 | 默认值 | 说明 |
| :---- | :---- | :---- | :---- |
| data | object | 必填 | 要回写到工作表里的数据。 支持的数据类型包括： Python 基本数据类型； 维度不超过2维的容器类型，如： list 和 tuple； pandas.DataFrame； 不支持写入图片。 |
| range | str | 空字符串 | 工作表中的选区描述。 可以为一个单元格。为要写入数据的选区的左上角。 当new\_sheet=True时可以为空。默认为新工作表的A1位置。 |
| new\_sheet | bool | False | 是否将数据写入到新建的工作表中。 |
| sheet\_name | str | 空字符串 | 写入数据的选区所在的工作表名称。 当 new\_sheet=False 时为表格中已经存在的工作表名称。 当 new\_sheet=True 时为新建的工作表的名称。 |
| overfill | bool | True | 当 range 不足以容纳 data 时，是否允许超出部分继续写入。 如果设置为 False 超出 range 的 data 部分会被丢弃。 |
| book\_url | str | 字符串 | 指定写入的表格文件地址。 必须为金山文档云文档地址。 默认当前表格。 |
| start\_row | int | 空值 | 选区左上单元格的行，从0开始 |
| start\_column | int | 空值 | 选区左上单元格的列，从0开始 |
| write\_df\_index | bool | False | 是否写入pandas.DataFrame里的index列 |

 

##### ¢  **示例**

a.      **将字符串、数字回写到工作表**

         1  \# 原始工作表

         2  \# \+-------+-----+

         3  \# | Name  | Age |

         4  \# \+-------+-----+

         5  \# |  foo  |  1  |

         6  \# \+-------+-----+

         7  \# |  bar  |  2  |

         8  \# \+-------+-----+

         9  \# |  baz  |  3  |

      10  \# \+-------+-----+

      11   

      12  \# 删除"B3:B4"区域内的数据

      13  delete\_xl(range="B3:B4")

      14   

      15  \# 删除后的工作表

      16  \# \+-------+-----+

      17  \# | Name  | Age |

      18  \# \+-------+-----+

      19  \# |  foo  |  1  |

      20  \# \+-------+-----+

      21  \# |  bar  | 	|

      22  \# \+-------+-----+

      23  \# |  baz  | 	|

      24  \# \+-------+-----+

      25   

 

b.      **将** pandas.DataFrame **回写到工作表。**

将 DataFrame 回写到工作表时，是按照数据在 DataFrame 中的相对位置（行/列）进行写入的。如果设置了 overfill=False 超过选区 range 的部分会被丢弃

 

         1  import pandas as pd

         2   

         3  \# 构造一个有 columns 的 DataFrame

         4  df \= pd.DataFrame({"Name": \["foo", "bar", "baz"\], "Age": \[1, 2, 3\]})

         5   

         6  \# 将 df 写入到当前工作表的 A1 位置

         7  \# 由于 df 中包含 columns 定义

         8  \# 最终会写入到 A1:B4 选区

         9  \# 相当于第1行是表头，其余3行为数据

      10  \# \+-------+-----+

      11  \# | Name  | Age |

      12  \# \+-------+-----+

      13  \# |  foo  |  1  |

      14  \# \+-------+-----+

      15  \# |  bar  |  2  |

      16  \# \+-------+-----+

      17  \# |  baz  |  3  |

      18  \# \+-------+-----+

      19  write\_xl(df, "A1")

      20   

      21  \# 构造一个无 columns 的 DataFrame

      22  df2 \= pd.DataFrame(\[\["foo", 1\], \["bar", 2\], \["baz", 3\]\])

      23   

      24  \# 将 df2 写入到当前工作表的 A1 位置

      25  \# 由于 df2 中没有 columns（未显式定义，默认使用 pandas.RangeIndex）

      26  \# 最终会写入到 A1:B3 选区

      27  \# 相当于没有表头，只有3行数据

      28  \# \+-------+-----+

      29  \# |  foo  |  1  |

      30  \# \+-------+-----+

      31  \# |  bar  |  2  |

      32  \# \+-------+-----+

      33  \# |  baz  |  3  |

      34  \# \+-------+-----+

      35  write\_xl(df2, "A1")

      36   

      37  \# 也可以单独回写某个 series，行为与只有一个“列”的 DataFrame 一致

      38  write\_xl(df\['name'\], "A1:B1")

 

 

c.      **将** list**、**tuple**和**set**回写到工作表。**

将一维list、tuple和set回写到工作表。

         1  \# 构造一个有10个元素的 list

         2  l \= \[i for i in range(10)\]

         3   

         4  \# 将 l 回写到以 A1 开头的一行中

         5  \# \+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+

         6  \# |  0  |  1  |  2  |  3  |  4  |  5  |  6  |  7  |  8  |  9  |

         7  \# \+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+

         8  write\_xl(l, "A1")

         9   

      10  \# 将 l 回写到当前工作表的 A1:C1 区域

      11  \# 即将 l 回写成工作表中的一行

      12  \# 但是此时 A1:C1 选区不足以容纳 10 个元素

      13  \# 且 overfill=False 截断 l 中的元素

      14  \# \+-----+-----+-----+

      15  \# |  0  |  1  |  2  |

      16  \# \+-----+-----+-----+

      17  write\_xl(l, "A1:C1", overfill=False)

      18   

      19  \# 将 l 回写到当前工作表的 A1：A10 区域

      20  \# 与之前的示例相同，即将 l 回写成工作表中的一列

      21  \# \+-----+

      22  \# |  0  |

      23  \# \+-----+

      24  \# |  1  |

      25  \# \+-----+

      26  \# |  2  |

      27  \# \+-----+

      28  \# |  3  |

      29  \# \+-----+

      30  \# |  4  |

      31  \# \+-----+

      32  \# |  5  |

      33  \# \+-----+

      34  \# |  6  |

      35  \# \+-----+

      36  \# |  7  |

      37  \# \+-----+

      38  \# |  8  |

      39  \# \+-----+

      40  \# |  9  |

      41  \# \+-----+

      42  write\_xl(l, "A1:A10")

      43   

      44  \# 将 l 回写到当前工作表的 A1:E2 区域

      45  \# 即将 l 回写成工作表中2行\*5列

      46  \# 此时要求 l 的长度必须不大于选区的长度

      47  \# 否则无法判断该如何写入数据，导致报错

      48  \# \+-----+-----+-----+-----+-----+

      49  \# |  0  |  1  |  2  |  3  |  4  |

      50  \# \+-----+-----+-----+-----+-----+

      51  \# |  5  |  6  |  7  |  8  |  9  |

      52  \# \+-----+-----+-----+-----+-----+

      53  write\_xl(l, "A1:E2")

将二维list、tuple和set回写到工作表。

         1  \# 构造一个二维的 list

         2  data \= \[\["foo", 1\], \["bar", 2\], \["baz", 3\]\]

         3   

         4  \# 将 data 回写到当前工作表的 A1 位置

         5  \# 将会在工作表中写入如下数据：

         6  \# data 中的每一个子列表，被处理成工作表中的一行

         7  \# \+-------+-----+

         8  \# |  foo  |  1  |

         9  \# \+-------+-----+

      10  \# |  bar  |  2  |

      11  \# \+-------+-----+

      12  \# |  baz  |  3  |

      13  \# \+-------+-----+

      14  write\_xl(data, "A1")

 

#### **3\.**     **delete\_xl() 函数**

通过 delete\_xl 函数对数据进行删除操作。

##### ¢  **函数签名**

         1  def delete\_xl(range: str \= "",

         2                sheet\_name: str | list\[str\] \= '',

         3                book\_url: str | None \= '',

         4                entire\_row: bool \= False,

         5                entire\_column: bool \= False,

         6                xl\_shift\_to\_left: bool \= False,

         7                start\_row: int | None \= None,

         8                start\_column: int | None \= None,

         9                drop\_sheet: bool \= False):

##### ¢  **参数列表**

| 参数 | 类型 | 默认值 | 说明 |
| :---- | :---- | :---- | :---- |
| range | str | 空字符串 | 工作表中的选区描述。 |
| sheet\_name | str|list\[str\] | 空字符串 | 写入数据的选区所在的工作表名称。 |
| book\_url | str | 字符串 | 指定写入的表格文件地址。 必须为金山文档云文档地址。 默认当前表格。 |
| entire\_row | bool | False | 是否删除整行 |
| entire\_column | bool | False | 是否删除整列 |
| xl\_shift\_to\_left | bool | False | 是否向左合并，如果为 False 则向上合并 |
| start\_row | int | 空值 | 工作表中的起始行（从0开始），如果不传start\_column则删除整行 |
| start\_column | int | 空值 | 工作表中的起始列（从0开始），如果不传start\_row则删除整列 |
| drop\_sheet | bool | False | 是否删除整个工作表 |

 

##### ¢  **示例**

a.      **删除工作表某个范围的数据**

         1  \# 原始工作表

         2  \# \+-------+-----+

         3  \# | Name  | Age |

         4  \# \+-------+-----+

         5  \# |  foo  |  1  |

         6  \# \+-------+-----+

         7  \# |  bar  |  2  |

         8  \# \+-------+-----+

         9  \# |  baz  |  3  |

      10  \# \+-------+-----+

      11   

      12  \# 删除"B3:B4"区域内的数据

      13  delete\_xl(range="B3:B4")

      14   

      15  \# 删除后的工作表

      16  \# \+-------+-----+

      17  \# | Name  | Age |

      18  \# \+-------+-----+

      19  \# |  foo  |  1  |

      20  \# \+-------+-----+

      21  \# |  bar  | 	|

      22  \# \+-------+-----+

      23  \# |  baz  | 	|

      24  \# \+-------+-----+

 

b.      **删除某行或某列数据**

         1  \#原始工作表

         2  \+-------+-----+

         3  | Name  | Age |

         4  \+-------+-----+

         5  |  foo  |  1  |

         6  \+-------+-----+

         7  |  bar  |  2  |

         8  \+-------+-----+

         9  |  baz  |  3  |

      10  \+-------+-----+

      11  删除"B3:B4"区域内的数据

      12  delete\_xl(range="B3:B4")

      13  删除后的工作表

      14  \+-------+-----+

      15  | Name  | Age |

      16  \+-------+-----+

      17  |  foo  |  1  |

      18  \+-------+-----+

      19  |  bar  | 	|

      20  \+-------+-----+

      21  |  baz  | 	|

      22  \+-------+-----+

 

c.      **删除整个工作表**

         1  delete\_xl(sheet\_name="sh1", drop\_sheet=True)

 

### **3.2 使用python访问数据表里的数据**

| 注意 由于数据表中的类型并不能简单使用 pandas.DataFrame 来承载，因此对数据表读写的支持目前还不完善。 |
| :---- |

#### **1\.**     **数据表中的字段类型**

不同于传统的表格产品，数据表中的每个字段，都是有类型的。这些类型包括：

| 字段类型 | 类型名称 | 值类型 | 说明 |
| :---- | :---- | :---- | :---- |
| MultiLineText | 文本 | string |   |
| Date | 日期 | string |   |
| Time | 时间 | string |   |
| Number | 数值 | numeric |   |
| Currency | 货币 | numeric |   |
| Percentage | 百分比 | numeric |   |
| ID | 身份证 | string |   |
| Phone | 电话 | string |   |
| Email | 电子邮箱 | string |   |
| URL | 超链接 | object | 不支持通过 Python 更新 |
| Checkbox | 复选框 | boolean |   |
| SingleSelect | 单选项 | object | 不支持通过 Python 更新 |
| MultipleSelect | 多选项 | object | 不支持通过 Python 更新 |
| Rating | 等级 | numeric | 会被降级成 Number 类型 |
| Complete | 进度条 | numeric |   |
| Contact | 联系人 | object | 不支持通过 Python 更新 |
| Attachment | 附件 | object | 不支持通过 Python 更新 |
| Link | 关联 | object | 不支持通过 Python 更新 |
| Note | 富文本 | object | 不支持通过 Python 更新 |
| Address | 地址 | object | 不支持通过 Python 更新 |
| Cascade | 级联 | object | 不支持通过 Python 更新 |

 

以下类型为数据表中的自动类型，即该类型的记录值是系统自动填充的，不支持外部更新。

| 字段类型 | 类型名称 |
| :---- | :---- |
| AutoNumber | 编号 |
| CreatedBy | 创建者 |
| CreatedTime | 创建时间 |
| LastModifiedBy | 最后修改者 |
| LastModifiedTime | 最后修改时间 |
| Formula | 公式 |
| Lookup | 引用 |

 

#### **2\.**     **dbt() 函数**

使用dbt()函数读取数据表中的数据。

##### ¢  **函数签名**

         1  def dbt(field: str | list\[str\] \= None,

         2          sheet\_name: str | list\[str\] \= '',

         3          book\_url: str \= '') \-\> \_\_pd.DataFrame | dict\[str, \_\_pd.DataFrame,

         4          condition: dict \= {}\]:

##### ¢  **参数列表**

| 参数 | 类型 | 默认值 | 说明 |
| :---- | :---- | :---- | :---- |
| field | str or list | None | 要返回的字段列表。 默认为None，表示返回所有字段。 |
| sheet\_name | str or list | 空字符串 | 字段所在的数据表名称，可为多个。 默认为当前激活的数据表。 如果为None则返回全部数据表数据。 |
| book\_url | str | 空字符串 | 字段所在的表格文件地址。 必须为金山文档云文档地址。 默认当前表格。 |
| condition | dict | {} | 过滤条件，细节参考 [附件1：dbt 函数筛选记录说明](https://kdocs.cn/l/cuUFLE0Ufojw?linkname=MMrEjw3roe) |

 

| 注意 dbt() 函数返回的 pandas.DataFrame.index 中包含每一条记录的 ID，供更新数据表使用时使用。 |
| :---- |

##### ¢  **示例**

以下示例会使用到如下虚拟的进销存表格，并假设当前正在打开的是数据表1

读取当前数据表数据表1中的产品名称和库存数量

|  |
| ----- |
| 表格中的数据均虚构，仅做示例使用 |

a.      读取当前数据表（数据表1）中的产品名称和库存数量。

         1  \# 返回数据表1中的字段名为产品名称和库存数量的记录，表头为字段名

         2  \# 返回的数据类似下表所示

         3  \#  其中 B，C，D 为 Index 中保存的记录 ID

         4  \# \+-----+-------------+----------+

         5  \# | 	|   产品名称   |  库存数量  |

         6  \# \+-----+-------------+----------+

         7  \# |  B  |  iPhone 12  |   100    |

         8  \# \+-----+-------------+----------+

         9  \# |  C  | MacBook Pro |   175    |

      10  \# \+-----+-------------+----------+

      11  \# |  D  | iPad Air 4  |   173	|

      12  \# \+-----+-------------+----------+

      13  df \= dbt(field=\['产品名称', '库存数量'\])

 

b.      读取当前数据表中，数据表1和数据表2的所有记录

         1  \# 此时返回的是一个包括两个 DataFrame 的 dict

         2  ds \= dbt(sheet\_name=\['数据表1', '数据表2'\])

         3  df1 \= ds\['数据表1'\]

         4  df2 \= ds\['数据表2'\]

 

c.      读取其它文档([https://www.kdocs.cn/l/bar)](https://www.kdocs.cn/l/bar\))中的全部数据表中记录

         1  \# 此时返回的是一个包括多个 DataFrame 的 dict

         2  ds \= dbt(sheet\_name=None, book\_url="https://www.kdocs.cn/l/bar")

 

#### **3\.**     **insert\_dbt() 函数**

使用insert\_dbt()函数向数据表中写入新记录。

##### ¢  **函数签名**

         1  def insert\_dbt(data: dict\[str, any\] | list\[dict\[str, any\]\] | \_\_pd.DataFrame,

         2                 sheet\_name: str \= '',

         3                 new\_sheet: bool \= False) \-\> None:

 

##### ¢  **参数列表**

| 参数 | 类型 | 默认值 | 说明 |
| :---- | :---- | :---- | :---- |
| data | object | 必填 | 要回写到数据表里的数据。 支持的数据类型包括： dict\[str, any\]包含记录名称和值的 dict； 维度不超过2维的 list 类型； pandas.DataFrame； 不支持写入附件等复杂类型。 |
| sheet\_name | str | 空字符串 | 写入数据的选区所在的数据表名称。 当 new\_sheet=False 时为表格中已经存在的数据表名称。 当 new\_sheet=True 时为新建的数据表的名称。 |
| new\_sheet | bool | False | 是否将数据写入到新建的数据表中。 |

 

| 提示 建议直接使用 dbt() 函数返回的 DataFrame，进行所需要的处理后，回写数据表。 |
| :---- |

##### ¢  **示例**

         1  \# 返回数据表1中的字段名为产品名称和库存数量的记录，表头为字段名

         2  \# 返回的数据类似下表所示

         3  \#  其中 B，C，D 为 Index 中保存的记录 ID

         4  \# \+-----+-------------+----------+

         5  \# | 	|   产品名称   |  库存数量  |

         6  \# \+-----+-------------+----------+

         7  \# |  B  |  iPhone 12  |   100    |

         8  \# \+-----+-------------+----------+

         9  \# |  C  | MacBook Pro |   175    |

      10  \# \+-----+-------------+----------+

      11  \# |  D  | iPad Air 4  |   173	|

      12  \# \+-----+-------------+----------+

      13  df \= dbt(field=\['产品名称', '库存数量'\])

      14   

      15  \# 将 df 中的数据写入到新的数据表2中

      16  insert\_dbt(df, sheet\_name="数据表2", new\_sheet=True)

      17   

      18  \# 向数据表2中，新增一条记录

      19  insert\_dbt({"产品名称": "iPad Air 5", "库存数量": 100 }, sheet\_name="数据表2")

      20   

      21  \# 向数据表2中，新增两条记录

      22  insert\_dbt(\[{"产品名称": "Mac mini M2"}, {"产品名称": "Mac mini M2 Pro"}\] , sheet\_name="数据表2")

 

#### **4\.**     **update\_dbt() 函数**

使用update\_dbt()函数更新数据表中记录

##### ¢  **函数签名**

         1  def update\_dbt(data: dict\[str, any\] | list\[dict\[str, any\]\] | \_\_pd.DataFrame,

         2                 sheet\_name: str \= '') \-\> None:

##### ¢  **参数列表**

| 参数 | 类型 | 默认值 | 说明 |
| :---- | :---- | :---- | :---- |
| data | object | 必填 | 要回写到数据表里的数据。 支持的数据类型包括： dict\[str, any\]包含记录ID、名称和值的 dict； 维度不超过2维的 list 类型； pandas.DataFrame； 不支持写入附件等复杂类型。 |
| sheet\_name | str | 空字符串 | 写入数据的选区所在的数据表名称。 当 new\_sheet=False 时为表格中已经存在的数据表名称。 当 new\_sheet=True 时为新建的数据表的名称。 |

 

##### ¢  **示例**

         1  \# 返回数据表1中的字段名为产品名称和库存数量的记录，表头为字段名

         2  \# 返回的数据类似下表所示

         3  \#  其中 B，C，D 为 Index 中保存的记录 ID

         4  \# \+-----+-------------+----------+

         5  \# | 	|   产品名称   |  库存数量  |

         6  \# \+-----+-------------+----------+

         7  \# |  B  |  iPhone 12  |   100    |

         8  \# \+-----+-------------+----------+

         9  \# |  C  | MacBook Pro |   175    |

      10  \# \+-----+-------------+----------+

      11  \# |  D  | iPad Air 4  |   173	|

      12  \# \+-----+-------------+----------+

      13  df \= dbt(field=\['产品名称', '库存数量'\])

      14   

      15  \# 修改 df 中的数据，并更新数据表中的记录

      16  df\['库存数量'\] \= df\['库存数量'\] \* 2

      17  update\_dbt(df)

      18   

      19  \# 单独修改数据表1中的记录

      20  \# 其中包括ID字段 \_rid 值为对应的 Index 中的值

      21  update\_dbt({"\_rid": "B", "产品名称": "iPhone 12 Pro"})

      22   

      23  \# 更新多条记录的值

      24  update\_dbt(\[{"\_rid": "C", "产品名称": "MacBook Pro M1"}, {"\_rid": "D", "库存数量": 200}\])

 

#### **5\.**     **delete\_dbt() 函数**

使用delete\_dbt()函数删除数据表中的数据。

##### ¢  **函数签名**

         1  def dbt(sheet\_name: str | list\[str\] \= '',

         2          book\_url: str \= '') \-\> \_\_pd.DataFrame | dict\[str, \_\_pd.DataFrame,

         3          condition: dict \= {}\]:

##### ¢  **参数列表**

| 参数 | 类型 | 默认值 | 说明 |
| :---- | :---- | :---- | :---- |
| sheet\_name | str or list | 空字符串 | 字段所在的数据表名称，可为多个。 默认为当前激活的数据表。 如果为None则返回全部数据表数据。 |
| book\_url | str | 空字符串 | 字段所在的表格文件地址。 必须为金山文档云文档地址。 默认当前表格。 |
| condition | dict | {} | 过滤条件，细节参考 [附件1：dbt 函数筛选记录说明](https://kdocs.cn/l/cuUFLE0Ufojw?linkname=MMrEjw3roe) 当没有 |

##### ¢  **示例代码**

以下示例会使用到如下虚拟的小费的信息

a.      case1:删除整表数据

         1  delete\_dbt(sheet\_name=\["数据表"\])

 

b.      case2: 根据条件删除数据。 如下代码，删除 食物为“炸蘑菇”的数据

         1  delete\_dbt(

         2    sheet\_name=\["小费数据"\],

         3    condition={

         4      "mode": "AND",

         5      "criteria": \[

         6          {

         7              "field": "食物",

         8              "op": "Intersected",

         9              "values": \[

      10                  "炸蘑菇"

      11              \]

      12          }

      13      \]

      14  })

 

## **4\.**   **内置的第三方库**

 

#### l  [pandas](https://github.com/pandas-dev/pandas)

Pandas是一个开源的数据分析和数据处理库，它是基于NumPy构建的，提供了高性能、易于使用的数据结构和数据分析工具，使得在Python中进行数据处理和分析变得更加简单和高效

#### l  [requests](https://github.com/psf/requests)

requests库是Python的一个HTTP客户端库，可以帮助用户发送各种类型的HTTP请求，如GET、POST、PUT、DELETE等，并获取响应。requests库具有简单易用、功能强大、灵活性高等特点，因此被广泛应用于Python网络编程中

 

#### l  [akshare](https://github.com/akfamily/akshare)

AkShare是基于Python的开源金融数据接口库，目的是实现对股票、期货、期权、基金、债券、外汇等金融产品和另类数据从数据采集，数据清洗到数据下载的工具，满足金融数据科学

#### l  [astropy](https://github.com/astropy/astropy)

Astropy用于天文学数据处理和分析。它提供了许多有用的工具和函数来操作各种类型的天文学数据，从图像和表格到天体物理学常见的坐标系转换和单位转换

#### l  [baostock](https://pypi.org/project/baostock/)

BaoStock是一个证券数据服务平台。考虑到 Python pandas 包在金融量化分析中体现出的优势， BaoStock 返回的绝大部分的数据格式都是 pandas DataFrame 类型，非常便于用 pandas/NumPy/Matplotlib 进行数据分析和可视化

#### l  [bs4](https://github.com/wention/BeautifulSoup4)

Beautiful Soup（简称BS4）是一个用于解析HTML和XML文档的Python库。它提供了一种简单而灵活的方式来导航、搜索和修改解析树，使得从网页中提取数据变得更加容易

#### l  [Cartopy](https://github.com/SciTools/cartopy)

Cartopy是一个Python包，用于地理空间数据处理，以便生成地图和其他地理空间数据分析。 Cartopy利用了强大的PROJ.4、NumPy和Shapely库，并在Matplotlib之上构建了一个编程接口，用于创建发布高质量的地图

#### l  [imbalanced-learn](https://github.com/scikit-learn-contrib/imbalanced-learn)

imbalanced-learn提供了一些技术来解决数据不平衡的问题。在分类问题中，如果数据集中的一个类别的样本数量远远大于另一个类别，这会导致模型对多数类别的偏向，从而降低对少数类别的识别能力。这种情况下，imbalanced-learn库可以帮助提高模型对少数类别的识别能力

#### l  [IPython](https://github.com/ipython/ipython)

IPython是一个交互式计算环境的扩展库，提供了一个强大的交互式环境和工具集，提供了许多方便的功能和特性，使得开发者可以更加高效地编写、测试和调试Python代码。它是Python数据科学和机器学习领域中常用的工具之一

#### l  [matplotlib](https://github.com/matplotlib/matplotlib)

Matplotlib是Python中一个常用的绘图库，可以用于绘制各种类型的图表，包括线图、散点图、条形图、等高线图、3D图等等。它是一个非常强大和灵活的库，被广泛用于数据科学、机器学习、工程学、金融等领域

#### l  [networkx](https://github.com/networkx/networkx)

NetworkX是一个用于创建、操作和学习复杂网络的Python库。它提供了一组丰富的工具和算法，用于分析和可视化网络结构，以及研究网络的属性和行为

#### l  [nltk](https://github.com/nltk/nltk)

Natural Language Toolkit（简称NLTK）是一个用于自然语言处理（NLP）的Python库。它提供了一系列工具和数据集，用于处理、分析和理解文本数据

#### l  [numpy](https://github.com/numpy/numpy)

NumPy（Numerical Python）是一个用于科学计算的Python库。它提供了一个高性能的多维数组对象（ndarray）和一组用于操作数组的函数，使得在Python中进行数值计算和数据处理变得更加高效和方便

#### l  [pyecharts](https://github.com/pyecharts/pyecharts/)

Pyecharts是一个用于生成交互式图表和可视化的Python库，它基于Echarts JavaScript库，并提供了一种简单而强大的方式来创建各种类型的图表。通过Pyecharts，可以轻松地将数据转化为各种图表，如折线图、柱状图、散点图、饼图等等，并且可以对图表进行各种定制，如修改颜色、添加标签、调整字体等等。使用Pyecharts可以大大提高数据可视化的效率，让用户更加直观地了解数据的分布和规律。同时，Pyecharts也支持多种输出格式，如HTML、PDF等，方便用户将图表嵌入到Web页面或生成报告中使用

#### l  [pymysql](https://github.com/PyMySQL/PyMySQL)

PyMySQL是Python中用于连接和操作MySQL数据库的一个库。它提供了Python编程语言和MySQL数据库之间的接口，使得Python程序可以方便地连接、查询和操作MySQL数据库

#### l  [pywavelets](https://github.com/PyWavelets/pywt)

PyWavelets是Python中用于小波变换的免费开源库。小波是在时间和频率上都局部化的数学基函数，小波变换则是利用小波的时频变换来分析和处理信号或数据。PyWavelets提供了丰富的功能和灵活的接口，可以对图像、音频、信号等数据进行小波变换、逆变换、阈值去噪、压缩等操作。此外，PyWavelets还支持多种小波基函数和边界处理方式，用户可以根据需要选择合适的小波基函数和参数

#### l  [scikit-image](https://github.com/scikit-image/scikit-image)

Scikit-image是一个基于Python脚本语言开发的数字图片处理包，它将图片作为numpy数组进行处理，正好与matlab一样。scikit-image对scipy.ndimage进行了扩展，提供了更多的图片处理功能。Scikit-image库包含了一些基本的图像处理功能，比如图像缩放、旋转、图像变换、阈值化处理等等。此外，它还包含了众多高级图像处理算法，比如边缘检测、形态学操作、直线和圆检测等等

#### l  [scikit-learn](https://github.com/scikit-learn/scikit-learn)

Scikit-learn（以前称为scikits.learn，也称为sklearn）是一个简单高效的数据挖掘和数据分析工具，建立在Python编程语言之上。它是为了解决真实世界中的问题而开发的，并且在学术和商业环境中都得到了广泛的应用。Scikit-learn的主要功能包括分类、回归、聚类、降维、模型选择和预处理

#### l  [scipy](https://github.com/scipy/scipy)

scipy是一个基于Python的开源科学计算库，它建立在NumPy库的基础上，提供了更高级的数学、科学和工程计算功能。scipy库包含了许多模块，每个模块都提供了一组相关的函数和工具，用于解决各种数学、科学和工程问题

#### l  [seaborn](https://github.com/mwaskom/seaborn)

Seaborn是一个基于Python的数据可视化库，它在matplotlib的基础上进行了更高级的API封装，使得作图更加容易，并且制作出来的图形也更加美观和具有吸引力。Seaborn提供了一种高度交互式界面，便于用户能够做出各种有吸引力的统计图表

#### l  [statsmodels](https://github.com/statsmodels/statsmodels)

statsmodels是一个Python库，提供了用于统计建模和计量经济学的函数和类。它包含了一系列统计模型，用于数据分析、探索性数据分析(EDA)、建模和推断。该库的目标是提供一种简单而一致的接口，使得用户可以在Python中进行各种统计任务

#### l  [sympy](https://github.com/sympy/sympy)

sympy是一个基于Python的符号计算库，它提供了符号计算的功能，可以进行符号代数、微积分、线性代数、离散数学等方面的计算。与其他数值计算库不同，sympy库执行的是精确计算，而不是数值近似，这使得它非常适合用于数学推导、符号计算和数学建模

#### l  [tushare](https://github.com/waditu/tushare)

tushare是一个基于Python的金融数据接口库，它提供了丰富的金融市场数据，包括股票、指数、基金、期货、外汇等数据。tushare库获取数据的来源是中国的金融市场，可以帮助获取和分析金融数据

 

#### l  [qrcode](https://github.com/lincolnloop/python-qrcode)

qrcode是一个基于Python的二维码生成库，它可以将文本、URL或其他数据转换成二维码图像。该库支持自定义二维码的大小、颜色、纠错级别等参数，同时还可以在二维码中添加logo图片。它的API简单易用，既可以生成基本的黑白二维码，也可以创建带有自定义样式的艺术二维码。

         1  import qrcode

         2   

         3  \# 生成二维码

         4  qr \= qrcode.QRCode(

         5      version=1,

         6      error\_correction=qrcode.constants.ERROR\_CORRECT\_L,

         7      box\_size=10,

         8      border=4,

         9  )

      10  qr.add\_data('https://www.baidu.com')

      11  qr.make(fit=True)

      12   

      13  img \= qr.make\_image(fill\_color="black", back\_color="white")

      14   

      15  img.show()

#### l  [jionlp](https://github.com/dongrixinyu/JioNLP)

jionlp是一个中文NLP工具包，提供了大量常用的中文文本处理功能，包括文本清洗、实体识别、地址解析、时间解析、摘要生成、新闻分类等。它设计简洁，即装即用，能够帮助开发者快速处理中文文本数据，适用于各类中文NLP任务。

         1  import jionlp as jio

         2   

         3  text \= '有疑问请联系张小姐18340234920，或拨打(028)58291283。'

         4  phones \= jio.remove\_phone\_number(text)

#### l  [jieba](https://github.com/fxsjy/jieba)

jieba是最常用的中文分词库之一，它提供了多种分词模式，包括精确模式、全模式、搜索引擎模式等。除了基本分词功能外，jieba还支持自定义词典、关键词提取、词性标注等功能。它采用基于前缀词典实现高效的词图扫描，使用动态规划查找最大概率路径，具有较好的分词准确率。

         1  import jieba

         2   

         3  seg\_list \= jieba.cut("我来到北京清华大学", cut\_all=True)

         4  print("Full Mode: " \+ "/ ".join(seg\_list))  \# 全模式

         5   

         6  seg\_list \= jieba.cut("我来到北京清华大学", cut\_all=False)

         7  print("Default Mode: " \+ "/ ".join(seg\_list))  \# 精确模式

         8   

         9  seg\_list \= jieba.cut("他来到了网易杭研大厦")  \# 默认是精确模式

      10  print(", ".join(seg\_list))

      11   

      12  seg\_list \= jieba.cut\_for\_search("小明硕士毕业于中国科学院计算所，后在日本京都大学深造")  \# 搜索引擎模式

      13  print(", ".join(seg\_list))

#### l  [faker](https://github.com/joke2k/faker)

faker是一个用于生成假数据的Python库，它可以生成各种类型的虚拟数据，包括姓名、地址、电话号码、邮箱、公司名称、信用卡号等。支持多种语言和地区的数据格式，对于开发测试、数据库填充、演示样例等场景非常有用。

         1  from faker import Faker

         2   

         3  fake \= Faker()

         4   

         5  print(f"Name: {fake.name()}")

         6  print(f"Address: {fake.address()}")

         7  print(f"Text: {fake.text()}")

#### l  [pypinyin](https://github.com/mozillazg/python-pinyin)

pypinyin是一个汉字转拼音的Python库，支持将中文汉字转换为拼音，提供多种拼音风格（包括带声调、数字声调、无声调等），可以处理多音字，支持自定义词库。它常用于中文文本的拼音化、汉字排序、模糊搜索等场景。

         1  from pypinyin import pinyin

         2   

         3  print(pinyin('中心'))

#### l  [polars](https://github.com/pola-rs/polars)

polars是一个高性能的数据处理库，使用Rust语言编写并提供Python接口。它提供了类似pandas的DataFrame API，但在处理大规模数据时具有更好的性能。polars支持惰性计算、并行处理、内存优化等特性，适合处理大规模数据分析和数据处理任务，特别是在需要高性能计算的场景下。

         1  import polars as pl

         2   

         3  \# 创建一个简单的DataFrame

         4  df \= pl.DataFrame({

         5        "A": \[1, 2, 3, 4\],

         6        "B": \[5, 6, 7, 8\]

         7  })

         8   

         9  \# 查看DataFrame

      10  print(df)

      11   

      12  \# 选择列

      13  print(df.select(\["A", "B"\]))

      14   

      15  \# 过滤行

      16  print(df.filter(pl.col("A") \> 2))

      17   

      18  \# 排序

      19  print(df.sort(by="A"))

      20   

      21  \# 聚合

      22  print(df.group\_by("A").agg(pl.col("B").mean()))

 

## **附件1：dbt 函数筛选记录说明**

在 dbt 中，使用 condition 参数对数据进行筛选，说明如下、

### **1\.**    **condition参数格式**

         1  {

         2      "mode": "AND", // 选填。表示各筛选条件之间的逻辑关系。只能是"AND"或"OR"。缺省值为"AND"

         3      "criteria": \[ // 结构体内必填。包含筛选条件的数组。每个字段上只能有一个筛选条件

         4          {

         5              "field": "名称", // 必填。根据 preferId 与否，需要填入字段名或字段id

         6              "op": "Intersected", // 必填。表示具体的筛选规则，见下

         7              "values": \[ // 必填。表示筛选规则中的值。数组形式。

         8                  "多维表", // 值为字符串时表示文本匹配

         9                  "12345"

      10              \]

      11          },

      12          {

      13              "field": "数量",

      14              "op": "greager",

      15              "values": \[

      16                  "1"

      17              \]

      18          }

      19      \]

      20  }

 

注 1：这里的 mode 必须大写，否则会出错

注 2：这里的 values，必须是一个数组，传 \["多维表"\]，相当于传 \[{ type: 'Text', value: '多维表' }\]，即不传默认帮你补充 Text 类型

注 3：复选框的值，values: \['0'\] 代表否，value: \['1'\] 代表是

 

### **2\. 筛选条件 op 参数说明**

         1  • "Equals": 等于

         2  • "NotEqu": 不等于

         3  • "Greater": 大于

         4  • "GreaterEqu": 大等于

         5  • "Less": 小于

         6  • "LessEqu": 小等于

         7  • "GreaterEquAndLessEqu": 介于（取等）

         8  • "LessOrGreater": 介于（不取等）

         9  • "BeginWith": 开头是

      10  • "EndWith": 结尾是

      11  • "Contains": 包含

      12  • "NotContains": 不包含

      13  • "Intersected": 指定值

      14  • "Empty": 为空

      15  • "NotEmpty": 不为空

values\[\]数组内的元素为字符串时，表示文本匹配

各筛选规则独立地限制了values数组内最多允许填写的元素数，当values内元素数超过阈值时，该筛选规则将失效。

a.      “为空、不为空”不允许填写元素；

b.      “介于”允许最多填写2个元素；

c.      “指定值”允许填写65535个元素；

d.      其他规则允许最多填写1个元素

 

使用指定值（Intersected）操作符时，values 中填写的值，应该是多维表中实际展示的值。比如筛选“货币”类型的列时，应带上货币符号，比如：

         1  {

         2      "mode": "AND",

         3      "criteria": \[{

         4          "field": "货币列",

         5          "op": "Intersected",

         6          "values": \[

         7              "$16.99"

         8          \]

         9      }\]

      10  }

 

### **3\. 日期的动态筛选**

目前还支持对日期进行动态筛选，此时values\[\]内的元素需以结构体的形式给出：

         1  condition \= {

         2              "mode": "AND",

         3              "criteria": \[

         4                  {

         5                      "field": "日期",

         6                      "op": "Equals",

         7                      "values": \[

         8                          {

         9                              "dynamicType": "lastMonth",

      10                              "type": "DynamicSimple"

      11                          }

      12                      \]

      13                  }

      14              \]

      15          }

 

上述示例对应的筛选条件为“等于上一个月”。

要使用日期动态筛选，values\[\]内的结构体需要指定"type": "DynamicSimple"，当"op"为"equals"时，"dynamicType"可以为如下的值（大小写不敏感）：

         1  • "today": 今天

         2  • "yesterday": 昨天

         3  • "tomorrow": 明天

         4  • "last7Days": 最近7天

         5  • "last30Days": 最近30天

         6  • "thisWeek": 本周

         7  • "lastWeek": 上周

         8  • "nextWeek"：下周

         9  • "thisMonth": 本月

      10  • "lastMonth": 上月

      11  • "nextMonth": 次月

当"op"为"greater"或"less"时，"dynamicType"只能是昨天、今天或明天。

 

 

## **附件2：PY脚本编辑器公网IP地址**

 

l  白名单CIDR的形式：

         1  101.201.253.202/32

         2  110.43.90.21/32

         3  110.43.90.22/31

         4  110.43.90.24/31

         5  114.112.66.4/30

         6  114.112.66.8/32

         7  140.210.67.133/32

         8  140.210.67.134/31

         9  140.210.67.136/30

      10  140.210.67.140/32

      11  110.43.67.132/30

      12  110.43.67.244/30

l  白名单IP的形式：

         1  101.201.253.202

         2  110.43.90.21

         3  110.43.90.22

         4  110.43.90.23

         5  110.43.90.24

         6  110.43.90.25

         7  114.112.66.4

         8  114.112.66.5

         9  114.112.66.6

      10  114.112.66.7

      11  114.112.66.8

      12  140.210.67.133

      13  140.210.67.134

      14  140.210.67.135

      15  140.210.67.136

      16  140.210.67.137

      17  140.210.67.138

      18  140.210.67.139

      19  140.210.67.140

      20  110.43.67.132

      21  110.43.67.133

      22  110.43.67.134

      23  110.43.67.135

      24  110.43.67.244

      25  110.43.67.245

      26  110.43.67.246

      27  110.43.67.247

