Django

Code

Show
Ignore:
Timestamp:
06/17/07 17:18:54 (1 year ago)
Author:
clong
Message:

per-object-permissions: Merged to trunk [5486] NOTE: Not fully tested, will be working on this over the next few weeks.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/branches/per-object-permissions/docs/add_ons.txt

    r4242 r5488  
    1 ===================== 
    2 The "contrib" add-ons 
    3 ===================== 
     1============================ 
     2The "django.contrib" add-ons 
     3============================ 
    44 
    55Django aims to follow Python's `"batteries included" philosophy`_. It ships 
    …… 
    77problems. 
    88 
    9 This code lives in ``django/contrib`` in the Django distribution. Here's a 
    10 rundown of the packages in ``contrib``: 
     9This code lives in ``django/contrib`` in the Django distribution. This document 
     10gives a rundown of the packages in ``contrib``, along with any dependencies 
     11those packages have. 
     12 
     13.. admonition:: Note 
     14 
     15    For most of these add-ons -- specifically, the add-ons that include either 
     16    models or template tags -- you'll need to add the package name (e.g., 
     17    ``'django.contrib.admin'``) to your ``INSTALLED_APPS`` setting and re-run 
     18    ``manage.py syncdb``. 
    1119 
    1220.. _"batteries included" philosophy: http://docs.python.org/tut/node12.html#batteries-included 
    …… 
    1826`Tutorial 2`_. 
    1927 
    20 .. _Tutorial 2: http://www.djangoproject.com/documentation/tutorial2/ 
     28.. _Tutorial 2: ../tutorial02/ 
     29 
     30Requires the auth_ and contenttypes_ contrib packages to be installed. 
    2131 
    2232auth 
    …… 
    2737See the `authentication documentation`_. 
    2838 
    29 .. _authentication documentation: http://www.djangoproject.com/documentation/authentication/ 
     39.. _authentication documentation: ../authentication/ 
    3040 
    3141comments 
    …… 
    4757See the `csrf documentation`_. 
    4858 
    49 .. _csrf documentation: http://www.djangoproject.com/documentation/csrf/ 
     59.. _csrf documentation: ../csrf/ 
    5060 
    5161formtools 
    5262========= 
    53  
    54 **New in Django development version** 
    5563 
    5664A set of high-level abstractions for Django forms (django.newforms). 
    …… 
    138146See the `flatpages documentation`_. 
    139147 
    140 .. _flatpages documentation: http://www.djangoproject.com/documentation/flatpages/ 
     148.. _flatpages documentation: ../flatpages/ 
     149 
     150Requires the sites_ contrib package to be installed as well. 
     151 
     152localflavor 
     153=========== 
     154 
     155A collection of various Django snippets that are useful only for a particular 
     156country or culture. For example, ``django.contrib.localflavor.usa.forms`` 
     157contains a ``USZipCodeField`` that you can use to validate U.S. zip codes. 
    141158 
    142159markup 
    143160====== 
    144161 
    145 A collection of template filters that implement these common markup languages: 
    146  
    147     * Textile 
    148     * Markdown 
    149     * ReST (ReStructured Text) 
    150  
    151 For documentation, read the source code in django/contrib/markup/templatetags/markup.py. 
     162A collection of template filters that implement common markup languages: 
     163 
     164    * ``textile`` -- implements `Textile`_ 
     165    * ``markdown`` -- implements `Markdown`_ 
     166    * ``restructuredtext`` -- implements `ReST (ReStructured Text)`_ 
     167 
     168In each case, the filter expects formatted markup as a string and returns a 
     169string representing the marked-up text. For example, the ``textile`` filter 
     170converts text that is marked-up in Textile format to HTML. 
     171 
     172To activate these filters, add ``'django.contrib.markup'`` to your 
     173``INSTALLED_APPS`` setting. Once you've done that, use ``{% load markup %}`` in 
     174a template, and you'll have access to these filters. For more documentation, 
     175read the source code in django/contrib/markup/templatetags/markup.py. 
     176 
     177.. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29 
     178.. _Markdown: http://en.wikipedia.org/wiki/Markdown 
     179.. _ReST (ReStructured Text): http://en.wikipedia.org/wiki/ReStructuredText 
    152180 
    153181redirects 
    …… 
    158186See the `redirects documentation`_. 
    159187 
    160 .. _redirects documentation: http://www.djangoproject.com/documentation/redirects/ 
     188.. _redirects documentation: ../redirects/ 
    161189 
    162190sites 
    …… 
    169197See the `sites documentation`_. 
    170198 
    171 .. _sites documentation: http://www.djangoproject.com/documentation/sites/ 
     199.. _sites documentation: ../sites/ 
    172200 
    173201sitemaps 
    …… 
    178206See the `sitemaps documentation`_. 
    179207 
    180 .. _sitemaps documentation: http://www.djangoproject.com/documentation/sitemaps/ 
     208.. _sitemaps documentation: ../sitemaps/ 
    181209 
    182210syndication 
    …… 
    187215See the `syndication documentation`_. 
    188216 
    189 .. _syndication documentation: http://www.djangoproject.com/documentation/syndication/ 
     217.. _syndication documentation: ../syndication/ 
    190218 
    191219Other add-ons 

  • django/branches/per-object-permissions/docs/apache_auth.txt

    r3940 r5488  
    6666    PythonOption DJANGO_SETTINGS_MODULE mysite.settings 
    6767 
    68 .. _authentication system: http://www.djangoproject.com/documentation/authentication/ 
     68.. _authentication system: ../authentication/ 
    6969.. _Subversion: http://subversion.tigris.org/ 
    7070.. _mod_dav: http://httpd.apache.org/docs/2.0/mod/mod_dav.html 
    71 .. _custom permissions: http://www.djangoproject.com/documentation/authentication/#custom-permissions 
     71.. _custom permissions: ../authentication/#custom-permissions 

  • django/branches/per-object-permissions/docs/api_stability.txt

    r3940 r5488  
    9999     there will at least be moderate changes. 
    100100      
    101 .. _caching: http://www.djangoproject.com/documentation/cache/ 
    102 .. _custom template tags and libraries: http://www.djangoproject.com/documentation/templates_python/ 
    103 .. _database lookup: http://www.djangoproject.com/documentation/db_api/ 
    104 .. _django-admin utility: http://www.djangoproject.com/documentation/django_admin/ 
    105 .. _fastcgi integration: http://www.djangoproject.com/documentation/fastcgi/ 
    106 .. _flatpages: http://www.djangoproject.com/documentation/flatpages/ 
    107 .. _generic views: http://www.djangoproject.com/documentation/generic_views/ 
    108 .. _internationalization: http://www.djangoproject.com/documentation/i18n/ 
    109 .. _legacy database integration: http://www.djangoproject.com/documentation/legacy_databases/ 
    110 .. _model definition: http://www.djangoproject.com/documentation/model_api/ 
    111 .. _mod_python integration: http://www.djangoproject.com/documentation/modpython/ 
    112 .. _redirects: http://www.djangoproject.com/documentation/redirects/ 
    113 .. _request/response objects: http://www.djangoproject.com/documentation/request_response/ 
    114 .. _sending email: http://www.djangoproject.com/documentation/email/ 
    115 .. _sessions: http://www.djangoproject.com/documentation/sessions/ 
    116 .. _settings: http://www.djangoproject.com/documentation/settings/ 
    117 .. _syndication: http://www.djangoproject.com/documentation/syndication/ 
    118 .. _template language: http://www.djangoproject.com/documentation/templates/ 
    119 .. _transactions: http://www.djangoproject.com/documentation/transactions/ 
    120 .. _url dispatch: http://www.djangoproject.com/documentation/url_dispatch/ 
    121 .. _forms and validation: http://www.djangoproject.com/documentation/forms/ 
    122 .. _serialization: http://www.djangoproject.com/documentation/serialization/ 
    123 .. _authentication: http://www.djangoproject.com/documentation/authentication/ 
     101.. _caching: ../cache/ 
     102.. _custom template tags and libraries: ../templates_python/ 
     103.. _database lookup: ../db-api/ 
     104.. _django-admin utility: ../django-admin/ 
     105.. _fastcgi integration: ../fastcgi/ 
     106.. _flatpages: ../flatpages/ 
     107.. _generic views: ../generic_views/ 
     108.. _internationalization: ../i18n/ 
     109.. _legacy database integration: ../legacy_databases/ 
     110.. _model definition: ../model-api/ 
     111.. _mod_python integration: ../modpython/ 
     112.. _redirects: ../redirects/ 
     113.. _request/response objects: ../request_response/ 
     114.. _sending email: ../email/ 
     115.. _sessions: ../sessions/ 
     116.. _settings: ../settings/ 
     117.. _syndication: ../syndication/ 
     118.. _template language: ../templates/ 
     119.. _transactions: ../transactions/ 
     120.. _url dispatch: ../url_dispatch/ 
     121.. _forms and validation: ../forms/ 
     122.. _serialization: ../serialization/ 
     123.. _authentication: ../authentication/ 

  • django/branches/per-object-permissions/docs/authentication.txt

    r4096 r5488  
    8787    myuser.groups.remove(group, group,...) 
    8888    myuser.groups.clear() 
    89     myuser.permissions = [permission_list] 
    90     myuser.permissions.add(permission, permission, ...) 
    91     myuser.permissions.remove(permission, permission, ...] 
    92     myuser.permissions.clear() 
     89    myuser.user_permissions = [permission_list] 
     90    myuser.user_permissions.add(permission, permission, ...) 
     91    myuser.user_permissions.remove(permission, permission, ...] 
     92    myuser.user_permissions.clear() 
    9393 
    9494In addition to those automatic API methods, ``User`` objects have the following 
    …… 
    145145      doesn't allow profiles. 
    146146 
    147 .. _Django model: http://www.djangoproject.com/documentation/model_api/ 
    148 .. _DEFAULT_FROM_EMAIL: http://www.djangoproject.com/documentation/settings/#default-from-email 
     147.. _Django model: ../model-api/ 
     148.. _DEFAULT_FROM_EMAIL: ../settings/#default-from-email 
    149149 
    150150Manager functions 
    …… 
    205205That's hashtype, salt and hash, separated by the dollar-sign character. 
    206206 
    207 Hashtype is either ``sha1`` (default) or ``md5`` -- the algorithm used to 
    208 perform a one-way hash of the password. Salt is a random string used to salt 
    209 the raw password to create the hash. 
     207Hashtype is either ``sha1`` (default), ``md5`` or ``crypt`` -- the algorithm 
     208used to perform a one-way hash of the password. Salt is a random string used 
     209to salt the raw password to create the hash. Note that the ``crypt`` method is 
     210only supported on platforms that have the standard Python ``crypt`` module 
     211available, and ``crypt`` support is only available in the Django development 
     212version. 
    210213 
    211214For example:: 
    …… 
    272275        # Do something for anonymous users. 
    273276 
    274 .. _request objects: http://www.djangoproject.com/documentation/request_response/#httprequest-objects 
    275 .. _session documentation: http://www.djangoproject.com/documentation/sessions/ 
     277.. _request objects: ../request_response/#httprequest-objects 
     278.. _session documentation: ../sessions/ 
    276279 
    277280How to log a user in 
    …… 
    318321            # Return an 'invalid login' error message. 
    319322 
     323Manually checking a user's password 
     324----------------------------------- 
     325 
     326If you'd like to manually authenticate a user by comparing a 
     327plain-text password to the hashed password in the database, use the 
     328convenience function `django.contrib.auth.models.check_password`. It 
     329takes two arguments: the plain-text password to check, and the full 
     330value of a user's ``password`` field in the database to check against, 
     331and returns ``True`` if they match, ``False`` otherwise. 
     332 
    320333How to log a user out 
    321334--------------------- 
    …… 
    378391``login_required`` does the following: 
    379392 
    380     * If the user isn't logged in, redirect to ``/accounts/login/``, passing 
    381       the current absolute URL in the query string as ``next``. For example: 
     393    * If the user isn't logged in, redirect to ``settings.LOGIN_URL`` 
     394      (``/accounts/login/`` by default), passing the current absolute URL 
     395      in the query string as ``next``. For example: 
    382396      ``/accounts/login/?next=/polls/3/``. 
    383397    * If the user is logged in, execute the view normally. The view code is 
    384398      free to assume the user is logged in. 
    385399 
    386 Note that you'll need to map the appropriate Django view to ``/accounts/login/``. 
    387 To do this, add the following line to your URLconf:: 
     400Note that you'll need to map the appropriate Django view to ``settings.LOGIN_URL``. 
     401For example, using the defaults, add the following line to your URLconf:: 
    388402 
    389403    (r'^accounts/login/$', 'django.contrib.auth.views.login'), 
    390404 
    391 Here's what ``django.contrib.auth.views.login`` does:: 
     405Here's what ``django.contrib.auth.views.login`` does: 
    392406 
    393407    * If called via ``GET``, it displays a login form that POSTs to the same 
    …… 
    396410    * If called via ``POST``, it tries to log the user in. If login is 
    397411      successful, the view redirects to the URL specified in ``next``. If 
    398       ``next`` isn't provided, it redirects to ``/accounts/profile/`` (which is 
    399       currently hard-coded). If login isn't successful, it redisplays the login 
    400       form. 
     412      ``next`` isn't provided, it redirects to ``settings.LOGIN_REDIRECT_URL`` 
     413      (which defaults to ``/accounts/profile/``). If login isn't successful, 
     414      it redisplays the login form. 
    401415 
    402416It's your responsibility to provide the login form in a template called 
    …… 
    442456    {% endblock %} 
    443457 
    444 .. _forms documentation: http://www.djangoproject.com/documentation/forms/ 
    445 .. _site framework docs: http://www.djangoproject.com/documentation/sites/ 
     458.. _forms documentation: ../forms/ 
     459.. _site framework docs: ../sites/ 
     460 
     461Other built-in views 
     462-------------------- 
     463 
     464In addition to the `login` view, the authentication system includes a 
     465few other useful built-in views: 
     466 
     467``django.contrib.auth.views.logout`` 
     468~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     469 
     470**Description:** 
     471 
     472Logs a user out. 
     473 
     474**Optional arguments:** 
     475 
     476    * ``template_name``: The full name of a template to display after 
     477      logging the user out. This will default to 
     478      ``registration/logged_out.html`` if no argument is supplied. 
     479 
     480**Template context:** 
     481 
     482    * ``title``: The string "Logged out", localized. 
     483 
     484``django.contrib.auth.views.logout_then_login`` 
     485~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     486 
     487**Description:** 
     488 
     489Logs a user out, then redirects to the login page. 
     490 
     491**Optional arguments:** 
     492 
     493    * ``login_url``: The URL of the login page to redirect to. This 
     494      will default to ``settings.LOGIN_URL`` if not supplied. 
     495 
     496``django.contrib.auth.views.password_change`` 
     497~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     498 
     499**Description:** 
     500 
     501Allows a user to change their password. 
     502 
     503**Optional arguments:** 
     504 
     505    * ``template_name``: The full name of a template to use for 
     506      displaying the password change form. This will default to 
     507      ``registration/password_change_form.html`` if not supplied. 
     508 
     509**Template context:** 
     510 
     511    * ``form``: The password change form. 
     512 
     513``django.contrib.auth.views.password_change_done`` 
     514~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     515 
     516**Description:** 
     517 
     518The page shown after a user has changed their password. 
     519 
     520**Optional arguments:** 
     521 
     522    * ``template_name``: The full name of a template to use. This will 
     523      default to ``registration/password_change_done.html`` if not 
     524      supplied. 
     525 
     526``django.contrib.auth.views.password_reset`` 
     527~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     528 
     529**Description:** 
     530 
     531Allows a user to reset their password, and sends them the new password 
     532in an email. 
     533 
     534**Optional arguments:** 
     535 
     536    * ``template_name``: The full name of a template to use for 
     537      displaying the password reset form. This will default to 
     538      ``registration/password_reset_form.html`` if not supplied. 
     539 
     540    * ``email_template_name``: The full name of a template to use for 
     541      generating the email with the new password. This will default to 
     542      ``registration/password_reset_email.html`` if not supplied. 
     543 
     544**Template context:** 
     545 
     546    * ``form``: The form for resetting the user's password. 
     547 
     548``django.contrib.auth.views.password_reset_done`` 
     549~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     550 
     551**Description:** 
     552 
     553The page shown after a user has reset their password. 
     554 
     555**Optional arguments:** 
     556 
     557    * ``template_name``: The full name of a template to use. This will 
     558      default to ``registration/password_reset_done.html`` if not 
     559      supplied. 
     560 
     561``django.contrib.auth.views.redirect_to_login`` 
     562~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     563 
     564**Description:** 
     565 
     566Redirects to the login page, and then back to another URL after a 
     567successful login. 
     568 
     569**Required arguments:** 
     570 
     571    * ``next``: The URL to redirect to after a successful login. 
     572 
     573**Optional arguments:** 
     574 
     575    * ``login_url``: The URL of the login page to redirect to. This 
     576      will default to ``settings.LOGIN_URL`` if not supplied. 
     577 
     578Built-in manipulators 
     579--------------------- 
     580 
     581If you don't want to use the built-in views, but want the convenience 
     582of not having to write manipulators for this functionality, the 
     583authentication system provides several built-in manipulators: 
     584 
     585    * ``django.contrib.auth.forms.AdminPasswordChangeForm``: A 
     586      manipulator used in the admin interface to change a user's 
     587      password. 
     588 
     589    * ``django.contrib.auth.forms.AuthenticationForm``: A manipulator 
     590      for logging a user in. 
     591 
     592    * ``django.contrib.auth.forms.PasswordChangeForm``: A manipulator 
     593      for allowing a user to change their password. 
     594 
     595    * ``django.contrib.auth.forms.PasswordResetForm``: A manipulator 
     596      for resetting a user's password and emailing the new password to 
     597      them. 
     598 
     599    * ``django.contrib.auth.forms.UserCreationForm``: A manipulator 
     600      for creating a new user. 
    446601 
    447602Limiting access to logged-in users that pass a test 
    …… 
    486641 
    487642``user_passes_test()`` takes an optional ``login_url`` argument, which lets you 
    488 specify the URL for your login page (``/accounts/login/`` by default). 
     643specify the URL for your login page (``settings.LOGIN_URL`` by default). 
    489644 
    490645Example in Python 2.3 syntax:: 
    …… 
    530685 
    531686As in the ``login_required`` decorator, ``login_url`` defaults to 
    532 ``'/accounts/login/'``. 
     687``settings.LOGIN_URL``. 
    533688 
    534689Limiting access to generic views 
    …… 
    545700        return object_detail(*args, **kwargs) 
    546701 
    547 .. _generic view: http://www.djangoproject.com/documentation/generic_views/ 
     702.. _generic view: ../generic_views/ 
    548703 
    549704Permissions 
    …… 
    576731------------------- 
    577732 
    578 Three basic permissions -- add, create and delete -- are automatically created 
     733Three basic permissions -- add, change and delete -- are automatically created 
    579734for each Django model that has a ``class Admin`` set. Behind the scenes, these 
    580735permissions are added to the ``auth_permission`` database table when you run 
    …… 
    607762``syncdb``. 
    608763 
    609 .. _model Meta attribute: http://www.djangoproject.com/documentation/model_api/#meta-options 
     764.. _model Meta attribute: ../model-api/#meta-options 
    610765 
    611766API reference 
    …… 
    646801   For more, see the `RequestContext docs`_. 
    647802 
    648    .. _RequestContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-requestcontext 
     803   .. _RequestContext docs: ../templates_python/#subclassing-context-requestcontext 
    649804 
    650805Users 
    …… 
    692847    {% endif %} 
    693848 
    694 .. _template context: http://www.djangoproject.com/documentation/templates_python/ 
     849.. _template context: ../templates_python/ 
    695850 
    696851Groups 
    …… 
    757912database. To send messages to anonymous users, use the `session framework`_. 
    758913 
    759 .. _session framework: http://www.djangoproject.com/documentation/sessions/ 
     914.. _session framework: ../sessions/ 
    760915 
    761916Other authentication sources 
    …… 
    814969 
    815970    class MyBackend: 
    816         def authenticate(username=None, password=None): 
     971        def authenticate(self, username=None, password=None): 
    817972            # Check the username/password and return a User. 
    818973 
    …… 
    820975 
    821976    class MyBackend: 
    822         def authenticate(token=None): 
     977        def authenticate(self, token=None): 
    823978            # Check the token and return a User. 
    824979 

  • django/branches/per-object-permissions/docs/cache.txt

    r3630 r5488  
    6767 
    6868After installing Memcached itself, you'll need to install the Memcached Python 
    69 bindings. They're in a single Python module, memcache.py, available at 
    70 ftp://ftp.tummy.com/pub/python-memcached/ . If that URL is no longer valid, 
    71 just go to the Memcached Web site (http://www.danga.com/memcached/) and get the 
    72 Python bindings from the "Client APIs" section. 
     69bindings. Two versions of this are available. Choose and install *one* of the 
     70following modules: 
     71 
     72    * The fastest available option is a module called ``cmemcache``, available 
     73      at http://gijsbert.org/cmemcache/ . (This module is only compatible with 
     74      the Django development version. Django 0.96 is only compatible with the 
     75      second option, below.) 
     76 
     77    * If you can't install ``cmemcache``, you can install ``python-memcached``, 
     78      available at ftp://ftp.tummy.com/pub/python-memcached/ . If that URL is 
     79      no longer valid, just go to the Memcached Web site 
     80      (http://www.danga.com/memcached/) and get the Python bindings from the 
     81      "Client APIs" section. 
    7382 
    7483To use Memcached with Django, set ``CACHE_BACKEND`` to 
    …… 
    251260See the `middleware documentation`_ for more on middleware. 
    252261 
    253 .. _`middleware documentation`: http://www.djangoproject.com/documentation/middleware/ 
     262.. _`middleware documentation`: ../middleware/ 
    254263 
    255264The per-view cache 

  • django/branches/per-object-permissions/docs/contributing.txt

    r4242 r5488  
    123123      tracker apply correct syntax highlighting, which is quite helpful. 
    124124 
    125     * Put the prefix "[patch] " before the title of your ticket. This will make 
    126       it obvious that the ticket includes a patch, and it will add the ticket 
    127       to the `list of tickets with patches`_. 
     125    * Check the "Has patch" box on the ticket details. This will make it 
     126      obvious that the ticket includes a patch, and it will add the ticket to 
     127      the `list of tickets with patches`_. 
    128128 
    129129    * The code required to fix a problem or add a feature is an essential part 
    …… 
    152152don't meet all the requirements of a `good patch`_. 
    153153 
    154 One way to help out is to *triage* bugs that have been reported by other users. 
    155 Pick an open ticket that is missing some details, and try to replicate the 
    156 problem. Fill in the missing pieces of the report. If the ticket doesn't have 
    157 a patch, create one. 
    158  
    159 Once you've completed all the missing details on the ticket and you have a 
    160 patch with all the required features, e-mail `django-developers`_. Indicate 
    161 that you have triaged a ticket, and recommend a course of action for dealing 
    162 with that ticket. 
    163  
    164 At first, this may require you to be persistent. If you find that your triaged 
    165 ticket still isn't getting attention, occasional polite requests for eyeballs 
    166 to look at your ticket may be necessary. However, as you earn a reputation for 
    167 quality triage work, you should find that it is easier to get the developers' 
    168 attention. 
     154One way to help out is to *triage* bugs that have been reported by other 
     155users. A couple of dedicated volunteers work on this regularly, but more help 
     156is always appreciated. 
     157 
     158Most of the workflow is based around the concept of a ticket's "triage stage". 
     159This stage describes where in its lifetime a given ticket is at any time. 
     160Along with a handful of flags, this field easily tells us what and who each 
     161ticket is waiting on. 
     162 
     163Since a picture is worth a thousand words, let's start there: 
     164 
     165.. image:: http://media.djangoproject.com/img/doc/djangotickets.png 
     166   :height: 451 
     167   :width: 590 
     168   :alt: Django's ticket workflow 
     169 
     170We've got two roles here: 
     171 
     172    * Core developers: people with commit access who make the decisions and 
     173      write the bulk of the code. 
     174 
     175    * Ticket triagers: community members who keep track of tickets, making 
     176      sure the tickets are always categorized correctly. 
     177 
     178Second, note the four triage stages: 
     179 
     180    1. A ticket starts as "Unreviewed", meaning that a triager has yet to 
     181       examine the ticket and move it along. 
     182 
     183    2. "Design decision needed" means "this concept requires a design 
     184       decision," which should be discussed either in the ticket comments or on 
     185       django-developers. 
     186 
     187    3. Once a ticket is ruled to be approved for fixing, it's moved into the 
     188       "Accepted" stage. This stage is where all the real work gets done. 
     189 
     190    4. If a ticket has an associated patch (see below), a triager will review the 
     191       patch. If the patch is complete, it'll be marked as "ready for checkin" so 
     192       that a core developer knows to review and check in the patches. 
     193 
     194The second part of this workflow involves a set of flags the describe what the 
     195ticket has or needs in order to be "ready for checkin": 
     196 
     197    "Has patch" 
     198        This means the ticket has an associated patch_. These will be 
     199        reviewed to see if the patch is "good". 
     200 
     201    "Needs documentation" 
     202        This flag is used for tickets with patches that need associated 
     203        documentation. Complete documentation of features is a prerequisite 
     204        before we can check a fix into the codebase. 
     205 
     206    "Needs tests" 
     207        This flags the patch as needing associated unit tests. Again, this is a 
     208        required part of a valid patch. 
     209 
     210    "Patch needs improvement" 
     211        This flag means that although the ticket *has* a patch, it's not quite 
     212        ready for checkin. This could mean the patch no longer applies 
     213        cleanly, or that the code doesn't live up to our standards. 
     214 
     215A ticket can be resolved in a number of ways: 
     216 
     217    "fixed" 
     218        Used by one of the core developers once a patch has been rolled into 
     219        Django and the issue is fixed. 
     220 
     221    "invalid" 
     222        Used if the ticket is found to be incorrect or a user error. 
     223 
     224    "wontfix" 
     225        Used when a core developer decides that this request is not 
     226        appropriate for consideration in Django. This is usually chosen after 
     227        discussion in the ``django-developers`` mailing list, and you should 
     228        feel free to join in when it's something you care about. 
     229 
     230    "duplicate" 
     231        Used when another ticket covers the same issue. By closing duplicate 
     232        tickets, we keep all the discussion in one place, which helps everyone. 
     233 
     234    "worksforme" 
     235        Used when the triage team is unable to replicate the original bug. 
     236 
     237If you believe that the ticket was closed in error -- because you're 
     238still having the issue, or it's popped up somewhere else, or the triagers have 
     239-- made a mistake, please reopen the ticket and tell us why. Please do not 
     240reopen tickets that have been marked as "wontfix" by core developers. 
    169241 
    170242.. _required details: `Reporting bugs`_ 
    171243.. _good patch: `Patch style`_ 
     244.. _patch: `Submitting patches`_ 
    172245 
    173246Submitting and maintaining translations 
    …… 
    187260 
    188261.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/ 
    189 .. _i18n documentation: http://www.djangoproject.com/documentation/i18n/ 
     262.. _i18n documentation: ../i18n/ 
    190263 
    191264Coding style 
    …… 
    207280      for details. 
    208281 
     282    * Please don't put your name in the code you contribute. Our policy is to 
     283      keep contributors' names in the ``AUTHORS`` file distributed with Django 
     284      -- not scattered throughout the codebase itself. Feel free to include a 
     285      change to the ``AUTHORS`` file in your patch if you make more than a 
     286      single trivial change. 
     287 
     288Template style 
     289-------------- 
     290 
    209291    * In Django template code, put one (and only one) space between the curly 
    210292      brackets and the tag contents. 
    …… 
    218300          {{foo}} 
    219301 
     302View style 
     303---------- 
     304 
    220305    * In Django views, the first parameter in a view function should be called 
    221306      ``request``. 
    …… 
    231316              # ... 
    232317 
    233     * Please don't put your name in the code. While we appreciate all 
    234       contributions to Django, our policy is not to publish individual 
    235       developer names in code -- for instance, at the top of Python modules. 
     318Model style 
     319----------- 
     320 
     321    * Field names should be all lowercase, using underscores instead of 
     322      camelCase. 
     323 
     324      Do this:: 
     325 
     326          class Person(models.Model): 
     327              first_name = models.CharField(maxlength=20) 
     328              last_name = models.CharField(maxlength=40) 
     329 
     330      Don't do this:: 
     331 
     332          class Person(models.Model): 
     333              FirstName = models.CharField(maxlength=20) 
     334              Last_Name = models.CharField(maxlength=40) 
     335 
     336    * The ``class Meta`` should appear *after* the fields are defined, with 
     337      a single blank line separating the fields and the class definition. 
     338 
     339      Do this:: 
     340 
     341          class Person(models.Model): 
     342              first_name = models.CharField(maxlength=20) 
     343              last_name = models.CharField(maxlength=40) 
     344 
     345              class Meta: 
     346                  verbose_name_plural = 'people' 
     347 
     348      Don't do this:: 
     349 
     350          class Person(models.Model): 
     351              first_name = models.CharField(maxlength=20) 
     352              last_name = models.CharField(maxlength=40) 
     353              class Meta: 
     354                  verbose_name_plural = 'people' 
     355 
     356      Don't do this, either:: 
     357 
     358          class Person(models.Model): 
     359              class Meta: 
     360                  verbose_name_plural = 'people' 
     361 
     362              first_name = models.CharField(maxlength=20) 
     363              last_name = models.CharField(maxlength=40) 
     364 
     365    * The order of model inner classes and standard methods should be as 
     366      follows (noting that these are not all required): 
     367 
     368        * All database fields 
     369        * ``class Meta`` 
     370        * ``class Admin`` 
     371        * ``def __str__()`` 
     372        * ``def save()`` 
     373        * ``def get_absolute_url()`` 
     374        * Any custom methods 
     375 
     376    * If ``choices`` is defined for a given model field, define the choices as 
     377      a tuple of tuples, with an all-uppercase name, either near the top of the 
     378      model module or just above the model class. Example:: 
     379 
     380          GENDER_CHOICES = ( 
     381              ('M', 'Male'), 
     382              ('F', 'Female'), 
     383          ) 
    236384 
    237385Committing code 
    …… 
    312460how to write new tests. 
    313461 
    314 .. _Testing Django applications: http://www.djangoproject.com/documentation/testing/ 
     462.. _Testing Django applications: ../testing/ 
    315463 
    316464Running the unit tests 
    …… 
    322470 
    323471Yes, the unit tests need a settings module, but only for database connection 
    324 info -- the ``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD``. 
    325 You will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just 
    326 needs to be present) and a ``SITE_ID`` setting (any integer value will do) in 
    327 order for all the tests to pass. 
     472info -- the ``DATABASE_NAME`` (required, but will be ignored), 
     473``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD`` settings. You 
     474will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just needs 
     475to be present) and a ``SITE_ID`` setting (any integer value will do) in order 
     476for all the tests to pass. 
    328477 
    329478The unit tests will not touch your existing databases; they create a new 
    …… 
    439588change the symlink to point to the old code. 
    440589 
     590A third option is to use a `path file`_ (``<something>.pth``) which should 
     591work on all systems (including Windows, which doesn't have symlinks 
     592available). First, make sure there are no files, directories or symlinks named 
     593``django`` in your ``site-packages`` directory. Then create a text file named 
     594``django.pth`` and save it to your ``site-packages`` directory. That file 
     595should contain a path to your copy of Django on a single line and optional 
     596comments. Here is an example that points to multiple branches. Just uncomment 
     597the line for the branch you want to use ('Trunk' in this example) and make 
     598sure all other lines are commented:: 
     599 
     600    # Trunk is a svn checkout of: 
     601    #   http://code.djangoproject.com/svn/django/trunk/ 
     602    # 
     603    /path/to/trunk 
     604 
     605    # <branch> is a svn checkout of: 
     606    #   http://code.djangoproject.com/svn/django/branches/<branch>/ 
     607    # 
     608    #/path/to/<branch> 
     609 
     610    # On windows a path may look like this: 
     611    # C:/path/to/<branch> 
     612 
    441613If you're using Django 0.95 or earlier and installed it using 
    442614``python setup.py install``, you'll have a directory called something like 
    …… 
    445617file. Then copy the branch's version of the ``django`` directory into 
    446618``site-packages``. 
     619 
     620.. _path file: http://docs.python.org/lib/module-site.html 
    447621 
    448622Official releases 
    …… 
    549723.. _django-users: http://groups.google.com/group/django-users 
    550724.. _`#django`: irc://irc.freenode.net/django 
    551 .. _list of tickets with patches: http://code.djangoproject.com/report/12 
     725.. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority 
    552726.. _PEP 8: http://www.python.org/peps/pep-0008.html 
    553 .. _i18n documentation: http://www.djangoproject.com/documentation/i18n/ 
    554727.. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n 
    555728.. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases 

  • django/branches/per-object-permissions/docs/db-api.txt

    <
    r4242 r5488  
    77objects. This document explains that API. 
    88 
    9 .. _`data models`: http://www.djangoproject.com/documentation/model_api/ 
     9.. _`data models`: ../model-api/ 
    1010 
    1111Throughout this reference, we'll refer to the following models, which comprise 
    …… 
    8686`AutoField documentation`_.) 
    8787 
    88 .. _AutoField documentation: http://www.djangoproject.com/documentation/model_api/#autofield 
     88.. _AutoField documentation: ../model-api/#autofield 
    8989 
    9090Explicitly specifying auto-primary-key values 
    …… 
    113113    b4.save()  # Overrides the previous blog with ID=3! 
    114114 
    115 See _`How Django knows to UPDATE vs. INSERT`, below, for the reason this 
     115See `How Django knows to UPDATE vs. INSERT`_, below, for the reason this 
    116116happens. 
    117117 
    …… 
    134134 
    135135The ``save()`` method has no return value. 
     136 
     137Updating ``ForeignKey`` fields works exactly the same way; simply assign an 
     138object of the right type to the field in question:: 
     139 
     140    joe = Author.objects.create(name="Joe") 
     141    entry.author = joe 
     142    entry.save() 
     143     
     144Django will complain if you try to assign an object of the wrong type. 
    136145