staran 0.3.0__tar.gz → 0.4.1__tar.gz

{staran-0.3.0/staran.egg-info → staran-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: staran
-Version: 0.3.0
+Version: 0.4.1
 Summary: staran - 高性能Python工具库
 Home-page: https://github.com/starlxa/staran
 Author: StarAn
@@ -24,13 +24,25 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# Staran - 智能特征工程工具包
+# Star## ✨ v0.4.1 新特性
+
+- 📋 **独立Schema模块** - 专门的表结构定义和管理模块
+- 📄 **文档自动生成** - 支持Markdown/PDF/HTML格式的技术文档生成
+- 🏢 **业务域支持** - AUM等业务领域的标准表结构定义
+- 🔗 **无缝集成** - Schema与特征工程examples模块完美集成
+- 🛠️ **模块化引擎架构** - 独立的引擎模块，支持Spark、Hive、图灵平台
+- 🔧 **统一接口设计** - 所有引擎提供一致的SQL生成、执行和下载接口
+- 🎯 **继承复用架构** - TuringEngine继承SparkEngine，复用SQL生成逻辑
+- 📦 **清晰代码分离** - SQL生成与平台特定执行逻辑完全分离
+- 🚀 **易于扩展** - 新增数据库支持只需实现BaseEngine接口
+- 📁 **独立引擎存储** - engines/文件夹专门存放所有数据库引擎
+- 🔄 **向后兼容** - 保持对原有API的完全兼容工程工具包
 
 ## � 专为机器学习设计的Python工具包
 
 Staran是一个强大的特征工程和数据处理工具包，提供从数据到模型的完整解决方案。特别针对工银图灵平台优化，让特征工程和模型训练变得前所未有的简单。
 
-## ✨ v0.3.0 新特性
+## ✨ v0.4.1 新特性
 
 - �️ **模块化引擎架构** - 独立的引擎模块，支持Spark、Hive、图灵平台
 - 🔧 **统一接口设计** - 所有引擎提供一致的SQL生成、执行和下载接口
@@ -82,6 +94,40 @@ result = turing_engine.create_table('my_table', sql, execute=True)
 download = turing_engine.download_table_data('my_table', 'file:///nfsHome/data.parquet')
 ```
 
+### Schema模块 - 表结构管理与文档生成
+
+```python
+from staran import get_aum_schemas, export_aum_docs, SchemaDocumentGenerator
+
+# 1. 获取预定义业务表结构
+schemas = get_aum_schemas()  # 获取AUM业务域的所有表结构
+
+for table_type, schema in schemas.items():
+    print(f"{table_type}: {schema.table_name} ({len(schema.fields)}个字段)")
+
+# 2. 生成业务文档
+docs = export_aum_docs('./docs', 'markdown')  # 生成Markdown格式文档
+
+# 3. 自定义文档生成
+generator = SchemaDocumentGenerator()
+doc_path = generator.export_schema_doc(
+    schema=schemas['behavior'],
+    business_domain="AUM",
+    table_type="behavior",
+    format_type="markdown"
+)
+
+# 4. 与特征工程集成
+from staran import create_aum_example, run_aum_example
+
+# 基于预定义schema创建特征工程示例
+example = create_aum_example()
+summary = example.get_summary()  # 获取特征统计信息
+
+# 一键运行完整流程
+results = run_aum_example('202507')  # 生成916个特征
+```
+
 ### 特征工程 - SQL自动生成
 
 ```python
@@ -315,7 +361,12 @@ tomorrow = date.add_days(1)         # 202504 (智能处理)
 
 ```
 staran/
-├── __init__.py                    # 主包入口，v0.3.0功能导出
+├── __init__.py                    # 主包入口，v0.4.1功能导出
+├── schemas/                       # 🆕 表结构定义与文档生成模块
+│   ├── __init__.py               # Schema模块入口
+│   ├── document_generator.py     # 文档生成器 (MD/PDF/HTML)
+│   └── aum/                      # AUM业务域表结构
+│       └── __init__.py           # AUM表结构定义
 ├── engines/                       # 🆕 模块化引擎架构
 │   ├── __init__.py               # 引擎模块入口
 │   ├── base.py                   # BaseEngine抽象基类
@@ -334,7 +385,7 @@ staran/
 │   ├── __init__.py               # 工具模块
 │   └── date.py                   # Date类实现
 ├── setup.py                      # 安装配置  
-├── README.md                     # 本文档 v0.3.0
+├── README.md                     # 本文档 v0.4.1
 └── quick-upload.sh               # 快速部署脚本
 ```
 
@@ -510,4 +561,4 @@ MIT License
 
 ---
 
-**Staran v0.3.0** - 模块化引擎架构，让机器学习特征工程变得前所未有的简单 🌟
+**Staran v0.4.1** - 模块化引擎架构，让机器学习特征工程变得前所未有的简单 🌟

{staran-0.3.0 → staran-0.4.1}/README.md

@@ -1,10 +1,22 @@
-# Staran - 智能特征工程工具包
+# Star## ✨ v0.4.1 新特性
+
+- 📋 **独立Schema模块** - 专门的表结构定义和管理模块
+- 📄 **文档自动生成** - 支持Markdown/PDF/HTML格式的技术文档生成
+- 🏢 **业务域支持** - AUM等业务领域的标准表结构定义
+- 🔗 **无缝集成** - Schema与特征工程examples模块完美集成
+- 🛠️ **模块化引擎架构** - 独立的引擎模块，支持Spark、Hive、图灵平台
+- 🔧 **统一接口设计** - 所有引擎提供一致的SQL生成、执行和下载接口
+- 🎯 **继承复用架构** - TuringEngine继承SparkEngine，复用SQL生成逻辑
+- 📦 **清晰代码分离** - SQL生成与平台特定执行逻辑完全分离
+- 🚀 **易于扩展** - 新增数据库支持只需实现BaseEngine接口
+- 📁 **独立引擎存储** - engines/文件夹专门存放所有数据库引擎
+- 🔄 **向后兼容** - 保持对原有API的完全兼容工程工具包
 
 ## � 专为机器学习设计的Python工具包
 
 Staran是一个强大的特征工程和数据处理工具包，提供从数据到模型的完整解决方案。特别针对工银图灵平台优化，让特征工程和模型训练变得前所未有的简单。
 
-## ✨ v0.3.0 新特性
+## ✨ v0.4.1 新特性
 
 - �️ **模块化引擎架构** - 独立的引擎模块，支持Spark、Hive、图灵平台
 - 🔧 **统一接口设计** - 所有引擎提供一致的SQL生成、执行和下载接口
@@ -56,6 +68,40 @@ result = turing_engine.create_table('my_table', sql, execute=True)
 download = turing_engine.download_table_data('my_table', 'file:///nfsHome/data.parquet')
 ```
 
+### Schema模块 - 表结构管理与文档生成
+
+```python
+from staran import get_aum_schemas, export_aum_docs, SchemaDocumentGenerator
+
+# 1. 获取预定义业务表结构
+schemas = get_aum_schemas()  # 获取AUM业务域的所有表结构
+
+for table_type, schema in schemas.items():
+    print(f"{table_type}: {schema.table_name} ({len(schema.fields)}个字段)")
+
+# 2. 生成业务文档
+docs = export_aum_docs('./docs', 'markdown')  # 生成Markdown格式文档
+
+# 3. 自定义文档生成
+generator = SchemaDocumentGenerator()
+doc_path = generator.export_schema_doc(
+    schema=schemas['behavior'],
+    business_domain="AUM",
+    table_type="behavior",
+    format_type="markdown"
+)
+
+# 4. 与特征工程集成
+from staran import create_aum_example, run_aum_example
+
+# 基于预定义schema创建特征工程示例
+example = create_aum_example()
+summary = example.get_summary()  # 获取特征统计信息
+
+# 一键运行完整流程
+results = run_aum_example('202507')  # 生成916个特征
+```
+
 ### 特征工程 - SQL自动生成
 
 ```python
@@ -289,7 +335,12 @@ tomorrow = date.add_days(1)         # 202504 (智能处理)
 
 ```
 staran/
-├── __init__.py                    # 主包入口，v0.3.0功能导出
+├── __init__.py                    # 主包入口，v0.4.1功能导出
+├── schemas/                       # 🆕 表结构定义与文档生成模块
+│   ├── __init__.py               # Schema模块入口
+│   ├── document_generator.py     # 文档生成器 (MD/PDF/HTML)
+│   └── aum/                      # AUM业务域表结构
+│       └── __init__.py           # AUM表结构定义
 ├── engines/                       # 🆕 模块化引擎架构
 │   ├── __init__.py               # 引擎模块入口
 │   ├── base.py                   # BaseEngine抽象基类
@@ -308,7 +359,7 @@ staran/
 │   ├── __init__.py               # 工具模块
 │   └── date.py                   # Date类实现
 ├── setup.py                      # 安装配置  
-├── README.md                     # 本文档 v0.3.0
+├── README.md                     # 本文档 v0.4.1
 └── quick-upload.sh               # 快速部署脚本
 ```
 
@@ -484,4 +535,4 @@ MIT License
 
 ---
 
-**Staran v0.3.0** - 模块化引擎架构，让机器学习特征工程变得前所未有的简单 🌟
+**Staran v0.4.1** - 模块化引擎架构，让机器学习特征工程变得前所未有的简单 🌟

staran-0.4.1/setup.py

@@ -0,0 +1,31 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="staran",
+    version="0.4.1",
+    description="staran - 高性能Python工具库",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    author="StarAn",
+    author_email="starlxa@icloud.com",
+    url="https://github.com/starlxa/staran",
+    packages=[
+        "staran",
+        "staran.tools",
+        "staran.features",
+        "staran.engines",
+        "staran.examples",
+        "staran.schemas",
+        "staran.schemas.aum",
+    ],
+    install_requires=[
+        "datetime",
+        "calendar",
+        "re",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+    ],
+    python_requires=">=3.7",
+)

