pyoceanbase 1.0.1__tar.gz

pyoceanbase-1.0.1/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## v1.0.1
+
+* 分发包改名 `pyoceanbase`，顶层 import 包同步改为 `pyoceanbase`，
+  可与上游 PyMySQL 共存。
+* 客户端标识改为 `pyoceanbase`。
+
+## v1.0.0
+
+* 首版。基线：上游 `PyMySQL 1.2.0`。
+* 默认置上握手包 capability bit27（`QUERY_ATTRIBUTES`），
+  OceanBase Oracle 租户可直接用 MySQL 协议登录；否则服务端报
+  `Error 1235: Oracle tenant for current client driver is not supported`。
+* 已在 OceanBase 4.2.1.11 Oracle 租户验证：连接、查询、绑定变量、
+  建表写入、事务提交回滚。

pyoceanbase-1.0.1/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010, 2013 PyMySQL contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

pyoceanbase-1.0.1/MANIFEST.in

@@ -0,0 +1 @@
+include README.md LICENSE CHANGELOG.md

pyoceanbase-1.0.1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: pyoceanbase
+Version: 1.0.1
+Summary: Pure Python OceanBase Driver (PyMySQL fork with Oracle tenant support)
+Author-email: Inada Naoki <songofacandy@gmail.com>, Yutaka Matsubara <yutaka.matsubara@gmail.com>
+License-Expression: MIT
+Project-URL: Project, https://github.com/oceanbase-driver/python-oceanbase-driver
+Project-URL: Changelog, https://github.com/oceanbase-driver/python-oceanbase-driver/blob/master/CHANGELOG.md
+Keywords: MySQL
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: rsa
+Requires-Dist: cryptography>=46.0.7; extra == "rsa"
+Provides-Extra: ed25519
+Requires-Dist: PyNaCl>=1.6.2; extra == "ed25519"
+Dynamic: license-file
+
+# python-oceanbase-driver
+
+Python 的 OceanBase 驱动，基于 `PyMySQL 1.2.0`，纯 Python，用法与 PyMySQL 完全一致，
+区别是默认置上握手包 capability bit27，可直连 OceanBase **Oracle 租户**。
+未打补丁的 MySQL 协议驱动连 Oracle 租户会被服务端拒绝：
+
+```text
+pyoceanbase.err.NotSupportedError: (1235, 'Oracle tenant for current client driver is not supported')
+```
+
+原理：OceanBase 登录时检查该位（`OB_CLIENT_SUPPORT_ORACLE_MODE`，
+与 MySQL 8.0 的 `CLIENT_QUERY_ATTRIBUTES` 同一位），mysql 8.0 客户端默认置位，
+PyMySQL 默认没置。本驱动默认置上，对 MySQL / MariaDB / OB MySQL 租户无副作用。
+
+## 安装
+
+```shell
+pip install pyoceanbase
+```
+
+注意：顶层包名为 `pyoceanbase`，可与上游 PyMySQL 共存于同一环境，按需选用。
+
+## 用法
+
+```python
+import pyoceanbase
+
+conn = pyoceanbase.connect(
+    host="HOST",
+    port=9090,
+    user="USER@TENANT#CLUSTER",
+    password="PASSWORD",
+    database="DBNAME",
+)
+with conn.cursor() as cur:
+    cur.execute("SELECT USER FROM DUAL")
+    print(cur.fetchone())
+conn.close()
+```
+
+## 注意事项
+
+1. 业务 SQL 须用 Oracle 方言（如 `FROM DUAL`、`SYSDATE`）。
+2. 默认 `autocommit=False`，写入后记得 `conn.commit()`（标准 PyMySQL 行为）。
+3. 数字类型默认返回 `Decimal`（标准 PyMySQL 行为），可用 `conv` 覆盖。
+4. DSN 参数等细节见上游文档：https://github.com/PyMySQL/PyMySQL
+
+## 协议
+
+MIT，与上游一致。

pyoceanbase-1.0.1/README.md

