staran 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

staran/__init__.py

@@ -3,19 +3,187 @@
 
 """
 Staran - 简化的Python工具库
-提供日期处理等实用功能，基于Python标准库实现
+=========================
+
+基于Python标准库的轻量级实用工具集，提供日期处理、SQL生成等常用功能。
+
+主要特性：
+- 零依赖：仅基于Python标准库
+- 智能格式：自动记忆输入格式并保持一致性
+- 直观API：符合Python习惯的设计
+- 类型安全：完整的参数验证
+
+工具模块：
+---------
+1. Date工具 - 智能日期处理
+2. SQL工具 - 数据分析SQL生成
+
+快速开始：
+---------
+
+Date工具基本用法::
+
+    from staran import Date
+    
+    # 智能格式记忆
+    date1 = Date('202504')      # 输出: 202504 (年月格式)
+    date2 = Date('20250415')    # 输出: 20250415 (完整格式)
+    date3 = Date(2025, 4, 15)   # 输出: 2025-04-15
+    
+    # 格式保持
+    new_date = date1.add_months(2)  # 输出: 202506 (保持原格式)
+
+SQL工具基本用法::
+
+    from staran import TableSchema, FeatureGenerator
+    
+    # 定义表结构
+    schema = TableSchema('user_behavior')
+    schema.add_primary_key('user_id', 'string')
+    schema.add_date_field('date', 'date')
+    schema.add_field('amount', 'decimal', aggregatable=True)
+    schema.add_field('status', 'string')
+    schema.set_monthly_unique(True)
+    
+    # 生成特征SQL
+    generator = FeatureGenerator(schema)
+    sql = generator.generate_spark_sql()
+    print(sql)
+
+多种输出格式::
+
+    date = Date('202504')
+    
+    print(date)                     # 202504 (默认格式)
+    print(date.format_full())      # 2025-04-01
+    print(date.format_chinese())   # 2025年04月01日
+    print(date.format_compact())   # 20250401
+
+SQL特征生成::
+
+    # 配置特征生成
+    from staran.sql import FeatureConfig
+    
+    config = FeatureConfig()
+    config.set_aggregation_types(['sum', 'avg', 'max'])
+    config.set_mom_months([1, 3])  # 1个月、3个月环比
+    
+    generator = FeatureGenerator(schema, config)
+    generator.print_feature_summary()
+
+日期运算::
+
+    date = Date(2025, 4, 15)
+    
+    # 日期运算
+    tomorrow = date.add_days(1)     # 2025-04-16
+    next_month = date.add_months(1) # 2025-05-15
+    
+    # 日期比较
+    other = Date(2025, 4, 20)
+    diff = other.difference(date)   # 5 (天数差)
+    print(date < other)             # True
+
+创建方式::
+
+    # 多种创建方式
+    today = Date()                  # 今日
+    birthday = Date(1990, 5, 15)    # 指定日期
+    event = Date('20240615')        # 从字符串
+    deadline = Date(year=2024, month=12, day=31)  # 关键字参数
+
+格式化选项::
+
+    date = Date('202504')
+    
+    # 常用格式
+    date.format_default()           # 202504 (默认)
+    date.format_full()              # 2025-04-01 (完整)
+    date.format_year_month()        # 2025-04 (年月)
+    date.format_chinese()           # 2025年04月01日 (中文)
+    date.format_iso()               # 2025-04-01 (ISO)
+    date.format_us()                # 04/01/2025 (美式)
+    date.format_european()          # 01/04/2025 (欧式)
+
+核心功能：
+---------
+Date工具：
+- Date: 智能日期类，支持格式记忆和多种输出
+- 日期运算：add_days(), add_months()
+- 格式化：多种预设格式方法
+- 比较：支持标准比较操作符
+- 转换：to_timestamp(), to_date(), to_datetime()
+- 信息：is_leap_year(), weekday(), days_in_month()
+
+SQL工具：
+- TableSchema: 表结构定义，支持字段类型和特性配置
+- FeatureGenerator: 特征生成器，支持聚合、环比、同比特征
+- SparkSQLGenerator: Spark SQL代码生成
+- 支持每人每月唯一数据的特征工程
+- 可配置的聚合类型和时间窗口
+
+版本信息：
+---------
+- 版本: 1.0.0
+- 许可: MIT
+- 作者: Staran Team
 """
 
 # 导入主要功能
 from .tools import Date
