dmpython-jdbc 2.5.32.post1__tar.gz → 2.5.32.post3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. dmpython_jdbc-2.5.32.post3/MANIFEST.in +12 -0
  2. dmpython_jdbc-2.5.32.post3/PKG-INFO +178 -0
  3. dmpython_jdbc-2.5.32.post3/README.en.md +177 -0
  4. dmpython_jdbc-2.5.32.post3/README.md +155 -0
  5. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/__init__.py +48 -0
  6. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/_sync.py +11 -0
  7. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/connection.py +174 -0
  8. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/cursor.py +244 -0
  9. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/dbtypes.py +68 -0
  10. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/dmsqlalchemy.py +63 -0
  11. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/exceptions.py +26 -0
  12. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/jdbc/__init__.py +11 -0
  13. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/jdbc/converters.py +74 -0
  14. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/jdbc/driver.py +49 -0
  15. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/jdbc/errors.py +16 -0
  16. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/jdbc/generated_keys.py +42 -0
  17. dmpython_jdbc-2.5.32.post3/_dmPython_jdbc/jdbc/sql.py +27 -0
  18. dmpython_jdbc-2.5.32.post3/dmpython_jdbc.egg-info/PKG-INFO +178 -0
  19. dmpython_jdbc-2.5.32.post3/dmpython_jdbc.egg-info/SOURCES.txt +39 -0
  20. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/pyproject.toml +2 -2
  21. dmpython_jdbc-2.5.32.post3/tests/e2e/.env.example +7 -0
  22. dmpython_jdbc-2.5.32.post3/tests/e2e/README.md +64 -0
  23. dmpython_jdbc-2.5.32.post3/tests/e2e/bootstrap.py +87 -0
  24. dmpython_jdbc-2.5.32.post3/tests/e2e/compose.yaml +38 -0
  25. dmpython_jdbc-2.5.32.post3/tests/e2e/healthcheck.sh +11 -0
  26. dmpython_jdbc-2.5.32.post3/tests/e2e/run.py +51 -0
  27. dmpython_jdbc-2.5.32.post3/tests/e2e/start-dm.sh +24 -0
  28. dmpython_jdbc-2.5.32.post3/tests/e2e/test.sh +16 -0
  29. dmpython_jdbc-2.5.32.post3/tests/e2e/test_live_dmasync.py +278 -0
  30. dmpython_jdbc-2.5.32.post3/tests/test_dmasync.py +385 -0
  31. dmpython_jdbc-2.5.32.post1/MANIFEST.in +0 -8
  32. dmpython_jdbc-2.5.32.post1/PKG-INFO +0 -116
  33. dmpython_jdbc-2.5.32.post1/README.md +0 -93
  34. dmpython_jdbc-2.5.32.post1/README.zh-CN.md +0 -93
  35. dmpython_jdbc-2.5.32.post1/_dmPython_jdbc/__init__.py +0 -486
  36. dmpython_jdbc-2.5.32.post1/dmpython_jdbc.egg-info/PKG-INFO +0 -116
  37. dmpython_jdbc-2.5.32.post1/dmpython_jdbc.egg-info/SOURCES.txt +0 -17
  38. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/LICENSE +0 -0
  39. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/NOTICE +0 -0
  40. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/_dmPython_jdbc/DmJdbcDriver18-8.1.3.140.jar +0 -0
  41. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/_dmpython_metadata.py +0 -0
  42. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/dmPython.py +0 -0
  43. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/dmpython-2.5.32.dist-info/METADATA +0 -0
  44. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/dmpython_jdbc.egg-info/dependency_links.txt +0 -0
  45. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/dmpython_jdbc.egg-info/requires.txt +0 -0
  46. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/dmpython_jdbc.egg-info/top_level.txt +0 -0
  47. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/setup.cfg +0 -0
  48. {dmpython_jdbc-2.5.32.post1 → dmpython_jdbc-2.5.32.post3}/setup.py +0 -0