@@ -0,0 +1,50 @@
+# python-oceanbase-driver
+
+Python 的 OceanBase 驱动，基于 `PyMySQL 1.2.0`，纯 Python，用法与 PyMySQL 完全一致，
+区别是默认置上握手包 capability bit27，可直连 OceanBase **Oracle 租户**。
+未打补丁的 MySQL 协议驱动连 Oracle 租户会被服务端拒绝：
+
+```text
+pyoceanbase.err.NotSupportedError: (1235, 'Oracle tenant for current client driver is not supported')
+```
+
+原理：OceanBase 登录时检查该位（`OB_CLIENT_SUPPORT_ORACLE_MODE`，
+与 MySQL 8.0 的 `CLIENT_QUERY_ATTRIBUTES` 同一位），mysql 8.0 客户端默认置位，
+PyMySQL 默认没置。本驱动默认置上，对 MySQL / MariaDB / OB MySQL 租户无副作用。
+
+## 安装
+
+```shell
+pip install pyoceanbase
+```
+
+注意：顶层包名为 `pyoceanbase`，可与上游 PyMySQL 共存于同一环境，按需选用。
+
+## 用法
+
+```python
+import pyoceanbase
+
+conn = pyoceanbase.connect(
+    host="HOST",
+    port=9090,
+    user="USER@TENANT#CLUSTER",
+    password="PASSWORD",
+    database="DBNAME",
+)
+with conn.cursor() as cur:
+    cur.execute("SELECT USER FROM DUAL")
+    print(cur.fetchone())
+conn.close()
+```
+
+## 注意事项
+
+1. 业务 SQL 须用 Oracle 方言（如 `FROM DUAL`、`SYSDATE`）。
+2. 默认 `autocommit=False`，写入后记得 `conn.commit()`（标准 PyMySQL 行为）。
+3. 数字类型默认返回 `Decimal`（标准 PyMySQL 行为），可用 `conv` 覆盖。
+4. DSN 参数等细节见上游文档：https://github.com/PyMySQL/PyMySQL
+
+## 协议
+
+MIT，与上游一致。

pyoceanbase-1.0.1/pyoceanbase/__init__.py

