文件上传和文件对象

阅读: 93300 评论：6

Django在处理文件上传时，文件数据会被打包封装在request.FILES中。

文件上传

一、简单上传，手动保存

这里的上传，指的是客户在浏览器页面，点击选择文件，上传到Django服务器中。

首先，写一个form模型，它必须包含一个FileField：

Django的表单forms系统，就是以Python代码的方式来写HTML表单代码，可以类比ORM。

from django import forms

class UploadFileForm(forms.Form):
    title = forms.CharField(max_length=50)
    file = forms.FileField()

处理这个表单的视图将在request.FILES中收到文件数据，可以用request.FILES['file']来获取上传文件的具体数据，其中的键值'file'是根据file = forms.FileField()的变量名来的。

注意：request.FILES只有在请求方法为POST,并且提交请求的<form>具有enctype="multipart/form-data"属性时才有效。否则，request.FILES将为空。

下面是一个接收上传文件的视图范例：

# views.py

from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import UploadFileForm

# 另外写一个处理上传过来的文件的方法，并在这里导入
from somewhere import handle_uploaded_file

def upload_file(request):
    if request.method == 'POST':
        form = UploadFileForm(request.POST, request.FILES)
        if form.is_valid():
            handle_uploaded_file(request.FILES['file'])
            return HttpResponseRedirect('/success/url/')
    else:
        form = UploadFileForm()
    return render(request, 'upload.html', {'form': form})

请注意，必须将request.FILES传递到form的构造函数中。

form = UploadFileForm(request.POST, request.FILES)

下面是一个处理上传文件的方法的参考例子：

def handle_uploaded_file(f):
    with open('some/file/name.txt', 'wb+') as destination:
        for chunk in f.chunks():
            destination.write(chunk)

遍历UploadedFile.chunks()，而不是直接使用read()方法，能确保大文件不会占用系统过多的内存。

二、使用模型处理上传的文件

如果是通过模型层的model来指定上传文件的保存方式的话，使用ModelForm更方便。调用form.save()的时候，文件对象会保存在相应的FileField的upload_to参数指定的地方。

from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import ModelFormWithFileField

# 这里暂时忽略了ModelFormWithFileField本身的内容

def upload_file(request):
    if request.method == 'POST':
        form = ModelFormWithFileField(request.POST, request.FILES)
        if form.is_valid():
            # 这么做就可以了，文件会被保存到Model中upload_to参数指定的位置
            form.save()
            return HttpResponseRedirect('/success/url/')
    else:
        form = ModelFormWithFileField()
    return render(request, 'upload.html', {'form': form})

如果手动构造一个对象，还可以简单地把文件对象直接从request.FILES赋值给模型：

from django.http import HttpResponseRedirect
from django.shortcuts import render
from .forms import UploadFileForm
from .models import ModelWithFileField

def upload_file(request):
    if request.method == 'POST':
        form = UploadFileForm(request.POST, request.FILES)
        if form.is_valid():
            instance = ModelWithFileField(file_field=request.FILES['file'])
            instance.save()
            return HttpResponseRedirect('/success/url/')
    else:
        form = UploadFileForm()
    return render(request, 'upload.html', {'form': form})

三、批量上传文件

注意：早先的MultipleFileField(widget=forms.ClearableFileInput(attrs={'multiple': True}))方式已经不支持了！

如果要使用一个表单字段同时上传多个文件，你需要先创建该字段小部件的一个子类，并将其上的allow_multiple_selected属性设置为True。

同时，为了让这些文件都能通过表单的验证过程，还必须创建一个FileField的子类。

参考下面（涉及的Form表单和类视图知识需要在后面的章节进行学习）：

# forms.py

from django import forms


class MultipleFileInput(forms.ClearableFileInput):
    allow_multiple_selected = True


class MultipleFileField(forms.FileField):
    def __init__(self, *args, **kwargs):
        kwargs.setdefault("widget", MultipleFileInput())
        super().__init__(*args, **kwargs)

    def clean(self, data, initial=None):
        single_file_clean = super().clean
        if isinstance(data, (list, tuple)):
            result = [single_file_clean(d, initial) for d in data]
        else:
            result = single_file_clean(data, initial)
        return result


