dmpython-jdbc 2.5.32__tar.gz → 2.5.32.post2__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.
- dmpython_jdbc-2.5.32.post2/MANIFEST.in +12 -0
- dmpython_jdbc-2.5.32.post2/PKG-INFO +200 -0
- dmpython_jdbc-2.5.32.post2/README.md +177 -0
- dmpython_jdbc-2.5.32.post2/README.zh-CN.md +169 -0
- {dmpython_jdbc-2.5.32 → dmpython_jdbc-2.5.32.post2}/_dmPython_jdbc/__init__.py +264 -64
- dmpython_jdbc-2.5.32.post2/_dmpython_metadata.py +27 -0
- {dmpython_jdbc-2.5.32 → dmpython_jdbc-2.5.32.post2}/dmPython.py +5 -2
- dmpython_jdbc-2.5.32.post2/dmpython-2.5.32.dist-info/METADATA +4 -0
- dmpython_jdbc-2.5.32.post2/dmpython_jdbc.egg-info/PKG-INFO +200 -0
- dmpython_jdbc-2.5.32.post2/dmpython_jdbc.egg-info/SOURCES.txt +27 -0
- {dmpython_jdbc-2.5.32 → dmpython_jdbc-2.5.32.post2}/dmpython_jdbc.egg-info/top_level.txt +1 -0
- {dmpython_jdbc-2.5.32 → dmpython_jdbc-2.5.32.post2}/pyproject.toml +2 -2
- dmpython_jdbc-2.5.32.post2/setup.py +15 -0
- dmpython_jdbc-2.5.32.post2/tests/e2e/.env.example +7 -0
- dmpython_jdbc-2.5.32.post2/tests/e2e/README.md +64 -0
- dmpython_jdbc-2.5.32.post2/tests/e2e/bootstrap.py +87 -0
- dmpython_jdbc-2.5.32.post2/tests/e2e/compose.yaml +38 -0
- dmpython_jdbc-2.5.32.post2/tests/e2e/healthcheck.sh +11 -0
- dmpython_jdbc-2.5.32.post2/tests/e2e/run.py +51 -0
- dmpython_jdbc-2.5.32.post2/tests/e2e/start-dm.sh +24 -0
- dmpython_jdbc-2.5.32.post2/tests/e2e/test.sh +16 -0
- dmpython_jdbc-2.5.32.post2/tests/e2e/test_live_dmasync.py +246 -0
- dmpython_jdbc-2.5.32.post2/tests/test_dmasync.py +310 -0
- dmpython_jdbc-2.5.32/MANIFEST.in +0 -5
- dmpython_jdbc-2.5.32/PKG-INFO +0 -78
- dmpython_jdbc-2.5.32/README.md +0 -55
- dmpython_jdbc-2.5.32/dmpython_jdbc.egg-info/PKG-INFO +0 -78
- dmpython_jdbc-2.5.32/dmpython_jdbc.egg-info/SOURCES.txt +0 -13
- {dmpython_jdbc-2.5.32 → dmpython_jdbc-2.5.32.post2}/LICENSE +0 -0
- {dmpython_jdbc-2.5.32 → dmpython_jdbc-2.5.32.post2}/NOTICE +0 -0
- {dmpython_jdbc-2.5.32 → dmpython_jdbc-2.5.32.post2}/_dmPython_jdbc/DmJdbcDriver18-8.1.3.140.jar +0 -0
- {dmpython_jdbc-2.5.32 → dmpython_jdbc-2.5.32.post2}/dmpython_jdbc.egg-info/dependency_links.txt +0 -0
- {dmpython_jdbc-2.5.32 → dmpython_jdbc-2.5.32.post2}/dmpython_jdbc.egg-info/requires.txt +0 -0
- {dmpython_jdbc-2.5.32 → dmpython_jdbc-2.5.32.post2}/setup.cfg +0 -0
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
include README.md
|
|
2
|
+
include README.zh-CN.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,200 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: dmpython-jdbc
|
|
3
|
+
Version: 2.5.32.post2
|
|
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.md) | [简体中文](README.zh-CN.md)
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
**The distribution name is `dmpython-jdbc`; the import name remains `dmPython`.** Application code does not need to change.
|
|
31
|
+
|
|
32
|
+
- macOS: use this package's JDBC shim
|
|
33
|
+
- Other platforms: forward `import dmPython` to the official driver
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
PyPI:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pip install dmpython-jdbc
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Cross-platform projects (official driver on Linux/Windows, this package on 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
|
+
If the project also depends on `dmSQLAlchemy`, see [Using with dmSQLAlchemy](#using-with-dmsqlalchemy). That package pulls official `dmpython` unconditionally.
|
|
54
|
+
|
|
55
|
+
From Git:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install "dmpython-jdbc @ git+https://github.com/Darley-Wey/dmpython-jdbc.git"
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
uv:
|
|
62
|
+
|
|
63
|
+
```toml
|
|
64
|
+
[tool.uv.sources]
|
|
65
|
+
dmpython-jdbc = { git = "https://github.com/Darley-Wey/dmpython-jdbc.git" }
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Pin a commit or tag by appending `@<ref>`, for example `@main` or `@v2.5.32`.
|
|
69
|
+
|
|
70
|
+
## Runtime requirements
|
|
71
|
+
|
|
72
|
+
- Python >= 3.12
|
|
73
|
+
- JDK (`brew install openjdk` on macOS). `JAVA_HOME` is probed at `/opt/homebrew/opt/openjdk` and `/usr/local/opt/openjdk`
|
|
74
|
+
- The Dameng JDBC driver is bundled in the wheel; override it with `DM_JDBC_JAR`
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
## Using with dmSQLAlchemy
|
|
78
|
+
|
|
79
|
+
`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.
|
|
80
|
+
|
|
81
|
+
Keep `dmSQLAlchemy`, prevent the resolver from installing official `dmpython` on macOS, and install `dmpython-jdbc` instead. The import name stays `dmPython`.
|
|
82
|
+
|
|
83
|
+
### uv
|
|
84
|
+
|
|
85
|
+
```toml
|
|
86
|
+
[project]
|
|
87
|
+
dependencies = [
|
|
88
|
+
"dmsqlalchemy",
|
|
89
|
+
"dmpython>=2.5.32; sys_platform != 'darwin'",
|
|
90
|
+
"dmpython-jdbc>=2.5.32; sys_platform == 'darwin'",
|
|
91
|
+
]
|
|
92
|
+
|
|
93
|
+
[tool.uv]
|
|
94
|
+
override-dependencies = [
|
|
95
|
+
"dmpython ; sys_platform != 'darwin'",
|
|
96
|
+
]
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`override-dependencies` rewrites `dmSQLAlchemy`'s `dmpython` requirement so it is skipped on macOS. `dmpython-jdbc` then provides the `dmPython` module.
|
|
100
|
+
|
|
101
|
+
`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`.
|
|
102
|
+
|
|
103
|
+
### pip on macOS
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
pip install "dmSQLAlchemy" --no-deps
|
|
107
|
+
pip install "SQLAlchemy>1.4.54" dmpython-jdbc
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Using as dmAsync's dmPython backend
|
|
111
|
+
|
|
112
|
+
The shim supports the basic connection and cursor API used by `dmAsync==1.0.0`:
|
|
113
|
+
`connect`, `execute`, `executemany`, `fetchone`/`fetchmany`/`fetchall`, async
|
|
114
|
+
iteration, `commit`, `rollback`, and `ping`. dmAsync calls the synchronous shim
|
|
115
|
+
through `asyncio.to_thread` for these database operations; connection creation
|
|
116
|
+
and closing remain synchronous in dmAsync 1.0.0.
|
|
117
|
+
|
|
118
|
+
For a development checkout on macOS:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
python -m pip install . "async-timeout>=4,<6"
|
|
122
|
+
python -m pip install "dmAsync==1.0.0" --no-deps
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`dmAsync` unconditionally requires official `dmPython`, so use the same
|
|
126
|
+
`[tool.uv].override-dependencies` configuration shown above when using uv.
|
|
127
|
+
Add `dmAsync==1.0.0` and `async-timeout>=4,<6` to your project dependencies;
|
|
128
|
+
dmAsync 1.0.0 imports `async_timeout` but does not declare it in its metadata.
|
|
129
|
+
The runtime version alias does not replace these resolver settings.
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
import asyncio
|
|
133
|
+
import os
|
|
134
|
+
import dmAsync
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
async def main():
|
|
138
|
+
conn = await dmAsync.connect(
|
|
139
|
+
host=os.environ["DM_HOST"],
|
|
140
|
+
port=int(os.environ.get("DM_PORT", "5236")),
|
|
141
|
+
user=os.environ["DM_USER"],
|
|
142
|
+
password=os.environ["DM_PASSWORD"],
|
|
143
|
+
autoCommit=False,
|
|
144
|
+
login_timeout=5000, # Milliseconds, forwarded to dmPython.
|
|
145
|
+
)
|
|
146
|
+
cur = await conn.cursor()
|
|
147
|
+
try:
|
|
148
|
+
await cur.execute("SELECT 1")
|
|
149
|
+
print(await cur.fetchone())
|
|
150
|
+
await conn.commit()
|
|
151
|
+
except Exception:
|
|
152
|
+
await conn.rollback()
|
|
153
|
+
raise
|
|
154
|
+
finally:
|
|
155
|
+
await cur.close()
|
|
156
|
+
await conn.close()
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
asyncio.run(main())
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`Connection.version` reports the server version. Identifier limits come from
|
|
163
|
+
JDBC metadata (`None` when unknown). `stmtcachesize` is `0` because the shim does
|
|
164
|
+
not implement a Python statement cache; setting a nonzero size is unsupported.
|
|
165
|
+
`status` reports shim liveness (`1` open, `0` closed), not a DPI transaction code.
|
|
166
|
+
Assignments to `autocommit` update the JDBC connection.
|
|
167
|
+
|
|
168
|
+
JDBC operations are serialized per connection across worker threads. Use one
|
|
169
|
+
connection per concurrent task: a lock does not isolate transactions or preserve
|
|
170
|
+
an execute/fetch sequence shared by several tasks. Cancelling an await does not
|
|
171
|
+
stop JDBC work already running in a thread; wait for that work to finish before
|
|
172
|
+
reusing or closing its connection. `callproc`, `callfunc`, explicit `prepare`,
|
|
173
|
+
`mogrify`, scrolling, holdable cursors and multiple result sets remain unsupported
|
|
174
|
+
and raise `NotSupportedError`. This does not establish full compatibility with
|
|
175
|
+
SQLAlchemy's separate `dm+dmasync://` dialect or dmAsync's connection pool.
|
|
176
|
+
|
|
177
|
+
### Adapter tests
|
|
178
|
+
|
|
179
|
+
With the dependencies above installed, run:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
python -m unittest discover -s tests -v
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Tests use the real dmAsync wrapper with a SQLite-backed double at the
|
|
186
|
+
JayDeBeApi boundary. They cover initialization, CRUD, transactions, cursor
|
|
187
|
+
lifecycle and per-connection locking without requiring a Dameng server.
|
|
188
|
+
|
|
189
|
+
For real-server verification, see [live Dameng E2E tests](tests/e2e/README.md).
|
|
190
|
+
With the dedicated test credentials configured, `bash tests/e2e/test.sh` builds
|
|
191
|
+
and tests the installed wheel against DM8, including binary/LOB round trips and
|
|
192
|
+
cross-connection transaction visibility.
|
|
193
|
+
|
|
194
|
+
## Limits
|
|
195
|
+
|
|
196
|
+
Stored-procedure OUT binds (`cursor.var`) and streaming LOB I/O are not supported. ORM CRUD is covered.
|
|
197
|
+
|
|
198
|
+
## License
|
|
199
|
+
|
|
200
|
+
The Python shim is MIT. `DmJdbcDriver18-*.jar` is Dameng's official JDBC driver and is not covered by MIT.
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# dmpython-jdbc
|
|
2
|
+
|
|
3
|
+
[English](README.md) | [简体中文](README.zh-CN.md)
|
|
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,169 @@
|
|
|
1
|
+
# dmpython-jdbc
|
|
2
|
+
|
|
3
|
+
[English](README.md) | [简体中文](README.zh-CN.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
|
+
从 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
|
+
需要钉到某个提交或 tag 时,在 URL 后加 `@<ref>`,例如 `@main` 或 `@v2.5.32`。
|
|
46
|
+
|
|
47
|
+
## 运行依赖
|
|
48
|
+
|
|
49
|
+
- Python >= 3.12
|
|
50
|
+
- JDK(macOS 可用 `brew install openjdk`)。`JAVA_HOME` 会自动探测 `/opt/homebrew/opt/openjdk` 和 `/usr/local/opt/openjdk`
|
|
51
|
+
- 达梦 JDBC 驱动已打包进 wheel;也可用环境变量 `DM_JDBC_JAR` 覆盖
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
## 配合 dmSQLAlchemy
|
|
55
|
+
|
|
56
|
+
`dmSQLAlchemy` 无条件依赖官方 `dmpython`(`Requires-Dist: dmPython`)。该包没有 macOS wheel,所以在 Mac 上 `pip install dmSQLAlchemy` 会尝试装达梦官方驱动并失败。
|
|
57
|
+
|
|
58
|
+
要保留 `dmSQLAlchemy`,又阻止解析器在 macOS 上装官方 `dmpython`,改装 `dmpython-jdbc`。import 名仍是 `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` 会改写 `dmSQLAlchemy` 对 `dmpython` 的依赖,让它在 macOS 上被跳过;然后由 `dmpython-jdbc` 提供 `dmPython` 模块。
|
|
77
|
+
|
|
78
|
+
`dmSQLAlchemy.extensions` 会调用 `importlib.metadata.version("dmPython")`。本包会安装 `.pth` 钩子,让这次查询返回 shim 版本 `2.5.32`,不依赖 setuptools/`pkg_resources`。
|
|
79
|
+
|
|
80
|
+
### macOS 上的 pip
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
pip install "dmSQLAlchemy" --no-deps
|
|
84
|
+
pip install "SQLAlchemy>1.4.54" dmpython-jdbc
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## 作为 dmAsync 的 dmPython 后端
|
|
88
|
+
|
|
89
|
+
本包支持 `dmAsync==1.0.0` 使用的基础连接和游标接口:`connect`、`execute`、
|
|
90
|
+
`executemany`、`fetchone`/`fetchmany`/`fetchall`、异步迭代、`commit`、`rollback`
|
|
91
|
+
和 `ping`。dmAsync 使用 `asyncio.to_thread` 调用同步 shim 完成这些数据库操作;
|
|
92
|
+
dmAsync 1.0.0 的建连和关闭仍是同步操作。
|
|
93
|
+
|
|
94
|
+
macOS 上在开发版仓库目录中安装:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
python -m pip install . "async-timeout>=4,<6"
|
|
98
|
+
python -m pip install "dmAsync==1.0.0" --no-deps
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`dmAsync` 无条件依赖官方 `dmPython`,因此使用 uv 时,需要保留上文的
|
|
102
|
+
`[tool.uv].override-dependencies` 配置,并在项目依赖中加入 `dmAsync==1.0.0`
|
|
103
|
+
和 `async-timeout>=4,<6`。dmAsync 1.0.0 导入了 `async_timeout`,但没有在包元数据中
|
|
104
|
+
声明该依赖。运行时的版本别名不能代替这些依赖解析配置。
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
import asyncio
|
|
108
|
+
import os
|
|
109
|
+
import dmAsync
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
async def main():
|
|
113
|
+
conn = await dmAsync.connect(
|
|
114
|
+
host=os.environ["DM_HOST"],
|
|
115
|
+
port=int(os.environ.get("DM_PORT", "5236")),
|
|
116
|
+
user=os.environ["DM_USER"],
|
|
117
|
+
password=os.environ["DM_PASSWORD"],
|
|
118
|
+
autoCommit=False,
|
|
119
|
+
login_timeout=5000, # 毫秒,直接传给 dmPython。
|
|
120
|
+
)
|
|
121
|
+
cur = await conn.cursor()
|
|
122
|
+
try:
|
|
123
|
+
await cur.execute("SELECT 1")
|
|
124
|
+
print(await cur.fetchone())
|
|
125
|
+
await conn.commit()
|
|
126
|
+
except Exception:
|
|
127
|
+
await conn.rollback()
|
|
128
|
+
raise
|
|
129
|
+
finally:
|
|
130
|
+
await cur.close()
|
|
131
|
+
await conn.close()
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
asyncio.run(main())
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`Connection.version` 返回服务端版本;标识符长度限制从 JDBC 元数据读取,未知时
|
|
138
|
+
返回 `None`。shim 不实现 Python 层语句缓存,因此 `stmtcachesize` 为 `0`,
|
|
139
|
+
不支持设为非零值。`status` 表示 shim 连接状态(`1` 开启、`0` 关闭),不是 DPI
|
|
140
|
+
事务状态码。修改 `autocommit` 会同步到 JDBC 连接。
|
|
141
|
+
|
|
142
|
+
同一连接的 JDBC 操作会在线程间串行执行。并发任务应各自持有连接:锁无法隔离事务,
|
|
143
|
+
也无法保证多个任务共享游标时 execute/fetch 的先后关系。取消 await 不会终止线程中
|
|
144
|
+
已经开始的 JDBC 操作;重新使用或关闭该连接前,应等待操作结束。`callproc`、
|
|
145
|
+
`callfunc`、显式 `prepare`、`mogrify`、游标滚动、跨提交保留游标以及多结果集仍不支持,
|
|
146
|
+
调用会抛出 `NotSupportedError`。这些适配不代表已完整验证 SQLAlchemy 的
|
|
147
|
+
`dm+dmasync://` 方言或 dmAsync 连接池。
|
|
148
|
+
|
|
149
|
+
### 适配测试
|
|
150
|
+
|
|
151
|
+
安装上述依赖后执行:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
python -m unittest discover -s tests -v
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
测试使用真实 dmAsync 包,在 JayDeBeApi 边界用 SQLite 模拟数据库,覆盖初始化、
|
|
158
|
+
CRUD、事务、游标生命周期和连接级锁,不需要达梦服务器。
|
|
159
|
+
|
|
160
|
+
真库验证见 [达梦端到端测试说明](tests/e2e/README.md)。配置专用测试账号后,执行
|
|
161
|
+
`bash tests/e2e/test.sh` 即可构建并测试实际安装的 wheel,覆盖二进制/LOB 数据往返、
|
|
162
|
+
跨连接事务可见性等。
|
|
163
|
+
## 限制
|
|
164
|
+
|
|
165
|
+
不支持存储过程出参(`cursor.var`)、LOB 流式读写等高级特性,覆盖 ORM CRUD 即可。
|
|
166
|
+
|
|
167
|
+
## 许可证
|
|
168
|
+
|
|
169
|
+
Python 兼容层使用 MIT。仓库中的 `DmJdbcDriver18-*.jar` 是达梦官方 JDBC 驱动,版权归达梦数据库所有,不受 MIT 覆盖。
|