@@ -0,0 +1,183 @@
+"""
+PyMySQL: A pure-Python MySQL client library.
+
+Copyright (c) 2010-2016 PyMySQL contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+"""
+
+import sys
+
+from .constants import FIELD_TYPE
+from .err import (
+    Warning,
+    Error,
+    InterfaceError,
+    DataError,
+    DatabaseError,
+    OperationalError,
+    IntegrityError,
+    InternalError,
+    NotSupportedError,
+    ProgrammingError,
+    MySQLError,
+)
+from .times import (
+    Date,
+    Time,
+    Timestamp,
+    DateFromTicks,
+    TimeFromTicks,
+    TimestampFromTicks,
+)
+
+# Fork version (upstream PyMySQL base: 1.2.0).
+# Used by setuptools and connection_attrs
+VERSION = (1, 0, 1, "final")
+VERSION_STRING = "1.0.1"
+
+### for mysqlclient compatibility
+### Django checks mysqlclient version.
+version_info = (2, 2, 8, "final", 1)
+__version__ = "2.2.8"
+
+
+def get_client_info():  # for MySQLdb compatibility
+    return __version__
+
+
+def install_as_MySQLdb():
+    """
+    After this function is called, any application that imports MySQLdb
+    will unwittingly actually use pyoceanbase.
+    """
+    sys.modules["MySQLdb"] = sys.modules["pyoceanbase"]
+
+
+# end of mysqlclient compatibility code
+
+threadsafety = 1
+apilevel = "2.0"
+paramstyle = "pyformat"
+
+from . import connections  # noqa: E402
+
+
+class DBAPISet(frozenset):
+    def __ne__(self, other):
+        if isinstance(other, set):
+            return frozenset.__ne__(self, other)
+        else:
+            return other not in self
+
+    def __eq__(self, other):
+        if isinstance(other, frozenset):
+            return frozenset.__eq__(self, other)
+        else:
+            return other in self
+
+    def __hash__(self):
+        return frozenset.__hash__(self)
+
+
+STRING = DBAPISet([FIELD_TYPE.ENUM, FIELD_TYPE.STRING, FIELD_TYPE.VAR_STRING])
+BINARY = DBAPISet(
+    [
+        FIELD_TYPE.BLOB,
+        FIELD_TYPE.LONG_BLOB,
+        FIELD_TYPE.MEDIUM_BLOB,
+        FIELD_TYPE.TINY_BLOB,
+    ]
+)
+NUMBER = DBAPISet(
+    [
+        FIELD_TYPE.DECIMAL,
+        FIELD_TYPE.DOUBLE,
+        FIELD_TYPE.FLOAT,
+        FIELD_TYPE.INT24,
+        FIELD_TYPE.LONG,
+        FIELD_TYPE.LONGLONG,
+        FIELD_TYPE.TINY,
+        FIELD_TYPE.YEAR,
+    ]
+)
+DATE = DBAPISet([FIELD_TYPE.DATE, FIELD_TYPE.NEWDATE])
+TIME = DBAPISet([FIELD_TYPE.TIME])
+TIMESTAMP = DBAPISet([FIELD_TYPE.TIMESTAMP, FIELD_TYPE.DATETIME])
+DATETIME = TIMESTAMP
+ROWID = DBAPISet()
+
+
+def Binary(x):
+    """Return x as a binary type."""
+    return bytes(x)
+
+
+def thread_safe():
+    return True  # match MySQLdb.thread_safe()
+
+
+Connect = connect = Connection = connections.Connection
+NULL = "NULL"
+
+
+__all__ = [
+    "BINARY",
+    "Binary",
+    "Connect",
+    "Connection",
+    "DATE",
+    "Date",
+    "Time",
+    "Timestamp",
+    "DateFromTicks",
+    "TimeFromTicks",
+    "TimestampFromTicks",
+    "DataError",
+    "DatabaseError",
+    "Error",
+    "FIELD_TYPE",
+    "IntegrityError",
+    "InterfaceError",
+    "InternalError",
+    "MySQLError",
+    "NULL",
+    "NUMBER",
+    "NotSupportedError",
+    "DBAPISet",
+    "OperationalError",
+    "ProgrammingError",
+    "ROWID",
+    "STRING",
+    "TIME",
+    "TIMESTAMP",
+    "Warning",
+    "apilevel",
+    "connect",
+    "connections",
+    "constants",
+    "converters",
+    "cursors",
+    "get_client_info",
+    "paramstyle",
+    "threadsafety",
+    "version_info",
+    "install_as_MySQLdb",
+    "__version__",
+]

pyoceanbase-1.0.1/pyoceanbase/_auth.py

