Skip to content

Commit 92acea7

Browse files
skheskhe
committed
docs: add full API reference, runnable examples, and pages CI
1 parent c2ba2f1 commit 92acea7

19 files changed

Lines changed: 1144 additions & 0 deletions

‎.github/workflows/docs-pages.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
workflow_dispatch:
9+
10+
permissions:
11+
contents: read
12+
pages: write
13+
id-token: write
14+
15+
concurrency:
16+
group: docs-${{ github.ref }}
17+
cancel-in-progress: true
18+
19+
jobs:
20+
build:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: actions/checkout@v4
24+
25+
- uses: actions/setup-python@v5
26+
with:
27+
python-version: "3.11"
28+
29+
- name: Install docs dependencies
30+
run: |
31+
python -m pip install --upgrade pip
32+
pip install mkdocs
33+
34+
- name: Build docs
35+
run: mkdocs build --strict
36+
37+
- name: Setup Pages
38+
if: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}
39+
uses: actions/configure-pages@v5
40+
41+
- name: Upload Pages artifact
42+
if: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}
43+
uses: actions/upload-pages-artifact@v3
44+
with:
45+
path: site
46+
47+
deploy:
48+
if: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}
49+
needs: build
50+
runs-on: ubuntu-latest
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
steps:
55+
- name: Deploy to GitHub Pages
56+
id: deployment
57+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,16 @@ cursor.close()
3939
conn.close()
4040
```
4141

42+
## Documentation
43+
44+
- GitHub Pages: https://skhe.github.io/dmPython/
45+
- Local preview:
46+
47+
```bash
48+
pip install mkdocs
49+
mkdocs serve
50+
```
51+
4252
## Building from Source
4353

4454
**Prerequisites:**

‎docs/api-reference.md‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
# API 参考
2+
3+
本页根据扩展源码 `src/native/py_Dameng.c`、`src/native/Connection.c`、`src/native/Cursor.c` 汇总公开接口。
4+
5+
## 模块级对象
6+
7+
### DB-API 元信息
8+
9+
- `dmPython.apilevel = "2.0"`
10+
- `dmPython.threadsafety = 1`
11+
- `dmPython.paramstyle = "qmark"`
12+
- `dmPython.version`
13+
- `dmPython.buildtime`
14+
15+
### 连接入口
16+
17+
- `dmPython.connect(...)`
18+
- `dmPython.Connect(...)`
19+
20+
两者均为 `Connection` 类型构造入口。
21+
22+
### `connect()` 参数
23+
24+
```python
25+
dmPython.connect(
26+
user=None,
27+
password=None,
28+
dsn=None,
29+
host=None,
30+
server=None,
31+
port=None,
32+
access_mode=None,
33+
autoCommit=None,
34+
connection_timeout=None,
35+
login_timeout=None,
36+
txn_isolation=None,
37+
app_name=None,
38+
compress_msg=None,
39+
use_stmt_pool=None,
40+
ssl_path=None,
41+
ssl_pwd=None,
42+
mpp_login=None,
43+
ukey_name=None,
44+
ukey_pin=None,
45+
rwseparate=None,
46+
rwseparate_percent=None,
47+
cursor_rollback_behavior=None,
48+
lang_id=None,
49+
local_code=None,
50+
cursorclass=None,
51+
schema=None,
52+
shake_crypto=None,
53+
catalog=None,
54+
dmsvc_path=None,
55+
parse_type=None,
56+
)
57+
```
58+
59+
说明：
60+
61+
- `host` 与 `server` 互斥（只允许设置一个）。
62+
- `user` 支持 `user/password@server:port[/schema][?catalog=...]` 形式。
63+
- 常量参数建议使用模块常量（如 `DSQL_AUTOCOMMIT_ON`、`ISO_LEVEL_READ_COMMITTED`）。
64+
65+
### 模块函数
66+
67+
- `DateFromTicks(ticks)`
68+
- `TimeFromTicks(ticks)`
69+
- `TimestampFromTicks(ticks)`
70+
- `StringFromBytes(bs)`
71+
72+
### 日期时间类型别名
73+
74+
- `Date`
75+
- `Time`
76+
- `Timestamp`
77+
- `DATETIME`
78+
79+
### 游标类型常量
80+
81+
- `TupleCursor`
82+
- `DictCursor`
83+
84+
用于 `connect(cursorclass=...)`。
85+
86+
## Connection
87+
88+
### 方法
89+
90+
- `cursor()`
91+
- `commit()`
92+
- `rollback()`
93+
- `close()`
94+
- `disconnect()`（`close()` 别名）
95+
- `debug(debug_type=dmPython.DEBUG_OPEN)`
96+
- `shutdown(shutdown_type=dmPython.SHUTDOWN_DEFAULT)`
97+
- `explain(statement)`
98+
- `ping(reconnect=0)`
99+
- `__enter__()`
100+
- `__exit__(exc_type, exc_value, exc_traceback)`
101+
102+
### 成员属性（只读）
103+
104+
- `dsn`
105+
- `server_status`
106+
- `warning`
107+
108+
### 计算属性（含可写项）
109+
110+
可读写：
111+
112+
- `access_mode`
113+
- `async_enable`
114+
- `auto_ipd`
115+
- `local_code`
116+
- `lang_id`
117+
- `app_name`
118+
- `txn_isolation`
119+
- `compress_msg`
120+
- `rwseparate`
121+
- `rwseparate_percent`
122+
- `use_stmt_pool`
123+
- `ssl_path`
124+
- `mpp_login`
125+
- `autoCommit`
126+
- `autocommit`
127+
- `connection_dead`
128+
- `connection_timeout`
129+
- `login_timeout`
130+
- `packet_size`
131+
- `port`
132+
133+
只读：
134+
135+
- `server_code`
136+
- `current_schema`
137+
- `str_case_sensitive`
138+
- `max_row_size`
139+
- `current_catalog`
140+
- `trx_state`
141+
- `server_version`
142+
- `cursor_rollback_behavior`
143+
- `user`
144+
- `server`
145+
- `inst_name`
146+
- `version`
147+
- `max_identifier_length`
148+
- `outputtypehandler`
149+
- `stmtcachesize`
150+
151+
以上属性多数存在同名 `DSQL_ATTR_*` 别名，例如：
152+
153+
- `connection.autoCommit` <=> `connection.DSQL_ATTR_AUTOCOMMIT`
154+
- `connection.port` <=> `connection.DSQL_ATTR_LOGIN_PORT`
155+
156+
## Cursor
157+
158+
### 方法
159+
160+
- `execute(statement, params=None, **kwargs)`
161+
- `executedirect(statement)`
162+
- `fetchall()`
163+
- `fetchone()`
164+
- `fetchmany(rows=arraysize)`
165+
- `prepare(statement)`
166+
- `parse(statement)`（当前实现返回 `NotSupportedError`）
167+
- `setinputsizes(*args, **kwargs)`
168+
- `executemany(statement, seq_of_params)`
169+
- `callproc(name, params=None)`
170+
- `callfunc(name, params=None)`
171+
- `setoutputsize(size, column=-1)`
172+
- `var(typ, size=0, arraysize=cursor.arraysize, inconverter=None, outconverter=None, typename=None, encoding_errors=None, bypass_decode=False, encodingErrors=None)`
173+
- `arrayvar(...)`（当前实现返回 `NotSupportedError`）
174+
- `bindnames()`（当前实现返回 `NotSupportedError`）
175+
- `close()`
176+
- `next()`
177+
- `nextset()`
178+
- `__enter__()`
179+
- `__exit__(exc_type, exc_value, exc_traceback)`
180+
181+
### 成员属性
182+
183+
- `arraysize`（可写）
184+
- `bindarraysize`（可写）
185+
- `rowcount`（只读）
186+
- `rownumber`（只读）
187+
- `with_rows`（只读）
188+
- `statement`（只读）
189+
- `connection`（只读）
190+
- `column_names`（只读）
191+
- `lastrowid`（只读）
192+
- `execid`（只读）
193+
- `_isClosed`（内部）
194+
- `_statement`（内部）
195+
- `output_stream`（可写）
196+
- `description`（只读计算属性）
197+
198+
## 异常层次
199+
200+
- `Warning`
201+
- `Error`
202+
- `InterfaceError`
203+
- `DatabaseError`
204+
- `DataError`
205+
- `OperationalError`
206+
- `IntegrityError`
207+
- `InternalError`
208+
- `ProgrammingError`
209+
- `NotSupportedError`
210+
211+
此外还提供 `DmError` 对象（包含 `code`、`offset`、`message`、`context`）。
212+
213+
## 常量
214+
215+
### 调试与关库
216+
217+
- `DEBUG_CLOSE`
218+
- `DEBUG_OPEN`
219+
- `DEBUG_SWITCH`
220+
- `DEBUG_SIMPLE`
221+
- `SHUTDOWN_DEFAULT`
222+
- `SHUTDOWN_ABORT`
223+
- `SHUTDOWN_IMMEDIATE`
224+
- `SHUTDOWN_TRANSACTIONAL`
225+
- `SHUTDOWN_NORMAL`
226+
227+
### 事务与访问模式
228+
229+
- `ISO_LEVEL_READ_DEFAULT`
230+
- `ISO_LEVEL_READ_UNCOMMITTED`
231+
- `ISO_LEVEL_READ_COMMITTED`
232+
- `ISO_LEVEL_REPEATABLE_READ`
233+
- `ISO_LEVEL_SERIALIZABLE`
234+
- `DSQL_MODE_READ_ONLY`
235+
- `DSQL_MODE_READ_WRITE`
236+
- `DSQL_AUTOCOMMIT_ON`
237+
- `DSQL_AUTOCOMMIT_OFF`
238+
239+
### 编码与语言
240+
241+
- `PG_UTF8`
242+
- `PG_GBK`
243+
- `PG_BIG5`
244+
- `PG_ISO_8859_9`
245+
- `PG_EUC_JP`
246+
- `PG_EUC_KR`
247+
- `PG_KOI8R`
248+
- `PG_ISO_8859_1`
249+
- `PG_SQL_ASCII`
250+
- `PG_GB18030`
251+
- `PG_ISO_8859_11`
252+
- `LANGUAGE_CN`
253+
- `LANGUAGE_EN`
254+
- `LANGUAGE_CNT_HK`（条件编译）
255+
256+
### 其他连接行为
257+
258+
- `DSQL_TRUE`
259+
- `DSQL_FALSE`
260+
- `DSQL_RWSEPARATE_ON`
261+
- `DSQL_RWSEPARATE_OFF`
262+
- `DSQL_TRX_ACTIVE`
263+
- `DSQL_TRX_COMPLETE`
264+
- `DSQL_MPP_LOGIN_GLOBAL`
265+
- `DSQL_MPP_LOGIN_LOCAL`
266+
- `DSQL_CB_CLOSE`
267+
- `DSQL_CB_PRESERVE`
268+
269+
### 数据类型对象
270+
271+
模块还导出一组数据类型对象，可用于绑定/类型判断：
272+
273+
- `INTERVAL`, `YEAR_MONTH_INTERVAL`
274+
- `BLOB`, `CLOB`, `LOB`
275+
- `BFILE`, `exBFILE`
276+
- `LONG_BINARY`, `LONG_STRING`
277+
- `DATE`, `TIME`, `TIMESTAMP`
278+
- `CURSOR`
279+
- `STRING`, `FIXED_STRING`, `BINARY`, `FIXED_BINARY`
280+
- `OBJECTVAR`, `objectvar`
281+
- `NUMBER`, `DOUBLE`, `REAL`, `BOOLEAN`, `DECIMAL`
282+
- `TIME_WITH_TIMEZONE`, `TIMESTAMP_WITH_TIMEZONE`
283+
- `BIGINT`, `ROWID`

0 commit comments

Comments
 (0)