django-attachments 技术文档

1. 安装指南

1.1 安装步骤

1. 将 attachments 添加到 Django 项目的 INSTALLED_APPS 中：

   INSTALLED_APPS = (
       ...
       'attachments',
   )
   

2. 在 urls.py 中添加 attachments 的 URL 模式：

   url(r'^attachments/', include('attachments.urls', namespace='attachments')),
   

3. 执行数据库迁移：

   ./manage.py migrate
   

4. 为用户分配权限：

   • 添加附件：attachments.add_attachment
   • 删除附件：attachments.delete_attachment
   • 删除他人附件：attachments.delete_foreign_attachments

5. 设置 DELETE_ATTACHMENTS_FROM_DISK 为 True，以在删除附件对象时从磁盘删除文件。

6. 配置 FILE_UPLOAD_MAX_SIZE（可选），限制文件上传大小。

1.2 注意事项

• 确保服务器正确处理上传的文件类型，避免安全风险。

2. 项目的使用说明

2.1 在 Admin 中使用

在 Django Admin 中，可以通过 AttachmentInlines 为模型添加附件列表：

from django.contrib import admin
from attachments.admin import AttachmentInlines

class MyEntryOptions(admin.ModelAdmin):
    inlines = (AttachmentInlines,)

2.2 在前端模板中使用

1. 加载 attachments_tags：

   {% load attachments_tags %}
   

2. 获取附件列表：

   {% get_attachments_for entry as attachments_list %}
   

3. 统计附件数量：

   {% attachments_count entry %}
   

4. 渲染附件上传表单：

   {% attachment_form [object] %}
   

5. 渲染附件删除链接：

   {% for att in attachments_list %}
       {{ att }} {% attachment_delete_link att %}
   {% endfor %}
   

3. 项目API使用文档

3.1 模板标签

• get_attachments_for [object]：获取指定对象的附件列表。
• attachments_count [object]：统计指定对象的附件数量。
• attachment_form：渲染附件上传表单。
• attachment_delete_link：渲染附件删除链接。

3.2 管理命令

• delete_stale_attachments：删除与对象无关的附件。

4. 项目安装方式

4.1 通过 pip 安装

pip install django-attachments

4.2 本地开发环境

使用 pipenv 安装本地开发环境：

pip install pipenv
pipenv install

4.3 运行测试

使用 pipenv 运行测试：

pipenv install --dev
pipenv run pytest attachments/

4.4 构建新版本

git tag
change version in setup.cfg
pip install -U setuptools
python setup.py sdist && python setup.py bdist_wheel --universal
twine upload --sign dist/*

5. 设置

• DELETE_ATTACHMENTS_FROM_DISK：删除附件时从磁盘删除文件，默认 False。
• FILE_UPLOAD_MAX_SIZE：限制文件上传大小，默认无限制。
• AppConfig.attachment_validators：自定义文件上传验证器。