APScheduler（定时任务—Python库）

一.APScheduler简介

Advanced Python Scheduler（APScheduler）是一个Python库，是一个轻量级的Python定时任务调度框架，它允许您安排稍后执行的Python代码，可以是一次执行，也可以是定期执行。

您可以随时添加新工作或删除旧工作。如果将作业存储在数据库中，它们也将在调度器重新启动并保持其状态后继续存在。当计划程序重新启动时，它将运行它在脱机1时应该运行的所有作业。

二.安装 APScheduler

$ pip install apscheduler

三.基本概念

APScheduler四大组件：

• 触发器 triggers ：用于设定触发任务的条件
• 任务储存器 job stores：用于存放任务，把任务存放在内存或数据库中
• 执行器 executors： 用于执行任务，可以设定执行模式为单线程或线程池
• 调度器 schedulers： 把上方三个组件作为参数，通过创建调度器实例来运行

3.1  触发器

每一个任务都有自己的触发器，触发器用于决定任务下次运行的时间。

3.2  任务储存器

默认情况下，任务存放在内存中。也可以配置存放在不同类型的数据库中。

如果任务存放在数据库中，那么任务的存取有一个序列化和反序列化的过程，同时修改和搜索任务的功能也是由任务储存器实现。

注:一个任务储存器不要共享给多个调度器，否则会导致状态混乱

3.3  执行器

任务会被执行器放入线程池或进程池去执行，执行完毕后，执行器会通知调度器。

3.4  调度器

一个调度器由上方三个组件构成，一般来说，一个程序只要有一个调度器就可以了。

开发者也不必直接操作任务储存器、执行器以及触发器，因为调度器提供了统一的接口，通过调度器就可以操作组件，比如任务的增删改查。

四.快速开始

#-*- coding:utf-8 -*-
from apscheduler.schedulers.blocking import BlockingScheduler

scheduler = BlockingScheduler()

#每个小时的22分到25分之间，每分钟会执行一次
@scheduler.scheduled_job('cron', minute='22-25')
def request_update_status():
    print('Doing job')

scheduler.start()

五.调度器组件详解

根据开发需求选择相应的组件，下面是不同的调度器组件：

• BlockingScheduler      阻塞式调度器：适用于只跑调度器的程序。
• BackgroundScheduler 后台调度器：适用于非阻塞的情况，调度器会在后台独立运行。
• AsyncIOScheduler        AsyncIO调度器，适用于应用使用AsnycIO的情况。
• GeventScheduler          Gevent调度器，适用于应用通过Gevent的情况。
• TornadoScheduler        Tornado调度器，适用于构建Tornado应用。
• TwistedScheduler        Twisted调度器，适用于构建Twisted应用。
• QtScheduler                    Qt调度器，适用于构建Qt应用。

任务储存器的选择，要看任务是否需要持久化。

如果你运行的任务是无状态的，选择默认任务储存器MemoryJobStore就可以应付。

但是，如果你需要在程序关闭或重启时，保存任务的状态，那么就要选择持久化的任务储存器。

如果，作者推荐使用SQLAlchemyJobStore并搭配PostgreSQL作为后台数据库。

这个方案可以提供强大的数据整合与保护功能。

 

执行器的选择，同样要看你的实际需求。

默认的ThreadPoolExecutor线程池执行器方案可以满足大部分需求。

如果，你的程序是计算密集型的，那么最好用ProcessPoolExecutor进程池执行器方案来充分利用多核算力。

也可以将ProcessPoolExecutor作为第二执行器，混合使用两种不同的执行器。

 

配置一个任务，就要设置一个任务触发器。触发器可以设定任务运行的周期、次数和时间。APScheduler有三种内置的触发器，其中包括：

• cron式调度（可选开始/结束时间）
• interval 基于间隔的执行（以偶数间隔运行作业，也可以选择开始/结束时间）
• date 日期 一次性延迟执行任务（在指定的日期/时间运行一次作业）
• 一个任务也可以设定多种触发器，比如，可以设定同时满足所有触发器条件而触发，或者满足一项即触发。复合触发器，请查阅一下文档：链接

