Skip to content

Commit 5256b5d

Browse files
mayneyaomayneyao
authored
Upgrade to v1 (#12)
* feat: field meta * feat: lazy query part1 * refactor: all * refactor: structure * test: add test case * docs: upgrade to v1 * chore: upgrade to v1.0.0
1 parent 80292f7 commit 5256b5d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+1607
-799
lines changed

‎.env.example‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
TEST_TABLE = https://integration.vika.ltd/space/spcYGJHMuVaKC/workbench/dstfigTYav0e7iClkd/viw0KXQPEjKMq
2-
TEST_API_TOKEN = uskbjQCFxC20nhd9jK8H4uC
2+
TEST_API_TOKEN = uskbjQCFxC20nhd7jK8H5uC
33
# 测试集成环境时，需要修改这里
4-
TEST_API_BASE = https://integration.vika.ltd
4+
TEST_API_BASE = https://integration.vika.ltd
5+
TEST_SPACE_ID = spcGww2HxqFNc
6+
TEST_FOLDER_ID = fod4Him18BAEZ

‎README.md‎

Lines changed: 116 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
> ⚠️ 请参考[迁移指南](https://github.com/vikadata/vika.py/blob/master/docs/upgrade-to-v1.md) 从 0.1.x 升级至 1.x 版本，旧版本我们将不再维护!
2+
13
![vika.py](https://socialify.git.ci/vikadata/vika.py/image?description=1&descriptionEditable=Vika%20is%20a%20API-based%20SaaS%20database%20platform%20for%20users%20and%20developers%20here%27s%20Python%20SDK%20for%20integration.&font=Inter&forks=1&issues=1&language=1&logo=https%3A%2F%2Fs1.vika.cn%2Fspace%2F2020%2F09%2F04%2F9fcd0d98c2c74274840fcde3341d5164&owner=1&pattern=Circuit%20Board&pulls=1&stargazers=1&theme=Light)
24

35
[Vika](https://vika.cn) Python SDK 是对维格表 Fusion API 的官方封装，提供类似 Django ORM 风格的 API。
@@ -8,7 +10,7 @@
810

911
### 环境要求
1012

11-
python3.6 +
13+
python3.6 +
1214

1315
### 安装
1416

@@ -26,21 +28,22 @@ pip install --upgrade vika
2628

2729
```python
2830
from vika import Vika
31+
2932
vika = Vika("your api_token")
3033

3134
dst = vika.datasheet("dstt3KGCKtp11fgK0t")
3235
# 传入表格URL 会自动解析表格 id，忽略视图 id。
3336
# dst = vika.datasheet("https://vika.cn/space/spcxcvEBLXf7X/workbench/dstt3KGCKtp11fgK0t/viwmKtRiYcPfk")
3437

3538
# 创建记录
36-
record = dst.records.create({"title":"new record from Python SDK"})
39+
record = dst.records.create({"title": "new record from Python SDK"})
3740
print(record.title)
38-
#print(record.标题)
41+
# print(record.标题)
3942

4043
# 批量创建记录
4144
records = dst.records.bulk_create([
42-
{"title":"new record from Python SDK"},
43-
{"title":"new record from Python SDK2"}
45+
{"title": "new record from Python SDK"},
46+
{"title": "new record from Python SDK2"}
4447
])
4548

4649
# 更新单个字段值
@@ -50,15 +53,14 @@ print(record.title)
5053

5154
# 更新多个字段值
5255
record.update({
53-
"title":"new title",
54-
"other_field": "new value",
56+
"title": "new title",
57+
"other_field": "new value",
5558
})
5659

5760
# 附件字段更新
58-
my_file = dst.upload_file(<本地或网络文件路径>)
61+
my_file = dst.upload_file( < 本地或网络文件路径 >)
5962
record.files = [my_file]
6063

61-
6264
# 过滤记录
6365
songs = dst_songs.records.filter(artist="faye wong")
6466
for song in songs:
@@ -77,6 +79,16 @@ record.json()
7779
# 删除符合过滤条件的一批记录
7880
dst.records.filter(title=None).delete()
7981

82+
# 获取字段
83+
field = dst.fields[0]
84+
field = dst.fields.get(name="标题")
85+
field = dst.fields.get(id="fidxxxxx")
86+
print(field.name, field.desc, field.type)
87+
88+
# 获取视图
89+
view = dst.views[0]
90+
print(view.type, view.name)
91+
8092
```
8193

8294
### 字段映射
@@ -88,8 +100,6 @@ dst.records.filter(title=None).delete()
88100
| Bug 标题\! | Bug状态 |
89101
| -------------- | ------- |
90102
| 登陆后页面崩溃 | 待修复 |
91-
| | |
92-
93103

94104
```python
95105
dst = vika.datasheet("dstt3KGCKtp11fgK0t",field_key_map={
@@ -106,13 +116,14 @@ record.state="已修复"
106116
```
107117

108118
保留使用 field id 作 key 的用法
119+
109120
```python
110121
bug = vika.datasheet("dstn2lEFltyGHe2j86", field_key="id")
111122
row = bug.records.get(flddpSLHEzDPQ="登陆后页面崩溃")
112123
row.flddpSLHEzDPQ = "登陆后页面崩溃"
113124
row.update({
114-
"flddpSLHEzDPQ": "登陆后页面崩溃",
115-
"fldwvNDf9teD2": "已修复"
125+
"flddpSLHEzDPQ": "登陆后页面崩溃",
126+
"fldwvNDf9teD2": "已修复"
116127
})
117128

118129
```
@@ -121,26 +132,27 @@ row.update({
121132

122133
```python
123134
bug = vika.datasheet("dstn2lEFltyGHe2j86", field_key="id", field_key_map={
124-
"title":"flddpSLHEzDPQ",
125-
"state":"fldwvNDf9teD2",
135+
"title": "flddpSLHEzDPQ",
136+
"state": "fldwvNDf9teD2",
126137
})
127138
```
128139

129-
## API
140+
## API
141+
142+
### 维格表
143+
#### records 方法
130144

131-
### records 方法
132145
`dst.records` 管理表格中的记录。
133146

134147
| 方法 | 参数 | 返回类型 | 说明 | 例子 |
135148
| ----------- | ------ | -------- | ------------------------------- | ---------------------------------------------------------------------------- |
136149
| create | dict | Record | 创建单条记录 | `dst.records.create({"title":"new title"})` |
137150
| bulk_create | dict[] | Record[] | 批量创建多条记录 | `dst.records.bulk_create([{"title":"new record1"},{"title":"new record2"}])` |
138151
| all | **dict | QuerySet | 返回记录集合,可传参定制返回内容 | `dst.records.all()` |
139-
| count | / | int | 记录总数 | `dst.records.count()` |
140152
| get | **dict | Record | 单条记录 | `dst.records.get(title="new title")` |
141153
| filter | **dict | QuerySet | 过滤一批记录 | `dst.records.filter(title="new title")` |
142154

143-
### QuerySet
155+
#### QuerySet
144156

145157
返回 QuerySet 的方法可以进行链式调用
146158

@@ -152,61 +164,82 @@ bug = vika.datasheet("dstn2lEFltyGHe2j86", field_key="id", field_key_map={
152164
| count | / | int | 记录总数 | `dst.records.filter(title="new title").count()` |
153165
| last | / | Record | 最后一条记录 | `dst.records.filter(title="new title").last()` |
154166
| first | / | Record | 第一条记录 | `dst.records.filter(title="new title").first()` |
155-
| update | **dict | int | 更新成功的记录数 | `dst.records.filter(title="new title").update(title="new title")` |
167+
| update | **dict | Record | 更新成功的记录数 | `dst.records.filter(title="new title").update(title="new title")` |
156168
| delete | / | bool | 是否删除成功 | `dst.records.filter(title="new title").delete()` |
157169

158-
### Record
159-
160-
查询出来的 QuerySet 是一个 Record 的集合。单个 Record 可以通过 `record.字段名` 的方式获取值。
161-
162-
| 方法/属性 | 参数 | 返回类型 | 说明 | 例子 |
163-
| ---- | ---- | -------- | ------------------------ | --------------- |
164-
| json | / | dict | 返回当前记录的所有字段值 | `record.json()` |
165-
| _id | / | str | _id 是保留属性，返回当前记录的 recordId | `record._id` |
166-
167-
### 字段值
168-
169-
维格列字段值与 Python 数据结构的映射关系。
170-
维格表中单元格为空的数据始终是 null，API 返回的记录中，不会包含值为 null 的字段。
171-
172-
| 维格列类型 | 数据类型 |
173-
| ---------- | -------------------- |
174-
| 单行文本 | str |
175-
| 多行文本 | str |
176-
| 单选 | str |
177-
| 多选 | str[] |
178-
| 网址 | str |
179-
| 电话 | str |
180-
| 邮箱 | str |
181-
| 数字 | number |
182-
| 货币 | number |
183-
| 百分比 | number |
184-
| 自增数字 | number |
185-
| 日期 | number |
186-
| 创建时间 | number |
187-
| 修改时间 | number |
170+
#### Record
171+
172+
查询出来的 QuerySet 是一个 Record 的集合。单个 Record 可以通过 `record.字段名` 的方式获取指定字段的值。
173+
174+
**请尽量避免字段名和 Record 保留的方法属性同名，表格中的同名字段会被遮蔽。如果确实存在，请使用字段映射配置**
175+
176+
| 方法/属性 | 参数 | 返回类型 | 说明 | 例子 |
177+
| --------- | ---- | -------- | --------------------------------------- | --------------- |
178+
| json | / | dict | 返回当前记录的所有字段值 | `record.json()` |
179+
| _id | / | str | _id 是保留属性，返回当前记录的 recordId | `record._id` |
180+
181+
#### 字段值
182+
183+
维格列字段值与 Python 数据结构的映射关系。 维格表中单元格为空的数据始终是 null，API 返回的记录中，不会包含值为 null 的字段。
184+
185+
| 维格列类型 | 数据类型 |
186+
| ---------- | ------------------- |
187+
| 单行文本 | str |
188+
| 多行文本 | str |
189+
| 单选 | str |
190+
| 多选 | str[] |
191+
| 网址 | str |
192+
| 电话 | str |
193+
| 邮箱 | str |
194+
| 数字 | number |
195+
| 货币 | number |
196+
| 百分比 | number |
197+
| 自增数字 | number |
198+
| 日期 | number |
199+
| 创建时间 | number |
200+
| 修改时间 | number |
188201
| 附件 | attachment object[] |
189-
| 成员 | unit object[] |
190-
| 勾选 | bool |
191-
| 评分 | int |
192-
| 创建人 | unit object |
193-
| 修改人 | unit object |
194-
| 神奇关联 | str[] |
195-
| 神奇引用 | any[] |
196-
| 智能公式 | str / bool |
202+
| 成员 | unit object[] |
203+
| 勾选 | bool |
204+
| 评分 | int |
205+
| 创建人 | unit object |
206+
| 修改人 | unit object |
207+
| 神奇关联 | str[] |
208+
| 神奇引用 | any[] |
209+
| 智能公式 | str / bool |
210+
211+
#### all 参数
212+
213+
all 方法会自动处理分页加载全部资源
214+
215+
_传入分页相关参数（pageNum、pageSize）时，SDK 不会再自动加载全部记录，只返回指定页数据_。
216+
217+
> 尽量避免在不加参数的情况下使用 dst.records.all 方法，获取全部数据。
218+
> API 每次请求最多获取 1000 条数据，如果你的数据量过大，接近 50000 的限制。在不加任何参数的情况下，调用 all 会串行请求 50 次 API。 不仅非常慢，而且消耗 API 请求额度。
219+
220+
*返回指定分页的记录*
221+
222+
```python
223+
dst.records.all(pageNum=3)
224+
```
197225

226+
*搭配视图使用*
198227

199-
### all 参数
228+
指定视图 id 返回和视图中相同的数据。
200229

201-
当首次调用 all 不传入任何参数时，默认加载第一个视图的记录，后续的 filter、get 均在本地缓存数据中进行，all 方法仅在首次调用时，从服务端获取数据。
230+
```python
231+
dst.records.all(viewId="viwxxxxxx")
232+
```
202233

203-
当调用 all 时，显式地传入参数，则利用服务端计算返回部分数据集。
234+
*使用公式筛选数据*
204235

205-
_传入分页相关参数（pageNum、pageSize）时，SDK 不会再自动加载全部记录_
236+
```python
237+
dst.records.all(filterByformula='{title}="hello"')
238+
```
206239

207240
| 参数 | 类型 | 说明 | 例子 |
208241
| --------------- | -------------- | ----------------------------------------------------------------------------- | ------------------------------------- |
209-
| viewId | str | 视图ID。默认为维格表中第一个视图。请求会返回视图中经过视图中筛选/排序后的结果 | |
242+
| viewId | str | 视图ID。请求会返回视图中经过视图中筛选/排序后的结果 | |
210243
| pageNum | int | 默认 1 | |
211244
| pageSize | int | 默认 100 ， 最大 1000 | |
212245
| sort | dict[] | 指定排序的字段，会覆盖视图排序条件 | `[{ field: 'field1', order: 'asc' }]` |
@@ -217,9 +250,12 @@ _传入分页相关参数（pageNum、pageSize）时，SDK 不会再自动加载
217250
| cellFormat | 'json' or 'string' | 默认为 'json'，指定为 'string' 时所有值都将被自动转换为 string 格式。 | |
218251
| fieldKey | 'name' or 'id' | 指定 field 查询和返回的 key。默认使用列名 'name'。 | |
219252

220-
221253
参见：[公式使用方式](https://vika.cn/help/tutorial-getting-started-with-formulas/)
222254

255+
### 空间站
256+
257+
### 文件目录
258+
223259
## 开发测试
224260

225261
复制测试模板到自己的空间站，每次测试时，保证表中只有一条 title = "无人生还" 的记录
@@ -248,26 +284,35 @@ python -m unittest test
248284

249285
+ [JavaScript SDK](https://github.com/vikadata/vika.js)
250286
+ [Golang SDK](https://github.com/vikadata/vika.go)
251-
+ [PHP SDK](https://github.com/vikadata/vika.php)
287+
+ [Java SDK](https://github.com/vikadata/vika.java)
252288

253289
## FAQ
254290

255291
### 可以拿到表格的字段类型（meta）信息吗？
256292

257-
目前不可以，后续 REST API 升级会暴露表格 meta 信息
293+
~~目前不可以，后续 REST API 升级会暴露表格 meta 信息~~
294+
295+
可以通过 fields/views 接口获取
258296

259297
### 可以自动创建单多选选项吗？
298+
260299
```
261300
record.tags = ["目前 tags 字段中不存在的选项"]
262301
```
263-
目前不可以，你只能赋值已经存在的选项。后续会支持 :D
302+
303+
~~目前不可以，你只能赋值已经存在的选项。后续会支持 :D~~
304+
305+
现在已经支持，如果写入不存在的单多选字段，自动创建该选项
264306

265307
### 单个表格最大支持多少条记录？
266308

267309
目前单表最大支持 5w 条记录
268310

269-
## TODO
311+
### 每次请求可以处理更多的记录吗？
312+
313+
目前是 10条。后续我们会根据实际情况，调整该限制的大小。
314+
315+
### 每次请求可以获取更多的记录吗?
316+
317+
目前最大值是 1000 条。后续我们会根据实际情况，调整该限制的大小。
270318

271-
+ [ ] 优化数据集较大时的网络请求
272-
+ [ ] 网络请求封装 & 错误处理
273-
+ [ ] filter 操作符

0 commit comments

Comments
 (0)