Package: icupy
icupyPython bindings forICU4Cusingpybind11.Changes from ICU4CNaming ConventionsRenamed functions, methods, and C++ enumerators to conform toPEP 8.Function Names:
Uselower_case_with_underscoresstyle.Method Names:
Uselower_case_with_underscoresstyle.
Also, use one leading underscore only for protected methods.C++ Enumerators: UseUPPER_CASE_WITH_UNDERSCORESstyle without a leading "k". (e.g.,kDateOffset→DATE_OFFSET)APIs that match Python reserved words: e.g.,with()→with_()Error HandlingUnlike the C/C++ APIs,icupyraises theicupy.icu.ICUErrorexception if an error code indicates a failure instead of receiving an error codeUErrorCode.You can access theicu::ErrorCodeobject fromICUError.args[0].
For example:fromicupyimporticutry:...excepticu.ICUErrorase:print(e.args[0])# → icupy.icu.ErrorCodeprint(e.args[0].get())# → icupy.icu.UErrorCodeExamplesicu::UnicodeStringwitherror callbackfromicupyimporticucnv=icu.ucnv_open('utf-8')action=icu.UCNV_TO_U_CALLBACK_ESCAPEcontext=icu.ConstVoidPtr(icu.UCNV_ESCAPE_C)icu.ucnv_set_to_ucall_back(cnv,action,context)utf8=b'\x61\xfe\x62'# Impossible bytess=icu.UnicodeString(utf8,-1,cnv)str(s)# → 'a\\xFEb'action=icu.UCNV_TO_U_CALLBACK_ESCAPEcontext=icu.ConstVoidPtr(icu.UCNV_ESCAPE_XML_DEC)icu.ucnv_set_to_ucall_back(cnv,action,context)s=icu.UnicodeString(utf8,-1,cnv)str(s)# → 'a&#254;b'icu::UnicodeStringwithuser callbackfromicupyimporticudef_to_callback(_context:object,_args:icu.UConverterToUnicodeArgs,_code_units:bytes,_length:int,_reason:icu.UConverterCallbackReason,_error_code:icu.UErrorCode,)->icu.UErrorCode:if_reason==icu.UCNV_ILLEGAL:_source=''.join(['%{:02X}'.format(x)forxin_code_units])icu.ucnv_cb_to_uwrite_uchars(_args,_source,len(_source),0)_error_code=icu.U_ZERO_ERRORreturn_error_codecnv=icu.ucnv_open('utf-8')action=icu.UConverterToUCallbackPtr(_to_callback)context=icu.ConstVoidPtr(None)icu.ucnv_set_to_ucall_back(cnv,action,context)utf8=b'\x61\xfe\x62'# Impossible bytess=icu.UnicodeString(utf8,-1,cnv)str(s)# → 'a%FEb'icu::DateFormatfromicupyimporticutz=icu.TimeZone.create_time_zone('America/Los_Angeles')fmt=icu.DateFormat.create_instance_for_skeleton('yMMMMd',icu.Locale.get_english())fmt.set_time_zone(tz)dest=icu.UnicodeString()s=fmt.format(0,dest)str(s)# → 'December 31, 1969'icu::MessageFormatfromicupyimporticufmt=icu.MessageFormat("At {1,time,::jmm} on {1,date,::dMMMM}, ""there was{2}on planet {0,number}.",icu.Locale.get_us(),)tz=icu.TimeZone.get_gmt()subfmts=fmt.get_formats()subfmts[0].set_time_zone(tz)subfmts[1].set_time_zone(tz)date=1637685775000.0# 2021-11-23T16:42:55Zobj=icu.Formattable([icu.Formattable(7),icu.Formattable(date,icu.Formattable.IS_DATE),icu.Formattable(icu.UnicodeString('a disturbance in the Force')),])dest=icu.UnicodeString()s=fmt.format(obj,dest)str(s)# → 'At 4:42 PM on November 23, there was a disturbance in the Force on planet 7.'icu::number::NumberFormatterfromicupyimporticufmt=icu.number.NumberFormatter.with_().unit(icu.MeasureUnit.get_meter()).per_unit(icu.MeasureUnit.get_second())print(fmt.locale(icu.Locale.get_us()).format_double(3000).to_string())# → '3,000 m/s'print(fmt.locale(icu.Locale.get_france()).format_double(3000).to_string())# → '3 000 m/s'print(fmt.locale('ar').format_double(3000).to_string())# → '٣٬٠٠٠ م/ث'icu::BreakIteratorfromicupyimporticutext=icu.UnicodeString('In the meantime Mr. Weston arrived with his small ship.')bi=icu.BreakIterator.create_sentence_instance(icu.Locale('en'))bi.set_text(text)list(bi)# → [20, 55]# filter based on common English language abbreviationsbi=icu.BreakIterator.create_sentence_instance(icu.Locale('en@ss=standard'))bi.set_text(text)list(bi)# → [55]icu::IDNA(UTS #46)fromicupyimporticuuts46=icu.IDNA.create_uts46_instance(icu.UIDNA_NONTRANSITIONAL_TO_ASCII)dest=icu.UnicodeString()info=icu.IDNAInfo()uts46.name_to_ascii(icu.UnicodeString('faß.ExAmPlE'),dest,info)info.get_errors()# → 0str(dest)# → 'xn--fa-hia.example'For more examples, seetests.InstallationPrerequisitesPython>=3.8ICU4C(ICU - The International Components for Unicode)(>=64 recommended)C++17 compatible compiler (seesupported compilers)CMake>=3.7Installing prerequisitesWindowsInstall the following dependencies.Python>=3.8Pre-built ICU4C binary package(>=64 recommended)Visual Studio 2015 Update 3 or newer. Visual Studio 2019 or newer recommendedCMake>=3.7Note: Add CMake to the system PATH.LinuxTo install dependencies, run the following command:Ubuntu/Debian:sudoaptinstallg++cmakelibicu-devpython3-devpython3-pipFedora:sudodnfinstallgcc-c++cmakeiculibicu-develpython3-develIf your system's ICU is out of date, considerbuilding ICU4C from sourceor installingpre-built
ICU4C binary package.Building icupy from sourceConfiguring environment variables:Windows:Set theICU_ROOTenvironment variable to the root of the ICU installation (default isC:\icu).
For example, if the ICU is located inC:\icu4c:setICU_ROOT=C:\icu4cor in PowerShell:$env:ICU_ROOT="C:\icu4c"To verify settings usingicuinfo(64-bit):%ICU_ROOT%\bin64\icuinfoor in PowerShell:&$env:ICU_ROOT\bin64\icuinfoLinux:If the ICU is located in a non-regular place, set thePKG_CONFIG_PATHandLD_LIBRARY_PATHenvironment variables.
For example, if the ICU is located in/usr/local:exportPKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATHexportLD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATHTo verify settings usingpkg-config:$pkg-config--cflags--libsicu-uc
-I/usr/local/include-L/usr/local/lib-licuuc-licudataInstalling from PyPI:pipinstallicupyOptionally, CMake environment variables are available.
For example, using the Ninja build system and Clang:CMAKE_GENERATOR=NinjaCXX=clang++pipinstallicupyAlternatively, installing development version from the git repository:pipinstallgit+https://github.com/miute/icupy.gitUsageConfiguring environment variables:Windows:Set theICU_ROOTenvironment variable to the root of the ICU installation (default isC:\icu).
For example, if the ICU is located inC:\icu4c:setICU_ROOT=C:\icu4cor in PowerShell:$env:ICU_ROOT="C:\icu4c"Linux:If the ICU is located in a non-regular place, set theLD_LIBRARY_PATHenvironment variables.
For example, if the ICU is located in/usr/local:exportLD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATHUsingicupy:importicupy.icuasicu# orfromicupyimporticuLicenseThis project is licensed under theMIT License.