sched — Event scheduler

Código-fonte: Lib/sched.py

O módulo sched define uma classe que implementa um agendador de eventos de uso geral:

class sched.scheduler(timefunc=time.monotonic, delayfunc=time.sleep)

A classe scheduler define uma interface genérica para agendar eventos. Ela precisa de duas funções para lidar com o “mundo externo” — timefunc deve ser chamável sem argumentos e retornar um número (o “tempo”, em quaisquer unidades). A função delayfunc deve ser chamável com um argumento, compatível com a saída de timefunc, e deve atrasar a mesma quantidade de unidades de tempo. delayfunc também será chamada com o argumento 0 após a execução de cada evento para permitir que outras threads executem em aplicações multithread.

Alterado na versão 3.3: Os parâmetros timefunc e delayfunc são opcionais.

Alterado na versão 3.3: A classe scheduler pode ser usada com segurança em ambientes multithread.

Exemplo:

>>> import sched, time
>>> s = sched.scheduler(time.time, time.sleep)
>>> def print_time(a='default'):
...     print("From print_time", time.time(), a)
...
>>> def print_some_times():
...     print(time.time())
...     s.enter(10, 1, print_time)
...     s.enter(5, 2, print_time, argument=('positional',))
...     # despite having higher priority, 'keyword' runs after 'positional' as enter() is relative
...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
...     s.enterabs(1_650_000_000, 10, print_time, argument=("first enterabs",))
...     s.enterabs(1_650_000_000, 5, print_time, argument=("second enterabs",))
...     s.run()
...     print(time.time())
...
>>> print_some_times()
1652342830.3640375
From print_time 1652342830.3642538 second enterabs
From print_time 1652342830.3643398 first enterabs
From print_time 1652342835.3694863 positional
From print_time 1652342835.3696074 keyword
From print_time 1652342840.369612 default
1652342840.3697174

Objetos Scheduler

As instâncias scheduler têm os seguintes métodos e atributos:

scheduler.enterabs(time, priority, action, argument=(), kwargs={})

Agenda um novo evento. O argumento time deve ser um tipo numérico compatível com o valor de retorno da função timefunc passada ao construtor. Eventos agendados para o mesmo time serão executados na ordem de sua prioridade priority. Um número menor representa uma prioridade maior.

Executa o evento significa executar action(*argument, **kwargs). argument é uma sequência que contém os argumentos posicionais para action. kwargs é um dicionário que contém os argumentos nomeados para action.

O valor de retorno é um evento que pode ser usado para cancelamento posterior do evento (veja cancel()).

Alterado na versão 3.3: o parâmetro argument é opcional.

Alterado na versão 3.3: o parâmetro kwargs foi adicionado.

scheduler.enter(delay, priority, action, argument=(), kwargs={})

Agenda um evento para atrasar delay mais unidades de tempo. Além do tempo relativo, os outros argumentos, o efeito e o valor de retorno são os mesmos de enterabs().

Alterado na versão 3.3: o parâmetro argument é opcional.

Alterado na versão 3.3: o parâmetro kwargs foi adicionado.

scheduler.cancel(event)

Remove o evento da fila. Se event não for um evento atualmente na fila, este método levantará uma ValueError.

scheduler.empty()

Retorna True se a fila de eventos estiver vazia.

scheduler.run(blocking=True)

Run all scheduled events. This method will wait (using the delayfunc() function passed to the constructor) for the next event, then execute it and so on until there are no more scheduled events.

Se blocking for falso, executa os eventos agendados que expirarão mais cedo (se houver) e então retorna o prazo da próxima chamada agendada no agendador (se houver).

Tanto action quanto delayfunc podem levantar uma exceção. Em ambos os casos, o agendador manterá um estado consistente e propagará a exceção. Se uma exceção for gerada por action, o evento não será tentado em chamadas futuras para run().

Se uma sequência de eventos demorar mais para ser executada do que o tempo disponível antes do próximo evento, o agendador simplesmente ficará para trás. Nenhum evento será descartado; o código de chamada é responsável por cancelar eventos que não são mais pertinentes.

Alterado na versão 3.3: O argumento blocking foi adicionado.

scheduler.queue

Atributo somente leitura que retorna uma lista de eventos futuros na ordem em que serão executados. Cada evento é exibido como uma tupla nomeada com os seguintes campos: time, priority, action, argument, kwargs.