ezr-database-sdk 0.1.2__py3-none-any.whl

ezr_database_sdk/__init__.py

@@ -0,0 +1,16 @@
+"""EZR internal database metadata SDK (synchronous and read-only)."""
+from .client import ConnectionInfo, EzrDatabaseSDK
+from .errors import (
+    SDKError, ConfigurationError, MetadataNotFoundError,
+    AmbiguousMetadataError, DatabaseError,
+)
+from .routing import (
+    get_code, physical_table_name, physical_table_name_by_int, physical_table_name_by_hash,
+)
+
+__all__ = [
+    'EzrDatabaseSDK', 'ConnectionInfo', 'SDKError', 'ConfigurationError',
+    'MetadataNotFoundError', 'AmbiguousMetadataError', 'DatabaseError',
+    'get_code', 'physical_table_name_by_int', 'physical_table_name_by_hash',
+    'physical_table_name',  # Deprecated compatibility entry point.
+]

ezr_database_sdk/client.py

@@ -0,0 +1,180 @@
+"""Synchronous, metadata-only client. An instance must not be shared across threads."""
+from collections.abc import Mapping
+from pathlib import Path
+import warnings
+
+import pymysql
+
+from .config import load_environment, read_yaml
+from .errors import DatabaseError, MetadataNotFoundError, AmbiguousMetadataError
+from .routing import (
+    physical_table_name_by_int, physical_table_name_by_hash,
+    _validate_int_key, _validate_hash_key,
+)
+
+# Explicit mapping: business SystemCode values do not always match brand field names.
+_BRAND_FIELDS = {
+    'bd': 'BdDbShardingId', 'crm': 'CrmDbShardingId',
+    'eop': 'EopDbShardingId', 'mall': 'MallDbShardingId',
+    'order': 'OrderDbShardingId', 'cms': 'CmsDbShardingId',
+    'rtl': 'RtlDbShardingId', 'log': 'LogDbShardingId',
+    'prod': 'ProdDbShardingId', 'pay': 'PayDbShardingId',
+    'ubs': 'UbsDbShardingId', 'dlake': 'DLakeShardingId',
+    'bigdata': 'BigDataShardingId', 'es': 'ESDbShardingId',
+    'esproduct': 'ESProdutShardingId', 'esreport': 'ESReportShardingId',
+    'oms': 'OmsDbShardingId',
+}
+
+
+class ConnectionInfo(dict):
+    """Original DB fields; repr hides the credential-bearing connection string.
+
+    Explicit key access and serialization still return the real credentials.
+    """
+
+    def __repr__(self):
+        return repr({key: '<redacted>' if key == 'DbConnString' else value
+                     for key, value in self.items()})
+
+    __str__ = __repr__
+
+
+class EzrDatabaseSDK:
+    """Read brand metadata for one configured environment, with lazy connection."""
+
+    def __init__(self, config: Mapping, *, env: str):
+        self._config = load_environment(config, env)
+        self.env = env
+        self._connection = None
+        self._closed = False
+
+    @classmethod
+    def from_yaml(cls, path: str | Path, *, env: str):
+        return cls(read_yaml(path), env=env)
+
+    def _ensure_open(self):
+        if self._closed:
+            raise RuntimeError('SDK instance has been closed')
+
+    def _query(self, sql: str, params: tuple) -> list[dict]:
+        self._ensure_open()
+        try:
+            if self._connection is None:
+                cfg = self._config
+                self._connection = pymysql.connect(
+                    host=cfg.host, port=cfg.port, user=cfg.user, password=cfg.password,
+                    charset='utf8mb4', autocommit=True,
+                    connect_timeout=cfg.connect_timeout, read_timeout=cfg.read_timeout,
+                    write_timeout=cfg.write_timeout,
+                    cursorclass=pymysql.cursors.DictCursor,
+                )
+            with self._connection.cursor() as cursor:
+                cursor.execute(sql, params)
+                return list(cursor.fetchall())
+        except Exception:
+            # Driver errors may include credentials or connection-string data.
+            raise DatabaseError('Database metadata read failed; check connectivity, permissions and schema') from None
+
+    def _shard_id(self, brand_id: int, database: str) -> int:
+        self._ensure_open()
+        if type(brand_id) is not int:
+            raise TypeError('brand_id must be an integer')
+        if brand_id <= 0:
+            raise ValueError('brand_id must be positive')
+        if not isinstance(database, str) or database.lower() not in _BRAND_FIELDS:
+            raise ValueError('Unsupported database; see the documented business database codes')
+        field = _BRAND_FIELDS[database.lower()]
+        rows = self._query(
+            f'SELECT * FROM `{self._config.brand_database}`.`ed_base_brand` WHERE `Id` = %s',
+            (brand_id,),
+        )
+        if not rows:
+            raise MetadataNotFoundError(f'Brand {brand_id} was not found')
+        if len(rows) != 1:
+            raise AmbiguousMetadataError('Multiple brand metadata records found')
+        value = rows[0].get(field)
+        if type(value) is not int or value <= 0:
+            raise MetadataNotFoundError(f'Brand {brand_id} has no valid {field} assignment')
+        return value
+
+    def get_table_shards(self, brand_id: int, database: str, table_code: str | None = None) -> list[dict]:
+        """Return raw table rules for a brand's business shard, including CopId.
+
+        CopId is not interpreted or silently prioritized. All matching rows are returned.
+        """
+        if table_code is not None and (not isinstance(table_code, str) or not table_code.strip()):
+            raise ValueError('table_code must be a nonempty string when provided')
+        shard_id = self._shard_id(brand_id, database)
+        sql = (f'SELECT * FROM `{self._config.base_database}`.`pf_sys_db_tableshard` '
+               'WHERE `ShardDbId` = %s')
+        params = (shard_id,)
+        if table_code is not None:
+            sql += ' AND `TableCode` = %s'
+            params += (table_code,)
+        return self._query(sql + ' ORDER BY `Id`', params)
+
+    def get_connection_strings(self, brand_id: int, database: str) -> list[ConnectionInfo]:
+        """Return all primary/replica and DbIndex nodes, preserving original fields."""
+        shard_id = self._shard_id(brand_id, database)
+        rows = self._query(
+            f'SELECT * FROM `{self._config.base_database}`.`pf_sys_db_shard_nodes` '
+            'WHERE `DbShardingId` = %s ORDER BY `DbIndex`, `IsMaster` DESC, `Id`',
+            (shard_id,),
+        )
+        return [ConnectionInfo(row) for row in rows]
+
+    def _get_table_rule(self, brand_id: int, database: str, table_code: str) -> dict:
+        rows = self.get_table_shards(brand_id, database, table_code)
+        if not rows:
+            raise MetadataNotFoundError('No table shard rule found; unsharded fallback is not assumed')
+        if len(rows) != 1:
+            raise AmbiguousMetadataError('Multiple table shard rules found; automatic selection is unsafe')
+        return rows[0]
+
+    def get_physical_table_name_by_int(self, brand_id: int, database: str, table_code: str,
+                                       shard_key: int) -> str:
+        """Load the table rule and route a nonnegative integer ID without hashing."""
+        _validate_int_key(shard_key)
+        rule = self._get_table_rule(brand_id, database, table_code)
+        return physical_table_name_by_int(rule['TableCode'], shard_key, rule['TableCount'])
+
+    def get_physical_table_name_by_hash(self, brand_id: int, database: str, table_code: str,
+                                        shard_key: str) -> str:
+        """Load the table rule and route a string ID using C#-compatible BKDR hash."""
+        _validate_hash_key(shard_key)
+        rule = self._get_table_rule(brand_id, database, table_code)
+        return physical_table_name_by_hash(rule['TableCode'], shard_key, rule['TableCount'])
+
+    def get_physical_table_name(self, brand_id: int, database: str, table_code: str,
+                                shard_key: int | str) -> str:
+        """Deprecated type-dispatch interface; use an explicit algorithm instead."""
+        warnings.warn(
+            'get_physical_table_name is deprecated; use get_physical_table_name_by_int '
+            'or get_physical_table_name_by_hash',
+            DeprecationWarning, stacklevel=2,
+        )
+        if isinstance(shard_key, str):
+            return self.get_physical_table_name_by_hash(brand_id, database, table_code, shard_key)
+        return self.get_physical_table_name_by_int(brand_id, database, table_code, shard_key)
+
+    def close(self):
+        if self._closed:
+            return
+        self._closed = True
+        connection, self._connection = self._connection, None
+        if connection is not None:
+            try:
+                connection.close()
+            except Exception:
+                raise DatabaseError('Unable to close the database connection') from None
+
+    def __enter__(self):
+        self._ensure_open()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        try:
+            self.close()
+        except DatabaseError:
+            if exc_type is None:
+                raise

