diff options
Diffstat (limited to 'parts/django/docs/misc')
| -rw-r--r-- | parts/django/docs/misc/api-stability.txt | 152 | ||||
| -rw-r--r-- | parts/django/docs/misc/design-philosophies.txt | 314 | ||||
| -rw-r--r-- | parts/django/docs/misc/distributions.txt | 36 | ||||
| -rw-r--r-- | parts/django/docs/misc/index.txt | 12 |
4 files changed, 0 insertions, 514 deletions
diff --git a/parts/django/docs/misc/api-stability.txt b/parts/django/docs/misc/api-stability.txt deleted file mode 100644 index 456d84b..0000000 --- a/parts/django/docs/misc/api-stability.txt +++ /dev/null @@ -1,152 +0,0 @@ -============= -API stability -============= - -:doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API -stability and forwards-compatibility. In a nutshell, this means that code you -develop against Django 1.0 will continue to work against 1.1 unchanged, and you -should need to make only minor changes for any 1.X release. - -What "stable" means -=================== - -In this context, stable means: - - - All the public APIs -- everything documented in the linked documents below, - 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 for at least two - minor version releases. Warnings will be issued when the deprecated method - is called. - - See :ref:`official-releases` for more details on how Django's version - numbering scheme works, and how features will be deprecated. - - - We'll only break backwards compatibility of these APIs if a bug or - security hole makes it completely unavoidable. - -Stable APIs -=========== - -In general, everything covered in the documentation -- with the exception of -anything in the :doc:`internals area </internals/index>` is considered stable as -of 1.0. This includes these APIs: - - - :doc:`Authorization </topics/auth>` - - - :doc:`Caching </topics/cache>`. - - - :doc:`Model definition, managers, querying and transactions - </topics/db/index>` - - - :doc:`Sending e-mail </topics/email>`. - - - :doc:`File handling and storage </topics/files>` - - - :doc:`Forms </topics/forms/index>` - - - :doc:`HTTP request/response handling </topics/http/index>`, including file - uploads, middleware, sessions, URL resolution, view, and shortcut APIs. - - - :doc:`Generic views </topics/http/generic-views>`. - - - :doc:`Internationalization </topics/i18n/index>`. - - - :doc:`Pagination </topics/pagination>` - - - :doc:`Serialization </topics/serialization>` - - - :doc:`Signals </topics/signals>` - - - :doc:`Templates </topics/templates>`, including the language, Python-level - :doc:`template APIs </ref/templates/index>`, and :doc:`custom template tags - and libraries </howto/custom-template-tags>`. We may add new template - tags in the future and the names may inadvertently clash with - external template tags. Before adding any such tags, we'll ensure that - Django raises an error if it tries to load tags with duplicate names. - - - :doc:`Testing </topics/testing>` - - - :doc:`django-admin utility </ref/django-admin>`. - - - :doc:`Built-in middleware </ref/middleware>` - - - :doc:`Request/response objects </ref/request-response>`. - - - :doc:`Settings </ref/settings>`. Note, though that while the :doc:`list of - built-in settings </ref/settings>` can be considered complete we may -- and - probably will -- add new settings in future versions. This is one of those - places where "'stable' does not mean 'complete.'" - - - :doc:`Built-in signals </ref/signals>`. Like settings, we'll probably add - new signals in the future, but the existing ones won't break. - - - :doc:`Unicode handling </ref/unicode>`. - - - Everything covered by the :doc:`HOWTO guides </howto/index>`. - -``django.utils`` ----------------- - -Most of the modules in ``django.utils`` are designed for internal use. Only -the following parts of :doc:`django.utils </ref/utils>` can be considered stable: - - - ``django.utils.cache`` - - ``django.utils.datastructures.SortedDict`` -- only this single class; the - rest of the module is for internal use. - - ``django.utils.encoding`` - - ``django.utils.feedgenerator`` - - ``django.utils.http`` - - ``django.utils.safestring`` - - ``django.utils.translation`` - - ``django.utils.tzinfo`` - -Exceptions -========== - -There are a few exceptions to this stability and backwards-compatibility -promise. - -Security fixes --------------- - -If we become aware of a security problem -- hopefully by someone following our -:ref:`security reporting policy <reporting-security-issues>` -- we'll do -everything necessary to fix it. This might mean breaking backwards compatibility; security trumps the compatibility guarantee. - -Contributed applications (``django.contrib``) ---------------------------------------------- - -While we'll make every effort to keep these APIs stable -- and have no plans to -break any contrib apps -- this is an area that will have more flux between -releases. As the Web evolves, Django must evolve with it. - -However, any changes to contrib apps will come with an important guarantee: -we'll make sure it's always possible to use an older version of a contrib app if -we need to make changes. Thus, if Django 1.5 ships with a backwards-incompatible -``django.contrib.flatpages``, we'll make sure you can still use the Django 1.4 -version alongside Django 1.5. This will continue to allow for easy upgrades. - -Historically, apps in ``django.contrib`` have been more stable than the core, so -in practice we probably won't have to ever make this exception. However, it's -worth noting if you're building apps that depend on ``django.contrib``. - -APIs marked as internal ------------------------ - -Certain APIs are explicitly marked as "internal" in a couple of ways: - - - Some documentation refers to internals and mentions them as such. If the - documentation says that something is internal, we reserve the right to - change it. - - - Functions, methods, and other objects prefixed by a leading underscore - (``_``). This is the standard Python way of indicating that something is - private; if any method starts with a single ``_``, it's an internal API. - diff --git a/parts/django/docs/misc/design-philosophies.txt b/parts/django/docs/misc/design-philosophies.txt deleted file mode 100644 index 631097a..0000000 --- a/parts/django/docs/misc/design-philosophies.txt +++ /dev/null @@ -1,314 +0,0 @@ -=================== -Design philosophies -=================== - -This document explains some of the fundamental philosophies Django's developers -have used in creating the framework. Its goal is to explain the past and guide -the future. - -Overall -======= - -.. _loose-coupling: - -Loose coupling --------------- - -.. index:: coupling; loose - -A fundamental goal of Django's stack is `loose coupling and tight cohesion`_. -The various layers of the framework shouldn't "know" about each other unless -absolutely necessary. - -For example, the template system knows nothing about Web requests, the database -layer knows nothing about data display and the view system doesn't care which -template system a programmer uses. - -Although Django comes with a full stack for convenience, the pieces of the -stack are independent of another wherever possible. - -.. _`loose coupling and tight cohesion`: http://c2.com/cgi/wiki?CouplingAndCohesion - -.. _less-code: - -Less code ---------- - -Django apps should use as little code as possible; they should lack boilerplate. -Django should take full advantage of Python's dynamic capabilities, such as -introspection. - -.. _quick-development: - -Quick development ------------------ - -The point of a Web framework in the 21st century is to make the tedious aspects -of Web development fast. Django should allow for incredibly quick Web -development. - -.. _dry: - -Don't repeat yourself (DRY) ---------------------------- - -.. index:: - single: DRY - single: Don't repeat yourself - -Every distinct concept and/or piece of data should live in one, and only one, -place. Redundancy is bad. Normalization is good. - -The framework, within reason, should deduce as much as possible from as little -as possible. - -.. seealso:: - - The `discussion of DRY on the Portland Pattern Repository`__ - - __ http://c2.com/cgi/wiki?DontRepeatYourself - -.. _explicit-is-better-than-implicit: - -Explicit is better than implicit --------------------------------- - -This, a `core Python principle`_, means Django shouldn't do too much "magic." -Magic shouldn't happen unless there's a really good reason for it. Magic is -worth using only if it creates a huge convenience unattainable in other ways, -and it isn't implemented in a way that confuses developers who are trying to -learn how to use the feature. - -.. _`core Python principle`: http://www.python.org/dev/peps/pep-0020/ - -.. _consistency: - -Consistency ------------ - -The framework should be consistent at all levels. Consistency applies to -everything from low-level (the Python coding style used) to high-level (the -"experience" of using Django). - -Models -====== - -Explicit is better than implicit --------------------------------- - -Fields shouldn't assume certain behaviors based solely on the name of the -field. This requires too much knowledge of the system and is prone to errors. -Instead, behaviors should be based on keyword arguments and, in some cases, on -the type of the field. - -Include all relevant domain logic ---------------------------------- - -Models should encapsulate every aspect of an "object," following Martin -Fowler's `Active Record`_ design pattern. - -This is why both the data represented by a model and information about -it (its human-readable name, options like default ordering, etc.) are -defined in the model class; all the information needed to understand a -given model should be stored *in* the model. - -.. _`Active Record`: http://www.martinfowler.com/eaaCatalog/activeRecord.html - -Database API -============ - -The core goals of the database API are: - -SQL efficiency --------------- - -It should execute SQL statements as few times as possible, and it should -optimize statements internally. - -This is why developers need to call ``save()`` explicitly, rather than the -framework saving things behind the scenes silently. - -This is also why the ``select_related()`` ``QuerySet`` method exists. It's an -optional performance booster for the common case of selecting "every related -object." - -Terse, powerful syntax ----------------------- - -The database API should allow rich, expressive statements in as little syntax -as possible. It should not rely on importing other modules or helper objects. - -Joins should be performed automatically, behind the scenes, when necessary. - -Every object should be able to access every related object, systemwide. This -access should work both ways. - -Option to drop into raw SQL easily, when needed ------------------------------------------------ - -The database API should realize it's a shortcut but not necessarily an -end-all-be-all. The framework should make it easy to write custom SQL -- entire -statements, or just custom ``WHERE`` clauses as custom parameters to API calls. - -URL design -========== - -Loose coupling --------------- - -URLs in a Django app should not be coupled to the underlying Python code. Tying -URLs to Python function names is a Bad And Ugly Thing. - -Along these lines, the Django URL system should allow URLs for the same app to -be different in different contexts. For example, one site may put stories at -``/stories/``, while another may use ``/news/``. - -Infinite flexibility --------------------- - -URLs should be as flexible as possible. Any conceivable URL design should be -allowed. - -Encourage best practices ------------------------- - -The framework should make it just as easy (or even easier) for a developer to -design pretty URLs than ugly ones. - -File extensions in Web-page URLs should be avoided. - -Vignette-style commas in URLs deserve severe punishment. - -.. _definitive-urls: - -Definitive URLs ---------------- - -.. index:: urls; definitive - -Technically, ``foo.com/bar`` and ``foo.com/bar/`` are two different URLs, and -search-engine robots (and some Web traffic-analyzing tools) would treat them as -separate pages. Django should make an effort to "normalize" URLs so that -search-engine robots don't get confused. - -This is the reasoning behind the :setting:`APPEND_SLASH` setting. - -Template system -=============== - -.. _separation-of-logic-and-presentation: - -Separate logic from presentation --------------------------------- - -We see a template system as a tool that controls presentation and -presentation-related logic -- and that's it. The template system shouldn't -support functionality that goes beyond this basic goal. - -If we wanted to put everything in templates, we'd be using PHP. Been there, -done that, wised up. - -Discourage redundancy ---------------------- - -The majority of dynamic Web sites use some sort of common sitewide design -- -a common header, footer, navigation bar, etc. The Django template system should -make it easy to store those elements in a single place, eliminating duplicate -code. - -This is the philosophy behind :ref:`template inheritance -<template-inheritance>`. - -Be decoupled from HTML ----------------------- - -The template system shouldn't be designed so that it only outputs HTML. It -should be equally good at generating other text-based formats, or just plain -text. - -XML should not be used for template languages ---------------------------------------------- - -.. index:: xml; suckiness of - -Using an XML engine to parse templates introduces a whole new world of human -error in editing templates -- and incurs an unacceptable level of overhead in -template processing. - -Assume designer competence --------------------------- - -The template system shouldn't be designed so that templates necessarily are -displayed nicely in WYSIWYG editors such as Dreamweaver. That is too severe of -a limitation and wouldn't allow the syntax to be as nice as it is. Django -expects template authors are comfortable editing HTML directly. - -Treat whitespace obviously --------------------------- - -The template system shouldn't do magic things with whitespace. If a template -includes whitespace, the system should treat the whitespace as it treats text --- just display it. Any whitespace that's not in a template tag should be -displayed. - -Don't invent a programming language ------------------------------------ - -The template system intentionally doesn't allow the following: - - * Assignment to variables - * Advanced logic - -The goal is not to invent a programming language. The goal is to offer just -enough programming-esque functionality, such as branching and looping, that is -essential for making presentation-related decisions. - -The Django template system recognizes that templates are most often written by -*designers*, not *programmers*, and therefore should not assume Python -knowledge. - -Safety and security -------------------- - -The template system, out of the box, should forbid the inclusion of malicious -code -- such as commands that delete database records. - -This is another reason the template system doesn't allow arbitrary Python code. - -Extensibility -------------- - -The template system should recognize that advanced template authors may want -to extend its technology. - -This is the philosophy behind custom template tags and filters. - -Views -===== - -Simplicity ----------- - -Writing a view should be as simple as writing a Python function. Developers -shouldn't have to instantiate a class when a function will do. - -Use request objects -------------------- - -Views should have access to a request object -- an object that stores metadata -about the current request. The object should be passed directly to a view -function, rather than the view function having to access the request data from -a global variable. This makes it light, clean and easy to test views by passing -in "fake" request objects. - -Loose coupling --------------- - -A view shouldn't care about which template system the developer uses -- or even -whether a template system is used at all. - -Differentiate between GET and POST ----------------------------------- - -GET and POST are distinct; developers should explicitly use one or the other. -The framework should make it easy to distinguish between GET and POST data. diff --git a/parts/django/docs/misc/distributions.txt b/parts/django/docs/misc/distributions.txt deleted file mode 100644 index d9281ad..0000000 --- a/parts/django/docs/misc/distributions.txt +++ /dev/null @@ -1,36 +0,0 @@ -=================================== -Third-party distributions of Django -=================================== - -Many third-party distributors are now providing versions of Django integrated -with their package-management systems. These can make installation and upgrading -much easier for users of Django since the integration includes the ability to -automatically install dependencies (like database adapters) that Django -requires. - -Typically, these packages are based on the latest stable release of Django, so -if you want to use the development version of Django you'll need to follow the -instructions for :ref:`installing the development version -<installing-development-version>` from our Subversion repository. - -If you're using Linux or a Unix installation, such as OpenSolaris, -check with your distributor to see if they already package Django. If -you're using a Linux distro and don't know how to find out if a package -is available, then now is a good time to learn. The Django Wiki contains -a list of `Third Party Distributions`_ to help you out. - -.. _`Third Party Distributions`: http://code.djangoproject.com/wiki/Distributions - - -For distributors -================ - -If you'd like to package Django for distribution, we'd be happy to help out! -Please join the `django-developers mailing list`_ and introduce yourself. - -We also encourage all distributors to subscribe to the `django-announce mailing -list`_, which is a (very) low-traffic list for announcing new releases of Django -and important bugfixes. - -.. _django-developers mailing list: http://groups.google.com/group/django-developers/ -.. _django-announce mailing list: http://groups.google.com/group/django-announce/ diff --git a/parts/django/docs/misc/index.txt b/parts/django/docs/misc/index.txt deleted file mode 100644 index b42baeb..0000000 --- a/parts/django/docs/misc/index.txt +++ /dev/null @@ -1,12 +0,0 @@ -Meta-documentation and miscellany -================================= - -Documentation that we can't find a more organized place for. Like that drawer in -your kitchen with the scissors, batteries, duct tape, and other junk. - -.. toctree:: - :maxdepth: 2 - - api-stability - design-philosophies - distributions |