class FileFieldForm(forms.Form):
    file_field = MultipleFileField()

然后，自己编写一个FormView的子类，并覆盖它的post方法，来处理多个文件上传：

# views.py
from django.views.generic.edit import FormView
from .forms import FileFieldForm

class FileFieldView(FormView):
    form_class = FileFieldForm
    template_name = 'upload.html'  # 用你的模版名替换.
    success_url = '...'  # 用你的URL或者reverse()替换.

    def post(self, request, *args, **kwargs):
        form_class = self.get_form_class()
        form = self.get_form(form_class)
        if form.is_valid():
            return self.form_valid(form)
        else:
            return self.form_invalid(form)

     def form_valid(self, form):
        files = form.cleaned_data["file_field"]
        for f in files:
            ...  # Do something with each file.  # 核心的存储文件过程在这里
        return super().form_valid()

下面是一个视图函数的例子：

def multiple_upload(request):
    if request.method == 'POST':
        form = FileFieldForm(request.POST, request.FILES)
        if form.is_valid():
            files = request.FILES.getlist('file_field')
            for file in files:
                file_path = settings.MEDIA_ROOT / file.name
                with open(file_path, 'wb') as destination:
                    for chunk in file.chunks():
                        destination.write(chunk)
    else:
        form = FileFieldForm()
    return render(request, 'uploads/multiple_upload.html', {'form':form})


#########    
# 下面是对应的前端代码    
    <h1>随意的文件个数</h1>
    <form enctype="multipart/form-data" action="/uploads/multiple_upload/" method="post">
        {{ form }}
        {% csrf_token %}
        <input type="submit" value="提交">
    </form>

四、关于上传文件的处理器

当用户上传一个文件的时候，Django会把文件数据传递给上传文件处理器。

上传处理器的配置定义在FILE_UPLOAD_HANDLERS中，默认为：

["django.core.files.uploadhandler.MemoryFileUploadHandler", "django.core.files.uploadhandler.TemporaryFileUploadHandler"]

在你保存上传文件之前，数据需要储存在某个地方。MemoryFileUploadHandler和TemporaryFileUploadHandler定义了Django的默认文件上传行为：将小文件读取到内存中，大文件放置在磁盘中。

通常，如果上传文件小于2.5MB，Django会把整个内容存到内存。这意味着，文件的保存仅仅涉及到内存中的读取和磁盘的写入，所以非常快。

但是，如果上传的文件很大，Django会把它写入一个临时文件，储存在你的系统临时目录中。在类Unix的平台下，Django会生成一个文件，名称类似于/tmp/tmpzfp6I6.upload。

你可以编写自己的 handlers 来自定义如何处理文件。比如，你可以使用自定义强制处理用户层面的配额，动态压缩数据，渲染进度条，甚至可以将数据发送到其他存储地址而不是本地。

五、动态修改上传处理器

有时候某些视图需要不同的上传行为。也就是说，在视图中动态修改处理器列表，即request.upload_handlers

比如，假设你正在编写 ProgressBarUploadHandler ，用来提供上传过程中的反馈。你需要添加这个处理程序到你的上传处理模块：

request.upload_handlers.insert(0, ProgressBarUploadHandler(request))

在这里使用 list.insert() （而不是 append() ），因为进度条处理程序需要在其他处理程序之前使用。

记住，列表中的上传处理程序是按顺序处理的。

如果你想完全替换掉先前的上传处理程序，只需要指定新列表：

request.upload_handlers = [ProgressBarUploadHandler(request)]

你只能在访问 request.POST 或 request.FILES 之前修改上传处理程序。开始上传动作后修改上传处理程序没有意义，并且Django 会报错。

而且，默认的， CsrfViewMiddleware中间件会访问request.POST。这意味着你需要在视图上使用 csrf_exempt() 来允许你改变上传处理程序。然后你需要在实际处理请求的函数上使用 csrf_protect() 。注意这可能会让处理程序在 CSRF 检测完成之前开始接受文件上传。如下所示：

from django.views.decorators.csrf import csrf_exempt, csrf_protect

@csrf_exempt
def upload_file_view(request):
    request.upload_handlers.insert(0, ProgressBarUploadHandler(request))
    return _upload_file_view(request)

@csrf_protect
def _upload_file_view(request):
    ... # Process request

File全局概念

在详细介绍Django的类文件系统之前，我们要了解一些它的基本概念、组织方式、使用套路、主要的类和继承关系。

如果你不了解这些，那么复杂的源码、交错的官方文档会让你陷入泥坑。不知道怎么用？什么时候用？用什么？为什么这么用？整个一团乱！这些代码都位于django.core.files模块中。

File的概念：Django对Python文件的封装。既可以用于文件上传过程中的处理，也可以单独使用。

File类：Django实现File的基类
ContentFile类：继承了File类，不同之处是它处理的是字符串
ImageFile 类：继承了File类，添加了图像的宽度和长度像素值，专门处理图片。
File类的其它子类：Django为File类编写的一系列Upload...子类，只是使用较少。
File storage的概念：将Django的File对象保存到存储系统的API，也就是Django如何将数据保存到硬盘中的。
Storage类：Django源码中所有存储类的基类，提供通用的接口API
FileSystemStorage：继承了Storage类，是Django原生实现的最重要、最常用、最普通的存储类。我们绝大多数时间实际使用的就是它！

File 对象

Django设计了自己的文件对象。

File 类

File 类是围绕Python原生file对象的轻度包装，添加了一些Django特有的东西。Django在内部使用File类的实例来表示文件对象。

每个File对象都包含下面的属性和方法：

name：文件名。包括MEDIA_ROOT定义的相对路径部分。
size：文件的尺寸，字节单位。
file：注意，这是File对象的file属性，不要搞混淆了！它表示File类封装的底层文件对象（Python文件对象）。
mode：文件的读/写模式
open(mode=None,*args, **kwargs)：打开或者重新打开文件。mode参数和Python内置的open方法的参数一样。可以使用上下文管理器with file.open() as f:
__iter__()：遍历文件一次生成一行。
chunks(chunk_size=None)：遍历文件，分割成指定大小的“块”。chunk_size 默认为64 KB。这对于非常大的文件特别有用，因为它允许从磁盘流式传输，避免将整个文件存储在内存中。
multiple_chunks(chunk_size=None)：以指定的chunk_size进行测试，如果文件大到需要分割成多个数据块进行访问，则返回True，否则返回False。
close()：关闭文件

除以上属性和方法之外，还有下面的方法：

encoding
fileno
flush
isatty
newlines
read
readinto
readline
readlines
seek
tell
truncate
write
writelines,
readable()
writable()
seekable()

望文生义，它们都和Python原生的文件操作方法类似。

如果你想创建一个 File 实例，最简单的方法是搭配 Python 内置的 file 对象：

>>> from django.core.files import File

# 使用Python原生的open()方法
>>> f = open('/path/to/hello.world', 'w')
>>> myfile = File(f)

感觉有点多此一举，是不是？不是的，这样的封装还是有作用的。

注意在这里创建的文件不会自动关闭。下面的方式可以用来自动关闭文件：

>>> from django.core.files import File

# Create a Python file object using open() and the with statement
>>> with open('/path/to/hello.world', 'w') as f:
...     myfile = File(f)
...     myfile.write('Hello World')
...
>>> myfile.closed
True
>>> f.closed
True

如果文件在访问后没有关闭，可能会出现文件描述符溢出的风险。

OSError: [Errno 24] Too many open files

ContentFile类

ContentFile类直接继承了File类，但是前者仅操作字符串或者字节数据，而不是确切的磁盘中的某个文件。例如：

from django.core.files.base import ContentFile

f1 = ContentFile("esta frase está en español")
f2 = ContentFile(b"these are bytes")

ImageFile 类

Django为图片特别提供了一个内置类，也就是django.core.files.images.ImageFile，它也继承了File类。只是额外增加了两个属性：

width：图片的像素宽度
height：图片的像素高度

