qrpa 1.0.13__py3-none-any.whl → 1.1.50__py3-none-any.whl

qrpa/time_utils.py

@@ -8,7 +8,6 @@ import calendar
 from datetime import date, datetime, timedelta, timezone
 from typing import Optional, Tuple, List, Union
 
-
 class TimeUtils:
     """时间工具类，提供各种时间相关的静态方法"""
 
@@ -94,6 +93,17 @@ class TimeUtils:
         last_month = today.month - 1 if today.month > 1 else 12
         return last_month
 
+    @staticmethod
+    def get_last_two_month() -> int:
+        """获取上上个月的月份"""
+        today = datetime.today()
+        # 计算上上个月：当前月份减2
+        last_two_month = today.month - 2
+        # 处理跨年情况
+        if last_two_month < 1:
+            last_two_month += 12
+        return last_two_month
+
     # ==================== 日期范围计算 ====================
 
     @staticmethod
@@ -149,6 +159,34 @@ class TimeUtils:
 
         return start_date.strftime(format_str), end_date.strftime(format_str)
 
+    @staticmethod
+    def get_month_first_day(start_from: Optional[str] = None, format_str: str = '%Y-%m-%d') -> str:
+        """
+        获取某月的第一天
+
+        Args:
+            start_from: 参考日期，格式为'YYYY-MM-DD'，默认使用今天
+            format_str: 返回的日期格式，默认是'%Y-%m-%d'
+
+        Returns:
+            指定格式的某月第一天日期字符串
+
+        Example:
+            >>> get_month_first_day('2025-07-02')
+            '2025-07-01'
+        """
+        if start_from:
+            try:
+                base_date = datetime.strptime(start_from, '%Y-%m-%d')
+            except ValueError:
+                raise ValueError("start_from 格式必须是 'YYYY-MM-DD'")
+        else:
+            base_date = datetime.today()
+
+        # 获取当月第一天
+        first_day = base_date.replace(day=1)
+        return first_day.strftime(format_str)
+
     @staticmethod
     def get_past_nth_day(n: int, start_from: Optional[str] = None, format_str: str = '%Y-%m-%d') -> str:
         """
@@ -260,15 +298,27 @@ class TimeUtils:
 
     @staticmethod
     def get_dates_from_first_of_month_to_yesterday() -> List[str]:
-        """获取从本月第一天到昨天的日期列表"""
+        """获取从本月第一天到昨天的日期列表
+        如果今天是本月第一天，则返回上个月的日期列表
+        """
         today = datetime.today()
-        first_day_of_month = today.replace(day=1)
         yesterday = today - timedelta(days=1)
 
-        date_list = []
-        current_date = first_day_of_month
+        # 如果今天是本月第一天，取上个月
+        if today.day == 1:
+            # 找到上个月最后一天
+            last_month_last_day = today - timedelta(days=1)
+            # 上个月第一天
+            first_day_of_last_month = last_month_last_day.replace(day=1)
+            start_date = first_day_of_last_month
+            end_date = last_month_last_day
+        else:
+            start_date = today.replace(day=1)
+            end_date = yesterday
 
-        while current_date <= yesterday:
+        date_list = []
+        current_date = start_date
+        while current_date <= end_date:
             date_list.append(current_date.strftime('%Y-%m-%d'))
             current_date += timedelta(days=1)
 
@@ -288,6 +338,24 @@ class TimeUtils:
 
         return first_day.strftime("%Y-%m-%d"), last_day.strftime("%Y-%m-%d")
 
+    @staticmethod
+    def get_last_two_month_range() -> Tuple[str, str]:
+        """获取上上个月的第一天和最后一天"""
+        today = datetime.today()
+        # 计算上上个月
+        last_two_month = today.month - 2
+        year = today.year
+
+        # 处理跨年情况
+        if last_two_month < 1:
+            last_two_month += 12
+            year -= 1
+
+        first_day = datetime(year, last_two_month, 1)
+        last_day = datetime(year, last_two_month, calendar.monthrange(year, last_two_month)[1])
+
+        return first_day.strftime("%Y-%m-%d"), last_day.strftime("%Y-%m-%d")
+
     @staticmethod
     def get_last_month_range_time_str() -> Tuple[str, str]:
         """获取上个月第一天和最后一天的时间字符串"""
@@ -318,6 +386,17 @@ class TimeUtils:
 
         return start_timestamp, end_timestamp
 
+    @staticmethod
+    def get_year_range_time(year=2024):
+        """获取某一整年的第一天和最后一天的毫秒级时间戳"""
+        first_day = datetime(year, 1, 1, 0, 0, 0)
+        last_day = datetime(year, 12, 31, 0, 0, 0, 0)
+
+        start_timestamp = int(first_day.timestamp() * 1000)
+        end_timestamp = int(last_day.timestamp() * 1000)
+
+        return start_timestamp, end_timestamp
+
     @staticmethod
     def is_in_month(time_str: str, month: int, fmt: str = "%Y-%m-%d") -> bool:
         """
