root/docs/trunk/api_stability.txt

==================
Stabilité de l'API 
==================

Bien que Django n'a pas encore atteint la version 1.0, la plupart des APIs
publiques sont stables depuis la version 0.95. Ce document explique quelles
APIs devraient ou non changer avant la sortie de la version 1.0.

Que signifie "stable"
====================

Dans ce contexte, stable signifie:

   - Toutes les APIs publiques -- tout ce qui est documenté dans les documents
     associés, et toutes les méthodes ne commençant pas par un trait souligné --
     ne seront pas touchées ou renommées sans fourniture de méthodes aux mêmes
     noms assurant la compatibilité descendante.
     
   - Si de nouvelles fonctionnalités sont ajoutées à ces APIs -- ce qui est
     tout à fait envisageable -- elles ne briseront ou ne changeront pas
     la raison d'être des méthodes existantes. En d'autres termes "stable"
     ne signifie pas (nécessairement) "finalisé".
          
   - Si, pour quelques raisons que ce soit, une API déclarée stable doit
     être supprimée ou remplacée, elle sera déclarée dépréciée mais restera
     intégrée à l'API jusqu'à la version 1.1 au minium. Des avertissements 
     seront levés quand la méthode dépréciée sera appelée.
          
   - Nous ne romprons la compatibilité descendante de ces APIs que si un
     bogue ou une faille de sécurité la rendent indispensable.
     
APIs stables 
============

Ces APIs sont stables:

   - `Gestion du cache`_.
   
   - `BibliothÚques et tags sur mesure des gabarits`_ (avec l'éventualité
     possible d'un petit changement sur la maniÚre dont les gabarits sont 
     enregistrés et chargés).
     
   - `Recherche en base de données`_ (exception faite de la validation; voir ci-dessous).
   
   - `Utilitaire django-admin`_.
   
   - `Intégration de FastCGI`_.
   
   - `Flatpages`_.
   
   - `Vues génériques`_.
   
   - `Internationalisation`_.
   
   - `Intégration de base de données existantes`_.
   
   - `Définition de modÚles`_ (exception faite des relations génériques; voir ci-dessous).
   
   - `Intégration de mod_python`_.
   
   - `Gestion des redirections`_.
   
   - `Objets request/response`_.
   
   - `Envoi d'emails`_.
   
   - `Sessions`_.
   
   - `ParamÚtres applicatifs`_.
   
   - `Syndication`_.
   
   - `Langage des gabarits`_ (exception faite de quelques possibles levées
     d'ambiguïtés concernant la maniÚre de passer des arguments aux tags et filtres).
   
   - `Transactions`_.
   
   - `Acheminement des URLs`_.   
   
Vous remarquerez que cette liste comprend la plupart des APIs de Django.
C'est exact -- la plupart des changements prévu entre maintenant et la version
1.0 sont actuellement en cours, ou ne concernent que de petites parties bien
précises. Une bonne estimation est que 90% de Django peut être considéré comme
compatible ascendant en ce moment.

Ceci étant dit, les APIs suivantes ne doivent pas être considérées comme
stables, et sont soumises à modification:

   - `Formulaires et validation`_ devrait probablement être complÚtement
     réécrit insistant moins sur les Manipulateurs en faveur des validations
     orientées modÚles.

   - `Serialisation`_ actuellement en grand chantier; modifications probables.

   - Le framework d'`authentification`_ est en cours de modification pour
     plus de flexibilité, et l'API changera nécessairement.

   - Les relations génériques seront probablement sorties du coeur du systÚme
     pour être placées dans le paquet contrib content-types évitant les
     dépendances entre le coeur du systÚme et les composants optionnels.
     
   - Le framework des commentaires, qui n'est pas encore documenté, sera
     probablement réécrit avant la version 1.0 de Django. Même si les changements
     apportés ne seront pas drastiques, il y aura néanmoins quelques changements
     modérés.
     
.. _gestion du cache: ../cache/
.. _bibliothÚques et tags sur mesure des gabarits: ../templates_python/
.. _recherche en base de données: ../db-api/
.. _utilitaire django-admin: ../django-admin/
.. _integration de fastcgi: ../fastcgi/
.. _flatpages: ../flatpages/
.. _vues géneriques: ../generic_views/
.. _internationalisation: ../i18n/
.. _integration de base de données existantes: ../legacy_databases/
.. _definition de modÚles: ../model-api/
.. _integration de mod_python: ../modpython/
.. _gestion des redirections: ../redirects/
.. _objets request/response: ../request_response/
.. _envoi d'emails: ../email/
.. _sessions: ../sessions/
.. _paramÚtres applicatifs: ../settings/
.. _syndication: ../syndication/
.. _langage des gabarits : ../templates/
.. _transactions: ../transactions/
.. _acheminement des URLs: ../url_dispatch/
.. _formulaires et validation: ../forms/
.. _serialisation: ../serialization/
.. _authentification: ../authentication/
A