FileExtensionValidator

Валидатор FileExtensionValidator применяется к полям типа FileField и ImageField в формах Django для проверки расширения загружаемых файлов. Он принимает список разрешенных расширений и проверяет, что имя загружаемого файла оканчивается на одно из них. Валидатор используется как в моделях, так и в формах, и автоматически вызывается при валидации формы через метод is_valid.

Основные параметры конструктора:

⁅b⁆allowed_extensions⁅/b⁆ - список разрешенных расширений файлов (например, ['pdf', 'docx', 'jpg']);
⁅b⁆message⁅/b⁆ - сообщение об ошибке, которое будет показано при несоответствии расширения (по умолчанию: "File extension “%(extension)s” is not allowed. Allowed extensions are: “%(allowed_extensions)s”.");
⁅b⁆code⁅/b⁆ - код ошибки (по умолчанию: "invalid_extension").

Синтаксис

from django.core.validators import FileExtensionValidator

# Использование в модели
file = models.FileField(
	upload_to='documents/',
	validators=[FileExtensionValidator(allowed_extensions=['pdf', 'docx'])]
)

# Использование в форме
file = forms.FileField(
	validators=[FileExtensionValidator(allowed_extensions=['jpg', 'png'])]
)

Пример

Создадим модель для загрузки документов с проверкой расширений:

from django.db import models
from django.core.validators import FileExtensionValidator

class Document(models.Model):
	title = models.CharField(max_length=100)
	file = models.FileField(
		upload_to='documents/',
		validators=[
			FileExtensionValidator(allowed_extensions=['pdf', 'doc', 'docx'])
		]
	)
	uploaded_at = models.DateTimeField(auto_now_add=True)
	
	def __str__(self):
		return self.title

Создадим форму для загрузки документов с дополнительной проверкой расширений:

from django import forms
from django.core.validators import FileExtensionValidator
from .models import Document

class DocumentForm(forms.ModelForm):
	class Meta:
		model = Document
		fields = ['title', 'file']
		
	def __init__(self, *args, **kwargs):
		super().__init__(*args, **kwargs)
		self.fields['file'].validators.append(
			FileExtensionValidator(
				allowed_extensions=['pdf', 'doc', 'docx'],
				message='Only PDF and Word documents are allowed.'
			)
		)

Используем форму в представлении для обработки загрузки файлов:

from django.shortcuts import render, redirect
from .forms import DocumentForm

def upload_document(request):
	if request.method == 'POST':
		form = DocumentForm(request.POST, request.FILES)
		if form.is_valid():
			form.save()
			return redirect('document_list')
	else:
		form = DocumentForm()
	return render(request, 'upload.html', {'form': form})

При попытке загрузить файл с недопустимым расширением пользователь увидит сообщение об ошибке:

"Only PDF and Word documents are allowed."

Пример

Валидатор FileExtensionValidator можно использовать с изображениями для ограничения загружаемых форматов:

from django.db import models
from django.core.validators import FileExtensionValidator

class GalleryImage(models.Model):
	title = models.CharField(max_length=100)
	image = models.ImageField(
		upload_to='gallery/',
		validators=[
			FileExtensionValidator(
				allowed_extensions=['jpg', 'jpeg', 'png', 'gif'],
				message='Only image files (JPEG, PNG, GIF) are allowed.'
			)
		]
	)
	description = models.TextField(blank=True)
	created_at = models.DateTimeField(auto_now_add=True)
	
	def __str__(self):
		return self.title

Создадим форму и проверим работу валидатора с различными расширениями:

from django import forms
from django.core.validators import FileExtensionValidator
from .models import GalleryImage

class GalleryImageForm(forms.ModelForm):
	class Meta:
		model = GalleryImage
		fields = ['title', 'image', 'description']
		
	def clean_image(self):
		image = self.cleaned_data.get('image')
		validator = FileExtensionValidator(
			allowed_extensions=['jpg', 'jpeg', 'png'],
			message='Only JPEG and PNG images are allowed.'
		)
		validator(image)
		return image

Попробуем загрузить изображение в неподдерживаемом формате:

# Попытка загрузить файл с расширением .bmp
form = GalleryImageForm(data={'title': 'Test Image'}, files={'image': bmp_file})

if not form.is_valid():
	res = form.errors['image']
	print(res)

Результат выполнения кода:

"Only JPEG and PNG images are allowed."

Пример

Валидатор можно использовать без модели для проверки файлов в чистых формах:

from django import forms
from django.core.validators import FileExtensionValidator

class FileUploadForm(forms.Form):
	file = forms.FileField(
		label='Select file',
		validators=[
			FileExtensionValidator(
				allowed_extensions=['txt', 'csv', 'json'],
				message='Please upload a text, CSV, or JSON file.'
			)
		]
	)
	description = forms.CharField(max_length=200, required=False)
	
	def clean_file(self):
		file = self.cleaned_data.get('file')
		if file.size > 1024 * 1024:  # 1 MB
			raise forms.ValidationError('File size must be under 1 MB.')
		return file

Проверим работу формы с допустимым и недопустимым расширением:

# Создание экземпляра формы
form = FileUploadForm()

# Проверка с недопустимым файлом
invalid_file = {'file': 'document.pdf'}
form_invalid = FileUploadForm(files=invalid_file)
if not form_invalid.is_valid():
	res = form_invalid.errors['file']
	print(res)

Результат выполнения кода:

"Please upload a text, CSV, or JSON file."

Смотрите также

класс FileField,
который представляет поле для загрузки файлов в формах
валидатор validate_image_file_extension,
который проверяет расширение файлов изображений
метод is_valid,
который запускает валидацию формы
атрибут errors,
который содержит ошибки валидации формы