@@ -561,7 +640,7 @@ class TimeUtils:
         return create_time.date() == yesterday.date()
 
     @staticmethod
-    def is_yesterday_date(date_str: str) -> bool:
+    def is_yesterday_date(date_str: str, format="%Y-%m-%d") -> bool:
         """
         判断给定的日期字符串是否是昨天
         
@@ -572,7 +651,7 @@ class TimeUtils:
             如果 date_str 是昨天的日期，返回 True，否则返回 False
         """
         try:
-            create_time = datetime.strptime(date_str, "%Y-%m-%d")
+            create_time = datetime.strptime(date_str, format)
             dt = datetime.now()
         except ValueError:
             raise ValueError("时间字符串格式不正确，请使用正确的格式：'%Y-%m-%d'")
@@ -607,7 +686,6 @@ class TimeUtils:
 
         return mtime_dt.strftime('%Y-%m-%d %H:%M:%S') if to_str else mtime_dt
 
-
 # ==================== 便捷函数 ====================
 # 为了保持向后兼容，提供一些便捷函数
 
@@ -615,197 +693,158 @@ def get_current_date() -> str:
     """获取当前日期，格式为 YYYYMMDD"""
     return TimeUtils.get_current_date()
 
-
 def get_current_datetime() -> str:
     """获取当前日期时间，格式为 YYYYMMDDHHMMSS"""
     return TimeUtils.get_current_datetime()
 
-
 def current_datetime() -> str:
     """获取当前日期时间，格式为 YYYY-MM-DD HH:MM:SS"""
     return TimeUtils.current_datetime()
 
-
 def today_date() -> str:
     """获取今天的日期，格式为 YYYY-MM-DD"""
     return TimeUtils.today_date()
 
-
 def today_date_hour() -> str:
     """获取今天的日期和小时，格式为 YYYY-MM-DD_HH"""
     return TimeUtils.today_date_hour()
 
-
 def get_yesterday(dt: Optional[str] = None) -> str:
     """获取昨天的日期"""
     return TimeUtils.get_yesterday(dt)
 
-
 def tomorrow_date() -> str:
     """获取明天的日期"""
     return TimeUtils.tomorrow_date()
 
-
 def before_yesterday() -> str:
     """获取前天的日期"""
     return TimeUtils.before_yesterday()
 
-
 def get_current_year() -> int:
     """获取当前年份"""
     return TimeUtils.get_current_year()
 
-
 def get_current_month() -> int:
     """获取当前月份"""
     return TimeUtils.get_current_month()
 
-
 def get_last_month() -> int:
     """获取上个月的月份"""
     return TimeUtils.get_last_month()
 
-
 def get_week_num() -> int:
     """获取当前是第几周"""
     return TimeUtils.get_week_num()
 
-
 def get_period() -> str:
     """获取当前时间段（上午/下午/晚上）"""
     return TimeUtils.get_period()
 
-
 def get_period2() -> str:
     """获取当前时间段（AM/PM）"""
     return TimeUtils.get_period2()
 
-
 def get_chinese_weekday(date_str: str) -> str:
     """根据输入的日期字符串返回中文星期几"""
     return TimeUtils.get_chinese_weekday(date_str)
 
-
 def get_weekday_name(date_str: str) -> str:
     """获取中文星期名称（简短格式）"""
     return TimeUtils.get_weekday_name(date_str)
 
-
 def is_in_month(time_str: str, month: int, fmt: str = "%Y-%m-%d") -> bool:
     """判断时间字符串是否在指定月份"""
     return TimeUtils.is_in_month(time_str, month, fmt)
 
-
 def date_trans(d_t: str) -> str:
     """无斜杠日期转成有斜杠日期"""
     return TimeUtils.date_trans(d_t)
 
-
 def is_date_greater_or_equal(date_str: str) -> bool:
     """比较指定日期是否大于或等于今天的日期"""
     return TimeUtils.is_date_greater_or_equal(date_str)
 
-
 def is_yesterday(create_time_str: str, dt: Optional[str] = None) -> bool:
     """判断给定的时间字符串是否是昨天"""
     return TimeUtils.is_yesterday(create_time_str, dt)
 
-
 def is_yesterday_date(date_str: str) -> bool:
     """判断给定的日期字符串是否是昨天"""
     return TimeUtils.is_yesterday_date(date_str)
 
