.. .. META INFORMATION OF TRANSLATION .. .. $TranslationStatus: Done $ .. $OriginalRevision: 11298 $ .. $TranslationAuthors: Robson Mendonça $ .. .. INFO OF THIS FILE (DO NOT EDIT! UPDATED BY SUBVERSION) .. .. $HeadURL$ .. $LastChangedRevision$ .. $LastChangedBy$ .. $LastChangedDate$ .. =================== Estabilidade de API =================== :doc:`O release do Django 1.0 ` vem com a promessa de estabilidade de API e compatibilidade futura. Em resumo, isto significa que o código que você construir utilizando o Django 1.0 irá funcionar com 1.1 sem mudanças, e você precisará fazer somente pequenas mudanças para qualquer release 1.x. O que "stable" significa ======================== Neste contexto, "stable" significa: - Todas as APIs públicas -- tudo que está documentado nos links abaixo, e todos os métodos que não comecem com um underscore -- não serão movidas nem renomeadas sem fornecer aliases de compatibilidade anterior. - Se novas funcionalidades são adicionadas a essas APIs -- o que é bem possível -- elas não irão quebrar ou mudar o significado dos métodos existentes. Em outras palavras, "stable" não significa, necessariamente, "completo". - Se, por alguma razão, uma API declarada "stable" tiver que ser removida ou substituída, ela será declarada obsoleta, porém irá permanecer até, pelo menos, duas novas versões secundárias. Avisos serão feitos quando um método obsoleto for chamado. Veja :ref:`official-releases` para mais detalhes de como a numeração das versões do Django funciona, e como as funcionalidades entrarão em desuso. - Nós somente iremos quebrar a compatibilidade anterior dessas APIs se um bug ou uma falha de segurança fizer com que seja completamente inevitável. APIs "stable" ============= Geralmente, tudo que foi documentado -- com excessão de qualquer item da :ref:`area interna ` é considerado "stable" na versão 1.0. Isto inclui estas APIs: - :doc:`Autorização ` - :doc:`Caching `. - :doc:`Definição de Model, gerenciadores, consultas e transações ` - :doc:`Envio de e-email `. - :doc:`Manipulação de arquivos e armazenamento ` - :doc:`Formulários ` - :doc:`Manipulação de requisições/respostas HTTP `, incluíndo envio de arquivos, middleware, sessões, resolução de URL, view, e "shortcut" APIs. - :doc:`Generic views `. - :doc:`Internacionalização `. - :doc:`Paginação ` - :doc:`Serialização ` - :doc:`Signals ` - :doc:`Templates `, incluíndo a linguagem, :doc:`APIs de template ` a nível do Python, e :doc:`bibliotecas e tags customizadas de template `. Nós podemos adicionar novas tags de template no futuro, e os nomes podem inadvertidamente chocar-se com tags de template externas. Antes de adicionar algo como tags, esteja seguro de que o Django mostrará um erro caso tente carregar tags com nomes duplicados. - :doc:`Testes ` - :doc:`Utilitário django-admin `. - :doc:`Middleware embutido ` - :doc:`Objetos request/response `. - :doc:`Settings `. Note, embora a :doc:`lista de configurações ` possa ser conciderada completa, nós podemos -- e provavelmente iremos -- adicionar novas configurações nas versões futuras. Este é um dos muitos lugares onde "'stable' não significa 'completo'". - :doc:`Signals embutidos `. Como nas settings, nós iremos provavelmente adicionar novos sinais no futuro, mas os existentes não devem quebrar. - :doc:`Manipulação de unicode `. - Tudo coberto pelos :ref:`guias HOWTO `. ``django.utils`` ---------------- A maioria dos módulos em ``django.utils`` são projetados para uso interno. Somente as seguintes partes do ``django.utils`` podem ser consideradas estáveis: - ``django.utils.cache`` - ``django.utils.datastructures.SortedDict`` -- somente está classe em particular; o resto do módulo é para uso interno. - ``django.utils.encoding`` - ``django.utils.feedgenerator`` - ``django.utils.http`` - ``django.utils.safestring`` - ``django.utils.translation`` - ``django.utils.tzinfo`` Exceções ======== Existem algumas poucas exceções para esta promessa de estabilidade e compatibilidade reversa. Correções de segurança ---------------------- Se nós tomarmos consciência de um problema de segurança -- esperamos sigam a nossa :ref:`política de relato de segurança ` -- nós iremos fazer tudo o que for necessário para corrigí-lo. Isto pode significar quebra de compatibilidade; A segurança triunfa sobre a garantia de compatibilidade. Aplicações contribuídas (``django.contrib``) -------------------------------------------- Nós faremos tudo para manter essas APIs estáveis -- e não temos planos de quebrar qualquer aplicação do contrib -- esta é uma área que terá mais fluxo entre os releases. Como a web evolui, o Django também deve evoluir com ela. No entanto, eventuais alterações nas aplicações do contrib virão com uma importante garantia: faremos o necessário para que seja possível utilizar uma versão mais antiga de uma aplicação do contrib se precisarmos fazer alterações. Desta forma, se o Django 1.5 vem com uma incompatibilidade no ``django.contrib.flatpages``, nós faremos de forma que você continue utilizando o Django 1.4 em paralelo com o Django 1.5. Isto continuará permitindo atualizações fáceis. Historicamente, aplicações em ``django.contrib`` têm sido mais estáveis que o núcleo, então, na pratica, nós provavelmente nunca teremos que abrir essa exceção. Entretanto, é importante observar se você está construindo aplicações que dependam do ``django.contrib``. APIs marcadas como internal --------------------------- Algumas APIs são explicitamente marcadas como "internal" (interna, em inglês) de algumas maneiras: - Algumas documentações referem e mencionam as partes internas como tal. Se a documentação diz que algo é interno, nós reservamos o direito de mudá-lo. - Funções, métodos, e outros objetos pré-fixados por um sublinhado (``_``). Este é um padrão do Python para indicar que algo é privado; se um método começa com um ``_``, ele pertence a API interna.