コンテンツにスキップ

pytilpack.python

pytilpack.python

Pythonのユーティリティ集。

本格的な用途にはpydash等の利用も検討する。

SingletonMixin

シングルトンパターンを提供するMixin。

例：

使用例::

class MyConfig(SingletonMixin):
    def __init__(self):
        self.value = "test"

config1 = MyConfig.get_singleton()
config2 = MyConfig.get_singleton()
assert config1 is config2  # 同じインスタンス

MyConfig.reset()
config3 = MyConfig.get_singleton()
assert config1 is not config3  # 新しいインスタンス

__new__(*args, **kwargs)

直接インスタンス化を禁止する。

ソースコード位置： pytilpack/python.py 
424
425
426
427
def __new__(cls, *args: typing.Any, **kwargs: typing.Any) -> typing.Any:
    """直接インスタンス化を禁止する。"""
    del args, kwargs  # noqa
    raise TypeError(f"{cls.__name__}() は直接インスタンス化できません。{cls.__name__}.get_singleton() を使用してください。")

get_singleton() classmethod

シングルトンインスタンスを取得する。

ソースコード位置： pytilpack/python.py 
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
@classmethod
def get_singleton[T](cls: type[T]) -> T:
    """シングルトンインスタンスを取得する。"""
    # ダブルチェックロッキングパターン
    if cls not in SingletonMixin._instances:
        with SingletonMixin._lock:
            if cls not in SingletonMixin._instances:
                # object.__new__() を使ってインスタンスを作成
                instance = object.__new__(cls)
                SingletonMixin._instances[cls] = instance
                # __init__() を初回のみ実行
                if cls not in SingletonMixin._initialized:
                    cls.__init__(instance)  # type: ignore[misc]
                    SingletonMixin._initialized[cls] = True
    return typing.cast(T, SingletonMixin._instances[cls])

reset() classmethod

シングルトンインスタンスをクリアする。

ソースコード位置： pytilpack/python.py 
445
446
447
448
449
450
451
452
@classmethod
def reset(cls) -> None:
    """シングルトンインスタンスをクリアする。"""
    with SingletonMixin._lock:
        if cls in SingletonMixin._instances:
            del SingletonMixin._instances[cls]
        if cls in SingletonMixin._initialized:
            del SingletonMixin._initialized[cls]

deprecated(reason=None)

DeprecationWarningを発生させるデコレーター。

ソースコード位置： pytilpack/python.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def deprecated[**P, R](reason: str | None = None) -> typing.Callable[[typing.Callable[P, R]], typing.Callable[P, R]]:
    """DeprecationWarningを発生させるデコレーター。"""

    def decorator(func: typing.Callable[P, R]) -> typing.Callable[P, R]:
        message = f"{func.__name__} is deprecated."
        if reason:
            message += f" {reason}"

        if inspect.iscoroutinefunction(func):

            @functools.wraps(func)
            async def async_wrapper(*args: P.args, **kwargs: P.kwargs):
                warnings.warn(message, category=DeprecationWarning, stacklevel=2)
                return await func(*args, **kwargs)

            return typing.cast(typing.Callable[P, R], async_wrapper)

        @functools.wraps(func)
        def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
            warnings.warn(message, category=DeprecationWarning, stacklevel=2)
            return func(*args, **kwargs)

        return sync_wrapper

    return decorator

coalesce(iterable, default_value=None) 

coalesce(
    iterable: typing.Iterable[T | None],
    default_value: None = None,
) -> T

coalesce(
    iterable: typing.Iterable[T | None], default_value: T
) -> T

Noneでない最初の要素を取得する。

ソースコード位置： pytilpack/python.py 
52
53
54
55
56
57
def coalesce[T](iterable: typing.Iterable[T | None], default_value: T | None = None) -> T | None:
    """Noneでない最初の要素を取得する。"""
    for item in iterable:
        if item is not None:
            return item
    return default_value

remove_none(iterable)

Noneを除去する。

