This document explains some of the fundamental philosophies Django’s developers\nhave used in creating the framework. Its goal is to explain the past and guide\nthe future.
\nA fundamental goal of Django’s stack is loose coupling and tight cohesion.\nThe various layers of the framework shouldn’t “know” about each other unless\nabsolutely necessary.
\nFor example, the template system knows nothing about web requests, the database\nlayer knows nothing about data display and the view system doesn’t care which\ntemplate system a programmer uses.
\nAlthough Django comes with a full stack for convenience, the pieces of the\nstack are independent of another wherever possible.
\nDjango apps should use as little code as possible; they should lack\nboilerplate. Django should take full advantage of Python’s dynamic\ncapabilities, such as introspection.
\nThe point of a web framework in the 21st century is to make the tedious aspects\nof web development fast. Django should allow for incredibly quick web\ndevelopment.
\nEvery distinct concept and/or piece of data should live in one, and only one,\nplace. Redundancy is bad. Normalization is good.
\nThe framework, within reason, should deduce as much as possible from as little\nas possible.
\n\nThis is a core Python principle listed in PEP 20, and it means Django\nshouldn’t do too much “magic.” Magic shouldn’t happen unless there’s a really\ngood reason for it. Magic is worth using only if it creates a huge convenience\nunattainable in other ways, and it isn’t implemented in a way that confuses\ndevelopers who are trying to learn how to use the feature.
\nThe framework should be consistent at all levels. Consistency applies to\neverything from low-level (the Python coding style used) to high-level (the\n“experience” of using Django).
\nFields shouldn’t assume certain behaviors based solely on the name of the\nfield. This requires too much knowledge of the system and is prone to errors.\nInstead, behaviors should be based on keyword arguments and, in some cases, on\nthe type of the field.
\nModels should encapsulate every aspect of an “object,” following Martin\nFowler’s Active Record design pattern.
\nThis is why both the data represented by a model and information about\nit (its human-readable name, options like default ordering, etc.) are\ndefined in the model class; all the information needed to understand a\ngiven model should be stored in the model.
\nThe core goals of the database API are:
\nIt should execute SQL statements as few times as possible, and it should\noptimize statements internally.
\nThis is why developers need to call save() explicitly, rather than the\nframework saving things behind the scenes silently.
This is also why the FETCH_PEERS fetch mode\nexists. It’s an optional performance booster for the common case of selecting\nrelated objects for every peer in a QuerySet.
The database API should allow rich, expressive statements in as little syntax\nas possible. It should not rely on importing other modules or helper objects.
\nJoins should be performed automatically, behind the scenes, when necessary.
\nEvery object should be able to access every related object, systemwide. This\naccess should work both ways.
\nThe database API should realize it’s a shortcut but not necessarily an\nend-all-be-all. The framework should make it easy to write custom SQL – entire\nstatements, or just custom WHERE clauses as custom parameters to API calls.
URLs in a Django app should not be coupled to the underlying Python code. Tying\nURLs to Python function names is a Bad And Ugly Thing.
\nAlong these lines, the Django URL system should allow URLs for the same app to\nbe different in different contexts. For example, one site may put stories at\n/stories/, while another may use /news/.
URLs should be as flexible as possible. Any conceivable URL design should be\nallowed.
\nThe framework should make it just as easy (or even easier) for a developer to\ndesign pretty URLs than ugly ones.
\nFile extensions in web-page URLs should be avoided.
\nVignette-style commas in URLs deserve severe punishment.
\nTechnically, foo.com/bar and foo.com/bar/ are two different URLs, and\nsearch-engine robots (and some web traffic-analyzing tools) would treat them as\nseparate pages. Django should make an effort to “normalize” URLs so that\nsearch-engine robots don’t get confused.
This is the reasoning behind the APPEND_SLASH setting.
We see a template system as a tool that controls presentation and\npresentation-related logic – and that’s it. The template system shouldn’t\nsupport functionality that goes beyond this basic goal.
\nThe majority of dynamic websites use some sort of common sitewide design –\na common header, footer, navigation bar, etc. The Django template system should\nmake it easy to store those elements in a single place, eliminating duplicate\ncode.
\nThis is the philosophy behind template inheritance.
\nThe template system shouldn’t be designed so that it only outputs HTML. It\nshould be equally good at generating other text-based formats, or just plain\ntext.
\nUsing an XML engine to parse templates introduces a whole new world of human\nerror in editing templates – and incurs an unacceptable level of overhead in\ntemplate processing.
\nThe template system shouldn’t be designed so that templates necessarily are\ndisplayed nicely in WYSIWYG editors such as Dreamweaver. That is too severe of\na limitation and wouldn’t allow the syntax to be as nice as it is. Django\nexpects template authors are comfortable editing HTML directly.
\nThe template system shouldn’t do magic things with whitespace. If a template\nincludes whitespace, the system should treat the whitespace as it treats text\n– just display it. Any whitespace that’s not in a template tag should be\ndisplayed.
\nThe goal is not to invent a programming language. The goal is to offer just\nenough programming-esque functionality, such as branching and looping, that is\nessential for making presentation-related decisions. The Django Template\nLanguage (DTL) aims to avoid advanced logic.
\nThe template system, out of the box, should forbid the inclusion of malicious\ncode – such as commands that delete database records.
\nThis is another reason the template system doesn’t allow arbitrary Python code.
\nThe template system should recognize that advanced template authors may want\nto extend its technology.
\nThis is the philosophy behind custom template tags and filters.
\nWriting a view should be as simple as writing a Python function. Developers\nshouldn’t have to instantiate a class when a function will do.
\nViews should have access to a request object – an object that stores metadata\nabout the current request. The object should be passed directly to a view\nfunction, rather than the view function having to access the request data from\na global variable. This makes it light, clean and easy to test views by passing\nin “fake” request objects.
\nA view shouldn’t care about which template system the developer uses – or even\nwhether a template system is used at all.
\nGET and POST are distinct; developers should explicitly use one or the other.\nThe framework should make it easy to distinguish between GET and POST data.
\nThe core goals of Django’s cache framework are:
\nA cache should be as fast as possible. Hence, all framework code surrounding\nthe cache backend should be kept to the absolute minimum, especially for\nget() operations.
The cache API should provide a consistent interface across the different\ncache backends.
\nThe cache API should be extensible at the application level based on the\ndeveloper’s needs (for example, see Cache key transformation).
\n