Feature freq string

borax/calendars/festivals2.py

@@ -30,6 +30,8 @@ class FreqConst:
     YEARLY = 0
     MONTHLY = 1
 
+    LABEL2VAL = {'monthly': 1, 'yearly': 0, 'm': 1, 'y': 0}
+
 
 class FestivalCatalog:
     basic = 'basic'
@@ -460,12 +462,17 @@ class SolarFestival(Festival):
     """
     date_class = date
 
-    def __init__(self, *, day: int, freq: int = FreqConst.YEARLY, month: int = 0, name: str = None):
+    def __init__(self, *, day: int, freq: Union[int, Literal['yearly', 'monthly', 'y', 'm']] = FreqConst.YEARLY,
+                 month: int = 0, name: str = None):
         if day < 0:
             day = -day
             reverse = 1
         else:
             reverse = 0
+        if isinstance(freq, str):
+            freq = FreqConst.LABEL2VAL.get(freq, -1)
+            if freq == -1:
+                raise ValueError('Invalid freq string.')
         super().__init__(name=name, freq=freq, month=month, day=day, reverse=reverse, schema=FestivalSchema.SOLAR)
 
     def _get_description(self) -> str:
@@ -680,13 +687,17 @@ class LunarFestival(Festival):
     """
     date_class = LunarDate
 
-    def __init__(self, *, day: int, freq: int = FreqConst.YEARLY, month: int = 0, leap: int = _IGNORE_LEAP_MONTH,
-                 name: str = None):
+    def __init__(self, *, day: int, freq: Union[int, Literal['yearly', 'monthly', 'y', 'm']] = FreqConst.YEARLY,
+                 month: int = 0, leap: int = _IGNORE_LEAP_MONTH, name: str = None):
         if day < 0:
             day = -day
             reverse = 1
         else:
             reverse = 0
+        if isinstance(freq, str):
+            freq = FreqConst.LABEL2VAL.get(freq, -1)
+            if freq == -1:
+                raise ValueError('Invalid freq string.')
         super().__init__(freq=freq, name=name, month=month, day=day, leap=leap, reverse=reverse,
                          schema=FestivalSchema.LUNAR)
 

docs/changelog.md

@@ -1,5 +1,9 @@
 # 更新日志
 