ソースコード位置： pytilpack/python.py 
60
61
62
def remove_none[T](iterable: typing.Iterable[T | None]) -> list[T]:
    """Noneを除去する。"""
    return [item for item in iterable if item is not None]

find(collection, predicate)

条件を満たす最初の要素を取得する。

ソースコード位置： pytilpack/python.py 
65
66
67
68
69
70
def find[T](collection: typing.Iterable[T], predicate: typing.Callable[[T], bool]) -> T | None:
    """条件を満たす最初の要素を取得する。"""
    for item in collection:
        if predicate(item):
            return item
    return None

find_index(collection, predicate)

条件を満たす最初の要素のインデックスを取得する。

ソースコード位置： pytilpack/python.py 
73
74
75
76
77
78
def find_index[T](collection: typing.Iterable[T], predicate: typing.Callable[[T], bool]) -> int:
    """条件を満たす最初の要素のインデックスを取得する。"""
    for i, item in enumerate(collection):
        if predicate(item):
            return i
    return -1

empty(x)

Noneまたは空の場合にTrueを返す。

関数名はis_null_or_empty等の方が正確であるが、 短く使いたいためemptyとしている。

ソースコード位置： pytilpack/python.py 
81
82
83
84
85
86
87
88
def empty(x: typing.Any) -> bool:
    """Noneまたは空の場合にTrueを返す。

    関数名はis_null_or_empty等の方が正確であるが、
    短く使いたいためemptyとしている。

    """
    return x is None or (isinstance(x, str) and x == "") or (hasattr(x, "__len__") and len(x) == 0)

default(x, default_value)

Noneまたは空の場合にデフォルト値を返す。

関数名はdefault_if_null_or_empty等の方が正確であるが、 短く使いたいためdefaultとしている。

ソースコード位置： pytilpack/python.py 
91
92
93
94
95
96
97
98
def default[T](x: typing.Any, default_value: T) -> T:
    """Noneまたは空の場合にデフォルト値を返す。

    関数名はdefault_if_null_or_empty等の方が正確であるが、
    短く使いたいためdefaultとしている。

    """
    return default_value if empty(x) else x

doc_summary(obj)

docstringの先頭1行分を取得する。

引数：

名前 タイプ デスクリプション デフォルト
obj Any

ドキュメント文字列を取得する対象。

 必須

戻り値：

タイプ デスクリプション
str

docstringの先頭1行分の文字列。取得できなかった場合は""。
ソースコード位置： pytilpack/python.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
def doc_summary(obj: typing.Any) -> str:
    """docstringの先頭1行分を取得する。

    Args:
        obj: ドキュメント文字列を取得する対象。

    Returns:
        docstringの先頭1行分の文字列。取得できなかった場合は""。

    """
    if obj is None:
        return ""
    return obj.__doc__.strip().split("\n", 1)[0] if hasattr(obj, "__doc__") and not empty(obj.__doc__) else ""

class_field_comments(cls)

クラスからクラスフィールド毎のコメントを取得する。

ソースコード位置： pytilpack/python.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def class_field_comments(cls: typing.Any) -> dict[str, str | None]:
    """クラスからクラスフィールド毎のコメントを取得する。"""
    source = inspect.getsource(cls)
    lines = source.splitlines()
    field_comments: dict[str, str | None] = {}
    prev_comment: str | None = None

    comment_pattern = re.compile(r"^\s*#\s*(.*)$")
    field_pattern = re.compile(r"^\s*(\w+)\s*(?:[:=])")

    for line in lines:
        line = line.rstrip()

        # コメント行の場合
        match = comment_pattern.match(line)
        if match:
            if prev_comment is None:
                prev_comment = match.group(1)
            else:
                # 複数行コメントの場合は先頭1行のみ使用する
                pass
            continue

        # クラスフィールド行の場合
        match = field_pattern.match(line)
        if match:
            var_name = match.group(1)
            if (
                var_name not in field_comments  # 上書きしない(先勝ち)
                and prev_comment is not None
            ):
                field_comments[var_name] = prev_comment
                prev_comment = None
        else:
            # コメントでもコードでもない行が出てきたらコメントをリセット
            prev_comment = None

    return field_comments

