home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / share / pyshared / PyICU-1.0.egg-info < prev    next >
Encoding:
Python egg package info  |  2010-07-18  |  9.9 KB  |  241 lines
  1. Metadata-Version: 1.0
  2. Name: PyICU
  3. Version: 1.0
  4. Summary: Python extension wrapping the ICU C++ API
  5. Home-page: http://pyicu.osafoundation.org/
  6. Author: Open Source Applications Foundation
  7. Author-email: UNKNOWN
  8. License: UNKNOWN
  9. Description: 
  10.         ---------------------
  11.         README file for PyICU
  12.         ---------------------
  13.         
  14.         .. contents::
  15.         
  16.         
  17.         Welcome
  18.         -------
  19.         
  20.         Welcome to PyICU, a Python extension wrapping IBM's International
  21.         Components for Unicode C++ library (ICU).
  22.         
  23.         PyICU is a project maintained by the Open Source Applications Foundation.
  24.         
  25.         The ICU homepage is: http://site.icu-project.org/
  26.         
  27.         
  28.         Building PyICU
  29.         --------------
  30.         
  31.         Before building PyICU the ICU libraries must be built and installed. Refer
  32.         to each system's instructions for more information.
  33.         
  34.         PyICU is built with distutils or setuptools:
  35.            - verify that the ``INCLUDES``, ``LFLAGS``, ``CFLAGS`` and ``LIBRARIES``
  36.              dictionaries in ``setup.py`` contain correct values for your platform
  37.            - ``python setup.py build``
  38.            - ``sudo python setup.py install``
  39.         
  40.         
  41.         Running PyICU
  42.         -------------
  43.         
  44.           - Mac OS X
  45.             Make sure that ``DYLD_LIBRARY_PATH`` contains paths to the directory(ies)
  46.             containing the ICU libs.
  47.         
  48.           - Linux & Solaris
  49.             Make sure that ``LD_LIBRARY_PATH`` contains paths to the directory(ies)
  50.             containing the ICU libs or that you added the corresponding ``-rpath``
  51.             argument to ``LFLAGS``.
  52.         
  53.           - Windows
  54.             Make sure that ``PATH`` contains paths to the directory(ies)
  55.             containing the ICU DLLs.
  56.         
  57.         
  58.         What's available
  59.         ----------------
  60.         
  61.         See the ``CHANGES`` file for an up to date log of changes and additions.
  62.         
  63.         
  64.         API Documentation
  65.         -----------------
  66.         
  67.         There is no API documentation for PyICU. The API for ICU is documented at
  68.         http://icu-project.org/apiref/icu4c/ and the following patterns can be
  69.         used to translate from the C++ APIs to the corresponding Python APIs.
  70.         
  71.           - strings
  72.         
  73.             The ICU string type, ``UnicodeString``, is a type pointing at a mutable
  74.             array of ``UChar`` Unicode 16-bit wide characters. The Python unicode type
  75.             is an immutable string of 16-bit or 32-bit wide Unicode characters.
  76.         
  77.             Because of these differences, ``UnicodeString`` and Python's ``unicode``
  78.             type are not merged into the same type when crossing the C++ boundary.
  79.             ICU APIs taking ``UnicodeString`` arguments have been overloaded to also
  80.             accept Python str or unicode type arguments. In the case of ``str``
  81.             objects, ``utf-8`` encoding is assumed when converting them to
  82.             ``UnicodeString`` objects.
  83.         
  84.             To convert a Python ``str`` encoded in a encoding other than ``utf-8`` to
  85.             an ICU ``UnicodeString`` use the ``UnicodeString(str, encodingName)``
  86.             constructor.
  87.         
  88.             ICU's C++ APIs accept and return ``UnicodeString`` arguments in several
  89.             ways: by value, by pointer or by reference.
  90.             When an ICU C++ API is documented to accept a ``UnicodeString`` reference
  91.             parameter, it is safe to assume that there are several corresponding
  92.             PyICU python APIs making it accessible in simpler ways:
  93.         
  94.             For example, the
  95.             ``'UnicodeString &Locale::getDisplayName(UnicodeString &)'`` API,
  96.             documented at
  97.             http://icu-project.org/apiref/icu4c/classLocale.html
  98.             can be invoked from Python in several ways:
  99.         
  100.             1. The ICU way
  101.         
  102.                 >>> from icu import UnicodeString, Locale
  103.                 >>> locale = Locale('pt_BR')
  104.                 >>> string = UnicodeString()
  105.                 >>> name = locale.getDisplayName(string)
  106.                 >>> name
  107.                 <UnicodeString: Portuguese (Brazil)>
  108.                 >>> name is string
  109.                 True                  <-- string arg was returned, modified in place
  110.         
  111.             2. The Python way
  112.         
  113.                 >>> from icu import Locale
  114.                 >>> locale = Locale('pt_BR')
  115.                 >>> name = locale.getDisplayName()
  116.                 >>> name
  117.                 u'Portuguese (Brazil)'
  118.         
  119.                 A ``UnicodeString`` object was allocated and converted to a Python
  120.                 ``unicode`` object.
  121.         
  122.             A UnicodeString can be coerced to a Python unicode string with Python's
  123.             ``unicode()`` constructor. The usual ``len()``, ``str()``, comparison,
  124.             ``[]`` and ``[:]`` operators are all available, with the additional
  125.             twists that slicing is not read-only and that ``+=`` is also available
  126.             since a UnicodeString is mutable. For example:
  127.         
  128.                 >>> name = locale.getDisplayName()
  129.                 u'Portuguese (Brazil)'
  130.                 >>> name = UnicodeString(name)
  131.                 >>> name
  132.                 <UnicodeString: Portuguese (Brazil)>
  133.                 >>> unicode(name)
  134.                 u'Portuguese (Brazil)'
  135.                 >>> len(name)
  136.                 19
  137.                 >>> str(name)           <-- works when chars fit with default encoding
  138.                 'Portuguese (Brazil)'
  139.                 >>> name[3]
  140.                 u't'
  141.                 >>> name[12:18]
  142.                 <UnicodeString: Brazil>
  143.                 >>> name[12:18] = 'the country of Brasil'
  144.                 >>> name
  145.                 <UnicodeString: Portuguese (the country of Brasil)>
  146.                 >>> name += ' oh joy'
  147.                 >>> name
  148.                 <UnicodeString: Portuguese (the country of Brasil) oh joy>
  149.         
  150.           - error reporting
  151.         
  152.             The C++ ICU library does not use C++ exceptions to report errors. ICU
  153.             C++ APIs return errors via a ``UErrorCode`` reference argument. All such
  154.             APIs are wrapped by Python APIs that omit this argument and throw an
  155.             ``ICUError`` Python exception instead. The same is true for ICU APIs
  156.             taking both a ``ParseError`` and a ``UErrorCode``, they are both to be
  157.             omitted.
  158.         
  159.             For example, the ``'UnicodeString &DateFormat::format(const Formattable &,
  160.             UnicodeString &, UErrorCode &)'`` API, documented at
  161.             http://icu-project.org/apiref/icu4c/classDateFormat.html
  162.             is invoked from Python with:
  163.         
  164.                 >>> from icu import DateFormat, Formattable
  165.                 >>> df = DateFormat.createInstance()
  166.                 >>> df
  167.                 <SimpleDateFormat: M/d/yy h:mm a>
  168.                 >>> f = Formattable(940284258.0, Formattable.kIsDate)
  169.                 >>> df.format(f)
  170.                 u'10/18/99 3:04 PM'
  171.              
  172.             Of course, the simpler ``'UnicodeString &DateFormat::format(UDate,
  173.             UnicodeString &)'`` documented here:
  174.             http://icu-project.org/apiref/icu4c/classDateFormat.html
  175.             can be used too:
  176.         
  177.                 >>> from icu import DateFormat
  178.                 >>> df = DateFormat.createInstance()
  179.                 >>> df
  180.                 <SimpleDateFormat: M/d/yy h:mm a>
  181.                 >>> df.format(940284258.0)
  182.                 u'10/18/99 3:04 PM'
  183.         
  184.           - dates
  185.         
  186.             ICU uses a double floating point type called ``UDate`` that represents the
  187.             number of milliseconds elapsed since 1970-jan-01 UTC for dates.
  188.         
  189.             In Python, the value returned by the ``time`` module's ``time()``
  190.             function is the number of seconds since 1970-jan-01 UTC. Because of this
  191.             difference, floating point values are multiplied by 1000 when passed to
  192.             APIs taking ``UDate`` and divided by 1000 when returned as ``UDate``.
  193.         
  194.             Python's ``datetime`` objects, with or without timezone information, can
  195.             also be used with APIs taking ``UDate`` arguments. The ``datetime``
  196.             objects get converted to ``UDate`` when crossing into the C++ layer.
  197.         
  198.           - arrays
  199.         
  200.             Many ICU API take array arguments. A list of elements of the array
  201.             element types is to be passed from Python.
  202.         
  203.           - StringEnumeration
  204.         
  205.             An ICU ``StringEnumeration`` has three ``next`` methods: ``next()`` which
  206.             returns a ``str`` objects, ``unext()`` which returns ``unicode`` objects
  207.             and ``snext()`` which returns ``UnicodeString`` objects.
  208.             Any of these methods can be used as an iterator, using the Python
  209.             built-in ``iter`` function. 
  210.         
  211.             For example, let ``e`` be a ``StringEnumeration`` instance::
  212.         
  213.               [s for s in e] is a list of 'str' objects
  214.               [s for s in iter(e.unext, None)] is a list of 'unicode' objects
  215.               [s for s in iter(e.snext, None)] is a list of 'UnicodeString' objects
  216.         
  217.           - timezones
  218.         
  219.             The ICU ``TimeZone`` type may be wrapped with an ``ICUtzinfo`` type for
  220.             usage with Python's ``datetime`` type. For example::
  221.         
  222.                tz = ICUtzinfo(TimeZone.createTimeZone('US/Mountain'))
  223.                datetime.now(tz)
  224.         
  225.             or, even simpler::
  226.         
  227.                tz = ICUtzinfo.getInstance('Pacific/Fiji')
  228.                datetime.now(tz)
  229.         
  230.             To get the default time zone use::
  231.         
  232.                defaultTZ = ICUtzinfo.getDefault()
  233.         
  234.             To get the time zone's id, use the ``tzid`` attribute or coerce the time
  235.             zone to a string::
  236.         
  237.                ICUtzinfo.getInstance('Pacific/Fiji').tzid -> 'Pacific/Fiji'
  238.                str(ICUtzinfo.getInstance('Pacific/Fiji')) -> 'Pacific/Fiji'
  239.         
  240. Platform: UNKNOWN
  241.