@@ -0,0 +1,272 @@
+"""
+Implements auth methods
+"""
+
+from .err import OperationalError
+
+
+try:
+    from cryptography.hazmat.backends import default_backend
+    from cryptography.hazmat.primitives import serialization, hashes
+    from cryptography.hazmat.primitives.asymmetric import padding
+
+    _have_cryptography = True
+except ImportError:
+    _have_cryptography = False
+
+from functools import partial
+import hashlib
+
+
+DEBUG = False
+SCRAMBLE_LENGTH = 20
+sha1_new = partial(hashlib.new, "sha1")
+
+
+# mysql_native_password
+# https://dev.mysql.com/doc/internals/en/secure-password-authentication.html#packet-Authentication::Native41
+
+
+def scramble_native_password(password, message):
+    """Scramble used for mysql_native_password"""
+    if not password:
+        return b""
+
+    stage1 = sha1_new(password).digest()
+    stage2 = sha1_new(stage1).digest()
+    s = sha1_new()
+    s.update(message[:SCRAMBLE_LENGTH])
+    s.update(stage2)
+    result = s.digest()
+    return _my_crypt(result, stage1)
+
+
+def _my_crypt(message1, message2):
+    result = bytearray(message1)
+
+    for i in range(len(result)):
+        result[i] ^= message2[i]
+
+    return bytes(result)
+
+
+# MariaDB's client_ed25519-plugin
+# https://mariadb.com/kb/en/library/connection/#client_ed25519-plugin
+
+_nacl_bindings = False
+
+
+def _init_nacl():
+    global _nacl_bindings
+    try:
+        from nacl import bindings
+
+        _nacl_bindings = bindings
+    except ImportError:
+        raise RuntimeError(
+            "'pynacl' package is required for ed25519_password auth method"
+        )
+
+
+def _scalar_clamp(s32):
+    ba = bytearray(s32)
+    ba0 = bytes(bytearray([ba[0] & 248]))
+    ba31 = bytes(bytearray([(ba[31] & 127) | 64]))
+    return ba0 + bytes(s32[1:31]) + ba31
+
+
+def ed25519_password(password, scramble):
+    """Sign a random scramble with elliptic curve Ed25519.
+
+    Secret and public key are derived from password.
+    """
+    # variable names based on rfc8032 section-5.1.6
+    #
+    if not _nacl_bindings:
+        _init_nacl()
+
+    # h = SHA512(password)
+    h = hashlib.sha512(password).digest()
+
+    # s = prune(first_half(h))
+    s = _scalar_clamp(h[:32])
+
+    # r = SHA512(second_half(h) || M)
+    r = hashlib.sha512(h[32:] + scramble).digest()
+
+    # R = encoded point [r]B
+    r = _nacl_bindings.crypto_core_ed25519_scalar_reduce(r)
+    R = _nacl_bindings.crypto_scalarmult_ed25519_base_noclamp(r)
+
+    # A = encoded point [s]B
+    A = _nacl_bindings.crypto_scalarmult_ed25519_base_noclamp(s)
+
+    # k = SHA512(R || A || M)
+    k = hashlib.sha512(R + A + scramble).digest()
+
+    # S = (k * s + r) mod L
+    k = _nacl_bindings.crypto_core_ed25519_scalar_reduce(k)
+    ks = _nacl_bindings.crypto_core_ed25519_scalar_mul(k, s)
+    S = _nacl_bindings.crypto_core_ed25519_scalar_add(ks, r)
+
+    # signature = R || S
+    return R + S
+
+
+# sha256_password
+
+
+def _roundtrip(conn, send_data):
+    conn.write_packet(send_data)
+    pkt = conn._read_packet()
+    pkt.check_error()
+    return pkt
+
+
+def _xor_password(password, salt):
+    # Trailing NUL character will be added in Auth Switch Request.
+    # See https://github.com/mysql/mysql-server/blob/7d10c82196c8e45554f27c00681474a9fb86d137/sql/auth/sha2_password.cc#L939-L945
+    salt = salt[:SCRAMBLE_LENGTH]
+    password_bytes = bytearray(password)
+    # salt = bytearray(salt)  # for PY2 compat.
+    salt_len = len(salt)
+    for i in range(len(password_bytes)):
+        password_bytes[i] ^= salt[i % salt_len]
+    return bytes(password_bytes)
+
+
+def sha2_rsa_encrypt(password, salt, public_key):
+    """Encrypt password with salt and public_key.
+
+    Used for sha256_password and caching_sha2_password.
+    """
+    if not _have_cryptography:
+        raise RuntimeError(
+            "'cryptography' package is required for sha256_password or"
+            + " caching_sha2_password auth methods"
+        )
+    message = _xor_password(password + b"\0", salt)
+    rsa_key = serialization.load_pem_public_key(public_key, default_backend())
+    return rsa_key.encrypt(
+        message,
+        padding.OAEP(
+            mgf=padding.MGF1(algorithm=hashes.SHA1()),
+            algorithm=hashes.SHA1(),
+            label=None,
+        ),
+    )
+
+
+def sha256_password_auth(conn, pkt):
+    if conn._secure:
+        if DEBUG:
+            print("sha256: Sending plain password")
+        data = conn.password + b"\0"
+        return _roundtrip(conn, data)
+
+    if pkt.is_auth_switch_request():
+        conn.salt = pkt.read_all()
+        if conn.salt.endswith(b"\0"):
+            conn.salt = conn.salt[:-1]
+        if not conn.server_public_key and conn.password:
+            # Request server public key
+            if DEBUG:
+                print("sha256: Requesting server public key")
+            pkt = _roundtrip(conn, b"\1")
+
+    if pkt.is_extra_auth_data():
+        conn.server_public_key = pkt._data[1:]
+        if DEBUG:
+            print("Received public key:\n", conn.server_public_key.decode("ascii"))
+
+    if conn.password:
+        if not conn.server_public_key:
+            raise OperationalError("Couldn't receive server's public key")
+
+        data = sha2_rsa_encrypt(conn.password, conn.salt, conn.server_public_key)
+    else:
+        data = b""
+
+    return _roundtrip(conn, data)
+
+
+def scramble_caching_sha2(password, nonce):
+    # (bytes, bytes) -> bytes
+    """Scramble algorithm used in cached_sha2_password fast path.
+
+    XOR(SHA256(password), SHA256(SHA256(SHA256(password)), nonce))
+    """
+    if not password:
+        return b""
+
+    p1 = hashlib.sha256(password).digest()
+    p2 = hashlib.sha256(p1).digest()
+    p3 = hashlib.sha256(p2 + nonce).digest()
+
+    res = bytearray(p1)
+    for i in range(len(p3)):
+        res[i] ^= p3[i]
+
+    return bytes(res)
+
+
+def caching_sha2_password_auth(conn, pkt):
+    # No password fast path
+    if not conn.password:
+        return _roundtrip(conn, b"")
+
+    if pkt.is_auth_switch_request():
+        # Try from fast auth
+        conn.salt = pkt.read_all()
+        if conn.salt.endswith(b"\0"):  # str.removesuffix is available in 3.9
+            conn.salt = conn.salt[:-1]
+        if DEBUG:
+            print(f"caching sha2: Trying fast path. salt={conn.salt.hex()!r}")
+        scrambled = scramble_caching_sha2(conn.password, conn.salt)
+        pkt = _roundtrip(conn, scrambled)
+    # else: fast auth is tried in initial handshake
+
+    if not pkt.is_extra_auth_data():
+        raise OperationalError(
+            "caching sha2: Unknown packet for fast auth: %s" % pkt._data[:1]
+        )
+
+    # magic numbers:
+    # 2 - request public key
+    # 3 - fast auth succeeded
+    # 4 - need full auth
+
+    pkt.advance(1)
+    n = pkt.read_uint8()
+
+    if n == 3:
+        if DEBUG:
+            print("caching sha2: succeeded by fast path.")
+        pkt = conn._read_packet()
+        pkt.check_error()  # pkt must be OK packet
+        return pkt
+
+    if n != 4:
+        raise OperationalError("caching sha2: Unknown result for fast auth: %s" % n)
+
+    if DEBUG:
+        print("caching sha2: Trying full auth...")
+
+    if conn._secure:
+        if DEBUG:
+            print("caching sha2: Sending plain password via secure connection")
+        return _roundtrip(conn, conn.password + b"\0")
+
+    if not conn.server_public_key:
+        pkt = _roundtrip(conn, b"\x02")  # Request public key
+        if not pkt.is_extra_auth_data():
+            raise OperationalError(
+                "caching sha2: Unknown packet for public key: %s" % pkt._data[:1]
+            )
+
+        conn.server_public_key = pkt._data[1:]
+        if DEBUG:
+            print(conn.server_public_key.decode("ascii"))
+
+    data = sha2_rsa_encrypt(conn.password, conn.salt, conn.server_public_key)
+    pkt = _roundtrip(conn, data)