Para instalar a biblioteca, execute:

pip install apscheduler

Escolhendo o agendador

O APScheduler oferece vários tipos de schedulers. Os mais utilizados são BlockingScheduler e BackgroundScheduler. A diferença principal está no comportamento em relação à thread principal:

• BlockingScheduler: após start(), bloqueia a execução da thread atual. É indicado quando o próprio agendamento é o único trabalho da aplicação.
• BackgroundScheduler: após start(), a thread principal continua. É útil quando você deseja que as tarefas rodem em paralelo sem travar o fluxo principal. Atenção: se não houver um loop ou outro mecanismo que mantenha o programa vivo, o processo pode terminar antes das tarefas serem executadas.

Exemplo com BackgroundScheduler e um laço para manter o programa ativo:

from apscheduler.schedulers.background import BackgroundScheduler
import time

def verificar_status():
    print('Verificação periódica em execução")

app_scheduler = BackgroundScheduler()
app_scheduler.add_job(verificar_status, 'interval', seconds=10)
app_scheduler.start()

while True:
    time.sleep(1)

Tipos de gatilhos

O APScheduler possui três gatilhos principais: date, interval e cron.

Gatilho date

Executa a tarefa uma única vez em um momento específico. Os parâmetros mais comuns são:

• run_date: data e hora de execução.
• timezone: fuso horário.

from apscheduler.schedulers.blocking import BlockingScheduler
from datetime import datetime

def exibir_hora():
    agora = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
    print(f'Horário atual: {agora}')

scheduler = BlockingScheduler()

# Executa uma vez no instante definido
scheduler.add_job(exibir_hora, 'date', run_date='2022-12-31 23:59:00')

# Executa imediatamente, já que não foi informado run_date
scheduler.add_job(exibir_hora, 'date')

scheduler.start()

Gatilho interval

Executa a tarefa repetidamente com intervalo fixo. Parâmetros principais: weeks, days, hours, minutes, seconds, start_date, end_date e timezone.

from apscheduler.schedulers.blocking import BlockingScheduler
from datetime import datetime

def registrar_evento():
    print(f'Evento: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}')

scheduler = BlockingScheduler()

# A cada 5 segundos, dentro de um período
scheduler.add_job(registrar_evento, 'interval', seconds=5,
                  start_date='2022-12-01 08:00:00',
                  end_date='2022-12-01 18:00:00')

# A cada 2 minutos, até a data limite
scheduler.add_job(registrar_evento, 'interval', minutes=2,
                  end_date='2022-12-31 23:59:59')

# A cada hora, sem limite
scheduler.add_job(registrar_evento, 'interval', hours=1)

scheduler.start()

Gatilho cron

Executa em horários recorrentes, semelhante ao cron do Linux. Parâmetros principais: year, month, day, week, day_of_week, hour, minute, second, start_date, end_date e timezone.

É possível usar expressões como *, intervalos (a-b), divisores (*/a) e combinações.

from apscheduler.schedulers.blocking import BlockingScheduler
from datetime import datetime

def mostrar_momento():
    print(f'Cron executado em: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}')

scheduler = BlockingScheduler()

# Diariamente às 17:36:00
scheduler.add_job(mostrar_momento, 'cron', hour=17, minute=36, second=0)

# De segunda a sexta-feira às 06:30
scheduler.add_job(mostrar_momento, 'cron',
                  day_of_week='mon-fri', hour=6, minute=30)

# No minuto 16, executa dos segundos 0 até 59
scheduler.add_job(mostrar_momento, 'cron', minute='16', second='0-59')

scheduler.start()