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

  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.