django-periodically 0.3.0

Periodically 允许您在 Python 中定义周期性任务，然后以您希望的方式运行它们（类似于 cron 作业）。


目标
-------

1. 任务及其调度应使用 Python 定义——而不是 crontabs 或数据库。
2. 应该有多种触发任务的方式，但定义它们的语法应该只有一个。仅仅因为您在一个服务器上使用 cron 作业触发任务，并不意味着您总能这样做。当您不能这样做时，您不需要重写所有代码——只需更改一个设置即可。
3. 该系统应该非常灵活，但……
4. ……应该有最常见调度（每小时、每天等）的快捷方式。
5. 该系统应尝试优雅地恢复，但……
6. ……如果出现任何问题，还应提醒管理员。


安装
------------

1. `pip install git+https://github.com/hzdg/django-periodically.git#egg=django-periodically`
2. 将 'periodically' 添加到 settings.py 中的 `INSTALLED_APPS`。
3. `python manage.py syncdb`


用法
-----

定义和调度任务
``````````````````````````````

Periodically 提供了一些调度周期性任务的方法。最简单的方法是使用提供的装饰器

.. code-block:: python

from periodically.decorators import *

@hourly()
def my_task()
print 'Do something!'

@every(minutes=45)
def my_other_task()
print 'Do something else every 45 minutes!'

然而，您也可以定义任务类

.. code-block:: python

from periodically.tasks import PeriodicTask
from periodically import register
from periodically.schedules import Daily

# 定义任务。
class MyTask(PeriodicTask)
def run(self)
print 'Do something.'

# 调度任务。
register.task(MyTask(), Daily())

任务可以在项目的任何地方调度，但 Periodically 会自动在 `INSTALLED_APPS` 中查找 `periodictasks` 模块，所以将所有任务定义在 `myapp/periodictasks.py` 中可能是个好主意。

运行您的任务
``````````````````

Periodically 使用可插拔的后端系统，将任务的定义和调度与其执行解耦。**默认后端不会自动运行您的任务**，所以您需要使用 `runtasks` 管理命令来告诉它这样做。通常，您会使用 cron 作业（或类似工具）来完成此操作。例如，在您的 crontab 文件中放置以下行将检查每五分钟需要运行的任务

.. code-block:: python

*/5 * * * * python /path/to/manage.py runtasks

### 调度后端

Periodically 的灵活性之一在于其调度后端系统。单个项目甚至可以使用多个后端！

使用自定义后端
`````````````````````

在 `settings.py` 中

.. code-block:: python

PERIODICALLY = {
...
'SCHEDULERS': {
'special': {
'backend': 'myapp.MySpecialBackend',
},
},
}

然后，在您的应用程序的 `periodictasks.py` 文件中

.. code-block:: python

@hourly(backend='special')
def do_something()
print 'Doing something!'

这种设置非常适合使用特定后端调度特定任务，但如果您发现想要更改所有任务使用的后端，只需覆盖默认设置会更简单

.. code-block:: python

PERIODICALLY = {
...
'SCHEDULERS': {
'default': {
'backend': 'myapp.MySpecialBackend',
},
},
}

在您的 `settings.py` 文件中包含上述代码后，所有任务都将默认使用 `myapp.MySpecialBackend`。

后端组
``````````````

有时创建后端组会很方便。一个很好的例子是您有多个不同的后端，这些后端都应该由 cron 作业触发。以下是如何在您的 `settings.py` 文件中添加后端到组中的示例

.. code-block:: python

PERIODICALLY = {
...
'SCHEDULERS': {
'default': {
'backend': 'myapp.MySpecialBackend',
'groups': ['cron'],
},
'special': {
'backend': 'myapp.MySpecialBackend',
'groups': ['cron'],
},
'another': {
'backend': 'myapp.AnotherBackend',
},
},
}

现在您将能够使用 `runtasks` 管理命令的 `--group` 选项选择性地运行任务
.. code-block:: python

python manage.py runtasks --group cron

您的 crontab 将如下所示
.. code-block:: python

*/5 * * * * python /path/to/manage.py runtasks --group cron

提示
```

如果您计划使用cron作业来触发任务执行，始终创建一个“cron”组是个好主意。这样，如果您以后添加了新的非cron后端，您就不必更改您的crontab；您只需不要将新的后端添加到“cron”组中。


日志记录
```````

定期使用Django的日志系统来通知您出现错误。要启用此功能，只需将“periodically”记录器添加到您的`settings.py`文件中。

.. code-block:: python

LOGGING = {
...
# 这一部分应该默认出现在您的设置文件中。
'handlers': {
'mail_admins': {
'level': 'ERROR',
'class': 'django.utils.log.AdminEmailHandler'
}
},
'loggers': {
...
# 添加以下内容以启用Periodically的日志记录。
'periodically': {
'handlers': ['mail_admins'],
'level': 'ERROR',
'propagate': True,
},
},
}

这是一个相对简单的设置，当定期任务失败时，会将电子邮件发送给网站管理员。但是，Django能够做更多。有关更多信息，请参阅[ Django 文档](https://docs.django.ac.cn/en/dev/topics/logging/)。