+from .sql import TableSchema, FeatureGenerator, SparkSQLGenerator
 
 # 主要导出
 __all__ = [
-    'Date'
+    'Date',
+    'TableSchema', 
+    'FeatureGenerator',
+    'SparkSQLGenerator'
 ]
 
 # 包信息
 __version__ = '1.0.0'
 __author__ = 'Staran Team'
-__description__ = 'Simple Python utilities based on standard library'
+__description__ = 'Simple Python utilities with smart format memory'
 __license__ = 'MIT'
+
+# 便捷函数示例
+def help_examples():
+    """
+    显示Staran使用示例
+    
+    Returns:
+        None: 打印示例到控制台
+    """
+    print("""
+Staran 使用示例
+===============
+
+1. 基本创建：
+   from staran import Date
+   
+   date1 = Date('202504')      # 202504
+   date2 = Date('20250415')    # 20250415  
+   date3 = Date(2025, 4, 15)   # 2025-04-15
+
+2. 格式保持：
+   date = Date('202504')
+   new_date = date.add_months(2)  # 202506 (保持格式)
+
+3. 多种格式：
+   date.format_full()         # 2025-04-01
+   date.format_chinese()      # 2025年04月01日
+   date.format_compact()      # 20250401
+
+4. 日期运算：
+   date.add_days(30)          # 增加30天
+   date.add_months(2)         # 增加2个月
+   date.difference(other)     # 计算天数差
+
+更多信息请查看: help(Date)
+    """)
+
+# 快捷访问帮助
+def examples():
+    """显示使用示例的快捷方法"""
+    help_examples()

staran/tools/__init__.py

@@ -2,8 +2,31 @@
 # -*- coding: utf-8 -*-
 
 """
-Staran Tools - 简化的工具集合
-提供日期处理等实用功能
+Staran Tools - 工具集合模块
+==========================
+
+提供各种实用工具类和函数：
+
+Date类 - 智能日期处理：
+- 格式记忆：根据输入自动设置默认格式
+- 多种创建方式：支持字符串、参数、关键字等
+- 丰富格式化：提供多种预设输出格式
+- 日期运算：支持天数、月数的加减运算
+- 标准比较：支持日期间的比较操作
+
+示例::
+
+    from staran.tools import Date
+    
+    # 创建日期
+    date = Date('202504')       # 自动记住YYYYMM格式
+    full_date = Date('20250415') # 自动记住YYYYMMDD格式
+    
+    # 运算保持格式
+    next_month = date.add_months(1)  # 输出: 202505
+    
+    # 多种格式输出
+    print(date.format_chinese())     # 2025年04月01日
 """
 
 # 导入date模块的主要类和函数
