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:

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:

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.

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: