121 lines
3.8 KiB
Plaintext
121 lines
3.8 KiB
Plaintext
=============
|
|
API stability
|
|
=============
|
|
|
|
Although Django has not reached a 1.0 release, the bulk of Django's public APIs are
|
|
stable as of the 0.95 release. This document explains which APIs will and will not
|
|
change before the 1.0 release.
|
|
|
|
What "stable" means
|
|
===================
|
|
|
|
In this context, stable means:
|
|
|
|
- All the public APIs -- everything documented in the linked documents, and
|
|
all methods that don't begin with an underscore -- will not be moved or
|
|
renamed without providing backwards-compatible aliases.
|
|
|
|
- If new features are added to these APIs -- which is quite possible --
|
|
they will not break or change the meaning of existing methods. In other
|
|
words, "stable" does not (necessarily) mean "complete."
|
|
|
|
- If, for some reason, an API declared stable must be removed or replaced, it
|
|
will be declared deprecated but will remain in the API until at least
|
|
version 1.1. Warnings will be issued when the deprecated method is
|
|
called.
|
|
|
|
- We'll only break backwards compatibility of these APIs if a bug or
|
|
security hole makes it completely unavoidable.
|
|
|
|
Stable APIs
|
|
===========
|
|
|
|
These APIs are stable:
|
|
|
|
- `Caching`_.
|
|
|
|
- `Custom template tags and libraries`_ (with the possible exception for a
|
|
small change in the way templates are registered and loaded).
|
|
|
|
- `Database lookup`_ (with the exception of validation; see below).
|
|
|
|
- `django-admin utility`_.
|
|
|
|
- `FastCGI integration`_.
|
|
|
|
- `Flatpages`_.
|
|
|
|
- `Generic views`_.
|
|
|
|
- `Internationalization`_.
|
|
|
|
- `Legacy database integration`_.
|
|
|
|
- `Model definition`_ (with the exception of generic relations; see below).
|
|
|
|
- `mod_python integration`_.
|
|
|
|
- `Redirects`_.
|
|
|
|
- `Request/response objects`_.
|
|
|
|
- `Sending email`_.
|
|
|
|
- `Sessions`_.
|
|
|
|
- `Settings`_.
|
|
|
|
- `Syndication`_.
|
|
|
|
- `Template language`_ (with the exception of some possible disambiguation
|
|
of how tag arguments are passed to tags and filters).
|
|
|
|
- `Transactions`_.
|
|
|
|
- `URL dispatch`_.
|
|
|
|
You'll notice that this list comprises the bulk of Django's APIs. That's right
|
|
-- most of the changes planned between now and Django 1.0 are either under the
|
|
hood, feature additions, or changes to a few select bits. A good estimate is
|
|
that 90% of Django can be considered forwards-compatible at this point.
|
|
|
|
That said, these APIs should *not* be considered stable, and are likely to
|
|
change:
|
|
|
|
- `Serialization`_ is under heavy development; changes are likely.
|
|
|
|
- The `authentication`_ framework is changing to be far more flexible, and
|
|
API changes may be necessary.
|
|
|
|
- Generic relations will most likely be moved out of core and into the
|
|
content-types contrib package to avoid core dependencies on optional
|
|
components.
|
|
|
|
- The comments framework, which is yet undocumented, will likely get a complete
|
|
rewrite before Django 1.0. Even if the change isn't quite that drastic,
|
|
there will at least be moderate changes.
|
|
|
|
.. _caching: ../cache/
|
|
.. _custom template tags and libraries: ../templates_python/
|
|
.. _database lookup: ../db-api/
|
|
.. _django-admin utility: ../django-admin/
|
|
.. _fastcgi integration: ../fastcgi/
|
|
.. _flatpages: ../flatpages/
|
|
.. _generic views: ../generic_views/
|
|
.. _internationalization: ../i18n/
|
|
.. _legacy database integration: ../legacy_databases/
|
|
.. _model definition: ../model-api/
|
|
.. _mod_python integration: ../modpython/
|
|
.. _redirects: ../redirects/
|
|
.. _request/response objects: ../request_response/
|
|
.. _sending email: ../email/
|
|
.. _sessions: ../sessions/
|
|
.. _settings: ../settings/
|
|
.. _syndication: ../syndication_feeds/
|
|
.. _template language: ../templates/
|
|
.. _transactions: ../transactions/
|
|
.. _url dispatch: ../url_dispatch/
|
|
.. _forms and validation: ../oldforms/
|
|
.. _serialization: ../serialization/
|
|
.. _authentication: ../authentication/
|