Python进阶(9) 定时运行程序 APScheduler

---

1. 前言

• 官网，源码，官方examples
• 安装pip install apscheduler
• 组件介绍
  • triggers：什么时候触发任务。
  • job stores：默认情况下将任务保存在内存中。还没用到需要序列化到数据库的情况。
  • executors：执行Job，主要取决于用了什么框架。默认使用线程池，常用的还有进程池。
  • schedulers：用于管理以上三个组件。

---

1. Scheduler

1.1. 基本概念

• 作用：用于管理 triggers，job stores，executors。
• 如何选择：主要就是根据运行的环境来选择。
  • BlockingScheduler：程序只有调度器运行时选择。
  • BackgroundScheduler：没有使用其他框架，且希望调度器在应用后台运行。

1.2. 基本API

• 所有的Scheduler都继承自 BaseScheduler。
• 初始化函数 def __init__(self, gconfig={}, **options):
  • gconfig 可以看做是一个全局初始化参数。
  • **options 可以看做是自定义初始化参数。
  • 上面两者所包含的参数是完全相同的，且自定义初始化参数会覆盖全局初始化参数。
  • 包含的参数有：
    • logger：str/logging.Logger，用于输出日志信息。
    • timezone：str/datetime.tzinfo，指定时区。
    • jobstore_retry_interval：int/float，当job store抛出异常时，最短的重试时间间隔。
    • job_defaults：dict，新建jobs的默认参数
    • jobstores：dict，job store alias -> job store instance or configuration dict
    • executors：dict， executor alias -> executor instance or configuration dict
• configure(gconfig={}, prefix='apscheduler.', **options)：在开始运行前设置参数。
  • 参数类型与初始化时相同。
• start(paused=False)：运行scheduler。
  • 如果paused=True则需要等到运行 resume() 方法后才会真正运行scheduler。
• shutdown(wait=True)：关闭scheduler
  • 同时关闭了 executors和job stores。
  • 不会停止正在运行的jobs。
  • wait=True时会等待所有jobs运行完成。
• pause()：暂停，与resume()配合使用。
• resume()：重新开始，与pause()配合使用。
• add/remove_executor
• add/remove_jobstore
• add/remove_listener
• job相关API
  • add_job()：参数太多
    • func
    • trigger：str或trigger对象，初始化参数通过 **trigger_args 来获得。
    • args：func 参数
    • kwargs：func 参数
    • id
    • name
    • misfire_grace_timec
    • coalesce
    • max_instances
    • next_run_time
    • jobstore：str，通过 alias 来选择。
    • executor：str，通过 alias 来选择。
    • replace_existing
    • **trigger_args：用于 trigger
  • modify_job(job_id, jobstore=None, **changes)
    • 改变某个job的参数。
  • reschedule_job(job_id, jobstore=None, trigger=None, **trigger_args)
    • 改变某个job的trigger，并修改下次运行时间。.
  • pause/resume_job：暂停/继续某个job。
  • get_jobs(jobstore=None, pending=None)
  • get_job(job_id, jobstore=None)
  • remove_job(job_id, jobstore=None)
  • remove_all_jobs(jobstore=None)
  • print_jobs(jobstore=None, out=sys.stdout)

1.3. 实例

from datetime import datetime
import time
import os

from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.schedulers.blocking import BlockingScheduler

def tick():
    print('Tick! The time is: %s' % datetime.now())


# background sheculer 实例
scheduler = BackgroundScheduler()
scheduler.add_job(tick, 'interval', seconds=3)
scheduler.start()
print('Press Ctrl+{0} to exit'.format('Break' if os.name == 'nt' else 'C'))
try:
    # This is here to simulate application activity (which keeps the main thread alive).
    while True:
        time.sleep(2)
except (KeyboardInterrupt, SystemExit):
    # Not strictly necessary if daemonic mode is enabled but should be done if possible
    scheduler.shutdown()

# blocking sheduler 实例
scheduler = BlockingScheduler()
scheduler.add_job(tick, 'interval', seconds=3)
print('Press Ctrl+{0} to exit'.format('Break' if os.name == 'nt' else 'C'))

try:
    scheduler.start()
except (KeyboardInterrupt, SystemExit):
    pass

---

2. trigger

2.1. 基本概念

• 基本作用：决定job运行的时间点/时间间隔。
• 分类
  • cron：功能最强大，可以指定时间、时间间隔、时间范围等。参考
  • date：指定某个时间点出发，只执行一次。
  • interval：指定时间间隔出发任务，可指定时间范围。

2.2. apscheduler.triggers.cron.CronTrigger

• 参数很多，功能强大。
• 对我来说，因为在linux中也常用，所以我用起来也最顺手。
• 主要参数：
  • year：int/str，4位
  • month：int/str，[1, 12]
  • day：int/str，[1, 31]
  • week：int/str，[1, 53]
  • day_of_week：int/str，[0, 6]，从周一开始，也可以用英文的钱三个小写字母。
  • hour：int/str，[0, 23]
  • minute：int/str，[0, 59]
  • second：int/str，[0, 59]
  • start_date：datetime/str
  • end_date：datetime/str
  • timezone：datetime.tzinfo|str
  • jitter：int/None，运行时间随机偏移[-jitter, jitter]秒。