比如下面的模型，使用 ImageField 来存储照片：

from django.db import models


class Car(models.Model):
    name = models.CharField(max_length=255)
    price = models.DecimalField(max_digits=5, decimal_places=2)
    photo = models.ImageField(upload_to="cars")
    specs = models.FileField(upload_to="specs")

所有的 Car 实例都拥有一个 photo 属性，你可以使用它来获取照片的详细信息：

>>> car = Car.objects.get(name="57 Chevy")
>>> car.photo
<ImageFieldFile: cars/chevy.jpg>
>>> car.photo.name
'cars/chevy.jpg'
>>> car.photo.path      # 图片在文件系统中的路径
'/media/cars/chevy.jpg'
>>> car.photo.url   # 访问图片的url
'http://media.example.com/cars/chevy.jpg'

car.photo 其实是一个 File 对象，这意味着它拥有前面所描述的所有方法和属性。

可以通过将文件名设置为相对于文件存储位置的路径来更改文件名（如果你正在使用默认的 FileSystemStorage ，则为 MEDIA_ROOT ）。

>>> import os
>>> from django.conf import settings
>>> initial_path = car.photo.path
>>> car.photo.name = "cars/chevy_ii.jpg"
>>> new_path = settings.MEDIA_ROOT + car.photo.name
>>> # Move the file on the filesystem
>>> os.rename(initial_path, new_path)
>>> car.save()
>>> car.photo.path
'/media/cars/chevy_ii.jpg'
>>> car.photo.path == new_path
True

如果要将一个磁盘上已经存在的文件保存到文件字段中，可以这么做：

>>> from pathlib import Path
>>> from django.core.files import File

>>> path = Path("/some/external/specs.pdf")
>>> car = Car.objects.get(name="57 Chevy")
>>> with path.open(mode="rb") as f:
...     car.specs = File(f, name=path.name)
...     car.save()
...

更多的 ImageField 使用例子：

>>> from PIL import Image
>>> car = Car.objects.get(name='57 Chevy')
>>> car.photo.width
191
>>> car.photo.height
287
>>> image = Image.open(car.photo)
# 抛出ValueError异常。因为你在尝试打开已经关闭的文件

>>> car.photo.open()  # 打开文件
<ImageFieldFile: cars/chevy.jpg>
>>> image = Image.open(car.photo)  # 再次创建Image实例
>>> image
<PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=191x287 at 0x7F99A94E9048>

另外，此时这个File对象会有两个附加的方法save和delete：

File.save（name，content，save = True）

使用提供的文件名和内容保存一个新的文件。这不会替换现有文件，但会创建一个新文件并更新该对象以指向该文件。如果save=True，将立刻执行模型的save方法。

>>> car.photo.save('myphoto.jpg', content, save=False)
>>> car.save()
# 等同于
>>> car.photo.save('myphoto.jpg', content, save=True)

File.delete（save = True）

从模型实例中删除文件。如果save=True，删除文件后将立刻执行模型的save方法。

File storage 类

STORAGES配置项

Django 4.2新增了settings.py中的STORAGES配置项。

它的默认值如下：

{
    "default": {
        "BACKEND": "django.core.files.storage.FileSystemStorage",
    },
    "staticfiles": {
        "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
    },
}

这是一个嵌套字典，每一个键值对都是存储后端名称和后端位置的形式。

你可以往里面添加自定义的存储类后端，但是初始的两个具有特殊意义，不要覆盖它们：

default：用于管理普通文件
staticfiles ：用于管理静态文件

下面是一个例子，假设有一个自定义的example存储类:

STORAGES = {
    # ...
    "example": {
        "BACKEND": "django.core.files.storage.FileSystemStorage",
        "OPTIONS": {
            "location": "/example",
            "base_url": "/example/",
        },
    },
}

配置中的OPTIONS 选项会传递给BACKEND的**kwargs参数。

配置好了后，要在代码中指定存储后端，只需要如下方式即可：

from django.core.files.storage import storages

example_storage = storages["example"]

Storage类

Storage类是Django为我们提供的存储基类，实现了一些标准的API和一些可以被子类重写的默认行为。

