# `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```

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

Нове в версії 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)

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

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

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