124 lines
4.8 KiB
Plaintext
124 lines
4.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:
|
|
|
|
- `Forms and validation`_ will most likely be completely rewritten to
|
|
deemphasize Manipulators in favor of validation-aware models.
|
|
|
|
- `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 dependancies 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: http://www.djangoproject.com/documentation/cache/
|
|
.. _custom template tags and libraries: http://www.djangoproject.com/documentation/templates_python/
|
|
.. _database lookup: http://www.djangoproject.com/documentation/db_api/
|
|
.. _django-admin utility: http://www.djangoproject.com/documentation/django_admin/
|
|
.. _fastcgi integration: http://www.djangoproject.com/documentation/fastcgi/
|
|
.. _flatpages: http://www.djangoproject.com/documentation/flatpages/
|
|
.. _generic views: http://www.djangoproject.com/documentation/generic_views/
|
|
.. _internationalization: http://www.djangoproject.com/documentation/i18n/
|
|
.. _legacy database integration: http://www.djangoproject.com/documentation/legacy_databases/
|
|
.. _model definition: http://www.djangoproject.com/documentation/model_api/
|
|
.. _mod_python integration: http://www.djangoproject.com/documentation/modpython/
|
|
.. _redirects: http://www.djangoproject.com/documentation/redirects/
|
|
.. _request/response objects: http://www.djangoproject.com/documentation/request_response/
|
|
.. _sending email: http://www.djangoproject.com/documentation/email/
|
|
.. _sessions: http://www.djangoproject.com/documentation/sessions/
|
|
.. _settings: http://www.djangoproject.com/documentation/settings/
|
|
.. _syndication: http://www.djangoproject.com/documentation/syndication/
|
|
.. _template language: http://www.djangoproject.com/documentation/templates/
|
|
.. _transactions: http://www.djangoproject.com/documentation/transactions/
|
|
.. _url dispatch: http://www.djangoproject.com/documentation/url_dispatch/
|
|
.. _forms and validation: http://www.djangoproject.com/documentation/forms/
|
|
.. _serialization: http://www.djangoproject.com/documentation/serialization/
|
|
.. _authentication: http://www.djangoproject.com/documentation/authentication/
|