time — функції для роботи з часом

Модуль time надає функції для отримання поточного часу та дати, вимірювання інтервалів часу та для затримок.

Епоха часу: OpenMV Cam на базі Alif та i.MX RT використовують епоху POSIX — 1970-01-01 00:00:00 UTC. OpenMV Cam на базі STM32 використовують епоху 2000-01-01 00:00:00 UTC. Рік епохи можна визначити під час виконання за допомогою gmtime(0)[0].

Підтримка фактичного календарного часу: Для цього потрібен годинник реального часу (RTC). На OpenMV Cam системний час забезпечується об’єктом machine.RTC. Поточний календарний час можна встановити за допомогою machine.RTC().datetime(tuple) та підтримується одним із:

  • Резервна батарея (необов’язковий компонент на деяких OpenMV Cam).

  • Мережевий протокол часу, наприклад ntptime (вимагає мережевого підключення).

  • Встановлення вручну при кожному вмиканні. RTC зазвичай підтримується між м’якими скиданнями, але втрачається при відключенні живлення, якщо не встановлено резервну батарею.

Якщо календарний час не підтримується, функції нижче, що посилаються на поточний абсолютний час, не поводитимуться належним чином.

Функції

time.gmtime(secs: int | None = None) → Tuple[int, int, int, int, int, int, int, int]
time.localtime(secs: int | None = None) → Tuple[int, int, int, int, int, int, int, int]

Перетворює час secs, виражений у секундах з моменту Епохи (дивіться вище), у 8-елементний кортеж: (year, month, mday, hour, minute, second, weekday, yearday). Якщо secs не задано або дорівнює None, використовується поточний час з RTC.

Функція gmtime() повертає кортеж дата-час у UTC, а localtime() повертає кортеж дата-час у місцевому часі.

Формат записів у 8-елементному кортежі:

  • year — рік включно з сотнею (наприклад, 2014).

  • month — від 1 до 12

  • mday — від 1 до 31

  • hour — від 0 до 23

  • minute — від 0 до 59

  • second — від 0 до 59

  • weekday — від 0 до 6, де 0 — понеділок, 6 — неділя

  • yearday — від 1 до 366

time.mktime(date_time_tuple: Tuple[int, int, int, int, int, int, int, int]) → int

Це зворотна функція до localtime. Її аргументом є повний 8-елементний кортеж, що представляє час відповідно до localtime. Повертає ціле число — кількість секунд з моменту Епохи.

time.sleep(seconds: float) → None

Призупиняє виконання на задану кількість секунд. seconds може бути числом з плаваючою крапкою для дробової кількості секунд. Для більш точних або цілочисельних затримок використовуйте функції sleep_ms() та sleep_us().

Виклик sleep(), включаючи sleep(0), гарантовано викликає очікувані функції зворотного виклику.

time.sleep_ms(ms: int) → None

Затримка на задану кількість мілісекунд, має бути додатньою або 0.

Ця функція затримає виконання щонайменше на вказану кількість мілісекунд, але може тривати довше, якщо необхідно виконати інші операції, наприклад обробники переривань або інші потоки. Передача 0 для ms все одно дозволить виконати інші операції. Використовуйте sleep_us() для більш точних затримок.

Виклик sleep_ms(), включаючи sleep_ms(0), гарантовано викликає очікувані функції зворотного виклику.

time.sleep_us(us: int) → None

Затримка на задану кількість мікросекунд, має бути додатньою або 0.

Ця функція намагається забезпечити точну затримку щонайменше us мікросекунд, але може тривати довше, якщо система має інші пріоритетніші операції для виконання.

time.ticks_ms() → int

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

Значення обертання явно не задається, але ми позначимо його як TICKS_MAX для спрощення обговорення. Період значень — TICKS_PERIOD = TICKS_MAX + 1. TICKS_PERIOD гарантовано є степенем двійки, але в іншому може відрізнятися від порту до порту. Однаковий період використовується для всіх функцій ticks_ms(), ticks_us(), ticks_cpu() (для простоти). Таким чином, ці функції повернуть значення в діапазоні [0 .. TICKS_MAX] включно, всього TICKS_PERIOD значень. Зверніть увагу, що використовуються лише невід’ємні значення. У більшості випадків слід розглядати значення, що повертаються цими функціями, як непрозорі. Єдиними доступними для них операціями є функції ticks_diff() та ticks_add(), описані нижче.

Примітка: Виконання стандартних математичних операцій (+, -) або реляційних операторів (<, <=, >, >=) безпосередньо над цими значеннями призведе до невірного результату. Виконання математичних операцій та передача їх результатів як аргументів до ticks_diff() або ticks_add() також призведе до невірних результатів цих функцій.

time.ticks_us() → int

Так само, як і ticks_ms() вище, але в мікросекундах.

time.ticks_cpu() → int

Подібна до ticks_ms() та ticks_us(), але з найвищою можливою роздільною здатністю в системі. Зазвичай це такти процесора, тому функція так і названа. Але це не обов’язково мають бути такти процесора — замість них може використовуватися інше джерело часу в системі (наприклад, таймер високої роздільної здатності). Точна одиниця часу (роздільна здатність) цієї функції не вказується на рівні модуля time, але документація для конкретного порту може надати детальнішу інформацію. Ця функція призначена для дуже точного профілювання або дуже жорстких петель реального часу. Уникайте її використання в переносному коді. Вона доступна на всіх OpenMV Cam.

time.ticks_add(ticks: int, delta: int) → int

Зміщує значення тактів на задане число, яке може бути як додатним, так і від’ємним. Для заданого значення ticks ця функція дозволяє обчислити значення тактів delta тактів до або після нього відповідно до модульно-арифметичного визначення значень тактів (дивіться ticks_ms() вище). Параметр ticks має бути безпосереднім результатом виклику функцій ticks_ms(), ticks_us() або ticks_cpu() (або попереднього виклику ticks_add()). Однак delta може бути довільним цілим числом або числовим виразом. ticks_add() корисна для обчислення дедлайнів для подій/завдань. (Примітка: для роботи з дедлайнами слід використовувати функцію ticks_diff().)

Приклади:

# Find out what ticks value there was 100ms ago
print(ticks_add(time.ticks_ms(), -100))

# Calculate deadline for operation and test for it
deadline = ticks_add(time.ticks_ms(), 200)
while ticks_diff(deadline, time.ticks_ms()) > 0:
    do_a_little_of_something()

# Find out TICKS_MAX used by this port
print(ticks_add(0, -1))
time.ticks_diff(ticks1: int, ticks2: int) → int

Вимірює різницю тактів між значеннями, поверненими функціями ticks_ms(), ticks_us() або ticks_cpu(), як знакове значення, яке може обертатися.

Порядок аргументів такий самий, як для оператора віднімання: ticks_diff(ticks1, ticks2) має те саме значення, що і ticks1 - ticks2. Однак значення, що повертаються функціями ticks_ms() тощо, можуть обертатися, тому безпосереднє використання віднімання на них дасть неправильний результат. Саме тому потрібна ticks_diff() — вона реалізує модульну (або, точніше, кільцеву) арифметику для отримання правильного результату навіть для значень, що обертаються (якщо вони не занадто далеко одне від одного, дивіться нижче). Функція повертає знакове значення в діапазоні [-TICKS_PERIOD/2 .. TICKS_PERIOD/2-1] (це типове визначення діапазону для знакових двійкових цілих чисел у доповненні до двох). Якщо результат від’ємний, це означає, що ticks1 відбувся раніше ticks2. В іншому разі ticks1 відбувся після ticks2. Це виконується лише якщо ticks1 та ticks2 відрізняються не більше ніж на TICKS_PERIOD/2-1 тактів. Якщо це не виконується, буде повернуто неправильний результат. Зокрема, якщо два значення тактів відрізняються рівно на TICKS_PERIOD/2-1 тактів, ця функція поверне це значення. Однак, якщо між ними пройшло TICKS_PERIOD/2 реальних тактів, функція натомість поверне -TICKS_PERIOD/2, тобто значення результату обернеться до від’ємного діапазону можливих значень.

