libs.utils.timekit module

timekit - datetime 拡張ユーティリティ

  • ExtendedDatetime: 柔軟な初期化と書式変換ができる datetime 拡張クラス

  • ExtendedDatetimeList: ExtendedDatetimeを要素とする日付リストを扱う補助クラス

Examples

>>> from cls.timekit import ExtendedDatetime
>>> t = ExtendedDatetime("2025-04-19 12:34:56")
>>> t.format("ymdhm")
'2025/04/19 12:34'

>>> t.set("2025-05-01 00:00:00")
>>> t.format("sql")
'2025-05-01 00:00:00.000000'

>>> from dateutil.relativedelta import relativedelta
>>> t2 = t + relativedelta(days=93)
>>> t2.format("ymd")
'2025/08/02'

>>> t + {"days": 1, "months": 2}
2025-07-02 00:00:00.000000

>>> ExtendedDatetime.range("今月").format("ymdhm")
['2025/04/01 00:00', '2025/04/30 23:59']

>>> ExtendedDatetime.range("今月").dict_format("ymd", "ja")
{'start': '2025年04月01日', 'end': '2025年04月30日'}

>>> ExtendedDatetime("2025-01-01 01:23:45", hours=-12).range("今年")
[2024-01-01 00:00:00.000000, 2024-12-31 23:59:59.999999]
libs.utils.timekit.DATE_RANGE_MAP: dict[str, DateRangeSpec] = {'all': {'keyword': ['全部'], 'range': <function <lambda>>}, 'first_day': {'keyword': ['最初'], 'range': <function <lambda>>}, 'last_day': {'keyword': ['最後'], 'range': <function <lambda>>}, 'last_month': {'keyword': ['先月', '昨月'], 'range': <function <lambda>>}, 'last_week': {'keyword': ['先週'], 'range': <function <lambda>>}, 'last_year': {'keyword': ['去年', '昨年'], 'range': <function <lambda>>}, 'this_month': {'keyword': ['今月'], 'range': <function <lambda>>}, 'this_week': {'keyword': ['今週'], 'range': <function <lambda>>}, 'this_year': {'keyword': ['今年'], 'range': <function <lambda>>}, 'today': {'keyword': ['今日', '本日', '当日'], 'range': <function <lambda>>}, 'two_months_ago': {'keyword': ['先々月'], 'range': <function <lambda>>}, 'year_before_last': {'keyword': ['一昨年'], 'range': <function <lambda>>}, 'yesterday': {'keyword': ['昨日'], 'range': <function <lambda>>}}

キーワードと日付範囲のマッピングリスト

class libs.utils.timekit.DateRangeSpec

Bases: TypedDict

日付範囲変換キーワード用辞書

keyword: list[str]
range: Callable[[datetime], list[datetime]]
class libs.utils.timekit.Delimiter

Bases: StrEnum

区切り記号

HYPHEN = 'hyphen'

ハイフン(ex %Y-%m-%d )

JAPANESE = 'japanese'

Japanese Style (ex %Y%年m%月d日 )

NUMBER = 'number'

区切り無し (ex %Y%m%d )

SLASH = 'slash'

スラッシュ(ex %Y/%m/%d )

UNDEFINED = ''

未定義

__new__(value)
class libs.utils.timekit.ExtendedDatetime

Bases: object

datetime拡張クラス

AcceptedType: TypeAlias = str | float | datetime.datetime | ForwardRef('ExtendedDatetime')

引数として受け付ける型

  • str: 日付文字列（ISO形式など）

  • float: UNIXタイムスタンプ

  • datetime / ExtendedDatetime: オブジェクトをそのまま利用

DEM

alias of Delimiter

FMT

alias of Format

__init__(value=None, **relativedelta_kwargs)

ExtendedDatetimeの初期化

Parameters:

  • value (AcceptedType, optional) –

    引数. Defaults to None.

    • None: 現在時刻( datetime.now() )で初期化

  • relativedelta_kwargs (dict) – 初期化時にrelativedelta()に渡す引数

