| 1 |
============= |
|---|
| 2 |
API stability |
|---|
| 3 |
============= |
|---|
| 4 |
|
|---|
| 5 |
Although Django has not reached a 1.0 release, the bulk of Django's public APIs are |
|---|
| 6 |
stable as of the 0.95 release. This document explains which APIs will and will not |
|---|
| 7 |
change before the 1.0 release. |
|---|
| 8 |
|
|---|
| 9 |
What "stable" means |
|---|
| 10 |
=================== |
|---|
| 11 |
|
|---|
| 12 |
In this context, stable means: |
|---|
| 13 |
|
|---|
| 14 |
- All the public APIs -- everything documented in the linked documents, and |
|---|
| 15 |
all methods that don't begin with an underscore -- will not be moved or |
|---|
| 16 |
renamed without providing backwards-compatible aliases. |
|---|
| 17 |
|
|---|
| 18 |
- If new features are added to these APIs -- which is quite possible -- |
|---|
| 19 |
they will not break or change the meaning of existing methods. In other |
|---|
| 20 |
words, "stable" does not (necessarily) mean "complete." |
|---|
| 21 |
|
|---|
| 22 |
- If, for some reason, an API declared stable must be removed or replaced, it |
|---|
| 23 |
will be declared deprecated but will remain in the API until at least |
|---|
| 24 |
version 1.1. Warnings will be issued when the deprecated method is |
|---|
| 25 |
called. |
|---|
| 26 |
|
|---|
| 27 |
- We'll only break backwards compatibility of these APIs if a bug or |
|---|
| 28 |
security hole makes it completely unavoidable. |
|---|
| 29 |
|
|---|
| 30 |
Stable APIs |
|---|
| 31 |
=========== |
|---|
| 32 |
|
|---|
| 33 |
These APIs are stable: |
|---|
| 34 |
|
|---|
| 35 |
- `Caching`_. |
|---|
| 36 |
|
|---|
| 37 |
- `Custom template tags and libraries`_ (with the possible exception for a |
|---|
| 38 |
small change in the way templates are registered and loaded). |
|---|
| 39 |
|
|---|
| 40 |
- `Database lookup`_ (with the exception of validation; see below). |
|---|
| 41 |
|
|---|
| 42 |
- `django-admin utility`_. |
|---|
| 43 |
|
|---|
| 44 |
- `FastCGI integration`_. |
|---|
| 45 |
|
|---|
| 46 |
- `Flatpages`_. |
|---|
| 47 |
|
|---|
| 48 |
- `Generic views`_. |
|---|
| 49 |
|
|---|
| 50 |
- `Internationalization`_. |
|---|
| 51 |
|
|---|
| 52 |
- `Legacy database integration`_. |
|---|
| 53 |
|
|---|
| 54 |
- `Model definition`_ (with the exception of generic relations; see below). |
|---|
| 55 |
|
|---|
| 56 |
- `mod_python integration`_. |
|---|
| 57 |
|
|---|
| 58 |
- `Redirects`_. |
|---|
| 59 |
|
|---|
| 60 |
- `Request/response objects`_. |
|---|
| 61 |
|
|---|
| 62 |
- `Sending email`_. |
|---|
| 63 |
|
|---|
| 64 |
- `Sessions`_. |
|---|
| 65 |
|
|---|
| 66 |
- `Settings`_. |
|---|
| 67 |
|
|---|
| 68 |
- `Syndication`_. |
|---|
| 69 |
|
|---|
| 70 |
- `Template language`_ (with the exception of some possible disambiguation |
|---|
| 71 |
of how tag arguments are passed to tags and filters). |
|---|
| 72 |
|
|---|
| 73 |
- `Transactions`_. |
|---|
| 74 |
|
|---|
| 75 |
- `URL dispatch`_. |
|---|
| 76 |
|
|---|
| 77 |
You'll notice that this list comprises the bulk of Django's APIs. That's right |
|---|
| 78 |
-- most of the changes planned between now and Django 1.0 are either under the |
|---|
| 79 |
hood, feature additions, or changes to a few select bits. A good estimate is |
|---|
| 80 |
that 90% of Django can be considered forwards-compatible at this point. |
|---|
| 81 |
|
|---|
| 82 |
That said, these APIs should *not* be considered stable, and are likely to |
|---|
| 83 |
change: |
|---|
| 84 |
|
|---|
| 85 |
- `Forms and validation`_ will most likely be completely rewritten to |
|---|
| 86 |
deemphasize Manipulators in favor of validation-aware models. |
|---|
| 87 |
|
|---|
| 88 |
- `Serialization`_ is under heavy development; changes are likely. |
|---|
| 89 |
|
|---|
| 90 |
- The `authentication`_ framework is changing to be far more flexible, and |
|---|
| 91 |
API changes may be necessary. |
|---|
| 92 |
|
|---|
| 93 |
- Generic relations will most likely be moved out of core and into the |
|---|
| 94 |
content-types contrib package to avoid core dependancies on optional |
|---|
| 95 |
components. |
|---|
| 96 |
|
|---|
| 97 |
- The comments framework, which is yet undocumented, will likely get a complete |
|---|
| 98 |
rewrite before Django 1.0. Even if the change isn't quite that drastic, |
|---|
| 99 |
there will at least be moderate changes. |
|---|
| 100 |
|
|---|
| 101 |
.. _caching: ../cache/ |
|---|
| 102 |
.. _custom template tags and libraries: ../templates_python/ |
|---|
| 103 |
.. _database lookup: ../db-api/ |
|---|
| 104 |
.. _django-admin utility: ../django-admin/ |
|---|
| 105 |
.. _fastcgi integration: ../fastcgi/ |
|---|
| 106 |
.. _flatpages: ../flatpages/ |
|---|
| 107 |
.. _generic views: ../generic_views/ |
|---|
| 108 |
.. _internationalization: ../i18n/ |
|---|
| 109 |
.. _legacy database integration: ../legacy_databases/ |
|---|
| 110 |
.. _model definition: ../model-api/ |
|---|
| 111 |
.. _mod_python integration: ../modpython/ |
|---|
| 112 |
.. _redirects: ../redirects/ |
|---|
| 113 |
.. _request/response objects: ../request_response/ |
|---|
| 114 |
.. _sending email: ../email/ |
|---|
| 115 |
.. _sessions: ../sessions/ |
|---|
| 116 |
.. _settings: ../settings/ |
|---|
| 117 |
.. _syndication: ../syndication/ |
|---|
| 118 |
.. _template language: ../templates/ |
|---|
| 119 |
.. _transactions: ../transactions/ |
|---|
| 120 |
.. _url dispatch: ../url_dispatch/ |
|---|
| 121 |
.. _forms and validation: ../forms/ |
|---|
| 122 |
.. _serialization: ../serialization/ |
|---|
| 123 |
.. _authentication: ../authentication/ |
|---|