例子

1.job_function每2小时运行一次，但仅在周六和周日运行：

from apscheduler.triggers.combining import AndTrigger
from apscheduler.triggers.interval import IntervalTrigger
from apscheduler.triggers.cron import CronTrigger

trigger = AndTrigger([IntervalTrigger(hours=2),
                      CronTrigger(day_of_week='sat,sun')])
scheduler.add_job(job_function, trigger)

2.在job_function每个星期一的凌晨2点和每个星期二的下午3点运行：

trigger = OrTrigger([CronTrigger(day_of_week='mon', hour=2),
                     CronTrigger(day_of_week='tue', hour=15)])
scheduler.add_job(job_function, trigger)

六  触发器使用详解

   6.1 date 在指定时间点触发任务

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

sched = BlockingScheduler()

def my_job(text):
    print(text)

# 在2020年11月6日执行
sched.add_job(my_job, 'date', run_date=date(2020, 11, 6), args=['text'])

sched.start()

在run_datee参数可以是date类型、datetime类型或文本类型。（在 ISO 8601格式）。

6.2  datetime类型（用于精确时间）

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

sched = BlockingScheduler()
def my_job(text):
    print(text)

# 在2020年6月18日 14点3分40秒执行，执行参数args
sched.add_job(my_job, 'date', run_date=datetime(2020, 6, 18, 14, 3, 40), args=['112233'])

sched.start()

 

6.3 运行日期也可以文本形式给出：

#-*- coding:utf-8 -*-
from datetime import date, datetime
from apscheduler.schedulers.blocking import BlockingScheduler

sched = BlockingScheduler()
def my_job(text):
    print(text)

# 在2020年6月18日 14点9分0秒执行，执行参数args
sched.add_job(my_job, 'date', run_date='2020-06-18 14:09:00', args=['112233'])
sched.start()

6.4 未指定时间，则会立即执行

#-*- coding:utf-8 -*-
from datetime import date, datetime
from apscheduler.schedulers.blocking import BlockingScheduler

sched = BlockingScheduler()
def my_job(text):
    print(text)

# 未显式指定，那么则立即执行
sched.add_job(my_job, args=['text'])
sched.start()

七  interval 周期触发任务

 7.1 每两小时触发一次

#-*- coding:utf-8 -*-
from apscheduler.schedulers.blocking import BlockingScheduler

def job_function():
    print("Hello World")

sched = BlockingScheduler()

# 每2小时触发
sched.add_job(job_function, 'interval', hours=2)
sched.start()

 

7.2 您可以使用start_date和end_date限制计划运行的时间段：

#-*- coding:utf-8 -*-
import time
from apscheduler.schedulers.blocking import BlockingScheduler

def job_function():
    print("Hello World")
    print(time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()))

sched = BlockingScheduler()

# 周期触发的时间范围在2020-06-18 14:23 至 2020-06-18 18:30 ,每两分钟一次
sched.add_job(job_function, 'interval', minutes=2, start_date='2020-06-18 14:23:00', end_date='2020-06-18 18:30:00')
sched.start()

7.3 也可以通过scheduled_job()装饰器实现

#-*- coding:utf-8 -*-
import time
from apscheduler.schedulers.blocking import BlockingScheduler

sched = BlockingScheduler()
@sched.scheduled_job('interval', id='my_job_id', minutes=20)
def job_function():
    print("Hello World")
    print(time.strftime("%Y-%m-%d %H:%M:%S",time.localtime()))

sched.start()

7.4 jitter振动参数，给每次触发添加一个随机浮动秒数，一般适用于多服务器，避免同时运行造成服务拥堵。

#-*- coding:utf-8 -*-
import time
from apscheduler.schedulers.blocking import BlockingScheduler

sched = BlockingScheduler()
#每两分钟执行一次，随机浮动秒数20秒（上下浮动20秒区间内）
@sched.scheduled_job('interval', id='my_job_id', minutes=2,jitter=20)
def job_function():
    print("Hello World")
    print(time.strftime("%Y-%m-%d %H:%M:%S",time.localtime()))

