Skip to content

Latest commit

 

History

History
386 lines (340 loc) · 15.4 KB

README_ja.md

File metadata and controls

386 lines (340 loc) · 15.4 KB
Raw

DebugTrace-py

DebugTrace-py は、Pythonのデバッグ時にトレースログを出力するライブラリで、 Python 3.7以降に対応しています。 メソッドの開始箇所に "_ = debugtrace.enter()" を埋め込む事で、開発中のプログラムの実行状況を出力する事ができます。

1. 特徴

  • debugtrace.enter() の呼び出し元のメソッド名、ソースファイル名および行番号を自動的に出力。
  • またそのスコープ終了時に終了ログを出力。
  • メソッドやオブジェクトのネストで、ログを自動的にインデント 。
  • 値の出力で自動的に改行。
  • __str__ メソッドを実装していないクラスのオブジェクトでもリフレクションを使用して内容を出力。
  • debugtrace.iniファイルの設定で、出力内容のカスタマイズが可能。
  • sys.stdout, sys.stderrまたはloggingパッケージを選択して出力可能

2. インストール

pip install debugtrace

3. 使用方法

デバッグ対象および関連する関数またはメソッドに対して以下を行います。

  • 関数またはメソッドの先頭に _ = debugtrace.enter() を挿入する。
  • 必要に応じて変数をログに出力する debugtrace.print('foo', foo) を挿入する。

以下は、DebugTrace-pyを使用したPythonプログラムの例とそれを実行した際のログです。

# readme_example.py
import datetime
import debugtrace

# Contact class
class Contact(object):
    def __init__(self, id: int, firstName: str, lastName: str, birthday: datetime.date) -> None:
        _ = debugtrace.enter(self)
        self.id = id
        self.firstName = firstName
        self.lastName  = lastName
        self.birthday  = birthday

def func2():
    _ = debugtrace.enter()
    contact = [
        Contact(1, 'Akane' , 'Apple', datetime.date(1991, 2, 3)),
        Contact(2, 'Yukari', 'Apple', datetime.date(1992, 3, 4))
    ]
    debugtrace.print('contact', contact)

def func1():
    _ = debugtrace.enter()
    debugtrace.print('Hello, World!')
    func2()

func1()

ログの出力内容:

2024-03-29 18:43:38.112156+0900 DebugTrace-py 1.4.0 on Python 3.12.0
2024-03-29 18:43:38.112209+0900   config file path: <No config file>
2024-03-29 18:43:38.112244+0900   logger: sys.stderr
2024-03-29 18:43:38.112329+0900 
2024-03-29 18:43:38.112367+0900 ______________________________ MainThread #134705475060800 ______________________________
2024-03-29 18:43:38.112384+0900 
2024-03-29 18:43:38.113719+0900 Enter func1 (readme_example.py:22) <- (readme_example.py:26)
2024-03-29 18:43:38.113813+0900 | Hello, World! (readme_example.py:23)
2024-03-29 18:43:38.113907+0900 | Enter func2 (readme_example.py:14) <- (readme_example.py:24)
2024-03-29 18:43:38.114001+0900 | | Enter Contact.__init__ (readme_example.py:7) <- (readme_example.py:16)
2024-03-29 18:43:38.114074+0900 | | Leave Contact.__init__ (readme_example.py:7) duration: 0:00:00.000008
2024-03-29 18:43:38.114166+0900 | | 
2024-03-29 18:43:38.114202+0900 | | Enter Contact.__init__ (readme_example.py:7) <- (readme_example.py:17)
2024-03-29 18:43:38.114240+0900 | | Leave Contact.__init__ (readme_example.py:7) duration: 0:00:00.000007
2024-03-29 18:43:38.114534+0900 | | 
2024-03-29 18:43:38.114574+0900 | | contacts = [
2024-03-29 18:43:38.114596+0900 | |   (__main__.Contact){
2024-03-29 18:43:38.114609+0900 | |     birthday: 1991-02-03, firstName: 'Akane', id: 1, lastName: 'Apple'
2024-03-29 18:43:38.114646+0900 | |   },
2024-03-29 18:43:38.114703+0900 | |   (__main__.Contact){
2024-03-29 18:43:38.114727+0900 | |     birthday: 1992-03-04, firstName: 'Yukari', id: 2, lastName: 'Apple'
2024-03-29 18:43:38.114738+0900 | |   }
2024-03-29 18:43:38.114748+0900 | | ] (readme_example.py:19)
2024-03-29 18:43:38.114778+0900 | | 
2024-03-29 18:43:38.114818+0900 | Leave func2 (readme_example.py:14) duration: 0:00:00.000863
2024-03-29 18:43:38.114859+0900 Leave func1 (readme_example.py:22) duration: 0:00:00.001086

4. 関数

主に以下の関数があります。

関数一覧
名 前説 明
enter 開始ログを出力します。
またコードブロックの終了時に終了ログを出力します。

引数:
invoker (object, optional): 呼び出し元のselfまたはclsを渡します。

使用例:
_ = debugtrace.enter(self)
_ = debugtrace.enter(cls)
_ = debugtrace.enter()
print 変数名と値を出力します。

引数:
name (str): 変数名など
value (object, optional): 出力する値(省力した場合はnameのみを出力)

以下はキーワード引数

force_reflection (bool, optional): Trueの場合、プライベートメンバーを出力する(デフォルト: False)
output_private (bool, optional): Trueの場合、プライベートメンバーを出力する(デフォルト: False)
output_method (bool, optional): Trueの場合、メソッドを出力する(デフォルト: False)
collection_limit (int, optional): list, tuple, dict等の要素の出力数の制限値 (デフォルト: -1)
bytes_limit (int, optional): bytesおよびbytearrayの要素の出力数の制限値 (デフォルト: -1)
string_limit (int, optional): 文字列値の出力文字数の制限値 (デフォルト: -1)
reflection_nest_limit (int, optional): リフレクションのネスト数の制限値 (デフォルト: -1)

