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',))
...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
...     s.run()
...     print(time.time())
...
>>> print_some_times()
930343690.257
From print_time 930343695.274 positional
From print_time 930343695.275 keyword
From print_time 930343700.273 default
930343700.276

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.