summaryrefslogtreecommitdiff
path: root/parts/django/docs/misc
diff options
context:
space:
mode:
authorNishanth Amuluru2011-01-08 11:20:57 +0530
committerNishanth Amuluru2011-01-08 11:20:57 +0530
commit65411d01d448ff0cd4abd14eee14cf60b5f8fc20 (patch)
treeb4c404363c4c63a61d6e2f8bd26c5b057c1fb09d /parts/django/docs/misc
parent2e35094d43b4cc6974172e1febf76abb50f086ec (diff)
downloadpytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.tar.gz
pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.tar.bz2
pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.zip
Added buildout stuff and made changes accordingly
--HG-- rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/dependency_links.txt rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/not-zip-safe rename : profile/management/__init__.py => parts/django/Django.egg-info/dependency_links.txt rename : taskapp/models.py => parts/django/django/conf/app_template/models.py rename : taskapp/tests.py => parts/django/django/conf/app_template/tests.py rename : taskapp/views.py => parts/django/django/conf/app_template/views.py rename : taskapp/views.py => parts/django/django/contrib/gis/tests/geo3d/views.py rename : profile/management/__init__.py => parts/django/tests/modeltests/delete/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/files/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/invalid_models/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/m2m_signals/__init__.py rename : profile/management/__init__.py => parts/django/tests/modeltests/model_package/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/commands/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/models.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/delete_regress/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/file_storage/__init__.py rename : profile/management/__init__.py => parts/django/tests/regressiontests/max_lengths/__init__.py rename : profile/forms.py => pytask/profile/forms.py rename : profile/management/__init__.py => pytask/profile/management/__init__.py rename : profile/management/commands/seed_db.py => pytask/profile/management/commands/seed_db.py rename : profile/models.py => pytask/profile/models.py rename : profile/templatetags/user_tags.py => pytask/profile/templatetags/user_tags.py rename : taskapp/tests.py => pytask/profile/tests.py rename : profile/urls.py => pytask/profile/urls.py rename : profile/utils.py => pytask/profile/utils.py rename : profile/views.py => pytask/profile/views.py rename : static/css/base.css => pytask/static/css/base.css rename : taskapp/tests.py => pytask/taskapp/tests.py rename : taskapp/views.py => pytask/taskapp/views.py rename : templates/base.html => pytask/templates/base.html rename : templates/profile/browse_notifications.html => pytask/templates/profile/browse_notifications.html rename : templates/profile/edit.html => pytask/templates/profile/edit.html rename : templates/profile/view.html => pytask/templates/profile/view.html rename : templates/profile/view_notification.html => pytask/templates/profile/view_notification.html rename : templates/registration/activate.html => pytask/templates/registration/activate.html rename : templates/registration/activation_email.txt => pytask/templates/registration/activation_email.txt rename : templates/registration/activation_email_subject.txt => pytask/templates/registration/activation_email_subject.txt rename : templates/registration/logged_out.html => pytask/templates/registration/logged_out.html rename : templates/registration/login.html => pytask/templates/registration/login.html rename : templates/registration/logout.html => pytask/templates/registration/logout.html rename : templates/registration/password_change_done.html => pytask/templates/registration/password_change_done.html rename : templates/registration/password_change_form.html => pytask/templates/registration/password_change_form.html rename : templates/registration/password_reset_complete.html => pytask/templates/registration/password_reset_complete.html rename : templates/registration/password_reset_confirm.html => pytask/templates/registration/password_reset_confirm.html rename : templates/registration/password_reset_done.html => pytask/templates/registration/password_reset_done.html rename : templates/registration/password_reset_email.html => pytask/templates/registration/password_reset_email.html rename : templates/registration/password_reset_form.html => pytask/templates/registration/password_reset_form.html rename : templates/registration/registration_complete.html => pytask/templates/registration/registration_complete.html rename : templates/registration/registration_form.html => pytask/templates/registration/registration_form.html rename : utils.py => pytask/utils.py
Diffstat (limited to 'parts/django/docs/misc')
-rw-r--r--parts/django/docs/misc/api-stability.txt152
-rw-r--r--parts/django/docs/misc/design-philosophies.txt314
-rw-r--r--parts/django/docs/misc/distributions.txt36
-rw-r--r--parts/django/docs/misc/index.txt12
4 files changed, 514 insertions, 0 deletions
diff --git a/parts/django/docs/misc/api-stability.txt b/parts/django/docs/misc/api-stability.txt
new file mode 100644
index 0000000..456d84b
--- /dev/null
+++ b/parts/django/docs/misc/api-stability.txt
@@ -0,0 +1,152 @@
+=============
+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
new file mode 100644
index 0000000..631097a
--- /dev/null
+++ b/parts/django/docs/misc/design-philosophies.txt
@@ -0,0 +1,314 @@
+===================
+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
new file mode 100644
index 0000000..d9281ad
--- /dev/null
+++ b/parts/django/docs/misc/distributions.txt
@@ -0,0 +1,36 @@
+===================================
+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
new file mode 100644
index 0000000..b42baeb
--- /dev/null
+++ b/parts/django/docs/misc/index.txt
@@ -0,0 +1,12 @@
+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