@@ -17,4 +40,4 @@ __all__ = [
 # 模块信息
 __version__ = '1.0.0'
 __author__ = 'Staran Team'
-__description__ = 'Staran simple tools collection'
+__description__ = 'Staran utilities with smart format memory'

staran/tools/date.py

@@ -22,10 +22,16 @@ class Date:
         - Date('20240615') - 从字符串
         - Date(year=2024, month=6, day=15) - 关键字参数
         """
+        # 默认格式设置
+        self._default_format = '%Y-%m-%d'  # 默认完整日期格式
+        self._input_format_type = 'full'   # 输入格式类型: 'full', 'year_month', 'timestamp', 'today'
+        
         if not args and not kwargs:
             # 无参数 - 今日
             today = datetime.date.today()
             self.year, self.month, self.day = today.year, today.month, today.day
+            self._input_format_type = 'today'
+            self._default_format = '%Y-%m-%d'
         elif len(args) == 1 and isinstance(args[0], str):
             # 字符串参数
             self._init_from_string(args[0])
@@ -33,6 +39,8 @@ class Date:
             # 单个整数参数 - 视为时间戳
             dt = datetime.datetime.fromtimestamp(args[0])
             self.year, self.month, self.day = dt.year, dt.month, dt.day
+            self._input_format_type = 'timestamp'
+            self._default_format = '%Y-%m-%d'
         elif len(args) in [2, 3]:
             # 位置参数
             self._init_from_args(args)
@@ -54,10 +62,14 @@ class Date:
             self.year = int(clean_string[:4])
             self.month = int(clean_string[4:6])
             self.day = 1
+            self._input_format_type = 'year_month'
+            self._default_format = '%Y%m'
         elif len(clean_string) == 8:  # YYYYMMDD
             self.year = int(clean_string[:4])
             self.month = int(clean_string[4:6])
             self.day = int(clean_string[6:8])
+            self._input_format_type = 'full'
+            self._default_format = '%Y%m%d'
         else:
             raise ValueError(f"Date string must be 6 (YYYYMM) or 8 (YYYYMMDD) digits after removing separators, got {len(clean_string)}")
     
@@ -66,8 +78,12 @@ class Date:
         if len(args) == 2:
             self.year, self.month = args
             self.day = 1
+            self._input_format_type = 'year_month'
+            self._default_format = '%Y-%m'
         elif len(args) == 3:
             self.year, self.month, self.day = args
+            self._input_format_type = 'full'
+            self._default_format = '%Y-%m-%d'
         else:
             raise ValueError("Expected 2 or 3 positional arguments")
     
@@ -79,6 +95,14 @@ class Date:
         
         if self.year is None or self.month is None:
             raise ValueError("year and month are required")
+        
+        # 根据是否提供day参数设置格式
+        if 'day' in kwargs:
+            self._input_format_type = 'full'
+            self._default_format = '%Y-%m-%d'
+        else:
+            self._input_format_type = 'year_month'
+            self._default_format = '%Y-%m'
     
     def _validate_date(self):
         """验证日期有效性"""
@@ -112,10 +136,58 @@ class Date:
         """转换为Python datetime.datetime对象"""
         return datetime.datetime(self.year, self.month, self.day)
     
-    def format(self, fmt='%Y-%m-%d'):
-        """格式化日期字符串"""
+    def format(self, fmt=None):
+        """
+        格式化日期字符串
+        如果不指定格式，使用默认格式（根据输入时的格式确定）
+        """
+        if fmt is None:
+            fmt = self._default_format
         return self.to_date().strftime(fmt)
     
+    def format_default(self):
+        """使用默认格式输出（保持输入时的格式风格）"""
+        return self.format()
+    
+    def format_full(self):
+        """完整日期格式: YYYY-MM-DD"""
+        return self.format('%Y-%m-%d')
+    
+    def format_compact(self):
+        """紧凑格式: YYYYMMDD"""
+        return self.format('%Y%m%d')
+    
+    def format_year_month(self):
+        """年月格式: YYYY-MM"""
+        return self.format('%Y-%m')
+    
+    def format_year_month_compact(self):
+        """年月紧凑格式: YYYYMM"""
+        return self.format('%Y%m')
+    
+    def format_chinese(self):
+        """中文格式: YYYY年MM月DD日"""
+        return self.format('%Y年%m月%d日')
+    
+    def format_chinese_short(self):
+        """中文短格式: YYYY年MM月（适用于年月类型）"""
+        if self._input_format_type == 'year_month':
+            return self.format('%Y年%m月')
+        else:
+            return self.format('%Y年%m月%d日')
+    
+    def format_iso(self):
+        """ISO 8601格式: YYYY-MM-DD"""
+        return self.format('%Y-%m-%d')
+    
+    def format_us(self):
+        """美式格式: MM/DD/YYYY"""
+        return self.format('%m/%d/%Y')
+    
+    def format_european(self):
+        """欧式格式: DD/MM/YYYY"""
+        return self.format('%d/%m/%Y')
+    
     def weekday(self):
         """返回星期几（0=Monday, 6=Sunday）"""
         return self.to_date().weekday()
@@ -136,13 +208,30 @@ class Date:
         """返回当年天数"""
         return 366 if self.is_leap_year() else 365
     
+    def get_default_format(self):
+        """获取默认格式字符串"""
+        return self._default_format
+    
+    def get_input_format_type(self):
+        """获取输入格式类型"""
+        return self._input_format_type
+    
+    def set_default_format(self, fmt):
+        """设置新的默认格式"""
+        self._default_format = fmt
+        return self
+    
     def add_days(self, days):
-        """增加天数，返回新的Date对象"""
+        """增加天数，返回新的Date对象，保持原始格式"""
         new_date = self.to_date() + datetime.timedelta(days=days)
-        return Date(new_date.year, new_date.month, new_date.day)
+        result = Date(new_date.year, new_date.month, new_date.day)
+        # 保持原始格式设置
+        result._default_format = self._default_format
+        result._input_format_type = self._input_format_type
+        return result
     
     def add_months(self, months):
-        """增加月数，返回新的Date对象"""
+        """增加月数，返回新的Date对象，保持原始格式"""
         new_month = self.month + months
         new_year = self.year
         
@@ -157,7 +246,11 @@ class Date:
         max_day = calendar.monthrange(new_year, new_month)[1]
         new_day = min(self.day, max_day)
         
-        return Date(new_year, new_month, new_day)
+        result = Date(new_year, new_month, new_day)
+        # 保持原始格式设置
+        result._default_format = self._default_format
+        result._input_format_type = self._input_format_type
+        return result
     
     def difference(self, other):
         """计算与另一个日期的天数差"""
@@ -169,8 +262,8 @@ class Date:
         return (date1 - date2).days
     
     def __str__(self):
-        """字符串表示"""
-        return f"{self.year}-{self.month:02d}-{self.day:02d}"
+        """字符串表示，使用默认格式"""
+        return self.format_default()
     
     def __repr__(self):
         """调试表示"""

staran-0.2.0.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: staran
+Version: 0.2.0
+Summary: staran - 高性能Python工具库
+Home-page: https://github.com/starlxa/staran
+Author: StarAn
+Author-email: starlxa@icloud.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: datetime
+Requires-Dist: calendar
+Requires-Dist: re
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

staran-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+staran/__init__.py,sha256=FdJTZ11EB1R2z70W8FsCSgudpbPE68rMEud19pp8VsU,5045
+staran/tools/__init__.py,sha256=KtudrYnxKD9HZEL4H-mrWlKrmsI3rYjJrLeC9YDTpG4,1054
+staran/tools/date.py,sha256=-QyEMWVx6czMuOIwcV7kR3gBMRVOwb5qevo7GEFSJKE,10488
+staran-0.2.0.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
+staran-0.2.0.dist-info/METADATA,sha256=ReWJRHI_LYkUc4YWsBTsX2cqCA3XKyJgtm65jAPLjOI,634
+staran-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+staran-0.2.0.dist-info/top_level.txt,sha256=NOUZtXSh5oSIEjHrC0lQ9WmoKtD010Q00dghWyag-Zs,7
+staran-0.2.0.dist-info/RECORD,,

staran-0.1.2.dist-info/METADATA

@@ -1,225 +0,0 @@
-Metadata-Version: 2.4
-Name: staran
-Version: 0.1.2
-Summary: staran - 高性能Python工具库
-Home-page: https://github.com/starlxa/staran
-Author: StarAn
-Author-email: starlxa@icloud.com
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: numpy>=1.20
-Requires-Dist: pandas
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# Staran - 简化的Python日期工具库
-
-## 📅 简洁高效的日期处理
-
-Staran是一个基于Python标准库的简洁日期工具库，提供直观易用的API，无需复杂依赖。
-
-## 🚀 快速开始
-
-### 安装
-```bash
-pip install staran
-```
-
-### 基本使用
-
-```python
-from staran import Date, today, from_string
-
-# 创建日期
-today_date = today()                    # 今日
-birthday = Date(1990, 5, 15)           # 指定日期
-event = from_string('20240615')        # 从字符串
-
-print(f"今天是: {today_date}")
-print(f"生日: {birthday}")
-print(f"活动日期: {event}")
-```
-
-## 📖 功能特性
-
-### 1. 多种创建方式
-```python
-from tools.date import Date
-
-# 方式1: 无参数 - 今日
-today = Date()
-
-# 方式2: 指定年月日
-birthday = Date(1990, 5, 15)
-
-# 方式3: 从字符串
-event1 = Date('20240615')      # YYYYMMDD
-event2 = Date('2024-06-15')    # 带分隔符
-monthly = Date('202406')       # YYYYMM (日期默认为1号)
-
-# 方式4: 关键字参数
-deadline = Date(year=2024, month=12, day=31)
-```
-
-### 2. 日期运算
-```python
-date = Date(2024, 6, 15)
-
-# 加减天数
-tomorrow = date.add_days(1)
-last_week = date.add_days(-7)
-
-# 加减月份
-next_month = date.add_months(1)
-last_year = date.add_months(-12)
-
-# 计算日期差
-diff_days = date.difference(Date(2024, 6, 1))  # 14天
-```
-
-### 3. 格式化和转换
-```python
-date = Date(2024, 6, 15)
-
-# 格式化
-print(date.format('%Y-%m-%d'))      # 2024-06-15
-print(date.format('%Y年%m月%d日'))   # 2024年06月15日
-
-# 转换
-timestamp = date.to_timestamp()     # 时间戳
-dt_date = date.to_date()           # datetime.date对象
-dt_datetime = date.to_datetime()    # datetime.datetime对象
-```
-
-### 4. 日期信息
-```python
-date = Date(2024, 6, 15)
-
-# 基本信息
-print(f"是否闰年: {date.is_leap_year()}")      # False
-print(f"星期几: {date.weekday()}")              # 5 (Saturday)
-print(f"当月天数: {date.days_in_month()}")      # 30
-print(f"当年天数: {date.days_in_year()}")       # 365
-```
-
-### 5. 日期比较
-```python
-date1 = Date(2024, 6, 15)
-date2 = Date(2024, 6, 16)
-
-print(date1 < date2)   # True
-print(date1 == Date(2024, 6, 15))  # True
-print(date1 >= date2)  # False
-```
-
-## 🎯 设计理念
-
-### 简洁性
-- 基于Python标准库，无额外依赖
-- 直观的API设计
-- 清晰的错误消息
-
-### 可靠性
-- 完整的日期验证
-- 处理边界情况（如闰年、月末）
-- 标准的Python对象行为
-
-### 实用性
-- 支持常见的日期操作
-- 灵活的创建方式
-- 便捷的格式化选项
-
-## 📁 项目结构
-
-```
-staran/
-├── __init__.py                # 主包入口
-├── setup.py                  # 安装配置
-├── LICENSE                   # MIT许可证
-├── README.md                 # 本文档
-├── test_simple.py            # 功能测试
-└── tools/                    # 核心模块
-    ├── __init__.py           # 工具模块入口
-    └── date/                 # 日期功能
-        ├── __init__.py       # 日期模块入口
-        └── date.py           # Date类实现
-```
-
-## 🧪 测试
-
-```bash
-# 运行测试
-python test_simple.py
-```
-
-预期输出：
-```
-📅 简化Date类测试
-==============================
-1. 基本创建:
-   今日: 2025-07-28
-   指定日期: 2024-06-15
-   从字符串: 2024-06-15
-
-2. 日期操作:
-   明天: 2025-07-29
-   下月: 2025-08-28
-
-3. 时间戳转换:
-   2024-06-15 时间戳: 1718380800.0
-
-4. 格式化:
-   格式化: 2024年06月15日
-
-5. 日期比较:
-   2024-06-15 < 2024-06-16: True
-   2024-06-15 == Date(2024, 6, 15): True
-
-✅ 所有测试通过!
-```
-
-## 📋 API参考
-
-### Date类
-
-#### 构造方法
-- `Date()` - 创建今日日期
-- `Date(year, month, day)` - 指定年月日
-- `Date(date_string)` - 从字符串创建
-- `Date(year=y, month=m, day=d)` - 关键字参数
-
-#### 核心方法
-- `add_days(days)` - 增加/减少天数
-- `add_months(months)` - 增加/减少月数
-- `difference(other)` - 计算日期差
-- `format(fmt)` - 格式化字符串
-- `to_timestamp()` - 转换为时间戳
-- `is_leap_year()` - 判断闰年
-
-#### 便捷函数
-- `today()` - 获取今日
-- `from_string(s)` - 从字符串创建
-- `from_timestamp(ts)` - 从时间戳创建
-
-## 📄 许可证
-
-MIT License - 详见 [LICENSE](LICENSE) 文件
-
-## 🤝 贡献
-
-欢迎提交Issue和Pull Request！
-
----
-
-**Staran** - 让日期处理变得简单 🌟

staran-0.1.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-staran/__init__.py,sha256=wSMdNd2y24sehitRAG7wOaewvcMQGbzWCKf9RMTt-3I,393
-staran/tools/__init__.py,sha256=FHWxsrVTBYoqcZaMgbZacRbDZWliqUN8gsS4F0I_rDQ,348
-staran/tools/date.py,sha256=UNydI8UyxgjcI1FTnLe0efPK_W6xE_xzgo1bhPU4xNM,7181
-staran-0.1.2.dist-info/licenses/LICENSE,sha256=2EmsBIyDCono4iVXNpv5_px9qt2b7hfPq1WuyGVMNP4,1361
-staran-0.1.2.dist-info/METADATA,sha256=VVS6or4C42EOP3_gaZrMT6ZJDBOqJI_PrUCGgA4sPEg,5046
-staran-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-staran-0.1.2.dist-info/top_level.txt,sha256=NOUZtXSh5oSIEjHrC0lQ9WmoKtD010Q00dghWyag-Zs,7
-staran-0.1.2.dist-info/RECORD,,