salt/doc/ref/internals/unicode.rst

Unicode in Salt

Though Unicode handling in large projects can often be complex, Salt adheres to several basic rules to help developers handle Unicode correctly.

(For a basic introduction to this problem, see Ned Batchelder's excellent intoroduction to the topic <http://nedbatchelder.com/text/unipain/unipain.html>.

Salt's basic workflow for Unicode handling is as follows:

1. Salt should convert whatever data is passed on CLI/API to Unicode. Internally, everything that Salt does should be Unicode unless it is printing to the screen or writing to storage.
2. Modules and various Salt pluggable systems use incoming data assuming Unicode.

   2.1) For Salt modules that query an API; the module should convert the data

   received from the API into Unicode.

   2.2) For Salt modules that shell out to get output; the module should

   convert data received into Unicode. (This does not apply if using the cmd <salt.modules.cmdmod> execution module, which should handle this for you.

   2.3) For Salt modules which print directly to the console (not via an

   outputter) or which write directly to disk, a string should be encoded when appropriate. To handle this conversion, the global variable __salt_system_encoding__ is available, which declares the locale of the system that Salt is running on.

3. When a function in a Salt module returns a string, it should return a unicode type in Python 2.
4. When Salt delivers the data to an outputter or a returner, it is the job of the outputter or returner to encode the Unicode before displaying it on the console or writing it to storage.