name：文件名
delete(name)：删除指定名字的文件。如果子类没有实现这个方法，会弹出NotImplementedError 异常。
exists(name)：如果文件已经存在，返回True，否则False
get_accessed_time(name): 返回上次访问该文件的时间，以datetime类型。如果子类没有实现这个方法，会弹出NotImplementedError 异常。
get_alternative_name(file_root, file_ext)：返回基于file_root和 file_ext参数的备用文件名，在扩展名之前，在文件名后附加一个下划线和一个随机的7个字符的字母数字字符串。3.0新增。
get_available_name(name, max_length=None)：据name参数返回自由可用的文件名。文件名的长度将不超过max_length（如果提供）。如果找不到自由的唯一文件名，则会引发SuspiciousFileOperation异常。
get_created_time(name)：返回文件的创建时间。如果子类没有实现这个方法，会弹出NotImplementedError 异常。
get_modified_time(name)：返回上次修改该文件的时间，以datetime类型。如果子类没有实现这个方法，会弹出NotImplementedError 异常。
get_valid_name(name)：根据name参数，返回一个在目标存储系统上可用的合法文件名。
generate_filename(filename)：验证并返回一个文件名。
listdir(path)：列出指定path下的内容，然会一个列表的二元元组。第一个元素是目录列表，第二个元素是文件列表。如果子类没有实现这个方法，会弹出NotImplementedError 异常。
open(name, mode='rb')：以指定的mode打开文件
path(name)：返回文件的路径，通过该路径可以使用Python原生的open()方法打开文件。如果子类没有实现这个方法，会弹出NotImplementedError 异常。
save(name, content, max_length=None)：保存文件。如果文件名已经存在，会自动修改生成合适的文件名。content参数必须是一个django.core.files.File的实例，或者可以被File包装的类文件对象。
size(name)：返回文件的大小，字节单位。如果子类没有实现这个方法，会弹出NotImplementedError 异常。
url(name)：返回URL，通过该URL可以访问文件的内容。如果子类没有实现这个方法，会弹出NotImplementedError 异常。

方法很多，不一定全要掌握，重点是下面这几个：

delete
exists
listdir
open
path
save
size
url

Django提供了一个default_storage属性，可以帮助我们获取STORAGES中的默认default配置后端。

>>> from django.core.files.base import ContentFile
>>> from django.core.files.storage import default_storage

# 注意，这个save方法是有返回值的！返回值是文件在存储系统中的路径。可以通过这个路径再去查找文件。
>>> path = default_storage.save('path/to/file', ContentFile(b'new content'))
>>> path
'path/to/file'

>>> default_storage.size(path)
11
>>> default_storage.open(path).read()
b'new content'

>>> default_storage.delete(path)
>>> default_storage.exists(path)
False

FileSystemStorage 类

实际上，我们不直接使用Storage类，而是使用FileSystemStorage 类，这也是Django唯一实现了的本地文件系统存储类。

class FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)

FileSystemStorage类直接继承了Storage类，并提供了下面的额外属性：

location：存放文件的目录的绝对路径。默认为MEDIA_ROOT设置的值。
base_url：用于访问文件的URL的基础前缀。默认为MEDIA_URL的值。
file_permissions_mode：文件的系统权限。默认为FILE_UPLOAD_PERMISSIONS配置项的值。
directory_permissions_mode：目录的系统权限。默认为FILE_UPLOAD_DIRECTORY_PERMISSIONS配置项的值。

FileSystemStorage类实现了全套的我们在Storage类中介绍过的子类必须实现的方法。

但是要注意， FileSystemStorage.delete() 方法如果删除不存在的文件，不会引发异常。

下面的代码将上传文件存储到 /media/photos ，而不是你在 MEDIA_ROOT 中设置的路径：

from django.core.files.storage import FileSystemStorage
from django.db import models

# 自定义存储路径
fs = FileSystemStorage(location='/media/photos')

class Car(models.Model):
    ...
    photo = models.ImageField(storage=fs)

Django 3.1开始，FileSystemStorage.save()方法支持使用pathlib.Path类，并且支持回调函数形式的storage参数，如下所示：

