Este documento descre a API de acesso a arquivos do Django.
Por padrão, o Django armazena arquivos localmente, usando as configurações MEDIA_ROOT e MEDIA_URL. O exemplos abaixo assumem que você está usando estes padrões.
No entanto, o Django provê formas de se criar um sistema de armazenamento customizado, que permite você personalizar completamente, onde e como o Django armazena arquivos. A segunda metade deste documento descreve como esses sistemas de armazenamento funcionam.
Quando você usa um FileField ou ImageField, o Django provê um conjunto de APIs que você pode usar para negociar com este arquivo.
Considere o seguinte model, usando um ImageField para armazenar uma foto:
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')
Qualquer instância de Car terá um atributo photo que você pode usar para obter os detalhes da foto anexa:
>>> car = Car.objects.get(name="57 Chevy")
>>> car.photo
<ImageFieldFile: chevy.jpg>
>>> car.photo.name
u'cars/chevy.jpg'
>>> car.photo.path
u'/media/cars/chevy.jpg'
>>> car.photo.url
u'http://media.example.com/cars/chevy.jpg'
Este objeto -- car.photo no exemplo -- é um objeto File, o que significa que ele tem todos os métodos e atributos descritos abaixo.
Internamente, o Django usa um django.core.files.File toda vez que ele precisa representar um arquivo. Este objeto é um pequeno contorno ao objeto file nativo do Python com algumas adições específicas do Django.
Na maior parte do tempo você simplesmente irá usar um File que o Django fornece a você (i.e. um arquivo atachado em um model, como mostrado acima, ou talvez um arquivo de upload).
Se você precisa construir um File você mesmo, o caminho mais fácil é criar um usando o objeto nativo file do Python:
>>> from django.core.files import File
# Cria um objeto file do Python usando open()
>>> f = open('/tmp/hello.world', 'w')
>>> myfile = File(f)
Agora você pode usar qualquer atributo ou método do File documentado na classe File.
Por trás das cenas, o Django se encarrega das decições sobre como e onde os arquivos são armazenados no sistema de arquivos. Este é um objeto que na verdade entende coisas como sistema de arquivos, abertura e leitura de arquivos, etc.
O sistema de armazenamento padrão do Django é dado pela configuração DEFAULT_FILE_STORAGE; se você não provê explicitamente um sistema de armazenamento, é este que será utilizado.
Veja abaixo detalhes do sistema de armazenamento nativo, e veja Escrevendo um sistema de armazenamento customizado para mais informações sobre criar seu próprio sistema de armazenamento.
Embora a maior parte do tempo você pretenda utilizar um objeto File (que se encarrega de armazenar os arquivos apropriadamente), você pode usar sistemas de armazenamento diretamente. Você pode criar uma instância de alguma classe customizada de armazenamento de arquivos, ou -- o que é mais frequente -- você pode usar o sistema padrão de armazenamento global:
>>> from django.core.files.storage import default_storage
>>> from django.core.files.base import ContentFile
>>> path = default_storage.save('/path/to/file', ContentFile('new content'))
>>> path
u'/path/to/file'
>>> default_storage.size(path)
11
>>> default_storage.open(path).read()
'new content'
>>> default_storage.delete(path)
>>> default_storage.exists(path)
False
Consulte API de armazenamento de arquivos. para saber mais sobre a API de armazenamento de arquivos.
O Django vem com uma classe nativa FileSystemStorage (definida em django.core.files.storage) que implementa o sistema de arquivos básico local. Seu construtor recebe dois argumentos:
| Argumento | Descrição |
|---|---|
| location | Opicional. O caminho absoluto para o diretório que receberá os arquivos. Se omitido, ele será setado com o valor do MEDIA_ROOT. |
| base_url | Opicional. URL que serve o arquivo armazenado em seu local. Se omitido, ele será o padrão definido no seu MEDIA_URL. |
Por exemplo, o seguinte código irá armazenar os arquivos enviados em /media/photos independentemente do que seu MEDIA_ROOT é:
from django.db import models
from django.core.files.storage import FileSystemStorage
fs = FileSystemStorage(location='/media/photos')
class Car(models.Model):
...
photo = models.ImageField(storage=fs)
Os sistemas de armazenamento customizados funcionam da mesma forma: você pode passá-los como o argumento storage para um FileField.
Dec 26, 2011