diff --git a/docs/howto/deployment/wsgi/modwsgi.txt b/docs/howto/deployment/wsgi/modwsgi.txt index 689effba17..90ca1c0527 100644 --- a/docs/howto/deployment/wsgi/modwsgi.txt +++ b/docs/howto/deployment/wsgi/modwsgi.txt @@ -74,6 +74,20 @@ should put in this file, and what else you can add to it. or by :ref:`using mod_wsgi daemon mode` and ensuring that each site runs in its own daemon process. +.. admonition:: Fixing ``UnicodeEncodeError`` for file uploads + + If you get a ``UnicodeEncodeError`` when uploading files with file names + that contain non-ASCII characters, make sure Apache is configured to accept + non-ASCII file names:: + + export LANG='en_US.UTF-8' + export LC_ALL='en_US.UTF-8' + + A common location to put this configuration is ``/etc/apache2/envvars``. + + See the :ref:`unicode-files` section of the Unicode reference guide for + details. + Using a virtualenv ================== @@ -222,24 +236,3 @@ Authenticating against Django's user database from Apache Django provides a handler to allow Apache to authenticate users directly against Django's authentication backends. See the :doc:`mod_wsgi authentication documentation `. - -If you get a UnicodeEncodeError -=============================== - -If you're taking advantage of the internationalization features of Django (see -:doc:`/topics/i18n/index`) and you intend to allow users to upload files, you must -ensure that the environment used to start Apache is configured to accept -non-ASCII file names. If your environment is not correctly configured, you -will trigger ``UnicodeEncodeError`` exceptions when calling functions like -the ones in :mod:`os.path` on filenames that contain non-ASCII characters. - -To avoid these problems, the environment used to start Apache should contain -settings analogous to the following:: - - export LANG='en_US.UTF-8' - export LC_ALL='en_US.UTF-8' - -Consult the documentation for your operating system for the appropriate syntax -and location to put these configuration items; ``/etc/apache2/envvars`` is a -common location on Unix platforms. Once you have added these statements -to your environment, restart Apache. diff --git a/docs/howto/deployment/wsgi/uwsgi.txt b/docs/howto/deployment/wsgi/uwsgi.txt index 89eb9b5698..932d16817b 100644 --- a/docs/howto/deployment/wsgi/uwsgi.txt +++ b/docs/howto/deployment/wsgi/uwsgi.txt @@ -108,6 +108,17 @@ Example ini configuration file usage:: uwsgi --ini uwsgi.ini +.. admonition:: Fixing ``UnicodeEncodeError`` for file uploads + + If you get a ``UnicodeEncodeError`` when uploading files with file names + that contain non-ASCII characters, make sure uWSGI is configured to accept + non-ASCII file names by adding this to your ``uwsgi.ini``:: + + env = LANG='en_US.UTF-8' + + See the :ref:`unicode-files` section of the Unicode reference guide for + details. + See the uWSGI docs on `managing the uWSGI process`_ for information on starting, stopping and reloading the uWSGI workers. diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt index f52076d2f7..399a823b84 100644 --- a/docs/ref/unicode.txt +++ b/docs/ref/unicode.txt @@ -358,6 +358,36 @@ A couple of tips to remember when writing your own template tags and filters: translation objects into strings. It's easier to work solely with Unicode strings at that point. +.. _unicode-files: + +Files +===== + +If you intend to allow users to upload files, you must ensure that the +environment used to run Django is configured to work with non-ASCII file names. +If your environment isn't configured correctly, you'll encounter +``UnicodeEncodeError`` exceptions when saving files with file names that +contain non-ASCII characters. + +Filesystem support for UTF-8 file names varies and might depend on the +environment. Check your current configuration in an interactive Python shell by +running:: + + import sys + sys.getfilesystemencoding() + +This should output "UTF-8". + +The ``LANG`` environment variable is responsible for setting the expected +encoding on Unix platforms. Consult the documentation for your operating system +and application server for the appropriate syntax and location to set this +variable. + +In your development environment, you might need to add a setting to your +``~.bashrc`` analogous to::: + + export LANG="en_US.UTF-8" + Email =====