libs.utils.timekit

  1"""
  2timekit - datetime 拡張ユーティリティ
  3
  4- `ExtendedDatetime`: 柔軟な初期化と書式変換ができる datetime 拡張クラス
  5- `ExtendedDatetimeList`: ExtendedDatetimeを要素とする日付リストを扱う補助クラス
  6
  7Examples:
  8    >>> from cls.timekit import ExtendedDatetime
  9    >>> t = ExtendedDatetime("2025-04-19 12:34:56")
 10    >>> t.format("ymdhm")
 11    '2025/04/19 12:34'
 12
 13    >>> t.set("2025-05-01 00:00:00")
 14    >>> t.format("sql")
 15    '2025-05-01 00:00:00.000000'
 16
 17    >>> from dateutil.relativedelta import relativedelta
 18    >>> t2 = t + relativedelta(days=93)
 19    >>> t2.format("ymd")
 20    '2025/08/02'
 21
 22    >>> t + {"days": 1, "months": 2}
 23    2025-07-02 00:00:00.000000
 24
 25    >>> ExtendedDatetime.range("今月").format("ymdhm")
 26    ['2025/04/01 00:00', '2025/04/30 23:59']
 27
 28    >>> ExtendedDatetime.range("今月").dict_format("ymd", "ja")
 29    {'start': '2025年04月01日', 'end': '2025年04月30日'}
 30
 31    >>> ExtendedDatetime("2025-01-01 01:23:45", hours=-12).range("今年")
 32    [2024-01-01 00:00:00.000000, 2024-12-31 23:59:59.999999]
 33
 34"""
 35
 36from datetime import datetime
 37from enum import StrEnum
 38from functools import total_ordering
 39from typing import Any, Callable, Optional, TypeAlias, TypedDict, Union
 40
 41from dateutil.relativedelta import MO, SU, relativedelta
 42
 43
 44class Format(StrEnum):
 45    """フォーマット変換で指定する種類"""
 46
 47    TS = "ts"
 48    """タイムスタンプ"""
 49    Y = "y"
 50    """年(%Y)"""
 51    YM = "ym"
 52    """年月(%Y/%m)"""
 53    YMD = "ymd"
 54    """年月日(%Y/%m/%d)"""
 55    YMDHM = "ymdhm"
 56    """年月日時分(%Y/%m/%d %H:%M)"""
 57    YMDHMS = "ymdhms"
 58    """年月日時分秒(%Y/%m/%d %H:%M:%S)"""
 59    HM = "hm"
 60    """時分(%H:%M)"""
 61    HMS = "hms"
 62    """時分秒(%H:%M:%S)"""
 63    SQL = "sql"
 64    """SQLite用フォーマット(%Y-%m-%d %H:%M:%S.%f)"""
 65    EXT = "ext"
 66    """ファイル拡張子用(%Y%m%d-%H%M%S)"""
 67
 68    JY = "jy"
 69    JYM = "jym"
 70    JYMD = "jymd"
 71
 72    JY_O = "jy_o"
 73    JYM_O = "jym_o"
 74    JYMD_O = "jymd_o"
 75
 76    Y_O = "y_o"
 77    YM_O = "ym_o"
 78    YMD_O = "ymd_o"
 79
 80
 81class Delimiter(StrEnum):
 82    """区切り記号"""
 83
 84    SLASH = "slash"
 85    """スラッシュ(ex: %Y/%m/%d)"""
 86    HYPHEN = "hyphen"
 87    """ハイフン(ex: %Y-%m-%d)"""
 88    NUMBER = "number"
 89    """区切り無し (ex: %Y%m%d)"""
 90    JAPANESE = "japanese"
 91    """Japanese Style (ex: %Y%年m%月d日)"""
 92    UNDEFINED = ""
 93    """未定義"""
 94
 95
 96class DateRangeSpec(TypedDict):
 97    """日付範囲変換キーワード用辞書"""
 98
 99    keyword: list[str]