• 对于没有指定的参数，根据输入参数分别设置为*或最小值：
  • 大于指定元素中最小的，设置为 *
  • 小于指定元素中最小的，设置为其最小值。
  • 举例：输入 day=1, minute=20，则设置second=0，其他元素为*。
• 其他常用的一些语法

Expression	Field	Description
*	any	fire on every value
*/a	any	Fire every a values, starting from the minimum
a-b	any	Fire on any value within the a-b range (a must be smaller than b)
a-b/c	any	Fire every c values within the a-b range
xth y	day	Fire on the x -th occurrence of weekday y within the month
last x	day	Fire on the last occurrence of weekday x within the month
last	day	Fire on the last day within the month
x,y,z	any	Fire on any matching expression; can combine any number of any of the above expressions

2.3. 其他 trigger

• apscheduler.triggers.interval.IntervalTrigger
  • 通过设置间隔时间来确定下次运行时间。
  • 主要参数：
    • weeks：int
    • days：int
    • hours：int
    • minutes：int
    • seconds：int
    • start_date：datetime/str
    • end_date：datetime/str
    • timezone：datetime.tzinfo|str
    • jitter：int/None，运行时间随机偏移[-jitter, jitter]秒。
• apscheduler.triggers.date.DateTrigger(run_date=None, timezone=None)
  • 只在给定的时间运行一次
  • run_date：datetime|str，指定运行时间。
  • timezone：datetime.tzinfo|str
• 集合操作：
  • apscheduler.triggers.combining.AndTrigger(triggers, jitter=None)
  • apscheduler.triggers.combining.OrTrigger(triggers, jitter=None)
  • 主要就是用于合并多个 triiger。

2.5. 举例：add_job 中trigger的应用

• 回顾一下 scheduler.add_job 方法，与trigger有关的参数有：
  • trigger=None：
    • 可以设置为字符串 date/interval/cron。
    • 也可以设置为上面提到过的各种 trigger 对象。
  • **trigger_args：即 add_job 方法中所有没有定义的命名参数都会作为trigger对象的参数导入。
• 举例：

# date
# 方法一
sched.add_job(my_job, 'date', run_date=datetime(2009, 11, 6, 16, 30, 5), args=['text'])
# 方法二
sched.add_job(my_job, 'date', run_date='2009-11-06 16:30:05', args=['text'])
# 方法三（马上执行）
sched.add_job(my_job, args=['text'])

# interval
# 方法一
sched.add_job(job_function, 'interval', hours=2, start_date='2010-10-10 09:30:00', end_date='2014-06-15 11:00:00')
# 方法二
@sched.scheduled_job('interval', id='my_job_id', hours=2)
def job_function():
    print("Hello World")

# cron
# 方法一
sched.add_job(job_function, 'cron', day_of_week='mon-fri', hour=5, minute=30, end_date='2014-05-30')
# 方法二
@sched.scheduled_job('cron', id='my_job_id', day='last sun')
def some_decorated_task():
    print("I am printed at 00:00:00 on the last Sunday of every month!")
# 方法三
sched.add_job(job_function, CronTrigger.from_crontab('0 0 1-15 may-aug *'))

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

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

---

3. executors & job store

3.1. Executors

• 用于指定通过什么后端来执行任务。
• 常用的有：线程池与进程池。
  • 默认使用线程池。
• 如何使用：
  • 第一步：在定义 scheduler 时输入 executors 参数。
    • 该参数是一个字典，key为executor的别名，value为executors的对象。
  • 第二步：在 add_job 的时候指定对应executor的别名。
• 其他：
  • 默认情况下，用线程池已经够了。
  • 计算密集型任务要使用进程池。

3.2. Job Stores

• 作用：将job保存到哪里。
  • 可以保存到各类数据库中。因为没用到，所以没细看。
  • 默认保存到内存中。
• 如何使用：
  • 第一步：在定义 scheduler 时输入 jobstores 参数。
    • 该参数是一个字典，key为executor的别名，value为executors的对象。
  • 第二步：在 add_job 的时候指定对应jobstore的别名。

3.3. 举例

from pytz import utc

from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.jobstores.sqlalchemy import SQLAlchemyJobStore
from apscheduler.executors.pool import ThreadPoolExecutor, ProcessPoolExecutor


jobstores = {
    'mongo': {'type': 'mongodb'},
    'default': SQLAlchemyJobStore(url='sqlite:///jobs.sqlite')
}

executors = {
    'default': {'type': 'threadpool', 'max_workers': 20},
    'processpool': ProcessPoolExecutor(max_workers=5)
}
# executors = {
#     'default': ThreadPoolExecutor(20),
#     'processpool': ProcessPoolExecutor(5)
# }

job_defaults = {
    'coalesce': False,
    'max_instances': 3
}
scheduler = BackgroundScheduler()

# .. do something else here, maybe add jobs etc.

scheduler.configure(jobstores=jobstores, executors=executors, job_defaults=job_defaults, timezone=utc)