ezr_database_sdk/config.py

@@ -0,0 +1,75 @@
+"""Strict environment selection and one-pass environment variable expansion."""
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+import os
+import re
+from pathlib import Path
+
+import yaml
+
+from .errors import ConfigurationError
+
+_VARIABLE = re.compile(r'\$\{([A-Za-z_][A-Za-z0-9_]*)\}')
+_IDENTIFIER = re.compile(r'[A-Za-z0-9_-]+\Z')
+
+
+def _expand(value):
+    if not isinstance(value, str):
+        return value
+
+    def replace(match):
+        name = match.group(1)
+        if name not in os.environ:
+            raise ConfigurationError(f'Missing environment variable: {name}')
+        return os.environ[name]
+
+    return _VARIABLE.sub(replace, value)
+
+
+@dataclass(frozen=True)
+class EnvironmentConfig:
+    host: str
+    user: str
+    password: str = field(repr=False)
+    port: int = 3306
+    base_database: str = 'ezp-base'
+    brand_database: str = 'ezp-ed'
+    connect_timeout: int = 10
+    read_timeout: int = 30
+    write_timeout: int = 30
+
+
+def load_environment(config: Mapping, env: str) -> EnvironmentConfig:
+    if not isinstance(env, str) or not env:
+        raise ConfigurationError('env must be an explicit nonempty environment name')
+    if not isinstance(config, Mapping):
+        raise ConfigurationError('Configuration must be a mapping')
+    environments = config.get('environments')
+    if not isinstance(environments, Mapping) or env not in environments:
+        raise ConfigurationError('Requested environment is not configured')
+    raw = environments[env]
+    if not isinstance(raw, Mapping):
+        raise ConfigurationError('Environment configuration must be a mapping')
+    allowed = EnvironmentConfig.__dataclass_fields__
+    if any(key not in allowed for key in raw):
+        raise ConfigurationError('Unknown environment configuration field')
+    data = {key: _expand(value) for key, value in raw.items()}
+    for key in ('host', 'user', 'password'):
+        if not isinstance(data.get(key), str) or (key != 'password' and not data[key].strip()):
+            raise ConfigurationError(f'{key} must be a string and is required')
+    for key, default in [('port', 3306), ('connect_timeout', 10), ('read_timeout', 30), ('write_timeout', 30)]:
+        value = data.get(key, default)
+        if type(value) is not int or value <= 0 or (key == 'port' and value > 65535):
+            raise ConfigurationError(f'{key} must be a positive integer in its valid range')
+    for key in ('base_database', 'brand_database'):
+        if key in data and (not isinstance(data[key], str) or not _IDENTIFIER.fullmatch(data[key])):
+            raise ConfigurationError(f'{key} must be a simple database identifier')
+    return EnvironmentConfig(**data)
+
+
+def read_yaml(path: str | Path) -> Mapping:
+    try:
+        with open(path, encoding='utf-8') as file:
+            return yaml.safe_load(file)
+    except (OSError, UnicodeError, yaml.YAMLError):
+        raise ConfigurationError('Unable to read SDK YAML configuration') from None

