# `trace` — Trace or track Python statement execution

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

Модуль `trace` дозволяє вам відстежувати виконання програми, генерувати списки охоплення анотованих інструкцій, друкувати зв’язки між викликами та функціями списку, що виконуються під час виконання програми. Його можна використовувати в іншій програмі або з командного рядка.

Дивись також

Coverage.py

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

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

Модуль `trace` можна викликати з командного рядка. Це може бути так просто:

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

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

--help

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

--version

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

Added in version 3.8: Додано параметр `--module`, який дозволяє запускати виконуваний модуль.

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

Під час виклику `trace` необхідно вказати принаймні одну з наступних опцій. Опція `--listfuncs` є взаємовиключною з опціями `--trace` і `--count`. Коли надається `--listfuncs`, ні `--count`, ні `--trace` не приймаються, і навпаки.

-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=".")