[Freeipa-devel] String guidelines in Python

[John Dennis]

There are a couple of simple things you should be aware of when it comes 
to using strings in our Python code.

1) If the string will be internationalized (e.g. is marked with _()) and 
it has more than one format substitution you *MUST* use *named* format 
specifiers, not positional format specifiers.

Here is an example of incorrect usage:

_("item %s has %s value") % (name, value)

Here is the correct usage:

_("item %(name)s has %(value)s value") % {'name':name, 'value':value}

-or-

_("item %(name)s has %(value)s value") % dict(name=name, value=value}

Why does this matter? Word ordering is locale dependent. Translators 
need the flexibility to reorder the words in the string. If you use 
positional format substitutions the translator can't reorder the 
wording. However, if you use named format substitutions the translator 
has the freedom to reorder the wording. Try to pick names for the for 
format specifiers which will provide hints to the translator as to 
meaning of the substitution.

2) If a function or method call has a signature like printf with a 
format string and a list of optional parameters to be formatted you 
should pass the format string and the parameters instead of formatting 
the string and just passing the format string. This is especially 
relevant to the logging methods.

Here is an example of incorrect usage:

self.debug("%s has %d items" % (self.name, self.count))

Here is the preferred usage:

self.debug("%s has %d items", self.name, self.count)

What's the difference and why does it matter? It's an efficiency issue. 
Many of the log methods will discard the message because it's filtered 
in some manner. If you pre-format the string you've done needless work 
if the message is discarded. The log routines will postpone formatting 
the message as long as it can and only formats the message after it 
determines the message will indeed be emitted. Other functions accepting 
a format string and optional parameters may also perform similar 
optimization. Converting some items into string format has significant 
cost, why perform that work only to discard it?

-- 
John Dennis <jdennis at redhat.com>

Looking to carve out IT costs?
www.redhat.com/carveoutcosts/