ezr_database_sdk/errors.py

@@ -0,0 +1,21 @@
+"""Public SDK errors; database driver details are deliberately not exposed."""
+
+
+class SDKError(Exception):
+    """Base SDK error."""
+
+
+class ConfigurationError(SDKError, ValueError):
+    """Invalid environment configuration."""
+
+
+class MetadataNotFoundError(SDKError, LookupError):
+    """Brand, shard assignment, or table rule is missing."""
+
+
+class AmbiguousMetadataError(SDKError):
+    """Multiple rules exist and selecting one would be unsafe."""
+
+
+class DatabaseError(SDKError):
+    """Database connection or read failed."""

ezr_database_sdk/routing.py

@@ -0,0 +1,61 @@
+"""Explicit routing algorithms compatible with the supplied C# GetCode."""
+import warnings
+
+
+def get_code(code: str) -> int:
+    """BKDR(seed=131), C# UTF-16 chars, unchecked Int32, masked positive."""
+    if not isinstance(code, str):
+        raise TypeError('code must be a string')
+    units = code.encode('utf-16-le', errors='surrogatepass')
+    value = 0
+    for index in range(0, len(units), 2):
+        char = units[index] | (units[index + 1] << 8)
+        value = (value * 131 + char) & 0xffffffff
+    return value & 0x7fffffff
+
+
+def _validate_int_key(shard_key: int) -> None:
+    if type(shard_key) is not int:
+        raise TypeError('integer routing requires an int shard_key, not bool or a numeric string')
+    if shard_key < 0:
+        raise ValueError('negative integer shard keys are not supported')
+
+
+def _validate_hash_key(shard_key: str) -> None:
+    if not isinstance(shard_key, str):
+        raise TypeError('hash routing requires a string shard_key; no implicit conversion is performed')
+
+
+def _table_name(base_table_name: str, value: int, shard_count: int) -> str:
+    if not isinstance(base_table_name, str):
+        raise TypeError('base_table_name must be a string')
+    if not base_table_name.strip():
+        raise ValueError('base_table_name must not be empty')
+    if type(shard_count) is not int:
+        raise TypeError('shard_count must be an integer')
+    if shard_count <= 0:
+        raise ValueError('shard_count must be positive')
+    return f'{base_table_name}{value % shard_count + 1}'
+
+
+def physical_table_name_by_int(base_table_name: str, shard_key: int, shard_count: int) -> str:
+    """Route a nonnegative integer ID directly by modulo, without hashing."""
+    _validate_int_key(shard_key)
+    return _table_name(base_table_name, shard_key, shard_count)
+
+
+def physical_table_name_by_hash(base_table_name: str, shard_key: str, shard_count: int) -> str:
+    """Route a string ID using C#-compatible BKDR hash, then modulo."""
+    _validate_hash_key(shard_key)
+    return _table_name(base_table_name, get_code(shard_key), shard_count)
+
+
+def physical_table_name(base_table_name: str, shard_key: int | str, shard_count: int) -> str:
+    """Deprecated type-dispatch interface; use an explicit algorithm instead."""
+    warnings.warn(
+        'physical_table_name is deprecated; use physical_table_name_by_int or physical_table_name_by_hash',
+        DeprecationWarning, stacklevel=2,
+    )
+    if isinstance(shard_key, str):
+        return physical_table_name_by_hash(base_table_name, shard_key, shard_count)
+    return physical_table_name_by_int(base_table_name, shard_key, shard_count)

