sched — Agendador de eventos

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',))
...     # apesar de ter prioridade mais alta, 'keyword' é executado depois de 'positional', pois enter() é relativo
...     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)

Executa todos os eventos agendados. Este método aguardará (usando a função delayfunc passada ao construtor) o próximo evento, depois o executará e assim por diante até que não haja mais eventos agendados.

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.