使用例:
debugtrace.print('Hellow')
debugtrace.print('foo', foo)
debugtrace.print('foo', foo, force_reflection=True)
debugtrace.print('foos', foos, collection_limit=1024)

5. debugtrace.ini ファイル

DebugTrace-py は、カレントディレクトリにあるdebugtrace.iniファイルを初期化に読み込みます。 セクションは、[debugtrace]です。

debugtrace.iniファイルで以下のオプションを指定できます。

list debugtrace.ini
オプション名説 明デフォルト値
logger debugtraceが使用するロガー
指定可能な値:
stdout - sys.stdoutへ出力
stderr - sys.stderrへ出力
logger - loggingパッケージを使用して出力
file:<ログファイルのパス> - ファイルに直接出力 		stderr
logging_config_file loggingパッケージに指定する設定ファイル名 logging.conf
logging_logger_name loggingパッケージを使用する場合のロガー名 debugtrace
is_enabled 指定可能な値:
False: ログ出力が無効
True: ログ出力が有効 		True
enter_format 関数またはメソッドに入る際に出力するログのフォーマット文字列
{0}: 関数名またはメソッド名
{1}: ファイル名
{2}: 行番号
{3}: 呼び出し元のファイル名
{4}: 呼び出し元の行番号 		Enter {0} ({1}:{2}) <- ({3}:{4})
leave_format 関数またはメソッドを出る際に出力するログのフォーマット文字列
{0}: 関数名またはメソッド名
{1}: ファイル名
{2}: 行番号
{3}: 関数またはメソッドに入ってからの時間 		Leave {0} ({1}:{2}) duration: {3}
thread_boundary_format スレッド境界のログ出力の文字列フォーマット
{0}: スレッド名
{1}: スレッドID 		______________________________ {0} #{1} ______________________________
maximum_indents インデントの最大数 32
indent_string コードのインデント文字列 \s
data_indent_string データのインデント文字列 \s\s
limit_string制限を超えた場合に出力する文字列 ...
non_output_string
(現在未使用)		 値を出力しない場合に代わりに出力する文字列 ...
cyclic_reference_string 循環参照している場合に出力する文字列 *** Cyclic Reference ***
varname_value_separator 変数名と値のセパレータ文字列 \s=\s
key_value_separator 辞書のキーと値および属性名と属性値のセパレータ文字列 :\s
print_suffix_format printメソッドで付加される文字列のフォーマット \s({1}:{2})
count_format list, tuple, dict等の要素数のフォーマット count:{}
minimum_output_count list, tuple, dict等の要素数を出力する最小値 128
length_format 文字列, bytesの要素数のフォーマット length:{}
minimum_output_length 文字列, bytesの要素数を出力する最小値 256
log_datetime_format loggerがStdOutまたはStdErrの場合のログの日時のフォーマット %Y-%m-%d %H:%M:%S.%f%z
maximum_data_output_width データの出力幅の最大値 70
bytes_count_in_line bytesの内容の1行の出力数 16
collection_limit list, tuple, dict等の要素の出力数の制限値 128
bytes_limit bytesおよびbytearrayの要素の出力数の制限値 256
string_limit 文字列値の出力文字数の制限値 256
reflection_nest_limit リフレクションのネスト数の制限値 4

\s はスペースに変換します。

1. ライセンス

MIT License (MIT)

© 2020 Masato Kokubo

7. リリースノート

DebugTrace-py 1.4.0 - 2024/3/31

  • print メソッドは、引数の value を返すようにしました。
  • 以下のプロパティのデフォルト値を変更しました。
プロパティ名 新デフォルト値 旧デフォルト値
minimum_output_count 128 16
minimum_output_length 256 16

DebugTrace-py 1.3.0 - 2023/3/4

  • enter メソッドのログ出力に、呼び出し元のソースファイル名と行番号を追加しました。
  • debugtrace.iniでlogging_levelの設定を廃止し、固定(DEBUG)にしました。
  • debugtrace.iniの設定項目にlog_datetime_formatを追加しました。

DebugTrace-py 1.2.0 - 2022/8/15

  • 開始時のログに実行時のPythonのバージョンを追加しました。
  • スレッドの切り替わりが分かるログを出力するようにしました。
  • 以下のプロパティのデフォルト値を変更しました。
プロパティ名 新デフォルト値 旧デフォルト値
minimum_output_count 16 5
minimum_output_length 16 5
collection_limit 128 512
bytes_limit 256 8192
string_limit 256 8192

DebugTrace-py 1.1.0 - 2021/11/28

  • __str__ または __repr__ を実装しているクラスのオブジェクトを出力するとエラーになる不具合を修正しました。
  • tuple, set, dict のデータ型を出力しないようにしました。
    (1, 2, 3) ← (tuple)(1, 2, 3)
    (1,) ← (tuple)(1)
    () ← (tuple)()
    {1, 2, 3} ← (set){1, 2, 3}
    {} ← (set){}
    {1: 'A', 2: 'B', 3; 'C'} ← (dict){1: 'A', 2: 'B', 3; 'C'}
    {:} ← (dict){}

DebugTrace-py 1.0.3 - 2021/8/12

  • データ出力の改行処理を改善

DebugTrace-py 1.0.2 - 2020/11/29

  • 開始時のメッセージの変更 ('DebugTrace-py ...' <- 'DebugTrace-python ...')

DebugTrace-py 1.0.1 - 2020/7/19

  • データ出力の改行処理を改善

DebugTrace-py 1.0.0 - 2020/5/26

  • 最初のリリース

© 2020 Masato Kokubo