Gerenciando arquivos¶
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.
Usando arquivos em models¶
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.
O objeto File
¶
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 em
O objeto File.
Armazenamento de arquivo¶
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.
Objetos 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.
A classe nativa de armazenamento filesystem¶
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
.