otsutil
よく使う関数やクラスを纏めたライブラリです。
このライブラリは以下の環境で作成・最適化されています。
Windows10/11, Python 3.13.0+
インストール
インストール
pip install otsutil
アップデート
pip install -U otsutil
アンインストール
pip uninstall otsutil
ロギングとセキュリティに関する注意事項
ロギング設定
本ライブラリはPython標準のloggingモジュールを利用しており、パッケージのルートでlogging.NullHandlerが設定されています。
そのため、ライブラリ単体で勝手にログが標準出力等へ出力されることはありません（デフォルトで「サイレント」に動作します）。
ログを確認・収集したい場合は、呼び出し側（アプリケーション側）で適切なハンドラやログレベルを設定してください。
機密データに関する前提
本ライブラリは、一般的なテキスト処理やファイル操作、データ管理を効率化するためのユーティリティです。
デバッグと原因究明を容易にするため、バリデーション失敗時やエラー発生時に、入力されたデータやパスなどの詳細なコンテキストがログや例外メッセージに出力される場合があります。
パスワード、APIキー、トークンなどの機密情報の処理には使用しないでください。
モジュール
以下のモジュールが存在します。
| モジュール名 | 概要 |
|---|---|
| cfg | 定数 |
| classes | スレッドセーフなコンテナやタイマーなどのクラス定義 |
| exceptions | 例外 |
| funcs | ファイル操作や型判定などの便利な関数定義 |
| types | パッケージ全体で共通利用する型ヒント・ジェネリクス共通定義 |
cfgモジュール
cfgモジュールでは以下の定数が定義されています。
| 定数名 | 概要 |
|---|---|
| JST | 日本のタイムゾーン。 |
classesモジュール
classesモジュールでは以下のクラスが定義されています。
| 名称 | 概要 |
|---|---|
| LockableDict | 要素の操作時に threading.RLock を使用するスレッドセーフな dict クラス。with obj: 構文によるコンテキストマネージャに対応し、複数の操作をアトミックに実行可能です。 |
| LockableList | 要素の操作時に threading.RLock を使用するスレッドセーフな list クラス。with obj: 構文によるコンテキストマネージャに対応し、複数の操作をアトミックに実行可能です。 |
| ObjectStore | オブジェクトを pickle + base64 でシリアライズし、ファイルに永続化・管理するクラス。カスタムクラスを保存する場合、そのクラスに __reduce__ を実装することでリスト内の要素なども含め高度な変換・復元が可能です。 |
| OtsuNone / OtsuNoneType | None を返す可能性のある辞書の get デフォルト値などに使用するセンチネルオブジェクト。bool() 判定では False を返します。 |
| Timer | 指定時間の経過判定および待機を行うタイマー。 同期的なブロック待機 ( join) に加え、asyncio による非同期待機 (ajoin) をサポート。for / async for 文で残り時間を yield しながら処理を行うイテレータ機能を持ちます。 |
注意事項・仕様
LockableDict / LockableListのスレッドセーフティ保証範囲
- アトミック性の対象: 各々のメソッド呼び出し（
append,get,pop等）およびwith obj:ブロック内で行う操作がRLockにより保護されます。 - 保証対象外:
with obj:はロック保持範囲を定義するものであり、処理失敗時の自動ロールバック（トランザクション機能）を提供するものではありません。- コンテナから取り出したミュータブルなオブジェクト（例:
dictの値として格納されたlist等）に対する直接変更操作は、コンテナのロック範囲外となります。
ObjectStoreのセキュリティモデル
- pickleの性質:
ObjectStoreは内部でpickleを使用しています。信頼できない第三者が作成・変更したファイルを読み込むと任意コード実行のリスクが存在します。 - 使用上の注意: 信頼できるローカルデータや自身が作成したデータの保存・復元用途に限定してご使用ください。外部ネットワーク経由で受信したデータなどの読み込みには利用しないでください。
Timerの待機・インターバル挙動
- join / ajoin:
span_seconds <= 0の場合は一括スリープ処理を行い、span_seconds > 0の場合はビジーループ防止のため、最小インターバル（0.001秒）を設けてポーリングを行います。 - wiggle_join / awiggle_join: 残り時間の
yield間隔は最小0.001秒に補正され、ビジーループを防ぎます。
exceptionsモジュール
exceptionsモジュールでは以下の例外が定義されています。
| 例外名 | 概要 |
|---|---|
| PathError | パスに関連する例外の基底クラス |
| PathTypeError | パスの形式や型に関連するエラー（PathErrorを継承） |
| ObjectStoreError | ObjectStore関連処理で発生する基底例外クラス |
| ObjectStoreSaveError | オブジェクトの保存に失敗した際に送出される例外（ObjectStoreErrorを継承） |
| ObjectStoreLoadError | オブジェクトの読み込みに失敗した際に送出される例外（ObjectStoreErrorを継承） |
funcsモジュール
funcsモジュールでは以下の関数が定義されています。
| 関数名 | 概要 |
|---|---|
| deduplicate | シーケンスから重複を取り除き、順序を保持したまま元の型（list/tuple）で返す。 |
| get_sub_paths | ディレクトリ内を探索し、ワイルドカードや拡張子による高度なフィルタリングを適用して子パスを一覧取得する。 |
| is_all_type | 反復可能オブジェクトの全ての要素が、指定した型であるか判定する。 |
| is_dict_key_type | dict[K, Any]か検証する。 |
| is_dict_type | dict[K, V]か検証する。 |
| is_dict_value_type | dict[K, V]か検証する。 |
| is_type | オブジェクトが指定した型であるか判定する（None 許容判定などを含む）。 |
| iter_sub_paths | get_sub_pathsのイテレータ版。 |
| load_json | JSON ファイルを読み込む。親ディレクトリがない場合は作成し、ファイルがない場合はデフォルト値を返します。 |
| read_lines | ファイルを1行ずつ読み出すジェネレータ。改行コードの自動除去やエンコーディング指定が可能です。 |
| same_path | パス群が（相対/絶対に関わらず）物理的に同じ場所を指しているか判定する。 |
| save_json | オブジェクトを JSON 形式で保存する。 |
| setup_path | パスを Path オブジェクトとして整備し、必要に応じて親ディレクトリを生成して利用可能な状態にする。 |
| str_to_path | 文字列を pathlib.Path に変換する。 |
| write_lines | 反復可能な文字列データを1行ずつファイルに書き出す。 |
typesモジュール
typesモジュールでは、ジェネリクス構文に対応した以下の型定義がされています。
| 名称 | 概要 |
|---|---|
| ExpectType[T] | isinstance(obj, ExpectType)で使用できる型。 |
| FloatInt | float または int に限定した数値型。 |
| HMSTuple | (時, 分, 秒) のタプル。型は (int, int, float)。 |
| OptPath | pathlib.Path またはNone |
| OptStr | str またはNone。 |
| OptStrPath | pathlib.PathまたはstrまたはNone。 |
| StrPath | pathlib.Path または str。 |
1 maintainer
Metadata
1 maintainer
Release files for otsutil 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| otsutil-2.0.0.tar.gz | 18.5 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| otsutil-2.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 35.6 kB
Release files / otsutil-2.0.0.tar.gz
| Download URL | otsutil-2.0.0.tar.gz |
|---|---|
| Size | 18.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d33189d6d1d4b0b0e4ad8dd60538551a073b7fa8d1c5f44e20c84da09cebac51
|
|
BLAKE2b-256 checksum How to use checksums |
1730f1944bd9d37fddb431b6bc01539968f667a5f9a0e8c7b8e0607b40574484
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.17
|
Release files / otsutil-2.0.0-py3-none-any.whl
| Download URL | otsutil-2.0.0-py3-none-any.whl |
|---|---|
| Size | 17.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a098226e960fd1167d4632804a6c7d6b649e8d1e5c3299064eb8f85e3784cc70
|
|
BLAKE2b-256 checksum How to use checksums |
c11ca6f694b3ab524b769a79ad9db472a29028f319e7f4634d40106077c9995f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.17
|
Security for otsutil 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