100    range: Callable[[datetime], list[datetime]]
101
102
103DATE_RANGE_MAP: dict[str, DateRangeSpec] = {
104    "today": {
105        "keyword": ["今日", "本日", "当日"],
106        "range": lambda x: [
107            x.replace(hour=0, minute=0, second=0, microsecond=0),
108            x.replace(hour=23, minute=59, second=59, microsecond=999999),
109        ],
110    },
111    "yesterday": {
112        "keyword": ["昨日"],
113        "range": lambda x: [
114            x + relativedelta(days=-1, hour=0, minute=0, second=0, microsecond=0),
115            x + relativedelta(days=-1, hour=23, minute=59, second=59, microsecond=999999),
116        ],
117    },
118    "this_week": {
119        "keyword": ["今週"],
120        "range": lambda x: [
121            x + relativedelta(weekday=MO(-1), hour=0, minute=0, second=0, microsecond=0),
122            x + relativedelta(weekday=SU, hour=23, minute=59, second=59, microsecond=999999),
123        ],
124    },
125    "last_week": {
126        "keyword": ["先週"],
127        "range": lambda x: [
128            x + relativedelta(weekday=MO(-2), hour=0, minute=0, second=0, microsecond=0),
129            x + relativedelta(weekday=SU(-1), hour=23, minute=59, second=59, microsecond=999999),
130        ],
131    },
132    "this_month": {
133        "keyword": ["今月"],
134        "range": lambda x: [
135            x + relativedelta(day=1, hour=0, minute=0, second=0, microsecond=0),
136            x + relativedelta(day=31, hour=23, minute=59, second=59, microsecond=999999),
137        ],
138    },
139    "last_month": {
140        "keyword": ["先月", "昨月"],
141        "range": lambda x: [
142            x + relativedelta(months=-1, day=1, hour=0, minute=0, second=0, microsecond=0),
143            x + relativedelta(months=-1, day=31, hour=23, minute=59, second=59, microsecond=999999),
144        ],
145    },
146    "two_months_ago": {
147        "keyword": ["先々月"],
148        "range": lambda x: [
149            x + relativedelta(months=-2, day=1, hour=0, minute=0, second=0, microsecond=0),
150            x + relativedelta(months=-2, day=31, hour=23, minute=59, second=59, microsecond=999999),
151        ],
152    },
153    "this_year": {
154        "keyword": ["今年"],
155        "range": lambda x: [
156            x + relativedelta(month=1, day=1, hour=0, minute=0, second=0, microsecond=0),
157            x + relativedelta(month=12, day=31, hour=23, minute=59, second=59, microsecond=999999),
158        ],
159    },
160    "last_year": {
161        "keyword": ["去年", "昨年"],
162        "range": lambda x: [
163            x + relativedelta(years=-1, month=1, day=1, hour=0, minute=0, second=0, microsecond=0),
164            x + relativedelta(years=-1, month=12, day=31, hour=23, minute=59, second=59, microsecond=999999),
165        ],
166    },
167    "year_before_last": {
168        "keyword": ["一昨年"],
169        "range": lambda x: [
170            x + relativedelta(years=-2, month=1, day=1, hour=0, minute=0, second=0, microsecond=0),
171            x + relativedelta(years=-2, month=12, day=31, hour=23, minute=59, second=59, microsecond=999999),
172        ],
173    },
174    "first_day": {
175        "keyword": ["最初"],
176        "range": lambda x: [
177            x + relativedelta(year=1900, month=1, day=1, hour=0, minute=0, second=0, microsecond=0),
178        ],
179    },
180    "last_day": {
181        "keyword": ["最後"],
182        "range": lambda x: [
183            x + relativedelta(days=1, hour=23, minute=59, second=59, microsecond=999999),
184        ],
185    },
186    "all": {
187        "keyword": ["全部"],
188        "range": lambda x: [
189            x + relativedelta(year=1900, month=1, day=1, hour=0, minute=0, second=0, microsecond=0),
190            x + relativedelta(days=1, hour=23, minute=59, second=59, microsecond=999999),
191        ],
192    },
193}
194"""キーワードと日付範囲のマッピングリスト"""
195
196
197@total_ordering
198class ExtendedDatetime:
199    """datetime拡張クラス"""
200
201    FMT = Format
202    DEM = Delimiter
203
204    _dt: datetime
205    """操作対象"""
206
207    # 型アノテーション用定数
208    AcceptedType: TypeAlias = Union[str, float, datetime, "ExtendedDatetime"]
209    """引数として受け付ける型
210    - **str**: 日付文字列（ISO形式など）
211    - **float**: UNIXタイムスタンプ
212    - **datetime** / **ExtendedDatetime**: オブジェクトをそのまま利用
213    """
214
215    def __init__(self, value: Optional[AcceptedType] = None, **relativedelta_kwargs: Any):
216        """
217        ExtendedDatetimeの初期化
218
219        Args:
220            value (Optional[AcceptedType], optional): 引数. Defaults to None.
221                - None: 現在時刻(`datetime.now()`)で初期化
222            relativedelta_kwargs (dict): 初期化時にrelativedelta()に渡す引数
223
224        """
225        self._dt = self.convert(value) if value else datetime.now()
226        if relativedelta_kwargs:
227            self._dt += relativedelta(**relativedelta_kwargs)
228
229    def __str__(self) -> str:
230        return self.format(Format.SQL)
231
232    def __repr__(self) -> str:
233        return self.format(Format.SQL)
234
235    def __eq__(self, other: Any) -> bool:
236        if isinstance(other, ExtendedDatetime):
237            return self.dt == other.dt
238        if isinstance(other, datetime):
239            return self.dt == other
240        if isinstance(other, str):
241            return self.format(Format.SQL) == other
242        return NotImplemented
243
244    def __lt__(self, other: Any) -> bool:
245        if isinstance(other, ExtendedDatetime):
246            return self.dt < other.dt
247        if isinstance(other, datetime):
248            return self.dt < other
249        return NotImplemented
250
251    def __add__(self, other: Union[relativedelta, dict[Any, Any]]) -> "ExtendedDatetime":
252        if isinstance(other, dict):
253            delta = relativedelta(**other)
254        elif isinstance(other, relativedelta):
255            delta = other
256        else:
257            raise TypeError("Expected dict or relativedelta")
258
259        return ExtendedDatetime(self._dt + delta)
260
261    def __sub__(self, other: Union[relativedelta, dict[Any, Any]]) -> "ExtendedDatetime":
262        if isinstance(other, dict):
263            delta = relativedelta(**other)
264        elif isinstance(other, relativedelta):
265            delta = other
266        else:
267            raise TypeError("Expected dict or relativedelta")
268
269        return ExtendedDatetime(self._dt - delta)
270
271    def __radd__(self, other: Union[relativedelta, dict[Any, Any]]) -> "ExtendedDatetime":
272        return self.__add__(other)
273
274    def __rsub__(self, other: Union[relativedelta, dict[Any, Any]]) -> "ExtendedDatetime":
275        return self.__sub__(other)
276
277    def __hash__(self) -> int:
278        return hash(self.dt)
279
280    def __getattr__(self, name: str) -> Any:
281        return getattr(self._dt, name)
282
283    @property
284    def dt(self) -> datetime:
285        """datetime型を返すプロパティ"""
286        return self._dt
287
288    @dt.setter
289    def dt(self, value: AcceptedType) -> None:
290        """dtに対するsetter"""
291        self._dt = self.convert(value)
292
293    def set(self, value: AcceptedType) -> None:
294        """
295        渡された値をdatetime型に変換して保持
296
297        Args:
298            value (AcceptedType): 入力値
299
300        """
301        self._dt = self.convert(value)
302
303    def format(self, fmt: Format, delimiter: Delimiter = Delimiter.UNDEFINED) -> str:
304        """
305        フォーマット変換
306
307        Args:
308            fmt (Format): 変換形式
309            delimiter (Delimiter): 区切り
310
311        Raises:
312            ValueError: 受け付けない変換形式
313
314        Returns:
315            str: 変換文字列
316
317        """
318        ret: str
319
320        if fmt.name.startswith("J"):
321            delimiter = Delimiter.JAPANESE
322
323        match fmt:
324            case Format.TS:
325                ret = str(self._dt.timestamp())
326            case Format.Y | Format.JY | Format.Y_O | Format.JY_O:
327                match delimiter:
328                    case Delimiter.JAPANESE:
329                        ret = self._dt.strftime("%Y年")
330                    case _:
331                        ret = self._dt.strftime("%Y")
332            case Format.YM | Format.JYM | Format.YM_O | Format.JYM_O:
333                match delimiter:
334                    case Delimiter.SLASH:
335                        ret = self._dt.strftime("%Y/%m")
336                    case Delimiter.HYPHEN:
337                        ret = self._dt.strftime("%Y-%m")
338                    case Delimiter.JAPANESE:
339                        ret = self._dt.strftime("%Y年%m月")
340                    case Delimiter.NUMBER:
341                        ret = self._dt.strftime("%Y%m")
342                    case _:
343                        ret = self._dt.strftime("%Y/%m")
344            case Format.YMD | Format.JYMD | Format.YMD_O | Format.JYMD_O:
345                match delimiter:
346                    case Delimiter.SLASH:
347                        ret = self._dt.strftime("%Y/%m/%d")
348                    case Delimiter.HYPHEN:
349                        ret = self._dt.strftime("%Y-%m-%d")
350                    case Delimiter.JAPANESE:
351                        ret = self._dt.strftime("%Y年%m月%d日")
352                    case Delimiter.NUMBER:
353                        ret = self._dt.strftime("%Y%m%d")
354                    case _:
355                        ret = self._dt.strftime("%Y/%m/%d")
356            case Format.YMDHM:
357                match delimiter:
358                    case Delimiter.SLASH:
359                        ret = self._dt.strftime("%Y/%m/%d %H:%M")
360                    case Delimiter.HYPHEN:
361                        ret = self._dt.strftime("%Y-%m-%d %H:%M")
362                    case Delimiter.JAPANESE:
363                        ret = self._dt.strftime("%Y年%m月%d日 %H時%M分")
364                    case Delimiter.NUMBER:
365                        ret = self._dt.strftime("%Y%m%d%H%M")
366                    case _:
367                        ret = self._dt.strftime("%Y/%m/%d %H:%M")
368            case Format.YMDHMS:
369                match delimiter:
370                    case Delimiter.SLASH:
371                        ret = self._dt.strftime("%Y/%m/%d %H:%M:%S")
372                    case Delimiter.HYPHEN:
373                        ret = self._dt.strftime("%Y-%m-%d %H:%M:%S")
374                    case Delimiter.JAPANESE:
375                        ret = self._dt.strftime("%Y年%m月%d日 %H時%M分%S秒")
376                    case Delimiter.NUMBER:
377                        ret = self._dt.strftime("%Y%m%d%H%M%S")
378                    case _:
379                        ret = self._dt.strftime("%Y/%m/%d %H:%M:%S")
380            case Format.HM:
381                match delimiter:
382                    case Delimiter.SLASH:
383                        ret = self._dt.strftime("%H:%M")
384                    case Delimiter.HYPHEN:
385                        ret = self._dt.strftime("%H:%M")
386                    case Delimiter.JAPANESE:
387                        ret = self._dt.strftime("%H時%M分")
388                    case Delimiter.NUMBER:
389                        ret = self._dt.strftime("%H%M")
390                    case _:
391                        ret = self._dt.strftime("%H:%M")
392            case Format.HMS:
393                match delimiter:
394                    case Delimiter.SLASH:
395                        ret = self._dt.strftime("%H:%M:%S")
396                    case Delimiter.HYPHEN:
397                        ret = self._dt.strftime("%H:%M:%S")
398                    case Delimiter.JAPANESE:
399                        ret = self._dt.strftime("%H時%M分%S秒")
400                    case Delimiter.NUMBER:
401                        ret = self._dt.strftime("%H%M%S")
402                    case _:
403                        ret = self._dt.strftime("%H:%M:%S")
404            case Format.SQL:
405                match delimiter:
406                    case Delimiter.SLASH:
407                        ret = self._dt.strftime("%Y/%m/%d %H:%M:%S.%f")
408                    case Delimiter.HYPHEN:
409                        ret = self._dt.strftime("%Y-%m-%d %H:%M:%S.%f")
410                    case Delimiter.NUMBER:
411                        ret = self._dt.strftime("%Y%m%d%H%M%S%f")
412                    case _:
413                        ret = self._dt.strftime("%Y-%m-%d %H:%M:%S.%f")
414            case Format.EXT:
415                ret = self._dt.strftime("%Y%m%d-%H%M%S")
416            case _:
417                raise ValueError(f"Unknown format: {fmt}")
418
419        return ret
420
421    def range(
422        self,
423        value: Union[str, list[str], list["ExtendedDatetime"], "ExtendedDatetimeList"],
424    ) -> "ExtendedDatetimeList":
425        """
426        キーワードが示す範囲をリストで返す
427
428        Args:
429            value (Union[...]): 範囲取得キーワード
430                - str: スペース区切りで分割してリスト化
431                - list: スペース区切りで再分割
432                - list[ExtendedDatetime]: リスト化されたExtendedDatetime型
433                - ExtendedDatetimeList: ExtendedDatetimeList型
434
435        Returns:
436            ExtendedDatetimeList: 日付リスト
437
438        """
439        if isinstance(value, str):
440            check_list = value.split()
441        else:
442            check_list = sum([str(x).split() for x in value], [])  # 平坦化
443
444        ret: list[datetime] = []
445        for word in check_list:
446            for _, range_map in DATE_RANGE_MAP.items():
447                if word in range_map["keyword"]:
448                    ret.extend(range_map["range"](self._dt))
449                    break
450            else:
451                try:
452                    try_time = self.convert(str(word))
453                    ret.append(try_time.replace(hour=0, minute=0, second=0, microsecond=0))
454                    ret.append(try_time.replace(hour=23, minute=59, second=59, microsecond=999999))
455                except ValueError:
456                    pass
457
458            continue
459
460        return ExtendedDatetimeList([ExtendedDatetime(x) for x in ret])
461
462    @classmethod
463    def valid_keywords(cls) -> list[str]:
464        """
465        有効なキーワード一覧
466
467        Returns:
468            list[str]: キーワード一覧
469
470        """
471        ret: list[str] = []
472        for _, range_map in DATE_RANGE_MAP.items():
473            ret.extend(range_map["keyword"])
474
475        return ret
476
477    @classmethod
478    def print_range(cls) -> str:
479        """
480        指定可能キーワードで取得できる範囲の一覧
481
482        Returns:
483            str: 出力メッセージ
484
485        """
486        base_instance = cls()
487        ret: str = ""
488
489        for _, val in DATE_RANGE_MAP.items():
490            for label in val["keyword"]:
491                scope = " ～ ".join(base_instance.range(label).format(Format.YMD))
492                ret += f"{label}：{scope}\n"
493
494        return ret.strip()
495
496    @staticmethod
497    def convert(value: AcceptedType) -> datetime:
498        """
499        引数の型を判定してdatetimeへ変換
500
501        Args:
502            value (AcceptedType): 変換対象
503
504        Raises:
505            TypeError: str型が変換できない場合
506
507        Returns:
508            datetime: 変換した型
509
510        """
511        if isinstance(value, ExtendedDatetime):
512            return value.dt
513        if isinstance(value, datetime):
514            return value
515        if isinstance(value, float):
516            return datetime.fromtimestamp(value)
517        if isinstance(value, str):
518            try:
519                return datetime.fromisoformat(value)
520            except ValueError:
521                return datetime.strptime(value, "%Y/%m/%d %H:%M")
522
523        raise TypeError("Unsupported type for datetime conversion")
524
525
526class ExtendedDatetimeList(list):  # type: ignore[type-arg]
527    """ExtendedDatetimeを要素とする日付リストを扱う補助クラス"""
528
529    Delimiter: TypeAlias = Delimiter
530
531    def __add__(self, other: Any) -> "ExtendedDatetimeList":
532        if isinstance(other, dict):
533            return ExtendedDatetimeList([dt + other for dt in self])
534        return NotImplemented
535
536    def __sub__(self, other: Any) -> "ExtendedDatetimeList":
537        if isinstance(other, dict):
538            return ExtendedDatetimeList([dt - other for dt in self])
539        return NotImplemented
540
541    @property
542    def start(self) -> ExtendedDatetime | None:
543        """最小日付を返す。空ならNone。"""
544        return min(self) if self else None
545
546    @property
547    def end(self) -> ExtendedDatetime | None:
548        """最大日付を返す。空ならNone。"""
549        return max(self) if self else None
550
551    @property
552    def period(self) -> list[ExtendedDatetime | None]:
553        """最小値と最大値をリストで返す"""
554        min_dt = min(self) if self else None
555        max_dt = max(self) if self else None
556
557        return [min_dt, max_dt]
558
559    def format(self, fmt: Format = Format.SQL, delimiter: Delimiter = Delimiter.UNDEFINED) -> list[str]:
560        """
561        全要素にformatを適用した文字列リストを返す
562
563        Args:
564            fmt (Format, optional): フォーマット変換. Defaults to "sql".
565            delimiter (Delimiter, optional): 区切り記号指定. Defaults to None.
566
567        Returns:
568            list[str]: 生成したリスト
569
570        """
571        return [dt.format(fmt, delimiter) for dt in self if isinstance(dt, ExtendedDatetime)]
572
573    def dict_format(self, fmt: Format = Format.SQL, delimiter: Delimiter = Delimiter.UNDEFINED) -> dict[str, str]:
574        """
575        全要素にformatを適用し、最小日付と最大日付を辞書で返す
576
577        Args:
578            fmt (Format, optional): フォーマット変換. Defaults to "sql".
579            delimiter (Delimiter, optional): 区切り記号指定. Defaults to None.
580
581        Returns:
582            dict[str, str]: 生成した辞書
583
584        """
585        date_range = [dt for dt in self if isinstance(dt, ExtendedDatetime)]
586
587        if not date_range:
588            return {}
589
590        return {"start": min(date_range).format(fmt, delimiter), "end": max(date_range).format(fmt, delimiter)}