Package: pyicu-praxa
ContentsWelcomeBuilding PyICURunning PyICUWhat’s availableAPI DocumentationWelcomeWelcome to PyICU, a Python extension wrapping IBM’s International
Components for Unicode C++ library (ICU).PyICU is a project maintained by the Open Source Applications Foundation.The ICU homepage is:http://site.icu-project.org/Building PyICUBefore building PyICU the ICU libraries must be built and installed. Refer
to each system’s instructions for more information.PyICU is built with distutils or setuptools:verify that theINCLUDES,LFLAGS,CFLAGSandLIBRARIESdictionaries insetup.pycontain correct values for your platformpython setup.py buildsudo python setup.py installRunning PyICUMac OS X
Make sure thatDYLD_LIBRARY_PATHcontains paths to the directory(ies)
containing the ICU libs.Linux & Solaris
Make sure thatLD_LIBRARY_PATHcontains paths to the directory(ies)
containing the ICU libs or that you added the corresponding-rpathargument toLFLAGS.Windows
Make sure thatPATHcontains paths to the directory(ies)
containing the ICU DLLs.What’s availableSee theCHANGESfile for an up to date log of changes and additions.API DocumentationThere is no API documentation for PyICU. The API for ICU is documented athttp://icu-project.org/apiref/icu4c/and the following patterns can be
used to translate from the C++ APIs to the corresponding Python APIs.stringsThe ICU string type,UnicodeString, is a type pointing at a mutable
array ofUCharUnicode 16-bit wide characters. The Python unicode type
is an immutable string of 16-bit or 32-bit wide Unicode characters.Because of these differences,UnicodeStringand Python’sunicodetype are not merged into the same type when crossing the C++ boundary.
ICU APIs takingUnicodeStringarguments have been overloaded to also
accept Python str or unicode type arguments. In the case ofstrobjects,utf-8encoding is assumed when converting them toUnicodeStringobjects.To convert a Pythonstrencoded in a encoding other thanutf-8to
an ICUUnicodeStringuse theUnicodeString(str, encodingName)constructor.ICU’s C++ APIs accept and returnUnicodeStringarguments in several
ways: by value, by pointer or by reference.
When an ICU C++ API is documented to accept aUnicodeStringreference
parameter, it is safe to assume that there are several corresponding
PyICU python APIs making it accessible in simpler ways:For example, the'UnicodeString&Locale::getDisplayName(UnicodeString&)'API,
documented athttp://icu-project.org/apiref/icu4c/classLocale.htmlcan be invoked from Python in several ways:The ICU way>>> from icu import UnicodeString, Locale
>>> locale = Locale('pt_BR')
>>> string = UnicodeString()
>>> name = locale.getDisplayName(string)
>>> name
<UnicodeString: Portuguese (Brazil)>
>>> name is string
True                  <-- string arg was returned, modified in placeThe Python way>>> from icu import Locale
>>> locale = Locale('pt_BR')
>>> name = locale.getDisplayName()
>>> name
u'Portuguese (Brazil)'AUnicodeStringobject was allocated and converted to a Pythonunicodeobject.A UnicodeString can be coerced to a Python unicode string with Python’sunicode()constructor. The usuallen(),str(), comparison,[]and[:]operators are all available, with the additional
twists that slicing is not read-only and that+=is also available
since a UnicodeString is mutable. For example:>>> name = locale.getDisplayName()
u'Portuguese (Brazil)'
>>> name = UnicodeString(name)
>>> name
<UnicodeString: Portuguese (Brazil)>
>>> unicode(name)
u'Portuguese (Brazil)'
>>> len(name)
19
>>> str(name)           <-- works when chars fit with default encoding
'Portuguese (Brazil)'
>>> name[3]
u't'
>>> name[12:18]
<UnicodeString: Brazil>
>>> name[12:18] = 'the country of Brasil'
>>> name
<UnicodeString: Portuguese (the country of Brasil)>
>>> name += ' oh joy'
>>> name
<UnicodeString: Portuguese (the country of Brasil) oh joy>error reportingThe C++ ICU library does not use C++ exceptions to report errors. ICU
C++ APIs return errors via aUErrorCodereference argument. All such
APIs are wrapped by Python APIs that omit this argument and throw anICUErrorPython exception instead. The same is true for ICU APIs
taking both aParseErrorand aUErrorCode, they are both to be
omitted.For example, the'UnicodeString&DateFormat::format(constFormattable &, UnicodeString &, UErrorCode &)'API, documented athttp://icu-project.org/apiref/icu4c/classDateFormat.htmlis invoked from Python with:>>> from icu import DateFormat, Formattable
>>> df = DateFormat.createInstance()
>>> df
<SimpleDateFormat: M/d/yy h:mm a>
>>> f = Formattable(940284258.0, Formattable.kIsDate)
>>> df.format(f)
u'10/18/99 3:04 PM'Of course, the simpler'UnicodeString&DateFormat::format(UDate,UnicodeString &)'documented here:http://icu-project.org/apiref/icu4c/classDateFormat.htmlcan be used too:>>> from icu import DateFormat
>>> df = DateFormat.createInstance()
>>> df
<SimpleDateFormat: M/d/yy h:mm a>
>>> df.format(940284258.0)
u'10/18/99 3:04 PM'datesICU uses a double floating point type calledUDatethat represents the
number of milliseconds elapsed since 1970-jan-01 UTC for dates.In Python, the value returned by thetimemodule’stime()function is the number of seconds since 1970-jan-01 UTC. Because of this
difference, floating point values are multiplied by 1000 when passed to
APIs takingUDateand divided by 1000 when returned asUDate.Python’sdatetimeobjects, with or without timezone information, can
also be used with APIs takingUDatearguments. Thedatetimeobjects get converted toUDatewhen crossing into the C++ layer.arraysMany ICU API take array arguments. A list of elements of the array
element types is to be passed from Python.StringEnumerationAn ICUStringEnumerationhas threenextmethods:next()which
returns astrobjects,unext()which returnsunicodeobjects
andsnext()which returnsUnicodeStringobjects.
Any of these methods can be used as an iterator, using the Python
built-initerfunction.For example, letebe aStringEnumerationinstance:[s for s in e] is a list of 'str' objects
[s for s in iter(e.unext, None)] is a list of 'unicode' objects
[s for s in iter(e.snext, None)] is a list of 'UnicodeString' objectstimezonesThe ICUTimeZonetype may be wrapped with anICUtzinfotype for
usage with Python’sdatetimetype. For example:tz = ICUtzinfo(TimeZone.createTimeZone('US/Mountain'))
datetime.now(tz)or, even simpler:tz = ICUtzinfo.getInstance('Pacific/Fiji')
datetime.now(tz)To get the default time zone use:defaultTZ = ICUtzinfo.getDefault()To get the time zone’s id, use thetzidattribute or coerce the time
zone to a string:ICUtzinfo.getInstance('Pacific/Fiji').tzid -> 'Pacific/Fiji'
str(ICUtzinfo.getInstance('Pacific/Fiji')) -> 'Pacific/Fiji'