..
.. META INFORMATION OF TRANSLATION
..
..   $TranslationStatus: Done, waiting for revision. $
..   $OriginalRevision: 14834 $
..   $TranslationAuthors: Robson Mendonça $
..
.. INFO OF THIS FILE (DO NOT EDIT! UPDATED BY SUBVERSION)
..
..   $HeadURL$
..   $LastChangedRevision$
..   $LastChangedBy$
..   $LastChangedDate$
..

====================
Gerenciando arquivos
====================

.. versionadded:: 1.0

Este documento descre a API de acesso a arquivos do Django.

Por padrão, o Django armazena arquivos localmente, usando as configurações
:setting:`MEDIA_ROOT` e :setting:`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.

.. _sistema de armazenamento: `Armazenamento de arquivo`_

Usando arquivos em models
=========================

Quando você usa um :class:`~django.db.models.FileField` ou
:class:`~django.db.models.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.

.. _objeto file nativo: http://docs.python.org/lib/bltin-file-objects.html

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 :class:`~django.core.files.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
:setting:`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
:doc:`/howto/custom-file-storage` 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 :doc:`/ref/files/storage` 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 :setting:`MEDIA_ROOT`.
``base_url``            Opicional. URL que serve o arquivo armazenado em
                        seu local. Se omitido, ele será o padrão definido
                        no seu :setting:`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 :doc:`sistemas de armazenamento customizados </howto/custom-file-storage>`
funcionam da mesma forma: você pode passá-los como o argumento ``storage`` para
um ``FileField``.