static convert(value)

引数の型を判定してdatetimeへ変換

Parameters:

value (AcceptedType) – 変換対象

Raises:

TypeError – str型が変換できない場合

Returns:

変換した型

Return type:

datetime

property dt: datetime

datetime型を返すプロパティ

format(fmt, delimiter=Delimiter.UNDEFINED)

フォーマット変換

Parameters:
Raises:

ValueError – 受け付けない変換形式

Returns:

変換文字列

Return type:

str

classmethod print_range()

指定可能キーワードで取得できる範囲の一覧

Returns:

出力メッセージ

Return type:

str

range(value)

キーワードが示す範囲をリストで返す

Parameters:

value (Union[...]) –

範囲取得キーワード

  • str: スペース区切りで分割してリスト化

  • list: スペース区切りで再分割

  • list[ExtendedDatetime]: リスト化されたExtendedDatetime型

  • ExtendedDatetimeList: ExtendedDatetimeList型

Returns:

日付リスト

Return type:

ExtendedDatetimeList

set(value)

渡された値をdatetime型に変換して保持

Parameters:

value (AcceptedType) – 入力値

Return type:

None

classmethod valid_keywords()

有効なキーワード一覧

Returns:

キーワード一覧

Return type:

list[str]

class libs.utils.timekit.ExtendedDatetimeList

Bases: list

ExtendedDatetimeを要素とする日付リストを扱う補助クラス

class Delimiter

Bases: StrEnum

区切り記号

HYPHEN = 'hyphen'

ハイフン(ex %Y-%m-%d )

JAPANESE = 'japanese'

Japanese Style (ex %Y%年m%月d日 )

NUMBER = 'number'

区切り無し (ex %Y%m%d )

SLASH = 'slash'

スラッシュ(ex %Y/%m/%d )

UNDEFINED = ''

未定義

__new__(value)
dict_format(fmt=Format.SQL, delimiter=Delimiter.UNDEFINED)

全要素にformatを適用し、最小日付と最大日付を辞書で返す

Parameters:

  • fmt (Format, optional) – フォーマット変換. Defaults to “sql”.

  • delimiter (Delimiter, optional) – 区切り記号指定. Defaults to None.

Returns:

生成した辞書

Return type:

dict[str, str]

property end: ExtendedDatetime | None

最大日付を返す。空ならNone。

format(fmt=Format.SQL, delimiter=Delimiter.UNDEFINED)

全要素にformatを適用した文字列リストを返す

Parameters:

  • fmt (Format, optional) – フォーマット変換. Defaults to “sql”.

  • delimiter (Delimiter, optional) – 区切り記号指定. Defaults to None.

Returns:

生成したリスト

Return type:

list[str]

property period: list[ExtendedDatetime | None]

最小値と最大値をリストで返す

property start: ExtendedDatetime | None

最小日付を返す。空ならNone。

class libs.utils.timekit.Format

Bases: StrEnum

フォーマット変換で指定する種類

EXT = 'ext'

ファイル拡張子用( %Y%m%d-%H%M%S )

HM = 'hm'

時分( %H:%M )

HMS = 'hms'

時分秒( %H:%M:%S )

JY = 'jy'
JYM = 'jym'
JYMD = 'jymd'
JYMD_O = 'jymd_o'
JYM_O = 'jym_o'
JY_O = 'jy_o'
SQL = 'sql'

SQLite用フォーマット( %Y-%m-%d %H:%M:%S.%f )

TS = 'ts'

タイムスタンプ

Y = 'y'

年( %Y )

YM = 'ym'

年月( %Y/%m )

YMD = 'ymd'

年月日( %Y/%m/%d )

YMDHM = 'ymdhm'

年月日時分( %Y/%m/%d %H:%M )

YMDHMS = 'ymdhms'

年月日時分秒( %Y/%m/%d %H:%M:%S )

YMD_O = 'ymd_o'
YM_O = 'ym_o'
Y_O = 'y_o'
__new__(value)