staran 0.4.2__py3-none-any.whl → 0.6.0__py3-none-any.whl

staran/tools/document_generator.py

@@ -0,0 +1,350 @@
+"""
+Schema文档生成器
+
+支持根据表结构定义生成多种格式的技术文档：
+- Markdown格式：适合开发团队和版本控制
+- PDF格式：适合正式交付和业务方审阅
+- HTML格式：适合在线查看和分享
+
+主要功能：
+1. 表结构自动解析
+2. 字段信息格式化
+3. 业务含义说明
+4. 技术规范文档
+5. 多格式导出支持
+"""
+
+import os
+from typing import Dict, List, Optional
+from datetime import datetime
+
+
+class SchemaDocumentGenerator:
+    """表结构文档生成器"""
+    
+    def __init__(self):
+        self.template_configs = {
+            'markdown': {
+                'extension': '.md',
+                'header_template': self._get_markdown_header_template(),
+                'field_template': self._get_markdown_field_template(),
+                'footer_template': self._get_markdown_footer_template()
+            },
+            'pdf': {
+                'extension': '.pdf', 
+                'requires_conversion': True,
+                'base_format': 'markdown'  # 先生成MD再转PDF
+            },
+            'html': {
+                'extension': '.html',
+                'header_template': self._get_html_header_template(),
+                'field_template': self._get_html_field_template(),
+                'footer_template': self._get_html_footer_template()
+            }
+        }
+    
+    def export_schema_doc(self, schema, business_domain: str, table_type: str, 
+                         output_dir: str = "./docs", format_type: str = "markdown") -> str:
+        """
+        导出表结构文档
+        
+        Args:
+            schema: TableSchema对象
+            business_domain: 业务域名称 (如: AUM, CRM, RISK)
+            table_type: 表类型 (如: behavior, asset_avg)
+            output_dir: 输出目录
+            format_type: 文档格式 ('markdown', 'pdf', 'html')
+            
+        Returns:
+            生成的文档文件路径
+        """
+        # 确保输出目录存在
+        os.makedirs(output_dir, exist_ok=True)
+        
+        # 生成文件名
+        timestamp = datetime.now().strftime("%Y%m%d")
+        filename = f"{business_domain}_{table_type}_schema_{timestamp}"
+        
+        if format_type.lower() == 'pdf':
+            # PDF格式先生成Markdown再转换
+            md_content = self._generate_markdown_content(schema, business_domain, table_type)
+            md_path = os.path.join(output_dir, f"{filename}.md")
+            
+            with open(md_path, 'w', encoding='utf-8') as f:
+                f.write(md_content)
+            
+            # 转换为PDF (这里可以集成pandoc或其他转换工具)
+            pdf_path = os.path.join(output_dir, f"{filename}.pdf")
+            self._convert_md_to_pdf(md_path, pdf_path)
+            return pdf_path
+            
+        elif format_type.lower() == 'html':
+            # HTML格式
+            html_content = self._generate_html_content(schema, business_domain, table_type)
+            html_path = os.path.join(output_dir, f"{filename}.html")
+            
+            with open(html_path, 'w', encoding='utf-8') as f:
+                f.write(html_content)
+            return html_path
+            
+        else:
+            # 默认Markdown格式
+            md_content = self._generate_markdown_content(schema, business_domain, table_type)
+            md_path = os.path.join(output_dir, f"{filename}.md")
+            
+            with open(md_path, 'w', encoding='utf-8') as f:
+                f.write(md_content)
+            return md_path
+    
+    def _generate_markdown_content(self, schema, business_domain: str, table_type: str) -> str:
+        """生成Markdown格式内容"""
+        content = []
+        
+        # 文档头部
+        content.append(f"# {business_domain} - {table_type.upper()}表结构文档")
+        content.append("")
+        content.append(f"## 基本信息")
+        content.append("")
+        content.append(f"- **表名**: `{schema.table_name}`")
+        content.append(f"- **业务域**: {business_domain}")
+        content.append(f"- **表类型**: {table_type}")
+        content.append(f"- **生成时间**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+        content.append(f"- **月度唯一性**: {'是' if getattr(schema, 'is_monthly_unique', False) else '否'}")
+        content.append("")
+        
+        # 表结构说明
+        content.append("## 表结构说明")
+        content.append("")
+        if hasattr(schema, 'description'):
+            content.append(f"{schema.description}")
+            content.append("")
+        
+        # 主键信息
+        if hasattr(schema, 'primary_key') and schema.primary_key:
+            content.append("### 主键字段")
+            content.append("")
+            content.append(f"- `{schema.primary_key}` (主键)")
+            content.append("")
+        
+        # 日期字段
+        if hasattr(schema, 'date_field') and schema.date_field:
+            content.append("### 日期字段")
+            content.append("")
+            content.append(f"- `{schema.date_field}` (日期字段)")
+            content.append("")
+        
+        # 字段详情表格
+        content.append("## 字段详情")
+        content.append("")
+        content.append("| 字段名 | 数据类型 | 业务含义 | 可聚合 | 备注 |")
+        content.append("|--------|----------|----------|--------|------|")
+        
+        if hasattr(schema, 'fields'):
+            for field_name, field in schema.fields.items():
+                # 简化数据类型显示
+                field_type_str = str(field.field_type) if hasattr(field, 'field_type') else 'string'
+                field_type = field_type_str.replace('FieldType.', '').lower()
+                comment = field.comment if hasattr(field, 'comment') else ''
+                aggregatable = '是' if getattr(field, 'aggregatable', False) else '否'
+                remarks = ''  # 可以从其他地方获取备注
+                
+                content.append(f"| `{field_name}` | {field_type} | {comment} | {aggregatable} | {remarks} |")
+        
+        content.append("")
+        
+        # 业务规则说明
+        content.append("## 业务规则")
+        content.append("")
+        content.append("### 数据更新规则")
+        if getattr(schema, 'is_monthly_unique', False):
+            content.append("- 每人每月一条记录")
+            content.append("- 月末批量更新")
+        else:
+            content.append("- 每人每日一条记录")
+            content.append("- 日终批量更新")
+        content.append("")
+        
+        content.append("### 数据质量要求")
+        content.append("- 主键字段不允许为空")
+        content.append("- 日期字段格式统一为YYYYMMDD")
+        content.append("- 金额字段精度保持2位小数")
+        content.append("- 比例字段取值范围[0,1]")
+        content.append("")
+        
+        # 使用说明
+        content.append("## 使用说明")
+        content.append("")
+        content.append("### 特征工程配置")
+        if table_type == 'behavior':
+            content.append("- 生成原始拷贝特征")
+            content.append("- 生成聚合特征")
+            content.append("- 不生成环比、同比特征")
+        else:
+            content.append("- 生成聚合特征")
+            content.append("- 生成5个月环比特征")
+            content.append("- 生成1年同比特征")
+        content.append("")
+        
+        content.append("### 示例SQL查询")
+        content.append("```sql")
+        content.append(f"-- 查询最新数据")
+        content.append(f"SELECT * FROM {schema.table_name}")
+        content.append(f"WHERE data_dt = (SELECT MAX(data_dt) FROM {schema.table_name})")
+        content.append(f"LIMIT 10;")
+        content.append("```")
+        content.append("")
+        
+        # 文档尾部
+        content.append("---")
+        content.append("*本文档由Staran Schema自动生成*")
+        
+        return "\n".join(content)
+    
+    def _generate_html_content(self, schema, business_domain: str, table_type: str) -> str:
+        """生成HTML格式内容"""
+        # 基础HTML模板，可以根据需要扩展
+        html_content = f"""
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{business_domain} - {table_type.upper()}表结构文档</title>
+    <style>
+        body {{ font-family: 'Microsoft YaHei', Arial, sans-serif; margin: 40px; }}
+        h1, h2, h3 {{ color: #333; }}
+        table {{ border-collapse: collapse; width: 100%; margin: 20px 0; }}
+        th, td {{ border: 1px solid #ddd; padding: 12px; text-align: left; }}
+        th {{ background-color: #f2f2f2; font-weight: bold; }}
+        code {{ background-color: #f4f4f4; padding: 2px 4px; border-radius: 3px; }}
+        .info-table {{ background-color: #f9f9f9; }}
+    </style>
+</head>
+<body>
+    <h1>{business_domain} - {table_type.upper()}表结构文档</h1>
+    
+    <h2>基本信息</h2>
+    <table class="info-table">
+        <tr><th>表名</th><td><code>{schema.table_name}</code></td></tr>
+        <tr><th>业务域</th><td>{business_domain}</td></tr>
+        <tr><th>表类型</th><td>{table_type}</td></tr>
+        <tr><th>生成时间</th><td>{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}</td></tr>
+        <tr><th>月度唯一性</th><td>{'是' if getattr(schema, 'is_monthly_unique', False) else '否'}</td></tr>
+    </table>
+    
+    <h2>字段详情</h2>
+    <table>
+        <thead>
+            <tr>
+                <th>字段名</th>
+                <th>数据类型</th>
+                <th>业务含义</th>
+                <th>可聚合</th>
+                <th>备注</th>
+            </tr>
+        </thead>
+        <tbody>
+"""
+        
+        # 添加字段行
+        if hasattr(schema, 'fields'):
+            for field_name, field in schema.fields.items():
+                # 简化数据类型显示
+                field_type_str = str(field.field_type) if hasattr(field, 'field_type') else 'string'
+                field_type = field_type_str.replace('FieldType.', '').lower()
+                comment = field.comment if hasattr(field, 'comment') else ''
+                aggregatable = '是' if getattr(field, 'aggregatable', False) else '否'
+                remarks = ''  # 可以从其他地方获取备注
+                
+                html_content += f"""
+            <tr>
+                <td><code>{field_name}</code></td>
+                <td>{field_type}</td>
+                <td>{comment}</td>
+                <td>{aggregatable}</td>
+                <td>{remarks}</td>
+            </tr>"""
+        
+        html_content += """
+        </tbody>
+    </table>
+    
+    <hr>
+    <p><em>本文档由Staran Schema自动生成</em></p>
+</body>
+</html>"""
+        
+        return html_content
+    
+    def _convert_md_to_pdf(self, md_path: str, pdf_path: str):
+        """将Markdown转换为PDF (需要安装pandoc或其他转换工具)"""
+        try:
+            import subprocess
+            # 尝试使用pandoc转换
+            subprocess.run([
+                'pandoc', md_path, '-o', pdf_path,
+                '--pdf-engine=xelatex',
+                '--variable=CJKmainfont:Microsoft YaHei'
+            ], check=True)
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            # 如果pandoc不可用，创建一个说明文件
+            with open(pdf_path.replace('.pdf', '_conversion_note.txt'), 'w', encoding='utf-8') as f:
+                f.write(f"PDF转换说明：\\n")
+                f.write(f"原始Markdown文件：{md_path}\\n")
+                f.write(f"如需PDF格式，请安装pandoc工具：\\n")
+                f.write(f"pip install pandoc\\n")
+                f.write(f"或访问：https://pandoc.org/installing.html\\n")
+    
+    def _get_markdown_header_template(self) -> str:
+        return "# {title}\\n\\n## 基本信息\\n\\n"
+    
+    def _get_markdown_field_template(self) -> str:
+        return "| {name} | {type} | {comment} | {aggregatable} |\\n"
+    
+    def _get_markdown_footer_template(self) -> str:
+        return "\\n---\\n*文档生成时间: {timestamp}*\\n"
+    
+    def _get_html_header_template(self) -> str:
+        return "<h1>{title}</h1>\\n<h2>基本信息</h2>\\n"
+    
+    def _get_html_field_template(self) -> str:
+        return "<tr><td>{name}</td><td>{type}</td><td>{comment}</td><td>{aggregatable}</td></tr>\\n"
+    
+    def _get_html_footer_template(self) -> str:
+        return "<hr><p><em>文档生成时间: {timestamp}</em></p>\\n"
+
+
+def export_business_docs(business_domain: str, schemas_dict: Dict, output_dir: str = "./docs", 
+                        format_type: str = "markdown") -> Dict[str, str]:
+    """
+    批量导出业务域表结构文档
+    
+    Args:
+        business_domain: 业务域名称
+        schemas_dict: 表结构字典 {table_type: schema}
+        output_dir: 输出目录
+        format_type: 文档格式
+        
+    Returns:
+        生成的文档文件路径字典
+    """
+    generator = SchemaDocumentGenerator()
+    results = {}
+    
+    for table_type, schema in schemas_dict.items():
+        file_path = generator.export_schema_doc(
+            schema=schema,
+            business_domain=business_domain,
+            table_type=table_type,
+            output_dir=output_dir,
+            format_type=format_type
+        )
+        results[table_type] = file_path
+    
+    return results
+
+
+__all__ = [
+    'SchemaDocumentGenerator',
+    'export_business_docs'
+]

{staran-0.4.2.dist-info → staran-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: staran
-Version: 0.4.2
+Version: 0.6.0
 Summary: staran - 高性能Python工具库
 Home-page: https://github.com/starlxa/staran
 Author: StarAn
@@ -24,7 +24,7 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# Star## ✨ v0.4.2 新特性
+# Star## ✨ v0.6.0 新特性
 
 - 📋 **独立Schema模块** - 专门的表结构定义和管理模块
 - 📄 **文档自动生成** - 支持Markdown/PDF/HTML格式的技术文档生成
@@ -42,7 +42,7 @@ Dynamic: summary
 
 Staran是一个强大的特征工程和数据处理工具包，提供从数据到模型的完整解决方案。特别针对工银图灵平台优化，让特征工程和模型训练变得前所未有的简单。
 
-## ✨ v0.4.2 新特性
+## ✨ v0.6.0 新特性
 
 - �️ **模块化引擎架构** - 独立的引擎模块，支持Spark、Hive、图灵平台
 - 🔧 **统一接口设计** - 所有引擎提供一致的SQL生成、执行和下载接口
@@ -361,7 +361,7 @@ tomorrow = date.add_days(1)         # 202504 (智能处理)
 
 ```
 staran/
-├── __init__.py                    # 主包入口，v0.4.2功能导出
+├── __init__.py                    # 主包入口，v0.6.0功能导出
 ├── schemas/                       # 🆕 表结构定义与文档生成模块
 │   ├── __init__.py               # Schema模块入口
 │   ├── document_generator.py     # 文档生成器 (MD/PDF/HTML)
@@ -385,7 +385,7 @@ staran/
 │   ├── __init__.py               # 工具模块
 │   └── date.py                   # Date类实现
 ├── setup.py                      # 安装配置  
-├── README.md                     # 本文档 v0.4.2
+├── README.md                     # 本文档 v0.6.0
 └── quick-upload.sh               # 快速部署脚本
 ```
 
@@ -561,4 +561,4 @@ MIT License
 
 ---
 
-**Staran v0.4.2** - 模块化引擎架构，让机器学习特征工程变得前所未有的简单 🌟
+**Staran v0.6.0** - 模块化引擎架构，让机器学习特征工程变得前所未有的简单 🌟

{staran-0.4.2.dist-info → staran-0.6.0.dist-info}/RECORD

@@ -1,4 +1,6 @@
-staran/__init__.py,sha256=cBUxN-qmS_Bf8r-8k94VdA-OLvjdRZyxTNfgd-X_AE8,7234
+staran/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+staran/banks/__init__.py,sha256=m4IUdFLXvNtgpmxDhKptCtALyaGkF1-T9hbNqdXczLI,544
+staran/banks/xinjiang_icbc/__init__.py,sha256=Ql3gQFh1h4EwUdU3fePW1chV5iAegxjLWiPxbYa_J80,3131
 staran/engines/__init__.py,sha256=aQCpDxY_JcKlApEsEp2wg_P3IwNDTCFb7OYcLHiPPmk,1627
 staran/engines/base.py,sha256=IIN-QxPsO-q3KmQ3Lz0cB9bs6Oac0Wy5MIF605HrHVw,7969
 staran/engines/hive.py,sha256=-KwZiAvK5cxwnoyYQlqGWrcZkeKhbd8QCX3chpbezd0,5894
@@ -12,13 +14,20 @@ staran/features/engines.py,sha256=kqdS2xjmCVi0Xz1Oc3WaTMIavgAriX8F7VvUgVcpfqo,10
 staran/features/generator.py,sha256=CI1F_PshOvokQJelsqSaVp-SNQpMc-WVmjMQKzgdeLw,23114
 staran/features/manager.py,sha256=2-3Hc3qthtyzwiuQy5QTz6RfhKK3szoylconzI3moc4,5201
 staran/features/schema.py,sha256=FwOfpTcxq4K8zkO3MFNqKPQBp_e8qY-N6gazqm9_lAQ,6067
-staran/schemas/__init__.py,sha256=2RkcWCaIkrOHd37zzRCla0-jNg4cPnc6BGmmW5Vha0Y,652
+staran/models/__init__.py,sha256=VbfrRjmnp8KlFSEZOa-buECAaERptzAnvUUZK9dpgtY,2390
+staran/models/bank_configs.py,sha256=wN3GA_8cb5wevDC-sWRcJ3lMuaHahZVjC85K_t2aQt0,8177
+staran/models/config.py,sha256=fTbZtJq4-ZuCSSd1eW7TkIbEdDyZv2agHJCYnwOCJ_s,8886
+staran/models/daifa_models.py,sha256=J7aqK41NDMDjacsjmxqwyuJfgf1kJx-Kaxj5CGQLISE,13166
+staran/models/registry.py,sha256=Zeey4TtbHtJ40odyZQzOLijyZCmlMBRuniPk_znS2Q8,10223
+staran/models/target.py,sha256=gKTTatxvOJjmE50qD6G6mhlYLuZL3Cvn3FLNbXl1eeU,10531
+staran/schemas/__init__.py,sha256=ztrBlQ3irbgM7gHB_dhiLEX1ZpDX2AAWOeiPnZTe-sk,779
 staran/schemas/document_generator.py,sha256=Mr7TjmKwspqxXnp9DhzZxsRx0l2Bo7MOI8mOxRtgwxU,13600
-staran/schemas/aum/__init__.py,sha256=jVkmJdhHGHdGE4rJ605zsRU2zIQMEHWnlgW2ZQk8AdU,13082
+staran/schemas/aum/__init__.py,sha256=z0cuC6A3z-1cPKMDYrn0wCumjKkpk_0kfqGfW1JNEbc,9815
 staran/tools/__init__.py,sha256=KtudrYnxKD9HZEL4H-mrWlKrmsI3rYjJrLeC9YDTpG4,1054
 staran/tools/date.py,sha256=-QyEMWVx6czMuOIwcV7kR3gBMRVOwb5qevo7GEFSJKE,10488
-staran-0.4.2.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
-staran-0.4.2.dist-info/METADATA,sha256=u8_IU7kGJqbFbKZLXUIgACqklcrSp56UWcawoWAtGtY,18809
-staran-0.4.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-staran-0.4.2.dist-info/top_level.txt,sha256=NOUZtXSh5oSIEjHrC0lQ9WmoKtD010Q00dghWyag-Zs,7
-staran-0.4.2.dist-info/RECORD,,
+staran/tools/document_generator.py,sha256=Mr7TjmKwspqxXnp9DhzZxsRx0l2Bo7MOI8mOxRtgwxU,13600
+staran-0.6.0.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
+staran-0.6.0.dist-info/METADATA,sha256=KTBVO9J_Z20Nya-Mj48lXDTUNjWRfbU9wwo81__y7fk,18809
+staran-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+staran-0.6.0.dist-info/top_level.txt,sha256=NOUZtXSh5oSIEjHrC0lQ9WmoKtD010Q00dghWyag-Zs,7
+staran-0.6.0.dist-info/RECORD,,