For the full documentation see Unicode.

For the impatient, here's a quick check list to ensure everything is ready to use unicode in your pylons application :

• Database configuration
  • encode your database to utf-8
  • encode your tables to utf-8
  • encode your columns to utf-8 (some databases such as MySQL allow that)

• SQLAlchemy
  • Use Unicode Columns instead of String Columns
  • Don't forget to define a _unicode_ method for your models. (when will it be invoked ?)

• • If you are using MySQL
    • you can add ?charset=utf8&use_unicode=0 at the end of the engine's url, typically in your development.ini :
      MyApp/development.ini

      sqlalchemy.url = mysql://user:password@host:port/database?charset=utf8&use_unicode=0

      as advised here

• FormAlchemy
  • add this line in mypylonsapp/forms/_init_.py:
    MyApp/myapp/forms/_init_.py

    from formalchemy import config as fa_config
    fa_config.encoding = 'utf8'

  • If you define your own _str_ and _repr_ methods (these will populate your form fields), don't forget to ENCODE your unicode strings to utf-8 before returning them.
    myapp/models/myModelClass.py

    class MyClass(BaseClass):
        def __repr__(self):
            return "< MyClass '%s' >" %(self.someMeaningfulUnicodeAttribute.encode("utf-8"))    
        def __str__(self):
            return "%s" %(self.someMeaningfulUnicodeAttribute.encode("utf-8"))

• Source code
  • put

    -*- encoding:utf-8 -*-

    at the top of every source file

  • if you use external tools to insert data in the database (such as phpmyadmin), check their character set configuration too (and maybe their source files ?)
  • always use unicode literals if your strings contains non-ascii characters (u"Hôtel") (or always user unicode literals (full stop) ? )

• Pylons configuration files
  • put this in config/environement.py (at the end of the load_environement function ?)
    myapp/config/environement.py

    config [ 'pylons.response_options' ][ 'charset' ] = 'utf-8'

• Mako templates
  • Don't forget to add the content-type meta in your HTML > Head

    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

• WebError
  • As of version 0.10-1, WebError seems to have a bug : when your application raises an exception, and if debug mode is on, WebError catches the exception and a helpful error page is displayed with the traceback, showing you where in the code your error is. Unfortunatly, if a line of code contains a non-ascii character, WebError will itself raise an error and you'll have an ungly 500 internal server error instead of the beautiful WebError rendered error page. To fix this, I tried the following, this might work for you :
    • In weberror/evalexception.py:686 : decode long_text_er using utf8. The line should look like this :
      weberror/evalexception.py line 686

      (long_er, len(long_text_er.splitlines()), long_text_er.decode('utf8'))

    • Same thing in weberror/evalexception.py:714 : decode short_text_er using utf8. The line should look like this :
      weberror/evalexception.py line 714

      (short_er, len(short_text_er.splitlines()), short_text_er.decode('utf8'),

    • In weberror/formatter.py, replace every occurence of latin to utf8.

WebError should now display the error page again, but unfortunatly non-ascii characters wont render correctly.

Note that Christoph Zwerschke has opened a trac ticket for this bug, and that he has proposed a simpler solution for this problem : just encode short_text_er and long_text_er to utf8 in weberror.evalexception.format_eval_html, leaving weberror/formatter.py. This solution did not work for me but could work for others.

I am looking for authors to complete me.

A somewhat similar checklist can be found at the django project documentation