{staran-0.3.0 → staran-0.4.1}/staran/__init__.py

@@ -158,9 +158,13 @@ from .features import (
 )
 from .engines import SparkEngine, HiveEngine, TuringEngine, BaseEngine, create_engine, create_turing_engine
 
-# 示例模块
+# Examples模块 - 业务示例
 from .examples import create_aum_example, run_aum_example
 
+# Schemas模块 - 表结构定义与文档生成
+from .schemas import SchemaDocumentGenerator
+from .schemas.aum import get_aum_schemas, export_aum_docs
+
 # 图灵平台引擎 (可选导入，避免依赖问题)
 try:
     from .features import quick_create_and_download
@@ -194,6 +198,10 @@ __all__ = [
     # 示例模块
     'create_aum_example',
     'run_aum_example',
+    # 表结构模块
+    'SchemaDocumentGenerator',
+    'get_aum_schemas',
+    'export_aum_docs',
     # 向后兼容
     'SQLManager',
     'SparkSQLGenerator'
@@ -206,9 +214,9 @@ if _TURING_AVAILABLE:
     ])
 
 # 包信息
-__version__ = '0.2.4'
+__version__ = '0.3.0'
 __author__ = 'Staran Team'
-__description__ = 'Smart feature engineering toolkit with modular engine architecture and examples'
+__description__ = 'Smart feature engineering toolkit with schema management, document generation and business examples'
 __license__ = 'MIT'
 
 # 便捷函数示例