get_bool(data, key, default_value=False, errors='strict')

辞書またはリストからbool値を取得する。

ソースコード位置： pytilpack/python.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
def get_bool(
    data: list | dict,
    key: str | int | list[str | int],
    default_value: bool = False,
    errors: typing.Literal["strict", "ignore"] = "strict",
) -> bool:
    """辞書またはリストからbool値を取得する。"""
    value = get(data, key, default_value, errors)
    if isinstance(value, bool):
        return value
    if errors == "ignore":
        return default_value
    raise ValueError(f"{_stringify_key(key)} is not bool: {value!r}")

get_int(data, key, default_value=0, errors='strict')

辞書またはリストからint値を取得する。

ソースコード位置： pytilpack/python.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
def get_int(
    data: list | dict,
    key: str | int | list[str | int],
    default_value: int = 0,
    errors: typing.Literal["strict", "ignore"] = "strict",
) -> int:
    """辞書またはリストからint値を取得する。"""
    value = get(data, key, default_value, errors)
    if isinstance(value, int):
        return value
    if errors == "ignore":
        return default_value
    raise ValueError(f"{_stringify_key(key)} is not int: {value!r}")

get_float(data, key, default_value=0.0, errors='strict')

辞書またはリストからfloat値を取得する。

ソースコード位置： pytilpack/python.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
def get_float(
    data: list | dict,
    key: str | int | list[str | int],
    default_value: float = 0.0,
    errors: typing.Literal["strict", "ignore"] = "strict",
) -> float:
    """辞書またはリストからfloat値を取得する。"""
    value = get(data, key, default_value, errors)
    if isinstance(value, float):
        return value
    if errors == "ignore":
        return default_value
    raise ValueError(f"{_stringify_key(key)} is not float: {value!r}")

get_str(data, key, default_value='', errors='strict')

辞書またはリストからstr値を取得する。

ソースコード位置： pytilpack/python.py 
201
202
203
204
205
206
207
208
209
210
211
212
213
def get_str(
    data: list | dict,
    key: str | int | list[str | int],
    default_value: str = "",
    errors: typing.Literal["strict", "ignore"] = "strict",
) -> str:
    """辞書またはリストからstr値を取得する。"""
    value = get(data, key, default_value, errors)
    if isinstance(value, str):
        return value
    if errors == "ignore":
        return default_value
    raise ValueError(f"{_stringify_key(key)} is not str: {value!r}")

get_list(data, key, default_value=None, errors='strict')

辞書またはリストからlist値を取得する。

ソースコード位置： pytilpack/python.py 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
def get_list(
    data: list | dict,
    key: str | int | list[str | int],
    default_value: list | None = None,
    errors: typing.Literal["strict", "ignore"] = "strict",
) -> list:
    """辞書またはリストからlist値を取得する。"""
    if default_value is None:
        default_value = []
    value = get(data, key, default_value, errors)
    if isinstance(value, list):
        return value
    if errors == "ignore":
        return default_value
    raise ValueError(f"{_stringify_key(key)} is not list: {value!r}")

get_dict(data, key, default_value=None, errors='strict')

辞書またはリストからdict値を取得する。

ソースコード位置： pytilpack/python.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
def get_dict(
    data: list | dict,
    key: str | int | list[str | int],
    default_value: dict | None = None,
    errors: typing.Literal["strict", "ignore"] = "strict",
) -> dict:
    """辞書またはリストからdict値を取得する。"""
    if default_value is None:
        default_value = {}
    value = get(data, key, default_value, errors)
    if isinstance(value, dict):
        return value
    if errors == "ignore":
        return default_value
    raise ValueError(f"{_stringify_key(key)} is not dict: {value!r}")

get(data, key, default_value=None, errors='strict', default_if_none=True)

辞書またはリストから値を取得する。

引数：