Неформальне обґрунтування наведених вище обмежень: Уявіть, що ви замкнені в кімнаті без можливості відстежувати плин часу, крім стандартного 12-поділкового годинника. Якщо ви подивитесь на циферблат зараз, а потім не подивитесь наступні 13 годин (наприклад, якщо заснете надовго), то наступного погляду вам здасться, що минула лише 1 година. Щоб уникнути цієї помилки, просто регулярно дивіться на годинник. Ваш застосунок має робити те саме. Метафора «занадто довгого сну» також безпосередньо відображається на поведінці застосунку: не дозволяйте йому виконувати жодне окреме завдання надто довго. Виконуйте завдання поетапно та відстежуйте час між ними.

ticks_diff() розроблена для підтримки різних шаблонів використання, зокрема:

  • Опитування з тайм-аутом. У цьому випадку порядок подій відомий, і ви будете мати справу лише з додатними результатами ticks_diff()

    # Wait for GPIO pin to be asserted, but at most 500us
start = time.ticks_us()
while pin.value() == 0:
    if time.ticks_diff(time.ticks_us(), start) > 500:
        raise TimeoutError

  • Планування подій. У цьому випадку результат ticks_diff() може бути від’ємним, якщо подія прострочена:

    # This code snippet is not optimized
now = time.ticks_ms()
scheduled_time = task.scheduled_time()
if ticks_diff(scheduled_time, now) > 0:
    print("Too early, let's nap")
    sleep_ms(ticks_diff(scheduled_time, now))
    task.run()
elif ticks_diff(scheduled_time, now) == 0:
    print("Right at time!")
    task.run()
elif ticks_diff(scheduled_time, now) < 0:
    print("Oops, running late, tell task to run faster!")
    task.run(run_faster=true)

Примітка: не передавайте значення time() до ticks_diff() — для них слід використовувати звичайні математичні операції. Але зверніть увагу, що time() також може (і буде) переповнюватися. Це відоме як https://en.wikipedia.org/wiki/Year_2038_problem .

time.time() → int

Повертає кількість секунд у вигляді цілого числа з моменту Епохи, за умови що базовий RTC встановлений та підтримується, як описано вище. Якщо RTC не встановлений, ця функція повертає кількість секунд з певної контрольної точки часу, специфічної для порту (для вбудованих плат без RTC з резервним живленням — зазвичай з моменту увімкнення або скидання). Якщо ви хочете розробити переносний застосунок MicroPython, не слід покладатися на цю функцію для забезпечення точності вищої за секунду. Якщо потрібна вища точність і абсолютні мітки часу, використовуйте time_ns(). Якщо прийнятні відносні часи, використовуйте функції ticks_ms() та ticks_us(). Якщо потрібен календарний час, кращим вибором є gmtime() або localtime() без аргументу.

Відмінність від CPython

У CPython ця функція повертає кількість секунд з моменту Unix-епохи (1970-01-01 00:00 UTC) як значення з плаваючою крапкою, зазвичай з точністю до мікросекунд. На OpenMV Cam вона повертає ціле число з точністю до однієї секунди — апаратне забезпечення не може одночасно представляти великий часовий діапазон і точність до долі секунди у float — і початок відліку залежить від плати (дивіться Епоха часу вище). Без встановленого RTC з резервним живленням замість цього ведеться відлік секунд з моменту увімкнення/скидання.

time.time_ns() → int

Подібна до time(), але повертає наносекунди з моменту Епохи у вигляді цілого числа (зазвичай великого цілого числа, тому виділяє пам’ять у купі).

Конструктори

class time.clock

Повертає об’єкт годинника.

Методи

tick() → None

Починає відстежування часу, що минув.

fps() → float

Зупиняє відстежування часу та повертає поточний FPS (кадрів на секунду).

Завжди спочатку викликайте tick, перед викликом цієї функції.

avg() → float

Зупиняє відстежування часу та повертає поточний середній час виконання в мілісекундах.

Завжди спочатку викликайте tick, перед викликом цієї функції.

reset() → None

Скидає об’єкт годинника.