---------------------
README file for PyICU
---------------------
.. contents::
Welcome
-------
Welcome 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 PyICU
--------------
Before 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 the ``INCLUDES``, ``LFLAGS``, ``CFLAGS`` and ``LIBRARIES``
dictionaries in ``setup.py`` contain correct values for your platform
- ``python setup.py build``
- ``sudo python setup.py install``
Running PyICU
-------------
- Mac OS X
Make sure that ``DYLD_LIBRARY_PATH`` contains paths to the directory(ies)
containing the ICU libs.
- Linux & Solaris
Make sure that ``LD_LIBRARY_PATH`` contains paths to the directory(ies)
containing the ICU libs or that you added the corresponding ``-rpath``
argument to ``LFLAGS``.
- Windows
Make sure that ``PATH`` contains paths to the directory(ies)
containing the ICU DLLs.
What's available
----------------
See the ``CHANGES`` file for an up to date log of changes and additions.
API Documentation
-----------------
There is no API documentation for PyICU. The API for ICU is documented at
http://icu-project.org/apiref/icu4c/ and the following patterns can be
used to translate from the C++ APIs to the corresponding Python APIs.
- strings
The ICU string type, ``UnicodeString``, is a type pointing at a mutable
array of ``UChar`` Unicode 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, ``UnicodeString`` and Python's ``unicode``
type are not merged into the same type when crossing the C++ boundary.
ICU APIs taking ``UnicodeString`` arguments have been overloaded to also
accept Python str or unicode type arguments. In the case of ``str``
objects, ``utf-8`` encoding is assumed when converting them to
``UnicodeString`` objects.
To convert a Python ``str`` encoded in a encoding other than ``utf-8`` to
an ICU ``UnicodeString`` use the ``UnicodeString(str, encodingName)``
constructor.
ICU's C++ APIs accept and return ``UnicodeString`` arguments in several
ways: by value, by pointer or by reference.
When an ICU C++ API is documented to accept a ``UnicodeString`` reference
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 at
http://icu-project.org/apiref/icu4c/classLocale.html
can be invoked from Python in several ways:
1. 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 place
2. The Python way
>>> from icu import Locale
>>> locale = Locale('pt_BR')
>>> name = locale.getDisplayName()
>>> name
u'Portuguese (Brazil)'
A ``UnicodeString`` object was allocated and converted to a Python
``unicode`` object.
A UnicodeString can be coerced to a Python unicode string with Python's
``unicode()`` constructor. The usual ``len()``, ``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 reporting
The C++ ICU library does not use C++ exceptions to report errors. ICU
C++ APIs return errors via a ``UErrorCode`` reference argument. All such
APIs are wrapped by Python APIs that omit this argument and throw an
``ICUError`` Python exception instead. The same is true for ICU APIs
taking both a ``ParseError`` and a ``UErrorCode``, they are both to be
omitted.
For example, the ``'UnicodeString &DateFormat::format(const Formattable &,
UnicodeString &, UErrorCode &)'`` API, documented at
http://icu-project.org/apiref/icu4c/classDateFormat.html
is 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.html
can 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'
- dates
ICU uses a double floating point type called ``UDate`` that represents the
number of milliseconds elapsed since 1970-jan-01 UTC for dates.
In Python, the value returned by the ``time`` module's ``time()``
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 taking ``UDate`` and divided by 1000 when returned as ``UDate``.
Python's ``datetime`` objects, with or without timezone information, can
also be used with APIs taking ``UDate`` arguments. The ``datetime``
objects get converted to ``UDate`` when crossing into the C++ layer.
- arrays
Many ICU API take array arguments. A list of elements of the array
element types is to be passed from Python.
- StringEnumeration
An ICU ``StringEnumeration`` has three ``next`` methods: ``next()`` which
returns a ``str`` objects, ``unext()`` which returns ``unicode`` objects
and ``snext()`` which returns ``UnicodeString`` objects.
Any of these methods can be used as an iterator, using the Python
built-in ``iter`` function.
For example, let ``e`` be a ``StringEnumeration`` instance::
[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' objects
- timezones
The ICU ``TimeZone`` type may be wrapped with an ``ICUtzinfo`` type for
usage with Python's ``datetime`` type. 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 the ``tzid`` attribute or coerce the time
zone to a string::
ICUtzinfo.getInstance('Pacific/Fiji').tzid -> 'Pacific/Fiji'
str(ICUtzinfo.getInstance('Pacific/Fiji')) -> 'Pacific/Fiji'