ezr_database_sdk-0.1.2.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: ezr-database-sdk
+Version: 0.1.2
+Summary: Synchronous read-only EZR brand database metadata and table routing SDK
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyMySQL>=1.0.0
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=5.0; extra == "release"
+
+# EZR Database SDK
+
+公司内部数据库元数据 SDK，提供同步、只读的 Python 接口：
+
+- 多环境基础库配置，实例间连接隔离。
+- 查询品牌的业务库连接节点和分表配置。
+- 根据整数或字符串 ID 计算物理表名，兼容 C# BKDR Hash。
+
+Python 3.10+，包名 `ezr-database-sdk`，导入名 `ezr_database_sdk`。
+
+## 安装与开发
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e .
+.venv/bin/python -m unittest discover -s tests -v
+```
+
+其他项目在自己的虚拟环境内安装本项目路径或已发布的 wheel：
+
+```bash
+python -m pip install /path/to/ezr-database-sdk
+```
+
+## 快速使用
+
+复制 `database.example.yaml` 为私有的 `database.yaml`，设置选中环境的配置变量：
+
+```python
+from ezr_database_sdk import (
+    EzrDatabaseSDK, physical_table_name_by_int, physical_table_name_by_hash,
+)
+
+with EzrDatabaseSDK.from_yaml("database.yaml", env="qcloud") as sdk:
+    rules = sdk.get_table_shards(brand_id=6812, database="crm")
+    nodes = sdk.get_connection_strings(brand_id=6812, database="crm")
+    # 计算已配置分表规则的表名：
+    # table = sdk.get_physical_table_name_by_int(6812, "crm", "实际逻辑表名", 123)
+    # hashed = sdk.get_physical_table_name_by_hash(6812, "crm", "实际逻辑表名", "123")
+
+# 不连接数据库的纯计算接口：
+assert physical_table_name_by_int("vip", 123, 16) == "vip12"
+assert physical_table_name_by_hash("vip", "123", 16) == "vip3"
+```
+
+两种算法通过方法名显式选择，并严格检查参数类型，不自动转换；整数方法传入字符串、Hash 方法传入整数均会报错。旧的自动分派接口仅保留兼容并标记弃用，迁移说明见使用文档。
+
+连接串含敏感凭据，禁止打印或写入日志。建议每个线程独立创建 SDK 实例，并使用上下文管理器关闭。
+
+详细配置、返回字段、业务库代号、算法兼容及错误处理见 [使用文档](docs/database-sdk.md)。
+
+## 发布
+
+```bash
+.venv/bin/python -m pip install -e '.[release]'
+.venv/bin/python upload.py --dry-run     # 预演，不修改、不上传
+.venv/bin/python upload.py --build-only  # 测试、构建、校验，不改版本、不上传
+# 正式发布（先配置 Twine 凭据；会递增版本并实际上传）：
+# .venv/bin/python upload.py
+```
+
+版本递增规则与 `kxy/framework` 一致，补丁号超过 19 时进位。仓库、凭据和故障恢复见 [发布文档](docs/releasing.md)。
+
+本项目从 `testdata` 工具项目独立迁出，不依赖其脚本、私有配置或数据库凭据。

ezr_database_sdk-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+ezr_database_sdk/__init__.py,sha256=81d8F__i61m4EdDyVU0HAjPDPIVFqNuPy-7fdAK18Go,668
+ezr_database_sdk/client.py,sha256=UIf72EebaADQdm2RswsVOLK3ozYXbEsNffjyW4GD4yo,7984
+ezr_database_sdk/config.py,sha256=YUuAhR7lgf534pzksAqrVoU24lfjVNyoHuloz-w0wFo,2970
+ezr_database_sdk/errors.py,sha256=lvqhraKDIWl0lSuUt7a00Sib01nNl0ZoaS4PtE7dljc,531
+ezr_database_sdk/routing.py,sha256=lbfEKPvXz3NeTkoSF_ugIjCdFmuekTsqxf54XRdWYuE,2624
+ezr_database_sdk-0.1.2.dist-info/METADATA,sha256=mNrTr9SrEj_7Ehng_KLrhMZ0UBujT4M3rVNe5v4OcSw,2981
+ezr_database_sdk-0.1.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+ezr_database_sdk-0.1.2.dist-info/top_level.txt,sha256=ClwqI7R7PyEr_1rCm0LsbqI54vtDAR3uCO9w0A_5jPw,17
+ezr_database_sdk-0.1.2.dist-info/RECORD,,

ezr_database_sdk-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ezr_database_sdk-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+ezr_database_sdk