-
 def get_file_mtime(file_path: str, to_str: bool = True, tz_offset: int = 8) -> Union[str, datetime]:
     """获取文件的修改时间"""
     return TimeUtils.get_file_mtime(file_path, to_str, tz_offset)
 
-
 def convert_timestamp_to_str(timestamp_ms: Optional[int]) -> str:
     """将毫秒时间戳转换为字符串"""
     return TimeUtils.convert_timestamp_to_str(timestamp_ms)
 
-
 def convert_timestamp_to_date(timestamp_ms: Union[int, float]) -> str:
     """将毫秒时间戳转换为日期字符串"""
     return TimeUtils.convert_timestamp_to_date(timestamp_ms)
 
-
 def convert_datetime_to_date(datetime_str: str) -> str:
     """将格式为 'YYYY-MM-DD HH:MM:SS' 的时间字符串转换为 'YYYY-MM-DD' 格式的日期字符串"""
     return TimeUtils.convert_datetime_to_date(datetime_str)
 
-
 def get_current_year_range() -> Tuple[str, str]:
     """获取当前年份的开始和结束日期"""
     return TimeUtils.get_current_year_range()
 
-
 def get_start_timestamps(date_str: str) -> int:
     """获取指定日期的开始毫秒时间戳（00:00:00.000）"""
     return TimeUtils.get_start_timestamps(date_str)
 
-
 def get_end_timestamps(date_str: str) -> int:
     """获取指定日期的结束毫秒时间戳（23:59:59.999）"""
     return TimeUtils.get_end_timestamps(date_str)
 
-
 def format_date_cross_platform(date_str: str) -> str:
     """跨平台格式化日期"""
     return TimeUtils.format_date_cross_platform(date_str)
 
-
 def get_past_7_days_range(start_from: Optional[str] = None) -> Tuple[str, str]:
     """获取过去7天的日期范围（包括结束日，共7天）"""
     return TimeUtils.get_past_7_days_range(start_from)
 
-
 def get_past_7_days_range_format(start_from: Optional[str] = None, format_str: str = '%Y-%m-%d') -> Tuple[str, str]:
     """获取过去7天的日期范围（包括结束日，共7天），支持自定义格式"""
     return TimeUtils.get_past_7_days_range_format(start_from, format_str)
 
-
 def get_past_nth_day(n: int, start_from: Optional[str] = None) -> str:
     """获取过去第n天的日期"""
     return TimeUtils.get_past_nth_day(n, start_from)
 
-
 def get_past_n_days_list(n: int, start_from: Optional[str] = None) -> List[str]:
     """获取过去n天的日期列表，从最旧到最近的日期"""
     return TimeUtils.get_past_n_days_list(n, start_from)
 
-
 def get_past_7_days_list(start_from: Optional[str] = None) -> List[str]:
     """获取过去7天的日期列表（不包含 start_from 当天），共7天"""
     return TimeUtils.get_past_7_days_list(start_from)
 
-
 def date_range(start_date: str, end_date: str) -> List[str]:
     """生成两个日期之间的日期列表"""
     return TimeUtils.date_range(start_date, end_date)
 
-
 def get_dates_from_first_of_month_to_yesterday() -> List[str]:
     """获取从本月第一天到昨天的日期列表"""
     return TimeUtils.get_dates_from_first_of_month_to_yesterday()
 
-
 def get_last_month_range() -> Tuple[str, str]:
     """获取上个月的第一天和最后一天"""
     return TimeUtils.get_last_month_range()
 
-
 def get_last_month_range_time_str() -> Tuple[str, str]:
     """获取上个月第一天和最后一天的时间字符串"""
     return TimeUtils.get_last_month_range_time_str()
 
-
 def get_last_month_range_time() -> Tuple[int, int]:
     """获取上个月第一天和最后一天的毫秒级时间戳"""
     return TimeUtils.get_last_month_range_time()
 
-
 # 为了向后兼容，保留一些旧函数名
 def get_past_7_days_range_old() -> Tuple[str, str]:
     """获取过去7天的日期范围（旧版本）"""
@@ -813,7 +852,6 @@ def get_past_7_days_range_old() -> Tuple[str, str]:
     start_date = end_date - timedelta(days=6)  # 往前推6天为开始日期
     return start_date.strftime('%Y-%m-%d'), end_date.strftime('%Y-%m-%d')
 
-
 def get_past_7_days_list_old() -> List[str]:
     """获取过去7天的日期列表（旧版本）"""
     today = datetime.today()
@@ -822,7 +860,6 @@ def get_past_7_days_list_old() -> List[str]:
         for i in range(1, 8)
     ]
 
-
 if __name__ == "__main__":
     # 测试示例
     print(f"当前日期: {today_date()}")