# `trace` — Trace or track Python statement execution

Вихідний код: Lib/trace.py

The `trace` module allows you to trace program execution, generate annotated statement coverage listings, print caller/callee relationships and list functions executed during a program run. It can be used in another program or from the command line.

Дивись також

Coverage.py

  Популярний сторонній інструмент покриття, який забезпечує виведення HTML разом із розширеними функціями, такими як покриття гілок.

## Використання командного рядка

The `trace` module can be invoked from the command line. It can be as simple as

    python -m trace --count -C . somefile.py ...

Вищезазначене виконає `somefile.py` і створить анотовані списки всіх модулів Python, імпортованих під час виконання в поточний каталог.

--help

  Показ використання та вихід.

--version

  Відображення версії модуля та вихід.

Added in version 3.8: Added `--module` option that allows running an executable module.

### Основні параметри

At least one of the following options must be specified when invoking `trace`. The `--listfuncs` option is mutually exclusive with the `--trace` and `--count` options. When `--listfuncs` is provided, neither `--count` nor `--trace` are accepted, and vice versa.

-c, --count

  Після завершення програми створити набір анотованих файлів списку, який показує, скільки разів було виконано кожен оператор. Дивіться також `--coverdir`, `--file` і `--no-report` нижче.

-t, --trace

  Відображення рядків у міру їх виконання.

-l, --listfuncs

  Відображення функцій, які виконуються під час запуску програми.

-r, --report

  Створіть анотований список із попередньої програми, яка використовувала параметри `--count` і `--file`. Це не виконує жодного коду.

-T, --trackcalls

  Відображення зв’язків викликів, відкритих під час запуску програми.

### Модифікатори

-f, --file=<file>

  Ім’я файлу для накопичення підрахунків протягом кількох трасування. Слід використовувати з параметром `--count`.

-C, --coverdir=<dir>

  Каталог, куди зберігаються файли звіту. Звіт про покриття для `package.module` записується у файл `dir/package/module.cover`.

-m, --missing

  Під час створення анотованих списків позначайте рядки, які не були виконані, `>>>>>>`.

-s, --summary

  Якщо використовується `--count` або `--report`, напишіть короткий підсумок у stdout для кожного обробленого файлу.

-R, --no-report

  Не створюйте анотовані списки. Це корисно, якщо ви маєте намір зробити кілька запусків за допомогою `--count`, а потім створити єдиний набір анотованих списків у кінці.

-g, --timing

  Перед кожним рядком додайте час із моменту запуску програми. Використовується лише під час трасування.

### Фільтри

Ці параметри можна повторювати кілька разів.

--ignore-module=<mod>

  Ігноруйте кожне з указаних імен модулів і його підмодулів (якщо це пакет). Аргументом може бути список імен, розділених комою.

--ignore-dir=<dir>

  Ігноруйте всі модулі та пакунки в названому каталозі та підкаталогах. Аргументом може бути список каталогів, розділених `os.pathsep`.

## Програмний інтерфейс

class trace.Trace(count=1, trace=1, countfuncs=0, countcallers=0, ignoremods=(), ignoredirs=(), infile=None, outfile=None, timing=False)

  Створіть об’єкт для відстеження виконання окремого оператора або виразу. Усі параметри є необов’язковими. count дозволяє підрахувати номери рядків. trace дозволяє відстежувати виконання рядків. countfuncs дозволяє відобразити список функцій, викликаних під час виконання. countcallers дає змогу відстежувати взаємозв’язок викликів. ignoremods — це список модулів або пакетів, які потрібно ігнорувати. ignoredirs — це список каталогів, модулі чи пакунки яких слід ігнорувати. infile — це ім’я файлу, з якого читається збережена інформація про кількість. outfile — це ім’я файлу, у який потрібно записати оновлену інформацію про кількість. час дозволяє відображати мітку часу щодо початку трасування.

  run(cmd)

    Виконайте команду та зберіть статистику виконання з поточними параметрами трасування. cmd має бути рядком або кодовим об’єктом, придатним для передачі в `exec()`.

  runctx(cmd, globals=None, locals=None)

    Виконайте команду та зберіть статистику виконання з поточними параметрами трасування у визначених глобальних і локальних середовищах. Якщо не визначено, globals і locals за замовчуванням порожні словники.

  runfunc(func, /, *args, **kwds)

    Викликати func із заданими аргументами під керуванням об’єкта `Trace` із поточними параметрами трасування.

  results()

    Повертає об’єкт `CoverageResults`, який містить сукупні результати всіх попередніх викликів `run`, `runctx` і `runfunc` для даного екземпляра `Trace`. Не скидає накопичені результати трасування.

class trace.CoverageResults

  Контейнер для результатів покриття, створений `Trace.results()`. Не має створюватися безпосередньо користувачем.

  update(other)

    Об’єднати дані з іншого об’єкта `CoverageResults`.

  write_results(show_missing=True, summary=False, coverdir=None, *, ignore_missing_files=False)

    Напишіть результати покриття. Встановіть show_missing, щоб показувати рядки, які не мали збігів. Встановіть summary, щоб включити до вихідних даних підсумок покриття для кожного модуля. coverdir вказує каталог, у який будуть виведені файли результатів покриття. Якщо `None`, результати для кожного вихідного файлу розміщуються в його каталозі.

    If ignore_missing_files is `True`, coverage counts for files that no longer exist are silently ignored. Otherwise, a missing file will raise a `FileNotFoundError`.

    Змінено в версії 3.13: Added ignore_missing_files parameter.

Простий приклад, що демонструє використання програмного інтерфейсу:

    import sys
    import trace

    # create a Trace object, telling it what to ignore, and whether to
    # do tracing or line-counting or both.
    tracer = trace.Trace(
        ignoredirs=[sys.prefix, sys.exec_prefix],
        trace=0,
        count=1)

    # run the new command using the given tracer
    tracer.run('main()')

    # make a report, placing output in the current directory
    r = tracer.results()
    r.write_results(show_missing=True, coverdir=".")