@@ -0,0 +1,12 @@
1
+ include README.md
2
+ include README.en.md
3
+ include LICENSE
4
+ include NOTICE
5
+ include pyproject.toml
6
+ recursive-include _dmPython_jdbc *.jar
7
+ recursive-include dmpython-2.5.32.dist-info *
8
+ include setup.py
9
+ recursive-include tests *.py
10
+ include tests/e2e/compose.yaml tests/e2e/start-dm.sh
11
+ include tests/e2e/healthcheck.sh
12
+ include tests/e2e/test.sh tests/e2e/.env.example tests/e2e/README.md
@@ -0,0 +1,178 @@
1
+ Metadata-Version: 2.4
2
+ Name: dmpython-jdbc
3
+ Version: 2.5.32.post3
4
+ Summary: macOS dmPython compatibility shim backed by JayDeBeApi
5
+ Author-email: Darley <darley.wey@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Darley-Wey/dmpython-jdbc
8
+ Project-URL: Repository, https://github.com/Darley-Wey/dmpython-jdbc
9
+ Project-URL: Issues, https://github.com/Darley-Wey/dmpython-jdbc/issues
10
+ Keywords: dameng,dmPython,jdbc,macos
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: MacOS
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Database
18
+ Requires-Python: >=3.12
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: JayDeBeApi>=1.2.3
22
+ Dynamic: license-file
23
+
24
+ # dmpython-jdbc
25
+
26
+ 简体中文 | [English](README.en.md)
27
+
28
+ macOS 上的达梦 `dmPython` 兼容层。官方驱动没有 macOS 版,这里用 JayDeBeApi + 达梦 JDBC 实现 DBAPI 子集,让 `dmSQLAlchemy` 的 `dm+dmPython://` 方言能在本机跑起来。
29
+
30
+ **发行名是 `dmpython-jdbc`,import 名仍是 `dmPython`。** 业务代码不用改。
31
+
32
+ - macOS:使用本包的 JDBC shim
33
+ - 其它平台:把 `import dmPython` 转发给已安装的官方驱动
34
+
35
+ ## 安装
36
+
37
+ PyPI:
38
+
39
+ ```bash
40
+ pip install dmpython-jdbc
41
+ ```
42
+
43
+ 跨平台项目(Linux/Windows 用官方驱动,macOS 用本包):
44
+
45
+ ```toml
46
+ [project]
47
+ dependencies = [
48
+ "dmpython>=2.5.32; sys_platform != 'darwin'",
49
+ "dmpython-jdbc>=2.5.32; sys_platform == 'darwin'",
50
+ ]
51
+ ```
52
+
53
+ 如果项目还依赖 `dmSQLAlchemy`,见 [配合 dmSQLAlchemy](#配合-dmsqlalchemy)。该包会无条件拉取官方 `dmpython`。
54
+
55
+ ## 运行依赖
56
+
57
+ - Python >= 3.12
58
+ - JDK(macOS 可用 `brew install openjdk`)。`JAVA_HOME` 会自动探测 `/opt/homebrew/opt/openjdk` 和 `/usr/local/opt/openjdk`
59
+ - 达梦 JDBC 驱动已打包进 wheel;也可用环境变量 `DM_JDBC_JAR` 覆盖
60
+
61
+
62
+ ## 配合 dmSQLAlchemy
63
+
64
+ `dmSQLAlchemy` 无条件依赖官方 `dmpython`(`Requires-Dist: dmPython`)。该包没有 macOS wheel,所以在 Mac 上 `pip install dmSQLAlchemy` 会尝试装达梦官方驱动并失败。
65
+
66
+ 要保留 `dmSQLAlchemy`,又阻止解析器在 macOS 上装官方 `dmpython`,改装 `dmpython-jdbc`。import 名仍是 `dmPython`。
67
+
68
+ ### uv
69
+
70
+ ```toml
71
+ [project]
72
+ dependencies = [
73
+ "dmsqlalchemy",
74
+ "dmpython>=2.5.32; sys_platform != 'darwin'",
75
+ "dmpython-jdbc>=2.5.32; sys_platform == 'darwin'",
76
+ ]
77
+
78
+ [tool.uv]
79
+ override-dependencies = [
80
+ "dmpython ; sys_platform != 'darwin'",
81
+ ]
82
+ ```
83
+
84
+ `override-dependencies` 会改写 `dmSQLAlchemy` 对 `dmpython` 的依赖,让它在 macOS 上被跳过;然后由 `dmpython-jdbc` 提供 `dmPython` 模块。
85
+
86
+ `dmSQLAlchemy.extensions` 会调用 `importlib.metadata.version("dmPython")`。本包会安装 `.pth` 钩子,让这次查询返回 shim 版本 `2.5.32`,不依赖 setuptools/`pkg_resources`。
87
+
88
+ ### macOS 上的 pip
89
+
90
+ ```bash
91
+ pip install "dmSQLAlchemy" --no-deps
92
+ pip install "SQLAlchemy>1.4.54" dmpython-jdbc
93
+ ```
94
+
95
+ ## 作为 dmAsync 的 dmPython 后端
96
+
97
+ 本包支持 `dmAsync==1.0.0` 使用的基础连接和游标接口:`connect`、`execute`、
98
+ `executemany`、`fetchone`/`fetchmany`/`fetchall`、异步迭代、`commit`、`rollback`
99
+ 和 `ping`。dmAsync 使用 `asyncio.to_thread` 调用同步 shim 完成这些数据库操作;
100
+ dmAsync 1.0.0 的建连和关闭仍是同步操作。
101
+
102
+ macOS 上在开发版仓库目录中安装:
103
+
104
+ ```bash
105
+ python -m pip install . "async-timeout>=4,<6"
106
+ python -m pip install "dmAsync==1.0.0" --no-deps
107
+ ```
108
+
109
+ `dmAsync` 无条件依赖官方 `dmPython`,因此使用 uv 时,需要保留上文的
110
+ `[tool.uv].override-dependencies` 配置,并在项目依赖中加入 `dmAsync==1.0.0`
111
+ 和 `async-timeout>=4,<6`。dmAsync 1.0.0 导入了 `async_timeout`,但没有在包元数据中
112
+ 声明该依赖。运行时的版本别名不能代替这些依赖解析配置。
113
+
114
+ ```python
115
+ import asyncio
116
+ import os
117
+ import dmAsync
118
+
119
+
120
+ async def main():
121
+ conn = await dmAsync.connect(
122
+ host=os.environ["DM_HOST"],
123
+ port=int(os.environ.get("DM_PORT", "5236")),
124
+ user=os.environ["DM_USER"],
125
+ password=os.environ["DM_PASSWORD"],
126
+ autoCommit=False,
127
+ login_timeout=5000, # 毫秒,直接传给 dmPython。
128
+ )
129
+ cur = await conn.cursor()
130
+ try:
131
+ await cur.execute("SELECT 1")
132
+ print(await cur.fetchone())
133
+ await conn.commit()
134
+ except Exception:
135
+ await conn.rollback()
136
+ raise
137
+ finally:
138
+ await cur.close()
139
+ await conn.close()
140
+
141
+
142
+ asyncio.run(main())
143
+ ```
144
+
145
+ `Connection.version` 返回服务端版本;标识符长度限制从 JDBC 元数据读取,未知时
146
+ 返回 `None`。shim 不实现 Python 层语句缓存,因此 `stmtcachesize` 为 `0`,
147
+ 不支持设为非零值。`status` 表示 shim 连接状态(`1` 开启、`0` 关闭),不是 DPI
148
+ 事务状态码。修改 `autocommit` 会同步到 JDBC 连接。
149
+
150
+ 同一连接的 JDBC 操作会在线程间串行执行。并发任务应各自持有连接:锁无法隔离事务,
151
+ 也无法保证多个任务共享游标时 execute/fetch 的先后关系。取消 await 不会终止线程中
152
+ 已经开始的 JDBC 操作;重新使用或关闭该连接前,应等待操作结束。`callproc`、
153
+ `callfunc`、显式 `prepare`、`mogrify`、游标滚动、跨提交保留游标以及多结果集仍不支持,
154
+ 调用会抛出 `NotSupportedError`。这些适配不代表已完整验证 SQLAlchemy 的
155
+ `dm+dmasync://` 方言或 dmAsync 连接池。
156
+
157
+ ### 适配测试
158
+
159
+ 安装上述依赖后执行:
160
+
161
+ ```bash
162
+ python -m unittest discover -s tests -v
163
+ ```
164
+
165
+ 测试使用真实 dmAsync 包,在 JayDeBeApi 边界用 SQLite 模拟数据库,覆盖初始化、
166
+ CRUD、事务、游标生命周期和连接级锁,不需要达梦服务器。
167
+
168
+ 真库验证见 [达梦端到端测试说明](tests/e2e/README.md)。配置专用测试账号后,执行
169
+ `bash tests/e2e/test.sh` 即可构建并测试实际安装的 wheel,覆盖二进制/LOB 数据往返、
170
+ 跨连接事务可见性等。
171
+
172
+ ## 限制
173
+
174
+ 不支持存储过程出参(`cursor.var`)、LOB 流式读写等高级特性,覆盖 ORM CRUD 即可。
175
+
176
+ ## 许可证
177
+
178
+ Python 兼容层使用 MIT。仓库中的 `DmJdbcDriver18-*.jar` 是达梦官方 JDBC 驱动,版权归达梦数据库所有,不受 MIT 覆盖。
@@ -0,0 +1,177 @@
1
+ # dmpython-jdbc
2
+
3
+ [简体中文](README.md) | English
4
+
5
+ macOS compatibility layer for Dameng `dmPython`. Dameng does not ship a macOS driver, so this package implements a DBAPI subset with JayDeBeApi + Dameng JDBC and makes dmSQLAlchemy's `dm+dmPython://` dialect work locally.
6
+
7
+ **The distribution name is `dmpython-jdbc`; the import name remains `dmPython`.** Application code does not need to change.
8
+
9
+ - macOS: use this package's JDBC shim
10
+ - Other platforms: forward `import dmPython` to the official driver
11
+
12
+ ## Install
13
+
14
+ PyPI:
15
+
16
+ ```bash
17
+ pip install dmpython-jdbc
18
+ ```
19
+
20
+ Cross-platform projects (official driver on Linux/Windows, this package on macOS):
21
+
22
+ ```toml
23
+ [project]
24
+ dependencies = [
25
+ "dmpython>=2.5.32; sys_platform != 'darwin'",
26
+ "dmpython-jdbc>=2.5.32; sys_platform == 'darwin'",
27
+ ]
28
+ ```
29
+
30
+ If the project also depends on `dmSQLAlchemy`, see [Using with dmSQLAlchemy](#using-with-dmsqlalchemy). That package pulls official `dmpython` unconditionally.
31
+
32
+ From Git:
33
+
34
+ ```bash
35
+ pip install "dmpython-jdbc @ git+https://github.com/Darley-Wey/dmpython-jdbc.git"
36
+ ```
37
+
38
+ uv:
39
+
40
+ ```toml
41
+ [tool.uv.sources]
42
+ dmpython-jdbc = { git = "https://github.com/Darley-Wey/dmpython-jdbc.git" }
43
+ ```
44
+
45
+ Pin a commit or tag by appending `@<ref>`, for example `@main` or `@v2.5.32`.
46
+
47
+ ## Runtime requirements
48
+
49
+ - Python >= 3.12
50
+ - JDK (`brew install openjdk` on macOS). `JAVA_HOME` is probed at `/opt/homebrew/opt/openjdk` and `/usr/local/opt/openjdk`
51
+ - The Dameng JDBC driver is bundled in the wheel; override it with `DM_JDBC_JAR`
52
+
53
+
54
+ ## Using with dmSQLAlchemy
55
+
56
+ `dmSQLAlchemy` unconditionally depends on official `dmpython` (`Requires-Dist: dmPython`). That package has no macOS wheel, so `pip install dmSQLAlchemy` on a Mac will try to install Dameng's driver and fail.
57
+
58
+ Keep `dmSQLAlchemy`, prevent the resolver from installing official `dmpython` on macOS, and install `dmpython-jdbc` instead. The import name stays `dmPython`.
59
+
60
+ ### uv
61
+
62
+ ```toml
63
+ [project]
64
+ dependencies = [
65
+ "dmsqlalchemy",
66
+ "dmpython>=2.5.32; sys_platform != 'darwin'",
67
+ "dmpython-jdbc>=2.5.32; sys_platform == 'darwin'",
68
+ ]
69
+
70
+ [tool.uv]
71
+ override-dependencies = [
72
+ "dmpython ; sys_platform != 'darwin'",
73
+ ]
74
+ ```
75
+
76
+ `override-dependencies` rewrites `dmSQLAlchemy`'s `dmpython` requirement so it is skipped on macOS. `dmpython-jdbc` then provides the `dmPython` module.
77
+
78
+ `dmSQLAlchemy.extensions` calls `importlib.metadata.version("dmPython")`. This package installs a `.pth` hook so that lookup returns the shim version `2.5.32` without needing setuptools/`pkg_resources`.
79
+
80
+ ### pip on macOS
81
+
82
+ ```bash
83
+ pip install "dmSQLAlchemy" --no-deps
84
+ pip install "SQLAlchemy>1.4.54" dmpython-jdbc
85
+ ```
86
+
87
+ ## Using as dmAsync's dmPython backend
88
+
89
+ The shim supports the basic connection and cursor API used by `dmAsync==1.0.0`:
90
+ `connect`, `execute`, `executemany`, `fetchone`/`fetchmany`/`fetchall`, async
91
+ iteration, `commit`, `rollback`, and `ping`. dmAsync calls the synchronous shim
92
+ through `asyncio.to_thread` for these database operations; connection creation
93
+ and closing remain synchronous in dmAsync 1.0.0.
94
+
95
+ For a development checkout on macOS:
96
+
97
+ ```bash
98
+ python -m pip install . "async-timeout>=4,<6"
99
+ python -m pip install "dmAsync==1.0.0" --no-deps
100
+ ```
101
+
102
+ `dmAsync` unconditionally requires official `dmPython`, so use the same
103
+ `[tool.uv].override-dependencies` configuration shown above when using uv.
104
+ Add `dmAsync==1.0.0` and `async-timeout>=4,<6` to your project dependencies;
105
+ dmAsync 1.0.0 imports `async_timeout` but does not declare it in its metadata.
106
+ The runtime version alias does not replace these resolver settings.
107
+
108
+ ```python
109
+ import asyncio
110
+ import os
111
+ import dmAsync
112
+
113
+
114
+ async def main():
115
+ conn = await dmAsync.connect(
116
+ host=os.environ["DM_HOST"],
117
+ port=int(os.environ.get("DM_PORT", "5236")),
118
+ user=os.environ["DM_USER"],
119
+ password=os.environ["DM_PASSWORD"],
120
+ autoCommit=False,
121
+ login_timeout=5000, # Milliseconds, forwarded to dmPython.
122
+ )
123
+ cur = await conn.cursor()
124
+ try:
125
+ await cur.execute("SELECT 1")
126
+ print(await cur.fetchone())
127
+ await conn.commit()
128
+ except Exception:
129
+ await conn.rollback()
130
+ raise
131
+ finally:
132
+ await cur.close()
133
+ await conn.close()
134
+
135
+
136
+ asyncio.run(main())
137
+ ```
138
+
139
+ `Connection.version` reports the server version. Identifier limits come from
140
+ JDBC metadata (`None` when unknown). `stmtcachesize` is `0` because the shim does
141
+ not implement a Python statement cache; setting a nonzero size is unsupported.
142
+ `status` reports shim liveness (`1` open, `0` closed), not a DPI transaction code.
143
+ Assignments to `autocommit` update the JDBC connection.
144
+
145
+ JDBC operations are serialized per connection across worker threads. Use one
146
+ connection per concurrent task: a lock does not isolate transactions or preserve
147
+ an execute/fetch sequence shared by several tasks. Cancelling an await does not
148
+ stop JDBC work already running in a thread; wait for that work to finish before
149
+ reusing or closing its connection. `callproc`, `callfunc`, explicit `prepare`,
150
+ `mogrify`, scrolling, holdable cursors and multiple result sets remain unsupported
151
+ and raise `NotSupportedError`. This does not establish full compatibility with
152
+ SQLAlchemy's separate `dm+dmasync://` dialect or dmAsync's connection pool.
153
+
154
+ ### Adapter tests
155
+
156
+ With the dependencies above installed, run:
157
+
158
+ ```bash
159
+ python -m unittest discover -s tests -v
160
+ ```
161
+
162
+ Tests use the real dmAsync wrapper with a SQLite-backed double at the
163
+ JayDeBeApi boundary. They cover initialization, CRUD, transactions, cursor
164
+ lifecycle and per-connection locking without requiring a Dameng server.
165
+
166
+ For real-server verification, see [live Dameng E2E tests](tests/e2e/README.md).
167
+ With the dedicated test credentials configured, `bash tests/e2e/test.sh` builds
168
+ and tests the installed wheel against DM8, including binary/LOB round trips and
169
+ cross-connection transaction visibility.
170
+
171
+ ## Limits
172
+
173
+ Stored-procedure OUT binds (`cursor.var`) and streaming LOB I/O are not supported. ORM CRUD is covered.
174
+
175
+ ## License
176
+
177
+ The Python shim is MIT. `DmJdbcDriver18-*.jar` is Dameng's official JDBC driver and is not covered by MIT.
@@ -0,0 +1,155 @@
1
+ # dmpython-jdbc
2
+
3
+ 简体中文 | [English](README.en.md)
4
+
5
+ macOS 上的达梦 `dmPython` 兼容层。官方驱动没有 macOS 版,这里用 JayDeBeApi + 达梦 JDBC 实现 DBAPI 子集,让 `dmSQLAlchemy` 的 `dm+dmPython://` 方言能在本机跑起来。
6
+
7
+ **发行名是 `dmpython-jdbc`,import 名仍是 `dmPython`。** 业务代码不用改。
8
+
9
+ - macOS:使用本包的 JDBC shim
10
+ - 其它平台:把 `import dmPython` 转发给已安装的官方驱动
11
+
12
+ ## 安装
13
+
14
+ PyPI:
15
+
16
+ ```bash
17
+ pip install dmpython-jdbc
18
+ ```
19
+
20
+ 跨平台项目(Linux/Windows 用官方驱动,macOS 用本包):
21
+
22
+ ```toml
23
+ [project]
24
+ dependencies = [
25
+ "dmpython>=2.5.32; sys_platform != 'darwin'",
26
+ "dmpython-jdbc>=2.5.32; sys_platform == 'darwin'",
27
+ ]
28
+ ```
29
+
30
+ 如果项目还依赖 `dmSQLAlchemy`,见 [配合 dmSQLAlchemy](#配合-dmsqlalchemy)。该包会无条件拉取官方 `dmpython`。
31
+
32
+ ## 运行依赖
33
+
34
+ - Python >= 3.12
35
+ - JDK(macOS 可用 `brew install openjdk`)。`JAVA_HOME` 会自动探测 `/opt/homebrew/opt/openjdk` 和 `/usr/local/opt/openjdk`
36
+ - 达梦 JDBC 驱动已打包进 wheel;也可用环境变量 `DM_JDBC_JAR` 覆盖
37
+
38
+
39
+ ## 配合 dmSQLAlchemy
40
+
41
+ `dmSQLAlchemy` 无条件依赖官方 `dmpython`(`Requires-Dist: dmPython`)。该包没有 macOS wheel,所以在 Mac 上 `pip install dmSQLAlchemy` 会尝试装达梦官方驱动并失败。
42
+
43
+ 要保留 `dmSQLAlchemy`,又阻止解析器在 macOS 上装官方 `dmpython`,改装 `dmpython-jdbc`。import 名仍是 `dmPython`。
44
+
45
+ ### uv
46
+
47
+ ```toml
48
+ [project]
49
+ dependencies = [
50
+ "dmsqlalchemy",
51
+ "dmpython>=2.5.32; sys_platform != 'darwin'",
52
+ "dmpython-jdbc>=2.5.32; sys_platform == 'darwin'",
53
+ ]
54
+
55
+ [tool.uv]
56
+ override-dependencies = [
57
+ "dmpython ; sys_platform != 'darwin'",
58
+ ]
59
+ ```
60
+
61
+ `override-dependencies` 会改写 `dmSQLAlchemy` 对 `dmpython` 的依赖,让它在 macOS 上被跳过;然后由 `dmpython-jdbc` 提供 `dmPython` 模块。
62
+
63
+ `dmSQLAlchemy.extensions` 会调用 `importlib.metadata.version("dmPython")`。本包会安装 `.pth` 钩子,让这次查询返回 shim 版本 `2.5.32`,不依赖 setuptools/`pkg_resources`。
64
+
65
+ ### macOS 上的 pip
66
+
67
+ ```bash
68
+ pip install "dmSQLAlchemy" --no-deps
69
+ pip install "SQLAlchemy>1.4.54" dmpython-jdbc
70
+ ```
71
+
72
+ ## 作为 dmAsync 的 dmPython 后端
73
+
74
+ 本包支持 `dmAsync==1.0.0` 使用的基础连接和游标接口:`connect`、`execute`、
75
+ `executemany`、`fetchone`/`fetchmany`/`fetchall`、异步迭代、`commit`、`rollback`
76
+ 和 `ping`。dmAsync 使用 `asyncio.to_thread` 调用同步 shim 完成这些数据库操作;
77
+ dmAsync 1.0.0 的建连和关闭仍是同步操作。
78
+
79
+ macOS 上在开发版仓库目录中安装:
80
+
81
+ ```bash
82
+ python -m pip install . "async-timeout>=4,<6"
83
+ python -m pip install "dmAsync==1.0.0" --no-deps
84
+ ```
85
+
86
+ `dmAsync` 无条件依赖官方 `dmPython`,因此使用 uv 时,需要保留上文的
87
+ `[tool.uv].override-dependencies` 配置,并在项目依赖中加入 `dmAsync==1.0.0`
88
+ 和 `async-timeout>=4,<6`。dmAsync 1.0.0 导入了 `async_timeout`,但没有在包元数据中
89
+ 声明该依赖。运行时的版本别名不能代替这些依赖解析配置。
90
+
91
+ ```python
92
+ import asyncio
93
+ import os
94
+ import dmAsync
95
+
96
+
97
+ async def main():
98
+ conn = await dmAsync.connect(
99
+ host=os.environ["DM_HOST"],
100
+ port=int(os.environ.get("DM_PORT", "5236")),
101
+ user=os.environ["DM_USER"],
102
+ password=os.environ["DM_PASSWORD"],
103
+ autoCommit=False,
104
+ login_timeout=5000, # 毫秒,直接传给 dmPython。
105
+ )
106
+ cur = await conn.cursor()
107
+ try:
108
+ await cur.execute("SELECT 1")
109
+ print(await cur.fetchone())
110
+ await conn.commit()
111
+ except Exception:
112
+ await conn.rollback()
113
+ raise
114
+ finally:
115
+ await cur.close()
116
+ await conn.close()
117
+
118
+
119
+ asyncio.run(main())
120
+ ```
121
+
122
+ `Connection.version` 返回服务端版本;标识符长度限制从 JDBC 元数据读取,未知时
123
+ 返回 `None`。shim 不实现 Python 层语句缓存,因此 `stmtcachesize` 为 `0`,
124
+ 不支持设为非零值。`status` 表示 shim 连接状态(`1` 开启、`0` 关闭),不是 DPI
125
+ 事务状态码。修改 `autocommit` 会同步到 JDBC 连接。
126
+
127
+ 同一连接的 JDBC 操作会在线程间串行执行。并发任务应各自持有连接:锁无法隔离事务,
128
+ 也无法保证多个任务共享游标时 execute/fetch 的先后关系。取消 await 不会终止线程中
129
+ 已经开始的 JDBC 操作;重新使用或关闭该连接前,应等待操作结束。`callproc`、
130
+ `callfunc`、显式 `prepare`、`mogrify`、游标滚动、跨提交保留游标以及多结果集仍不支持,
131
+ 调用会抛出 `NotSupportedError`。这些适配不代表已完整验证 SQLAlchemy 的
132
+ `dm+dmasync://` 方言或 dmAsync 连接池。
133
+
134
+ ### 适配测试
135
+
136
+ 安装上述依赖后执行:
137
+
138
+ ```bash
139
+ python -m unittest discover -s tests -v
140
+ ```
141
+
142
+ 测试使用真实 dmAsync 包,在 JayDeBeApi 边界用 SQLite 模拟数据库,覆盖初始化、
143
+ CRUD、事务、游标生命周期和连接级锁,不需要达梦服务器。
144
+
145
+ 真库验证见 [达梦端到端测试说明](tests/e2e/README.md)。配置专用测试账号后,执行
146
+ `bash tests/e2e/test.sh` 即可构建并测试实际安装的 wheel,覆盖二进制/LOB 数据往返、
147
+ 跨连接事务可见性等。
148
+
149
+ ## 限制
150
+
151
+ 不支持存储过程出参(`cursor.var`)、LOB 流式读写等高级特性,覆盖 ORM CRUD 即可。
152
+
153
+ ## 许可证
154
+
155
+ Python 兼容层使用 MIT。仓库中的 `DmJdbcDriver18-*.jar` 是达梦官方 JDBC 驱动,版权归达梦数据库所有,不受 MIT 覆盖。
@@ -0,0 +1,48 @@
1
+ """
2
+ dmPython-compatible shim for local macOS development.
3
+
4
+ Dameng does not ship a macOS dmPython build (libdmdpi is closed-source),
5
+ so this module implements a DBAPI subset with JayDeBeApi + DmJdbcDriver
6
+ and makes dmSQLAlchemy's `dm+dmPython://` dialect usable on Mac.
7
+
8
+ Dependencies:
9
+ - JayDeBeApi is installed with this package (JPype1 comes with it)
10
+ - brew install openjdk (JAVA_HOME is probed at /opt/homebrew/opt/openjdk)
11
+ - Dameng JDBC driver JAR is packaged; override with DM_JDBC_JAR
12
+
13
+ Limits: no cursor.var / OUT binds, no streaming LOB I/O. ORM CRUD is enough.
14
+
15
+ Layout, top layer first; each imports only from those below it:
16
+ __init__ the public dmPython module surface
17
+ connection, cursor DBAPI objects
18
+ dmsqlalchemy dialect adjustments and stubs only dmSQLAlchemy needs
19
+ jdbc/ Java, JayDeBeApi and Dameng JDBC driver details
20
+ exceptions, dbtypes DBAPI vocabulary shared by every layer
21
+ """
22
+ from . import dbtypes, exceptions
23
+ from .connection import Connection, connect
24
+ from .cursor import Cursor
25
+ from .dbtypes import * # noqa: F401,F403
26
+ from .dmsqlalchemy import objedctvar, parse_mysql_stmt, parse_tsql_stmt
27
+ from .exceptions import * # noqa: F401,F403
28
+
29
+ version = "2.5.32" # spoof the official version; dmSQLAlchemy parses it
30
+ apilevel = "2.0"
31
+ threadsafety = 1
32
+ paramstyle = "qmark" # compiled to JDBC `?`; dialect do_execute uses positional binds
33
+
34
+ # dmPython.py re-exports exactly these names as the dmPython module on macOS.
35
+ __all__ = [
36
+ "version",
37
+ "apilevel",
38
+ "threadsafety",
39
+ "paramstyle",
40
+ "connect",
41
+ "Connection",
42
+ "Cursor",
43
+ *exceptions.__all__,
44
+ *dbtypes.__all__,
45
+ "parse_mysql_stmt",
46
+ "parse_tsql_stmt",
47
+ "objedctvar",
48
+ ]
@@ -0,0 +1,11 @@
1
+ """Per-connection locking shared by Connection and Cursor."""
2
+ from functools import wraps
3
+
4
+
5
+ def serialized(method):
6
+ """Serialize JDBC access across dmAsync's worker threads per connection."""
7
+ @wraps(method)
8
+ def locked(self, *args, **kwargs):
9
+ with self._lock:
10
+ return method(self, *args, **kwargs)
11
+ return locked