From f611ffaab3be0c9a9d21b6bd404fdefb30a3e909 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Sat, 28 Aug 2010 02:40:57 +0000 Subject: [PATCH] Fixed #13820 -- Started the deprecation process for mod_python. Thanks to Robert Coup for the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@13648 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- django/core/handlers/modpython.py | 4 ++ docs/faq/admin.txt | 6 +-- docs/howto/apache-auth.txt | 7 ++++ docs/howto/deployment/fastcgi.txt | 13 +++---- docs/howto/deployment/index.txt | 2 +- docs/howto/deployment/modpython.txt | 13 ++++--- docs/howto/deployment/modwsgi.txt | 25 ++++++++++++ docs/howto/static-files.txt | 2 +- docs/internals/deprecation.txt | 4 ++ docs/ref/contrib/gis/deployment.txt | 26 ++++++++----- docs/ref/signals.txt | 3 +- docs/releases/1.3.txt | 34 ++++++++++++++++- docs/topics/install.txt | 59 +++++++++++++++++------------ docs/topics/settings.txt | 19 +++++----- 14 files changed, 152 insertions(+), 65 deletions(-) diff --git a/django/core/handlers/modpython.py b/django/core/handlers/modpython.py index b1e3e17227..17e739600c 100644 --- a/django/core/handlers/modpython.py +++ b/django/core/handlers/modpython.py @@ -1,5 +1,6 @@ import os from pprint import pformat +from warnings import warn from django import http from django.core import signals @@ -179,6 +180,9 @@ class ModPythonHandler(BaseHandler): request_class = ModPythonRequest def __call__(self, req): + warn(('The mod_python handler is deprecated; use a WSGI or FastCGI server instead.'), + PendingDeprecationWarning) + # mod_python fakes the environ, and thus doesn't process SetEnv. This fixes that os.environ.update(req.subprocess_env) diff --git a/docs/faq/admin.txt b/docs/faq/admin.txt index cd0e4f92b6..ac2e594ed2 100644 --- a/docs/faq/admin.txt +++ b/docs/faq/admin.txt @@ -52,11 +52,11 @@ admin. Using the same trick of extracting the user from the request, the :meth:`~django.contrib.admin.ModelAdmin.has_change_permission` can be used to control the visibility and editability of objects in the admin. -My admin-site CSS and images showed up fine using the development server, but they're not displaying when using mod_python. +My admin-site CSS and images showed up fine using the development server, but they're not displaying when using mod_wsgi. --------------------------------------------------------------------------------------------------------------------------- -See :ref:`serving the admin files ` -in the "How to use Django with mod_python" documentation. +See :ref:`serving the admin files ` +in the "How to use Django with mod_wsgi" documentation. My "list_filter" contains a ManyToManyField, but the filter doesn't display. ---------------------------------------------------------------------------- diff --git a/docs/howto/apache-auth.txt b/docs/howto/apache-auth.txt index 2ebae0b736..b3723f92c6 100644 --- a/docs/howto/apache-auth.txt +++ b/docs/howto/apache-auth.txt @@ -2,6 +2,13 @@ Authenticating against Django's user database from Apache ========================================================= +.. warning:: + + Support for mod_python has been deprecated within Django. At that + time, this method of authentication will no longer be provided by + Django. The community is welcome to offer its own alternate + solutions using WSGI middleware or other approaches. + Since keeping multiple authentication databases in sync is a common problem when dealing with Apache, you can configuring Apache to authenticate against Django's :doc:`authentication system ` directly. For example, you diff --git a/docs/howto/deployment/fastcgi.txt b/docs/howto/deployment/fastcgi.txt index 9326ee97dc..c2b8aa8b53 100644 --- a/docs/howto/deployment/fastcgi.txt +++ b/docs/howto/deployment/fastcgi.txt @@ -20,14 +20,14 @@ serve pages to a Web server. The Web server delegates the incoming Web requests (via a socket) to FastCGI, which executes the code and passes the response back to the Web server, which, in turn, passes it back to the client's Web browser. -Like mod_python, FastCGI allows code to stay in memory, allowing requests to be -served with no startup time. Unlike mod_python_ (or `mod_perl`_), a FastCGI -process doesn't run inside the Web server process, but in a separate, +Like mod_wsgi, FastCGI allows code to stay in memory, allowing requests to be +served with no startup time. While mod_wsgi can either be configured embedded +in the Apache webserver process or as a separate daemon process, a FastCGI +process never runs inside the Web server process, always in a separate, persistent process. .. _mod_wsgi: http://code.google.com/p/modwsgi/ .. _mod_perl: http://perl.apache.org/ -.. _mod_python: http://www.modpython.org/ .. admonition:: Why run code in a separate process? @@ -35,8 +35,7 @@ persistent process. languages (most notably PHP, Python and Perl) inside the process space of your Web server. Although this lowers startup time -- because code doesn't have to be read off disk for every request -- it comes at the cost of - memory use. For mod_python, for example, every Apache process gets its own - Python interpreter, which uses up a considerable amount of RAM. + memory use. Due to the nature of FastCGI, it's even possible to have processes that run under a different user account than the Web server process. That's a nice @@ -361,7 +360,7 @@ Serving admin media files Regardless of the server and configuration you eventually decide to use, you will also need to give some thought to how to serve the admin media files. The -advice given in the :ref:`modpython ` documentation +advice given in the :ref:`mod_wsgi ` documentation is also applicable in the setups detailed above. Forcing the URL prefix to a particular value diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt index 70c2ff8bbd..2eff3e6ace 100644 --- a/docs/howto/deployment/index.txt +++ b/docs/howto/deployment/index.txt @@ -10,8 +10,8 @@ ways to easily deploy Django: :maxdepth: 1 modwsgi - modpython fastcgi + mod_python (deprecated) If you're new to deploying Django and/or Python, we'd recommend you try :doc:`mod_wsgi ` first. In most cases it'll be the easiest, diff --git a/docs/howto/deployment/modpython.txt b/docs/howto/deployment/modpython.txt index d35cac8fcd..90a85cac5c 100644 --- a/docs/howto/deployment/modpython.txt +++ b/docs/howto/deployment/modpython.txt @@ -2,6 +2,13 @@ How to use Django with Apache and mod_python ============================================ +.. warning:: + + Support for mod_python will be deprecated in a future release of Django. If + you are configuring a new deployment, you are strongly encouraged to + consider using :doc:`mod_wsgi ` or any of the + other :doc:`supported backends `. + .. highlight:: apache The `mod_python`_ module for Apache_ can be used to deploy Django to a @@ -214,8 +221,6 @@ Or add the debugging information to the template of your page. .. _mod_python documentation: http://modpython.org/live/current/doc-html/directives.html -.. _serving-media-files: - Serving media files =================== @@ -267,10 +272,6 @@ the ``media`` subdirectory and any URL that ends with ``.jpg``, ``.gif`` or .. _Apache: http://httpd.apache.org/ .. _Cherokee: http://www.cherokee-project.com/ -.. _howto-deployment-modpython-serving-the-admin-files: - -.. _serving-the-admin-files: - Serving the admin files ======================= diff --git a/docs/howto/deployment/modwsgi.txt b/docs/howto/deployment/modwsgi.txt index fc51f24f80..e873006af0 100644 --- a/docs/howto/deployment/modwsgi.txt +++ b/docs/howto/deployment/modwsgi.txt @@ -53,6 +53,8 @@ just above the final ``import`` line to place your project on the path. Remember replace 'mysite.settings' with your correct settings file, and '/usr/local/django' with your own project's location. +.. _serving-media-files: + Serving media files =================== @@ -106,6 +108,29 @@ in the mod_wsgi documentation on `hosting static files`_. .. _hosting static files: http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines#Hosting_Of_Static_Files +.. _serving-the-admin-files: + +Serving the admin files +======================= + +Note that the Django development server automagically serves admin media files, +but this is not the case when you use any other server arrangement. You're +responsible for setting up Apache, or whichever media server you're using, to +serve the admin files. + +The admin files live in (:file:`django/contrib/admin/media`) of the Django +distribution. + +Here are two recommended approaches: + + 1. Create a symbolic link to the admin media files from within your + document root. This way, all of your Django-related files -- code **and** + templates -- stay in one place, and you'll still be able to ``svn + update`` your code to get the latest admin templates, if they change. + + 2. Or, copy the admin media files so that they live within your Apache + document root. + Details ======= diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt index c3692d5271..209cf38c36 100644 --- a/docs/howto/static-files.txt +++ b/docs/howto/static-files.txt @@ -31,7 +31,7 @@ Using this method is **inefficient** and **insecure**. Do not use this in a production setting. Use this only for development. For information on serving static files in an Apache production environment, -see the :ref:`Django mod_python documentation `. +see the :ref:`Django mod_wsgi documentation `. How to do it ============ diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index e045795338..b313871128 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -98,6 +98,10 @@ their deprecation, as per the :ref:`Django deprecation policy * The ``no`` language code has been deprecated in favor of the ``nb`` language code. + * 1.5 + * The ``mod_python`` request handler has been deprecated since the 1.3 + release. The ``mod_wsgi`` handler should be used instead. + * 2.0 * ``django.views.defaults.shortcut()``. This function has been moved to ``django.contrib.contenttypes.views.shortcut()`` as part of the diff --git a/docs/ref/contrib/gis/deployment.txt b/docs/ref/contrib/gis/deployment.txt index c8dde3e540..fa7fe69267 100644 --- a/docs/ref/contrib/gis/deployment.txt +++ b/docs/ref/contrib/gis/deployment.txt @@ -6,15 +6,15 @@ Deploying GeoDjango GeoDjango uses the GDAL geospatial library which is not thread safe at this time. Thus, it is *highly* recommended - to not use threading when deploying -- in other words, use a + to not use threading when deploying -- in other words, use a an appropriate configuration of Apache or the prefork method when using FastCGI through another web server. Apache ====== -In this section there are some example ``VirtualHost`` directives for +In this section there are some example ``VirtualHost`` directives for when deploying using either ``mod_python`` or ``mod_wsgi``. At this -time, we recommend ``mod_wsgi``, as it is now officially recommended +time, we recommend ``mod_wsgi``, as it is now officially recommended way to deploy Django applications with Apache. Moreover, if ``mod_python`` is used, then a prefork version of Apache must also be used. As long as ``mod_wsgi`` is configured correctly, it does not @@ -23,7 +23,7 @@ matter whether the version of Apache is prefork or worker. .. note:: The ``Alias`` and ``Directory`` configurations in the the examples - below use an example path to a system-wide installation folder of Django. + below use an example path to a system-wide installation folder of Django. Substitute in an appropriate location, if necessary, as it may be different than the path on your system. @@ -36,7 +36,7 @@ Example:: WSGIDaemonProcess geodjango user=geo group=geo processes=5 threads=1 WSGIProcessGroup geodjango WSGIScriptAlias / /home/geo/geodjango/world.wsgi - + Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/" Order allow,deny @@ -44,13 +44,13 @@ Example:: Allow from all IndexOptions FancyIndexing - + .. warning:: If the ``WSGIDaemonProcess`` attribute ``threads`` is not set to ``1``, then - Apache may crash when running your GeoDjango application. Increase the + Apache may crash when running your GeoDjango application. Increase the number of ``processes`` instead. For more information, please consult Django's @@ -59,10 +59,16 @@ For more information, please consult Django's ``mod_python`` -------------- +.. warning:: + Support for mod_python will be deprecated in a future release of Django. If + you are configuring a new deployment, you are strongly encouraged to + consider using :doc:`mod_wsgi ` or any of the + other :doc:`supported backends `. + Example:: - + SetHandler mod_python PythonHandler django.core.handlers.modpython @@ -70,12 +76,12 @@ Example:: PythonDebug On PythonPath "['/var/www/apps'] + sys.path" - + Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/" SetHandler None - + .. warning:: diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt index d10003448f..69ed48bc30 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -393,8 +393,7 @@ Sent when Django begins processing an HTTP request. Arguments sent with this signal: ``sender`` - The handler class -- i.e. - :class:`django.core.handlers.modpython.ModPythonHandler` or + The handler class -- e.g. :class:`django.core.handlers.wsgi.WsgiHandler` -- that handled the request. diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index e391415e96..51de6fdd92 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -42,13 +42,45 @@ custom widget to your form that sets the ``render_value`` argument:: username = forms.CharField(max_length=100) password = forms.PasswordField(widget=forms.PasswordInput(render_value=True)) +.. _deprecated-features-1.3: Features deprecated in 1.3 ========================== +Django 1.3 deprecates some features from earlier releases. +These features are still supported, but will be gradually phased out +over the next few release cycles. +Code taking advantage of any of the features below will raise a +``PendingDeprecationWarning`` in Django 1.3. This warning will be +silent by default, but may be turned on using Python's `warnings +module`_, or by running Python with a ``-Wd`` or `-Wall` flag. + +.. _warnings module: http://docs.python.org/library/warnings.html + +In Django 1.4, these warnings will become a ``DeprecationWarning``, +which is *not* silent. In Django 1.5 support for these features will +be removed entirely. + +.. seealso:: + + For more details, see the documentation :doc:`Django's release process + ` and our :doc:`deprecation timeline + `.` + +``mod_python`` support +~~~~~~~~~~~~~~~~~~~~~~ + +The ``mod_python`` library has not had a release since 2007 or a commit since +2008. The Apache Foundation board voted to remove ``mod_python`` from the set +of active projects in its version control repositories, and its lead developer +has shifted all of his efforts toward the lighter, slimmer, more stable, and +more flexible ``mod_wsgi`` backend. + +If you are currently using the ``mod_python`` request handler, it is strongly +encouraged you redeploy your Django instances using :doc:`mod_wsgi +`. What's new in Django 1.3 ======================== - diff --git a/docs/topics/install.txt b/docs/topics/install.txt index 3114517f62..2965c32ab6 100644 --- a/docs/topics/install.txt +++ b/docs/topics/install.txt @@ -27,27 +27,38 @@ probably already have it installed. Install Apache and mod_wsgi ============================= -If you just want to experiment with Django, skip ahead to the next section; -Django includes a lightweight web server you can use for testing, so you won't -need to set up Apache until you're ready to deploy Django in production. +If you just want to experiment with Django, skip ahead to the next +section; Django includes a lightweight web server you can use for +testing, so you won't need to set up Apache until you're ready to +deploy Django in production. -If you want to use Django on a production site, use Apache with `mod_wsgi`_. -mod_wsgi is similar to mod_perl -- it embeds Python within Apache and loads -Python code into memory when the server starts. Code stays in memory throughout -the life of an Apache process, which leads to significant performance gains over -other server arrangements. Make sure you have Apache installed, with the -mod_wsgi module activated. Django will work with any version of Apache that -supports mod_wsgi. +If you want to use Django on a production site, use Apache with +`mod_wsgi`_. mod_wsgi can operate in one of two modes: an embedded +mode and a daemon mode. In embedded mode, mod_wsgi is similar to +mod_perl -- it embeds Python within Apache and loads Python code into +memory when the server starts. Code stays in memory throughout the +life of an Apache process, which leads to significant performance +gains over other server arrangements. In daemon mode, mod_wsgi spawns +an independent daemon process that handles requests. The daemon +process can run as a different user than the webserver, possibly +leading to improved security, and the daemon process can be restarted +without restarting the entire Apache webserver, possibly making +refreshing your codebase more seamless. Consult the mod_wsgi +documentation to determine which mode is right for your setup. Make +sure you have Apache installed, with the mod_wsgi module activated. +Django will work with any version of Apache that supports mod_wsgi. -See :doc:`How to use Django with mod_wsgi ` for -information on how to configure mod_wsgi once you have it installed. +See :doc:`How to use Django with mod_wsgi ` +for information on how to configure mod_wsgi once you have it +installed. -If you can't use mod_wsgi for some reason, fear not: Django supports many other -deployment options. A great second choice is :doc:`mod_python -`, the predecessor to mod_wsgi. Additionally, Django -follows the WSGI_ spec, which allows it to run on a variety of server platforms. -See the `server-arrangements wiki page`_ for specific installation instructions -for each platform. +If you can't use mod_wsgi for some reason, fear not: Django supports +many other deployment options. Another option is :doc:`FastCGI +`, perfect for using Django with servers +other than Apache. Additionally, Django follows the WSGI_ spec, which +allows it to run on a variety of server platforms. See the +`server-arrangements wiki page`_ for specific installation +instructions for each platform. .. _Apache: http://httpd.apache.org/ .. _mod_wsgi: http://code.google.com/p/modwsgi/ @@ -255,15 +266,15 @@ latest bug fixes and improvements, follow these instructions: links. (Environment variables can be defined on Windows systems `from the Control Panel`_.) - .. admonition:: What about Apache and mod_python? + .. admonition:: What about Apache and mod_wsgi? - If you take the approach of setting ``PYTHONPATH``, you'll need to - remember to do the same thing in your Apache configuration once you - deploy your production site. Do this by setting ``PythonPath`` in your - Apache configuration file. + If you take the approach of setting ``PYTHONPATH``, you'll need + to remember to do the same thing in your WSGI application once + you deploy your production site. Do this by appending to + ``sys.path`` in your WSGI application. More information about deployment is available, of course, in our - :doc:`How to use Django with mod_python ` + :doc:`How to use Django with mod_wsgi ` documentation. 4. On Unix-like systems, create a symbolic link to the file diff --git a/docs/topics/settings.txt b/docs/topics/settings.txt index 59c02c3021..6d96190a90 100644 --- a/docs/topics/settings.txt +++ b/docs/topics/settings.txt @@ -64,20 +64,19 @@ Use the ``--settings`` command-line argument to specify the settings manually:: .. _django-admin.py: ../django-admin/ -On the server (mod_python) +On the server (mod_wsgi) -------------------------- -In your live server environment, you'll need to tell Apache/mod_python which -settings file to use. Do that with ``SetEnv``:: +In your live server environment, you'll need to tell your WSGI +application what settings file to use. Do that with ``os.environ``:: - - SetHandler python-program - PythonHandler django.core.handlers.modpython - SetEnv DJANGO_SETTINGS_MODULE mysite.settings - + import os -Read the :doc:`Django mod_python documentation ` for -more information. + os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings' + +Read the :doc:`Django mod_wsgi documentation +` for more information and other common +elements to a Django WSGI application. Default settings ================