+## v4.1.1
+
+- `SolarFestival` 和`LunarFestival` 初始化函数 `freq` 参数支持字符串设置（ [ #56](https://github.com/kinegratii/borax/issues/56) ）
+
 ## v4.1.0 (20240131)
 
 > Borax最低python版本要求为python3.9

docs/guides/festivals2.md

@@ -2,6 +2,8 @@
 
 > 模块： `borax.calendars.festivals2`
 
+> Updated in 4.1.1: SolarFestival和LunarFestival的freq参数支持字符串形式。
+
 > Updated in 4.1.0：新增 Festival.code属性。
 
 > Updated in 3.5.6: 星期型节日(WeekFestival)类支持倒数序号。如：“国际麻风节(1月最后一个星期天)”
@@ -161,11 +163,13 @@ class SolarFestival(*, day: int, freq: int = FreqConst.YEARLY, month: int = 0, n
 
 参数定义
 
-| 参数  | 描述                                                         | 取值           |
-| ----- | ------------------------------------------------------------ | -------------- |
-| freq  | 节日频率，“每年”或“每月”，默认“每年”。                       | 0:每年；1:每月 |
-| month | 月份。                                    | 0,1-12         |
-| day   | 日期序号。当month取值0时，表示一年的第几天；否则表示该月的第几天。允许取负值，表示一年/一个月的倒数 第几天。 |                |
+| 参数  | 描述                                                         | 取值                                           |
+| ----- | ------------------------------------------------------------ | ---------------------------------------------- |
+| freq  | 节日频率，“每年”或“每月”，默认“每年”。                       | 0/yearly/y:每年；1/monthly/m:每月 <sup>1</sup> |
+| month | 月份。                                                       | 0,1-12                                         |
+| day   | 日期序号。当month取值0时，表示一年的第几天；否则表示该月的第几天。允许取负值，表示一年/一个月的倒数 第几天。 |                                                |
+
+1. v4.1.1 新增字符串形式。
 
 6种形式定义
 
@@ -186,12 +190,14 @@ class LunarFestival(*, day:int, freq:int=FreqConst.YEARLY, month:int=0, leap:int
 
 参数定义
 
-| 参数  | 描述                                                         | 取值            |
-| ----- | ------------------------------------------------------------ | --------------- |
-| freq  | 节日频率，“每年”或“每月”，默认“每年”。                       | 0:每年；1:每月  |
-| month | 月份。                                                       | 0,1-12          |
-| leap  | 闰月标记。取值参见 `LeapConst`。                             | LeapConst.MIXED |
-| day   | 日期序号。当month未设置时，表示一年的第几天；否则表示该月的第几天。允许取负值，表示一年/一个月的倒数 第几天。 |                 |
+| 参数  | 描述                                                         | 取值                                           |
+| ----- | ------------------------------------------------------------ | ---------------------------------------------- |
+| freq  | 节日频率，“每年”或“每月”，默认“每年”。                       | 0/yearly/y:每年；1/monthly/m:每月 <sup>1</sup> |
+| month | 月份。                                                       | 0,1-12                                         |
+| leap  | 闰月标记。取值参见 `LeapConst`。                             | LeapConst.MIXED                                |
+| day   | 日期序号。当month未设置时，表示一年的第几天；否则表示该月的第几天。允许取负值，表示一年/一个月的倒数 第几天。 |                                                |
+
+1. v4.1.1 新增字符串形式。
 
 ### WeekFestival
 
@@ -386,7 +392,7 @@ Festival.list_days_in_future(end_date=None, reverse: bool = False, count: int =
 Festival.list_days_in_past(end_date=None, reverse: bool = False, count: int = -1) -> List[WrappedDate]
 ```
 
-返回今后时间（[today, end_date]）之间（含起止日期）匹配本 Festival 的日期列表。
+返回过去时间（[today, end_date]）之间（含起止日期）匹配本 Festival 的日期列表。
 
 ### get_one_day
 
@@ -687,7 +693,7 @@ pprint.pprint(days)
 FestivalLibrary.monthdaycalendar(year: int, month: int, firstweekday: int = 0)
 ```
 
-返回二维列表，每一行表示一个星期。逻辑同iter_month_daytuples。
+返回二维列表，每一行表示一个星期。逻辑同`iter_month_daytuples` 。
 
 ### to_csv
 

tests/test_festival2_list.py

@@ -47,6 +47,13 @@ def test_reverse(self):
         self.assertEqual(date(2021, 2, 28), sf2.at(year=2021, month=2))
         self.assertEqual(date(2020, 2, 29), sf2.at(year=2020, month=2))
 
+    def test_freq_string(self):
+        sf = SolarFestival(freq='monthly', day=1)
+        self.assertTrue(sf.is_(date(2024, 2, 1)))
+
+        with self.assertRaises(ValueError):
+            SolarFestival(freq='33', day=1)
+
 
 class WeekFestivalTestCase(unittest.TestCase):
     def test_basic_logic(self):
@@ -136,6 +143,12 @@ def test_monthly(self):
         with self.assertRaises(FestivalError):
             lf.at(year=2021)
 
+    def test_freq_string(self):
+        lf = LunarFestival(freq='m', day=1)
+        self.assertTrue(lf.is_(LunarDate(2024, 1, 1)))
+        with self.assertRaises(ValueError):
+            LunarFestival(freq='xxx', day=1)
+
 
 class CheckFestivalTestCase(unittest.TestCase):
     def test_all_days(self):