名前 タイプ デスクリプション デフォルト
data list | dict

取得元の辞書またはリスト。

 必須
key str | int | list[str | int]

取得する値のキー。

 必須
default_value T | None

取得できなかった場合のデフォルト値。

 None
errors Literal['strict', 'ignore']

エラー時の挙動。"strict"で例外を発生させる。"ignore"でデフォルト値を返す。

 'strict'
default_if_none bool

値がNoneの場合にデフォルト値を返すか否か。

 True

戻り値：

タイプ デスクリプション
T | None

取得した値。取得できなかった場合はdefault_value。

発生：

タイプ デスクリプション
ValueError

errors="strict"の場合、キー/インデックスが見つからない場合やNoneの場合に発生。
ソースコード位置： pytilpack/python.py 
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
def get[T](
    data: list | dict,
    key: str | int | list[str | int],
    default_value: T | None = None,
    errors: typing.Literal["strict", "ignore"] = "strict",
    default_if_none: bool = True,
) -> T | None:
    """辞書またはリストから値を取得する。

    Args:
        data: 取得元の辞書またはリスト。
        key: 取得する値のキー。
        default_value: 取得できなかった場合のデフォルト値。
        errors: エラー時の挙動。"strict"で例外を発生させる。"ignore"でデフォルト値を返す。
        default_if_none: 値がNoneの場合にデフォルト値を返すか否か。

    Returns:
        取得した値。取得できなかった場合はdefault_value。

    Raises:
        ValueError: errors="strict"の場合、キー/インデックスが見つからない場合やNoneの場合に発生。

    """
    if not isinstance(key, list):
        key = [key]
    for k in key:
        if isinstance(data, dict):
            if k in data:
                data = data[k]  # type: ignore[assignment]
            else:
                return default_value  # key not found
        elif isinstance(data, list):
            if isinstance(k, int):
                if 0 <= k < len(data):
                    data = data[k]  # type: ignore[assignment]
                else:
                    return default_value  # key not found
            else:
                # key error
                if errors == "strict":
                    raise ValueError(f"{_stringify_key(key)} not found")
                return default_value
        else:
            # data error
            if errors == "strict":
                raise ValueError(f"{_stringify_key(key)} not found")
            return default_value

    # 値がNoneの場合
    if data is None and default_if_none:
        return default_value

    return typing.cast(T, data)

convert(value, target_type, default_value, errors='ignore')

値をTの型に変換する。

引数：

名前 タイプ デスクリプション デフォルト
value Any

変換元の値。

 必須
target_type type[T]

変換先の型。

 必須
default_value T

取得できなかった場合のデフォルト値。

 必須
errors Literal['strict', 'ignore']

エラー時の挙動。"strict"で例外を発生させる。"ignore"でデフォルト値を返す。

 'ignore'

戻り値：

タイプ デスクリプション
T

取得した値。取得できなかった場合はdefault_value。

発生：

タイプ デスクリプション
ValueError

errors="strict"の場合で値の変換に失敗した場合に発生。
ソースコード位置： pytilpack/python.py 
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
def convert[T](
    value: typing.Any,
    target_type: type[T],
    default_value: T,
    errors: typing.Literal["strict", "ignore"] = "ignore",
) -> T:
    """値をTの型に変換する。

    Args:
        value: 変換元の値。
        target_type: 変換先の型。
        default_value: 取得できなかった場合のデフォルト値。
        errors: エラー時の挙動。"strict"で例外を発生させる。"ignore"でデフォルト値を返す。

    Returns:
        取得した値。取得できなかった場合はdefault_value。

    Raises:
        ValueError: errors="strict"の場合で値の変換に失敗した場合に発生。

    """
    if value is None:
        return default_value

    if isinstance(value, target_type):
        return value

    if target_type is bool:
        if isinstance(value, str):
            value = value.lower()
            if value in ("true", "1"):
                return typing.cast(T, True)
            elif value in ("false", "0"):
                return typing.cast(T, False)
            else:
                if errors == "ignore":
                    return default_value
                raise ValueError(f"値の変換に失敗しました: {value!r} to {target_type.__name__}")
        elif isinstance(value, int) and value in (0, 1):
            return typing.cast(T, bool(value))
        else:
            if errors == "ignore":
                return default_value
            raise ValueError(f"値の変換に失敗しました: {value!r} to {target_type.__name__}")

    try:
        # intなどを想定した型変換
        value = target_type(value)  # type: ignore[call-arg]
        return typing.cast(T, value)
    except Exception as e:
        if errors == "ignore":
            return default_value
        raise ValueError(f"値の変換に失敗しました: {value!r} to {target_type.__name__}") from e

