|
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/ |