staran-0.4.1/staran/engines/__init__.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+数据库引擎模块
+提供统一的数据库引擎接口
+"""
+
+# 基础组件
+from .base import BaseEngine, DatabaseType
+
+# 具体引擎实现
+from .spark import SparkEngine
+from .hive import HiveEngine
+
+# 图灵平台引擎 (可选导入)
+try:
+    from .turing import TuringEngine, create_turing_engine
+    _TURING_AVAILABLE = True
+except ImportError:
+    TuringEngine = None
+    create_turing_engine = None
+    _TURING_AVAILABLE = False
+
+# 便捷创建函数
+def create_engine(engine_type: str, database_name: str, **kwargs) -> BaseEngine:
+    """
+    创建数据库引擎的便捷函数
+    
+    Args:
+        engine_type: 引擎类型 ('spark', 'hive', 'turing')
+        database_name: 数据库名称
+        **kwargs: 其他参数
+        
+    Returns:
+        数据库引擎实例
+    """
+    engine_type = engine_type.lower()
+    
+    if engine_type == 'spark':
+        return SparkEngine(database_name, **kwargs)
+    elif engine_type == 'hive':
+        return HiveEngine(database_name, **kwargs)
+    elif engine_type == 'turing':
+        if not _TURING_AVAILABLE:
+            raise ImportError("TuringEngine不可用，请确保turingPythonLib已安装")
+        return TuringEngine(database_name, **kwargs)
+    else:
+        raise ValueError(f"不支持的引擎类型: {engine_type}")
+
+# 主要导出
+__all__ = [
+    'BaseEngine',
+    'DatabaseType',
+    'SparkEngine',
+    'HiveEngine',
+    'create_engine'
+]
+
+# 如果图灵引擎可用，添加到导出
+if _TURING_AVAILABLE:
+    __all__.extend([
+        'TuringEngine',
+        'create_turing_engine'
+    ])

staran-0.4.1/staran/engines/base.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+数据库引擎基类
+定义统一的SQL生成、执行和数据下载接口
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional, List, Callable
+from enum import Enum
+from datetime import datetime
+
+
+class DatabaseType(Enum):
+    """数据库类型枚举"""
+    SPARK = "spark"
+    HIVE = "hive"
+    MYSQL = "mysql"
+    POSTGRESQL = "postgresql"
+
+
+class BaseEngine(ABC):
+    """
+    数据库引擎基类
+    整合SQL生成、执行和数据下载功能
+    """
+    
+    def __init__(self, database_name: str, sql_executor: Optional[Callable] = None):
+        """
+        初始化引擎
+        
+        Args:
+            database_name: 数据库名称
+            sql_executor: SQL执行器函数 (可选)
+        """
+        self.database_name = database_name
+        self.sql_executor = sql_executor
+        self.execution_history = []
+    
+    @abstractmethod
+    def get_engine_type(self) -> DatabaseType:
+        """获取引擎类型"""
+        pass
+    
+    @abstractmethod
+    def get_engine_name(self) -> str:
+        """获取引擎名称"""
+        pass
+    
+    # ==================== SQL生成方法 ====================
+    
+    @abstractmethod
+    def generate_create_table_sql(self, table_name: str, select_sql: str, 
+                                if_not_exists: bool = True) -> str:
+        """生成创建表的SQL"""
+        pass
+    
+    @abstractmethod
+    def generate_insert_sql(self, table_name: str, select_sql: str) -> str:
+        """生成插入数据的SQL"""
+        pass
+    
+    @abstractmethod
+    def generate_drop_table_sql(self, table_name: str, if_exists: bool = True) -> str:
+        """生成删除表的SQL"""
+        pass
+    
+    def generate_aggregation_sql(self, schema, year: int, month: int, 
+                               aggregation_types: List[str]) -> str:
+        """生成聚合特征SQL (可被子类重写)"""
+        base_table = self.get_full_table_name(schema.table_name)
+        pk_field = schema.primary_key
+        date_field = schema.date_field
+        
+        # 获取可聚合字段
+        agg_fields = [field for field in schema.fields.values() if field.aggregatable]
+        
+        # 构建聚合选择语句
+        select_parts = [pk_field, f"'{year}-{month:02d}-01' as feature_month"]
+        
+        for field in agg_fields:
+            for agg_type in aggregation_types:
+                alias = f"{field.name}_{agg_type}"
+                select_parts.append(f"{agg_type.upper()}({field.name}) as {alias}")
+        
+        sql = f"""
+        SELECT {', '.join(select_parts)}
+        FROM {base_table}
+        WHERE YEAR({date_field}) = {year} 
+          AND MONTH({date_field}) = {month}
+        GROUP BY {pk_field}
+        """
+        
+        return sql.strip()
+    
+    # ==================== SQL执行方法 ====================
+    
+    def execute_sql(self, sql: str, description: str = "") -> Any:
+        """
+        执行SQL语句
+        
+        Args:
+            sql: SQL语句
+            description: 执行描述
+            
+        Returns:
+            执行结果
+        """
+        if self.sql_executor:
+            result = self.sql_executor(sql)
+            self.execution_history.append({
+                'sql': sql,
+                'description': description,
+                'timestamp': datetime.now(),
+                'result': result
+            })
+            return result
+        else:
+            print(f"SQL (未执行): {description or 'SQL语句'}")
+            print(f"  {sql[:100]}...")
+            return None
+    
+    def create_table(self, table_name: str, select_sql: str, 
+                    execute: bool = False) -> Dict[str, Any]:
+        """
+        创建表
+        
+        Args:
+            table_name: 表名
+            select_sql: 选择SQL
+            execute: 是否立即执行
+            
+        Returns:
+            操作结果
+        """
+        full_table_name = self.get_full_table_name(table_name)
+        create_sql = self.generate_create_table_sql(full_table_name, select_sql)
+        
+        result = {
+            'table_name': table_name,
+            'full_table_name': full_table_name,
+            'sql': create_sql,
+            'executed': execute
+        }
+        
+        if execute:
+            exec_result = self.execute_sql(create_sql, f"创建表 {table_name}")
+            result['execution_result'] = exec_result
+            result['status'] = 'success' if exec_result is not None else 'simulated'
+        else:
+            result['status'] = 'prepared'
+        
+        return result
+    
+    # ==================== 数据下载方法 ====================
+    
+    @abstractmethod
+    def download_table_data(self, table_name: str, output_path: str, 
+                          **kwargs) -> Dict[str, Any]:
+        """
+        下载表数据 (子类必须实现)
+        
+        Args:
+            table_name: 表名
+            output_path: 输出路径
+            **kwargs: 其他参数
+            
+        Returns:
+            下载结果
+        """
+        pass
+    
+    def download_query_result(self, sql: str, output_path: str, 
+                            **kwargs) -> Dict[str, Any]:
+        """
+        下载查询结果 (默认实现，子类可重写)
+        
+        Args:
+            sql: 查询SQL
+            output_path: 输出路径
+            **kwargs: 其他参数
+            
+        Returns:
+            下载结果
+        """
+        # 创建临时表然后下载
+        temp_table = f"temp_query_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+        
+        try:
+            # 创建临时表
+            self.create_table(temp_table, sql, execute=True)
+            
+            # 下载数据
+            result = self.download_table_data(temp_table, output_path, **kwargs)
+            
+            # 清理临时表
+            self.drop_table(temp_table, execute=True)
+            
+            return result
+            
+        except Exception as e:
+            return {
+                'status': 'error',
+                'message': f"下载查询结果失败: {str(e)}",
+                'error': str(e)
+            }
+    
+    # ==================== 工具方法 ====================
+    
+    def get_full_table_name(self, table_name: str) -> str:
+        """获取完整的表名（包含数据库名）"""
+        if '.' in table_name:
+            return table_name  # 已经包含数据库名
+        return f"{self.database_name}.{table_name}"
+    
+    def generate_table_name(self, base_name: str, year: int, month: int, 
+                          suffix: str = "raw") -> str:
+        """
+        生成标准化的表名
+        格式: {base_name}_{yyyy}_{MM}_{suffix}
+        """
+        return f"{base_name}_{year}_{month:02d}_{suffix}"
+    
+    def drop_table(self, table_name: str, execute: bool = False) -> Dict[str, Any]:
+        """删除表"""
+        full_table_name = self.get_full_table_name(table_name)
+        drop_sql = self.generate_drop_table_sql(full_table_name)
+        
+        result = {
+            'table_name': table_name,
+            'full_table_name': full_table_name,
+            'sql': drop_sql,
+            'executed': execute
+        }
+        
+        if execute:
+            exec_result = self.execute_sql(drop_sql, f"删除表 {table_name}")
+            result['execution_result'] = exec_result
+            result['status'] = 'success' if exec_result is not None else 'simulated'
+        else:
+            result['status'] = 'prepared'
+        
+        return result
+    
+    def get_execution_history(self) -> List[Dict]:
+        """获取SQL执行历史"""
+        return self.execution_history.copy()
+    
+    def clear_history(self):
+        """清空执行历史"""
+        self.execution_history.clear()
+    
+    def __str__(self):
+        return f"{self.__class__.__name__}(db={self.database_name}, type={self.get_engine_type().value})"