from django.conf import settings
from django.db import models
from .storages import MyLocalStorage, MyRemoteStorage


def select_storage():
    return MyLocalStorage() if settings.DEBUG else MyRemoteStorage()


class MyModel(models.Model):
    my_file = models.FileField(storage=select_storage)

这就赋予了我们在运行过程中，动态选择存储类的能力。

InMemoryStorage类

class InMemoryStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)

Django在4.2版本中新增了InMemoryStorage类，从名字就可以看出，这是一个基于内存的存储类。它没有持久化特性，但是比磁盘存储速度更快。

具备以下属性：

location：存放文件的目录的绝对路径。默认为MEDIA_ROOT设置的值。
base_url：用于访问文件的URL的基础前缀。默认为MEDIA_URL的值。
file_permissions_mode：文件的系统权限。默认为FILE_UPLOAD_PERMISSIONS配置项的值。
directory_permissions_mode：目录的系统权限。默认为FILE_UPLOAD_DIRECTORY_PERMISSIONS配置项的值。

自定义Storage类

如果你需要自定义文件储存功能，比如把文件储存在远程系统中，你可以自己编写Storage类来实现这一功能。

实际上大多数情况下，对于本地磁盘存储，我们直接使用FileSystemStorage即可，对于别的需求，一般有第三方的存储类可用，在Django的生态库里查找即可。自己编写Storage类存在可靠性、可用性、安全性、性能问题，新手绕行，老手慎重。

但无论如何，这里还是给出基本的编写过程，以供参考：

第一：必须继承 Django.core.files.storage.Storage

from django.core.files.storage import Storage

class MyStorage(Storage):
    ...

第二：Django 必须能以无参数的状态，实例化你的存储系统。这意味着所有的设置项都应从 dango.conf.settings 中获取:

from django.conf import settings
from django.core.files.storage import Storage

class MyStorage(Storage):
    def __init__(self, option=None):
        if not option:
            option = settings.CUSTOM_STORAGE_OPTIONS
        ...

第三：在你的存储类中，除了其他自定义的方法外，还必须实现 _open() 以及 _save() 方法。另外，如果你的类提供了本地文件存储功能，还必须重写 path() 方法。

第四：你的存储类必须是 deconstructible可解构的，以便在迁移中的字段上使用它时可以序列化。

第五：尽量实现下列方法：

Storage.delete()
Storage.exists()
Storage.listdir()
Storage.size()
Storage.url()

举例来说，如果列出某些存储后端的内容的代价很昂贵，那么你可以不实现 Storage.listdir() 方法。

另一个例子是只处理写入文件的后端。在这种情况下，你不需要实现上述任何方法。

另外，下面是经常会用到专为自定义存储对象设计的两个钩子函数：

_open(name, mode='rb')：真正执行打开文件功能的方法。它将被 Storage.open() 调用。
_save(name, content)：真正执行保存功能的方法。它将被 Storage.save()调用。

要使用自定义的Storage类，只需要在settings.py的STORAGES配置中添加它，然后就可以在代码中引用了。

HttpResponse对象生成CSV文件

评论总数： 6

点击登录后方可评论

打卡第二遍

By 多浪的河流 On 2020年11月6日 15:53 回复

这个直接翻译过来理解起来还是有点乱啊

By 尴尬村村长 On 2019年8月28日 16:55 回复

form类怎么映射为表单的html文件都没有讲解就直接开始用了，完全一脸懵逼啊，form类怎么作为表单在页面呈现啊？

By 王希知 On 2019年3月14日 21:43 回复

老师这from.py里面没有ModelFormWithFileField啊？

By WEI丶weiksjsks On 2018年1月31日 22:00 回复

而是特指你自己预先创建的那个带有文件上传字段的模型类

博主回复 WEI丶weiksjsks 2018年1月31日 22:34 回复

我看的时候也是感觉怪怪的，感觉还是要把这些文件名做区分比较好，一个文件名代表一个意思，不要有其他的意思

GardenBaby_ 回复 WEI丶weiksjsks 2020年1月12日 15:56 回复