convert_or_none(value, target_type, default_value=None, errors='ignore')

値をTの型に変換する。Noneの場合はデフォルト値を返す。

引数：

名前 タイプ デスクリプション デフォルト
value Any

変換元の値。

 必須
target_type type[T]

変換先の型。

 必須
default_value T | None

取得できなかった場合のデフォルト値。

 None
errors Literal['strict', 'ignore']

エラー時の挙動。"strict"で例外を発生させる。"ignore"でデフォルト値を返す。

 'ignore'

戻り値：

タイプ デスクリプション
T | None

取得した値。取得できなかった場合はdefault_value。

発生：

タイプ デスクリプション
ValueError

errors="strict"の場合で値の変換に失敗した場合に発生。
ソースコード位置： pytilpack/python.py 
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
def convert_or_none[T](
    value: typing.Any,
    target_type: type[T],
    default_value: T | None = None,
    errors: typing.Literal["strict", "ignore"] = "ignore",
) -> T | None:
    """値をTの型に変換する。Noneの場合はデフォルト値を返す。

    Args:
        value: 変換元の値。
        target_type: 変換先の型。
        default_value: 取得できなかった場合のデフォルト値。
        errors: エラー時の挙動。"strict"で例外を発生させる。"ignore"でデフォルト値を返す。

    Returns:
        取得した値。取得できなかった場合はdefault_value。

    Raises:
        ValueError: errors="strict"の場合で値の変換に失敗した場合に発生。

    """
    if value is None:
        return default_value
    return convert(value, target_type, default_value, errors)

merge(dst, src)

2つのオブジェクトをマージする。

引数：

名前 タイプ デスクリプション デフォルト
dst Any

マージ先のオブジェクト。

 必須
src Any

マージ元のオブジェクト。

 必須

戻り値：

タイプ デスクリプション
Any

マージされたオブジェクト。
ソースコード位置： pytilpack/python.py 
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
def merge(dst: typing.Any, src: typing.Any) -> typing.Any:
    """2つのオブジェクトをマージする。

    Args:
        dst: マージ先のオブジェクト。
        src: マージ元のオブジェクト。

    Returns:
        マージされたオブジェクト。

    """
    # pydanticモデルの場合はdictに変換
    dst = pydantic_to_dict(dst)
    src = pydantic_to_dict(src)

    # 両方がdictの場合は再帰的にマージ
    if isinstance(dst, dict) and isinstance(src, dict):
        result = dst.copy()
        for key, value in src.items():
            if key in result:
                result[key] = merge(result[key], value)
            else:
                result[key] = value
        return result

    # 両方がリストの場合は結合
    if isinstance(dst, list) and isinstance(src, list):
        return dst + src

    # それ以外の場合はsrcで上書き
    return src

pydantic_to_dict(obj, **kwargs)

pydanticモデルの場合はmodel_dumpでdictに変換する。

ソースコード位置： pytilpack/python.py 
488
489
490
491
492
def pydantic_to_dict(obj: typing.Any, **kwargs) -> typing.Any:
    """pydanticモデルの場合はmodel_dumpでdictに変換する。"""
    if hasattr(obj, "model_dump") and any("pydantic" in base.__module__ for base in obj.__class__.__mro__):
        obj = obj.model_dump(**({"exclude_unset": True} | kwargs))
    return obj