Django Swingtime 技术文档

1. 安装指南

在开始使用 Django Swingtime 之前，请确保您的环境满足以下要求：

• Python 3.8 或更高版本
• Django 版本介于 3.2 到 5.0 之间
• python-dateutil 包

您可以通过以下命令安装 Django Swingtime：

pip install django-swingtime

安装完成后，需要在您的 Django 项目的 settings.py 文件中添加 'swingtime' 到 INSTALLED_APPS 列表。

INSTALLED_APPS = [
    # ...
    'swingtime',
    # ...
]

接着，运行以下命令进行数据库迁移：

python manage.py migrate swingtime

这样，Django Swingtime 就被成功安装并可以在您的项目中使用了。

2. 项目的使用说明

Django Swingtime 提供了一个 Event 模型，它可以包含一个或多个 Occurrence 实例，这些实例具体描述了事件的发生时间和结束时间。

创建一个事件类型

首先，创建一个事件类型（EventType），这将用于为事件分类。

from swingtime.models import EventType

et = EventType.objects.create(abbr='work', label='工作相关事件')

创建一个事件

然后，创建一个事件（Event）并将其关联到前面创建的事件类型。

from swingtime.models import Event

evt = Event.objects.create(
    title='新 TPS 封面表格',
    description='完成它，Lumbergh！',
    event_type=et
)

添加事件发生实例

为事件添加具体的发生时间。

from datetime import datetime
from swingtime.models import models as swingtime

# 从 2018 年 3 月 18 日 16:00 开始，持续 15 分钟，共发生 5 次
evt.add_occurrences(datetime(2018, 3, 18, 16), datetime(2018, 3, 18, 16, 15), count=5)

显示事件

您可以通过 Django 的管理界面查看创建的事件及其发生实例，或者使用查询 API 显示它们。

for o in evt.occurrence_set.all():
    print(o)

3. 项目API使用文档

Django Swingtime 的 API 设计简洁，易于使用。以下是一些常用的 API 方法：

创建事件

models.create_event 函数是一个便捷的方法，可以用来快速创建一个周期性事件。

from swingtime.models import create_event
from dateutil.rrule import rrule

# 创建一个每月最后一个星期五下午 5 点的 payroll 事件
evt = create_event(
    '发薪日',
    ('pay', '薪资发放'),  # 事件类型，可以即时创建
    freq=rrule.MONTHLY,
    byweekday=rrule.FR(-1),
    until=datetime(2023, 8, 1),
    start_time=datetime(2023, 4, 1, 17)
)

事件表单

forms.MultipleOccurrenceForm 表单用于处理复杂的事件输入。

from swingtime.forms import MultipleOccurrenceForm

# 创建并保存表单实例
form = MultipleOccurrenceForm(...)
if form.is_valid():
    form.save()

4. 项目安装方式

除了使用 pip 安装 Django Swingtime 外，您还可以通过以下步骤手动安装：

1. 下载 Django Swingtime 的源代码。
2. 解压下载的文件到您的项目中。
3. 将 swingtime 目录添加到您的项目的 Python 路径中。
4. 在项目的 settings.py 文件中添加 'swingtime' 到 INSTALLED_APPS。
5. 执行数据库迁移。

通过这些步骤，您就可以在项目中使用 Django Swingtime 了。