sched.start()

 八. cron 强大的类crontab表达式

# 注意参数顺序
class apscheduler.triggers.cron.CronTrigger(
year=None, 
month=None, 
day=None, 
week=None, 
day_of_week=None, 
hour=None, 
minute=None,
second=None, 
start_date=None, 
end_date=None, 
timezone=None, 
jitter=None)

当省略时间参数时，在显式指定参数之前的参数会被设定为*，之后的参数会被设定为最小值，week 和day_of_week的最小值为*。

比如，设定day=1, minute=20等同于设定year='*', month='*', day=1, week='*', day_of_week='*', hour='*', minute=20, second=0，即每个月的第一天，且当分钟到达20时就触发。

表达式类型

表达式	参数类型	描述
*	所有	通配符。例：minutes=*即每分钟触发
*/a	所有	可被a整除的通配符。
a-b	所有	范围a-b触发
a-b/c	所有	范围a-b，且可被c整除时触发
xth y	日	第几个星期几触发。x为第几个，y为星期几
last x	日	一个月中，最后个星期几触发
last	日	一个月最后一天触发
x,y,z	所有	组合表达式，可以组合确定值或上方的表达式

注！month和day_of_week参数分别接受的是英语缩写jan– dec 和 mon – sun

     8.1  列1

#-*- coding:utf-8 -*-


from apscheduler.schedulers.blocking import BlockingScheduler

def job_function():
    print("Hello World")

sched = BlockingScheduler()

# 任务会在6月、7月、8月、11月和12月的第三个周五，00:00、01:00、02:00和03:00触发
sched.add_job(job_function, 'cron', month='6-8,11-12', day='3rd fri', hour='0-3')

sched.start()

8.2 列2：start_date 和 end_date 可以用来适用时间范围

#-*- coding:utf-8 -*-
import time
from apscheduler.schedulers.blocking import BlockingScheduler

def job_function():
    print("Hello World")
    print(time.strftime("%Y-%m-%d %H:%S:%M",time.localtime()))

sched = BlockingScheduler()
# 在2020-06-20 00:00:00前，每周一到每周五 15:43运行
sched.add_job(job_function, 'cron', day_of_week='mon-fri', hour=15, minute=43, end_date='2020-06-20')
sched.start()

8.3 通过 scheduled_job() 装饰器实现：

#-*- coding:utf-8 -*-

import time
from apscheduler.schedulers.blocking import BlockingScheduler

sched = BlockingScheduler()

@sched.scheduled_job('cron', id='my_job_id', day='last sun')
def some_decorated_task():
    #每个月的最后一个星期天00：00:00打印
    print("I am printed at 00:00:00 on the last Sunday of every month!")
sched.start()

8.4 使用标准crontab表达式：

#-*- coding:utf-8 -*-
import time
from apscheduler.schedulers.blocking import BlockingScheduler
from apscheduler.triggers.cron import CronTrigger

sched = BlockingScheduler()
def job_function():
    print("Hello World")

# 格式: 秒 分 时 日 月 年,每年的5-8月每两分钟执行一次
sched.add_job(job_function, CronTrigger.from_crontab('0/2 * * may-aug *'))
sched.start()

8.5  也可以添加jitter振动参数

#-*- coding:utf-8 -*-

import time
from apscheduler.schedulers.blocking import BlockingScheduler

sched = BlockingScheduler()

def job_function():
    print("Hello World")
    print(time.strftime("%Y-%m-%d %H:%M:%S",time.localtime()))

# 每小时上下浮动120秒触发
sched.add_job(job_function, 'cron', hour='*', jitter=120)
sched.start()

8.6 夏令时问题

有些timezone时区可能会有夏令时的问题。这个可能导致令时切换时，任务不执行或任务执行两次。避免这个问题，可以使用UTC时间，或提前预知并规划好执行的问题

# 在Europe/Helsinki时区, 在三月最后一个周一就不会触发；在十月最后一个周一会触发两次
sched.add_job(job_function, 'cron', hour=3, minute=30)