|
1 ============= |
|
2 API stability |
|
3 ============= |
|
4 |
|
5 :doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API |
|
6 stability and forwards-compatibility. In a nutshell, this means that code you |
|
7 develop against Django 1.0 will continue to work against 1.1 unchanged, and you |
|
8 should need to make only minor changes for any 1.X release. |
|
9 |
|
10 What "stable" means |
|
11 =================== |
|
12 |
|
13 In this context, stable means: |
|
14 |
|
15 - All the public APIs -- everything documented in the linked documents below, |
|
16 and all methods that don't begin with an underscore -- will not be moved or |
|
17 renamed without providing backwards-compatible aliases. |
|
18 |
|
19 - If new features are added to these APIs -- which is quite possible -- |
|
20 they will not break or change the meaning of existing methods. In other |
|
21 words, "stable" does not (necessarily) mean "complete." |
|
22 |
|
23 - If, for some reason, an API declared stable must be removed or replaced, it |
|
24 will be declared deprecated but will remain in the API for at least two |
|
25 minor version releases. Warnings will be issued when the deprecated method |
|
26 is called. |
|
27 |
|
28 See :ref:`official-releases` for more details on how Django's version |
|
29 numbering scheme works, and how features will be deprecated. |
|
30 |
|
31 - We'll only break backwards compatibility of these APIs if a bug or |
|
32 security hole makes it completely unavoidable. |
|
33 |
|
34 Stable APIs |
|
35 =========== |
|
36 |
|
37 In general, everything covered in the documentation -- with the exception of |
|
38 anything in the :doc:`internals area </internals/index>` is considered stable as |
|
39 of 1.0. This includes these APIs: |
|
40 |
|
41 - :doc:`Authorization </topics/auth>` |
|
42 |
|
43 - :doc:`Caching </topics/cache>`. |
|
44 |
|
45 - :doc:`Model definition, managers, querying and transactions |
|
46 </topics/db/index>` |
|
47 |
|
48 - :doc:`Sending e-mail </topics/email>`. |
|
49 |
|
50 - :doc:`File handling and storage </topics/files>` |
|
51 |
|
52 - :doc:`Forms </topics/forms/index>` |
|
53 |
|
54 - :doc:`HTTP request/response handling </topics/http/index>`, including file |
|
55 uploads, middleware, sessions, URL resolution, view, and shortcut APIs. |
|
56 |
|
57 - :doc:`Generic views </topics/http/generic-views>`. |
|
58 |
|
59 - :doc:`Internationalization </topics/i18n/index>`. |
|
60 |
|
61 - :doc:`Pagination </topics/pagination>` |
|
62 |
|
63 - :doc:`Serialization </topics/serialization>` |
|
64 |
|
65 - :doc:`Signals </topics/signals>` |
|
66 |
|
67 - :doc:`Templates </topics/templates>`, including the language, Python-level |
|
68 :doc:`template APIs </ref/templates/index>`, and :doc:`custom template tags |
|
69 and libraries </howto/custom-template-tags>`. We may add new template |
|
70 tags in the future and the names may inadvertently clash with |
|
71 external template tags. Before adding any such tags, we'll ensure that |
|
72 Django raises an error if it tries to load tags with duplicate names. |
|
73 |
|
74 - :doc:`Testing </topics/testing>` |
|
75 |
|
76 - :doc:`django-admin utility </ref/django-admin>`. |
|
77 |
|
78 - :doc:`Built-in middleware </ref/middleware>` |
|
79 |
|
80 - :doc:`Request/response objects </ref/request-response>`. |
|
81 |
|
82 - :doc:`Settings </ref/settings>`. Note, though that while the :doc:`list of |
|
83 built-in settings </ref/settings>` can be considered complete we may -- and |
|
84 probably will -- add new settings in future versions. This is one of those |
|
85 places where "'stable' does not mean 'complete.'" |
|
86 |
|
87 - :doc:`Built-in signals </ref/signals>`. Like settings, we'll probably add |
|
88 new signals in the future, but the existing ones won't break. |
|
89 |
|
90 - :doc:`Unicode handling </ref/unicode>`. |
|
91 |
|
92 - Everything covered by the :doc:`HOWTO guides </howto/index>`. |
|
93 |
|
94 ``django.utils`` |
|
95 ---------------- |
|
96 |
|
97 Most of the modules in ``django.utils`` are designed for internal use. Only |
|
98 the following parts of :doc:`django.utils </ref/utils>` can be considered stable: |
|
99 |
|
100 - ``django.utils.cache`` |
|
101 - ``django.utils.datastructures.SortedDict`` -- only this single class; the |
|
102 rest of the module is for internal use. |
|
103 - ``django.utils.encoding`` |
|
104 - ``django.utils.feedgenerator`` |
|
105 - ``django.utils.http`` |
|
106 - ``django.utils.safestring`` |
|
107 - ``django.utils.translation`` |
|
108 - ``django.utils.tzinfo`` |
|
109 |
|
110 Exceptions |
|
111 ========== |
|
112 |
|
113 There are a few exceptions to this stability and backwards-compatibility |
|
114 promise. |
|
115 |
|
116 Security fixes |
|
117 -------------- |
|
118 |
|
119 If we become aware of a security problem -- hopefully by someone following our |
|
120 :ref:`security reporting policy <reporting-security-issues>` -- we'll do |
|
121 everything necessary to fix it. This might mean breaking backwards compatibility; security trumps the compatibility guarantee. |
|
122 |
|
123 Contributed applications (``django.contrib``) |
|
124 --------------------------------------------- |
|
125 |
|
126 While we'll make every effort to keep these APIs stable -- and have no plans to |
|
127 break any contrib apps -- this is an area that will have more flux between |
|
128 releases. As the Web evolves, Django must evolve with it. |
|
129 |
|
130 However, any changes to contrib apps will come with an important guarantee: |
|
131 we'll make sure it's always possible to use an older version of a contrib app if |
|
132 we need to make changes. Thus, if Django 1.5 ships with a backwards-incompatible |
|
133 ``django.contrib.flatpages``, we'll make sure you can still use the Django 1.4 |
|
134 version alongside Django 1.5. This will continue to allow for easy upgrades. |
|
135 |
|
136 Historically, apps in ``django.contrib`` have been more stable than the core, so |
|
137 in practice we probably won't have to ever make this exception. However, it's |
|
138 worth noting if you're building apps that depend on ``django.contrib``. |
|
139 |
|
140 APIs marked as internal |
|
141 ----------------------- |
|
142 |
|
143 Certain APIs are explicitly marked as "internal" in a couple of ways: |
|
144 |
|
145 - Some documentation refers to internals and mentions them as such. If the |
|
146 documentation says that something is internal, we reserve the right to |
|
147 change it. |
|
148 |
|
149 - Functions, methods, and other objects prefixed by a leading underscore |
|
150 (``_``). This is the standard Python way of indicating that something is |
|
151 private; if any method starts with a single ``_``, it's an internal API. |
|
152 |