Django在处理文件上传时,文件数据会被打包封装在request.FILES
中。
首先,写一个form模型,它必须包含一个FileField
:
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}) # 思考一下这个return语句是否可以缩进到else语句中呢?
请注意,必须将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 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})
如果要使用一个表单字段同时上传多个文件,需要设置字段HTML标签的multiple属性为True,如下所示:
# forms.py from django import forms class FileFieldForm(forms.Form): file_field = forms.FileField(widget=forms.ClearableFileInput(attrs={'multiple': True}))
然后,自己编写一个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) files = request.FILES.getlist('file_field') if form.is_valid(): for f in files: ... # 对每个文件做处理 return self.form_valid(form) else: return self.form_invalid(form)
当用户上传一个文件的时候,Django会把文件数据传递给上传文件处理器。
上传处理器的配置定义在FILE_UPLOAD_HANDLERS
中,默认为:
["django.core.files.uploadhandler.MemoryFileUploadHandler", "django.core.files.uploadhandler.TemporaryFileUploadHandler"]
MemoryFileUploadHandler
和TemporaryFileUploadHandler
定义了Django的默认文件上传行为:将小文件读取到内存中,大文件放置在磁盘中。
你可以编写自己的 handlers 来自定义如何处理文件。比如,你可以使用自定义强制处理用户层面的配额,动态压缩数据,渲染进度条,甚至可以将数据发送到其他存储地址而不是本地。
在你保存上传文件之前,数据需要储存在某个地方。通常,如果上传文件小于2.5MB,Django会把整个内容存到内存。 这意味着,文件的保存仅仅涉及到内存中的读取和磁盘的写入,所以非常快。
但是,如果上传的文件很大,Django会把它写入一个临时文件,储存在你的系统临时目录中。在类Unix的平台下,Django会生成一个文件,名称类似于/tmp/tmpzfp6I6.upload
。
有时候某些视图需要不同的上传行为。也就是说,在视图中动态修改处理器列表,即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
在详细介绍Django对文件进行处理的功能之前,我们要了解一些它的基本概念、组织方式、使用套路、主要的类和继承关系。
如果你不了解这些,那么复杂的源码、交错的官方文档会让你陷入泥坑。不知道怎么用?什么时候用?用什么?为什么这么用?整个一团乱!
这些代码都位于django.core.files
模块中,它们主要包括:
File
类:Django实现File的基类ContentFile
类:继承了File类,不同之处是它处理的是字符串ImageFile
类:继承了File类,添加了图像的宽度和长度像素值File
类的其它子类:实际上Django为File
类还编写了一系列Upload...
子类,只是使用较少。settings.DEFAULT_FILE_STORAGE
:一个Django配置项,用来指定默认的文件存储类。默认值为'django.core.files.storage.FileSystemStorage'
,在globa_settings
中。get_storage_class()
方法:Django提供的一个函数,通过字符串反射的方式获取指定的存储类或者DEFAULT_FILE_STORAGE
设置的存储类DefaultStorage
类:对get_storage_class()
方法返回的对象类的进一步封装default_storage
:DefaultStorage
类的实例Storage
类:Django源码中所有存储类的基类,提供通用的接口APIFileSystemStorage
:继承了Storage
类,是Django原生实现的最重要、最常用、最普通的存储类。我们绝大多数时间实际使用的就是它!Django设计了自己的文件对象。要记住,Django的File对象可以脱离本章的文件上传概念,独立使用!
File 类是围绕Python原生file对象的轻度包装,添加了一些Django特有的东西。Django在内部使用File类的实例来表示文件对象。
每个File对象都包含下面的属性和方法:
MEDIA_ROOT
定义的相对路径部分。open(mode=None):打开或者重新打开文件。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
类直接继承了File
类,但是前者操作的是字符串或者字节内容,而不是确切的文件。例如:
from django.core.files.base import ContentFile f1 = ContentFile("esta frase está en español") f2 = ContentFile(b"these are bytes")
Django为图片特别提供了一个内置类,也就是django.core.files.images.ImageFile
,它也继承了File类。只是额外增加了两个属性:
比如下面的模型,使用 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')
所有的 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
更多的 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:
使用提供的文件名和内容保存一个新的文件。这不会替换现有文件,但会创建一个新文件并更新该对象以指向该文件(也就是说保留外面那层用来封装的皮,把内部实际的文件内容替换掉)。如果save=True,将立刻执行模型的save方法。
>>> car.photo.save('myphoto.jpg', content, save=False) >>> car.save() # 等同于 >>> car.photo.save('myphoto.jpg', content, save=True)
从模型实例中删除文件。如果save=True,删除文件后将立刻执行模型的save方法。
在本章的一开始,我们实现了一个简单的文件上传例子。用户从浏览器通过POST发送过来文件数据,Django通过request.FILES
拿到数据,然后我们简单粗暴地使用Python语言原生的文件操作API将数据保存到了文件系统中,通常也就是硬盘中。
Django为了方便我们,提供了存储类,用来帮助我们将数据保存到存储器中,不需要手动调用open方法。
你在模型中可能看到过这样的写法:
file=models.FileField(storage='xxx',......)
其中的storage参数就是我们要指定的存储器类。如果你不指定这个参数,Django就会使用settings中配置的默认存储类进行处理。
所以,我们首先要知道DEFAULT_FILE_STORAGE
配置项,它指定Django默认的存储类,默认值为'django.core.files.storage.FileSystemStorage'
。一般情况下,我们无感静默使用,什么都不用做。
但是,Django总是千方百计为我们开后门,提供钩子。
Django额外又为我们提供了三种获取存储类的简便方法,用于在代码中动态修改要使用的存储类:
get_storage_class
(import_path=None)先看看它的源代码:
def get_storage_class(import_path=None): return import_string(import_path or settings.DEFAULT_FILE_STORAGE)
就两行!
它的作用是返回实现了存储API的存储类或者模块。
如果不提供参数,就使用settings.DEFAULT_FILE_STORAGE
,也就是上面说的。
如果提供参数,Django将使用Python的字符串反射机制,获取对应的模块。
get_storage_class
方法可以用在任何地方,它不属于任何类,是个独立函数。
DefaultStorage
类看看它的源代码:
class DefaultStorage(LazyObject): def _setup(self): self._wrapped = get_storage_class()()
三行!调用上面的get_storage_class
方法并实例化,然后赋值给_wrapped
,最后获得的就是'django.core.files.storage.FileSystemStorage'
。
default_storage
变量源代码如下:
default_storage = DefaultStorage()
根本就是DefaultStorage
的一个实例。所以,from django.core.files.storage import default_storage
其实就是获得了一个FileSystemStorage
对象。
看下面的例子:
>>> 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
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
异常。
方法很多,不一定全要掌握,重点是下面这几个:
实际上,我们不直接使用Storage类,而是使用FileSystemStorage 类,这也是Django实现的唯一的本地文件系统存储类。
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)
这就赋予了我们在运行过程中,动态选择存储类的能力。
如果你需要自定义文件储存功能,比如把文件储存在远程系统中,你可以自己编写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()
调用。
打卡第二遍
这个直接翻译过来理解起来还是有点乱啊
form类怎么映射为表单的html文件都没有讲解就直接开始用了,完全一脸懵逼啊,form类怎么作为表单在页面呈现啊?
老师 这from.py里面没有ModelFormWithFileField啊?
而是特指你自己预先创建的那个带有文件上传字段的模型类
我看的时候也是感觉怪怪的,感觉还是要把这些文件名做区分比较好,一个文件名代表一个意思,不要有其他的意思