diff options
author | Nishanth Amuluru | 2011-01-08 11:20:57 +0530 |
---|---|---|
committer | Nishanth Amuluru | 2011-01-08 11:20:57 +0530 |
commit | 65411d01d448ff0cd4abd14eee14cf60b5f8fc20 (patch) | |
tree | b4c404363c4c63a61d6e2f8bd26c5b057c1fb09d /parts/django/docs/misc | |
parent | 2e35094d43b4cc6974172e1febf76abb50f086ec (diff) | |
download | pytask-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.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, 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 |