Metadata-Version: 1.1
Name: wcwidth
Version: 0.1.5
Summary: Measures number of Terminal column cells of wide-character codes
Home-page: https://github.com/jquast/wcwidth
Author: Jeff Quast
Author-email: contact@jeffquast.com
License: MIT
Description: .. image:: https://img.shields.io/travis/jquast/wcwidth.svg
            :target: https://travis-ci.org/jquast/wcwidth
            :alt: Travis Continous Integration
        
        .. image:: https://img.shields.io/coveralls/jquast/wcwidth.svg
            :target: https://coveralls.io/r/jquast/wcwidth
            :alt: Coveralls Code Coverage
        
        .. image:: https://img.shields.io/pypi/v/wcwidth.svg
            :target: https://pypi.python.org/pypi/wcwidth/
            :alt: Latest Version
        
        .. image:: https://img.shields.io/github/license/jquast/wcwidth.svg
            :target: https://pypi.python.org/pypi/wcwidth/
            :alt: License
        
        .. image:: https://img.shields.io/pypi/wheel/wcwidth.svg
            :alt: Wheel Status
        
        .. image:: https://img.shields.io/pypi/dm/wcwidth.svg
            :target: https://pypi.python.org/pypi/wcwidth/
            :alt: Downloads
        
        
        ============
        Introduction
        ============
        
        This API is mainly for Terminal Emulator implementors, or those writing
        programs that expect to interpreted by a terminal emulator and wish to
        determine the printable width of a string on a Terminal.
        
        Usually, the length of the string is equivalent to the number of cells
        it occupies except that there are are also some categories of characters
        which occupy 2 or even 0 cells.  POSIX-conforming systems provide
        ``wcwidth(3)`` and ``wcswidth(3)`` of which this module's interface mirrors
        precisely.
        
        This library aims to be forward-looking, portable, and most correct.  The most
        current release of this API is based from Unicode Standard release files:
        
        ``EastAsianWidth-8.0.0.txt``
          *2015-02-10, 21:00:00 GMT [KW, LI]*
        
        ``DerivedGeneralCategory-8.0.0.txt``
          *2015-02-13, 13:47:11 GMT [MD]*
        
        Installation
        ------------
        
        The stable version of this package is maintained on pypi, install using pip::
        
            pip install wcwidth
        
        Example
        -------
        
        To Display ``u'コンニチハ'`` right-adjusted on screen of 80 columns::
        
            >>> from wcwidth import wcswidth
            >>> text = u'コンニチハ'
            >>> print(u' ' * (80 - wcswidth(text)) + text)
        
        wcwidth, wcswidth
        -----------------
        Use function ``wcwidth()`` to determine the length of a *single character*,
        and ``wcswidth()`` to determine the length of a *string of characters*.
        
        Function ``wcswidth()`` simply returns the sum of all values along a string,
        individually mapped over function ``wcwidth()``, or, ``-1`` in total
        if any part of the string's return value from ``wcwidth()`` results in
        a value of ``-1``.
        
        Return values of wcwidth are:
        
        ``-1``
          Indeterminate (not printable).
        
        ``0``
          Does not advance the cursor, such as NULL or Combining.
        
        ``2``
          Characters of category East Asian Wide (W) or East Asian
          Full-width (F) which are displayed using two terminal cells.
        
        ``1``
          All others.
        
        A more exact list of conditions of these return values may be found in the
        module docstring::
        
            $ pydoc wcwidth
        
        =======
        Caveats
        =======
        
        This library does its best to return the most appropriate return value for a
        very particular terminal user interface where a monospaced fixed-cell
        rendering is expected.  As the POSIX Terminal programming interface does not
        provide any means to determine the unicode support level of a connecting
        terminal, we can only do our best to return what we **assume** to be correct
        for the given codepoint, and not the result of any terminal emulator
        particular.
        
        ==========
        Developing
        ==========
        
        Execute the command ``python setup.py develop`` to prepare an environment
        for running tests (``python setup.py test``), updating tables (
        ``python setup.py update``) or using any of the scripts in the ``bin/``
        sub-folder.  These files are only made available in the source repository.
        
        You may determine an exacting list of these discrepancies using the project
        file `wcwidth-libc-comparator.py
        <https://github.com/jquast/wcwidth/tree/master/bin/wcwidth-libc-comparator.py>`_.
        
        Updating Tables
        ---------------
        
        The command ``python setup.py update`` will fetch the following resources:
        
        - http://www.unicode.org/Public/UNIDATA/EastAsianWidth.txt
        - http://www.unicode.org/Public/UNIDATA/extracted/DerivedGeneralCategory.txt
        
        And generates the table files:
        
        - `wcwidth/table_wide.py <https://github.com/jquast/wcwidth/tree/master/wcwidth/table_wide.py>`_
        - `wcwidth/table_zero.py <https://github.com/jquast/wcwidth/tree/master/wcwidth/table_zero.py>`_
        
        wcwidth.c
        ---------
        
        This code was originally derived directly from C code of the same name,
        whose latest version is available at
        http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c And is authored by Markus Kuhn,
        2007-05-26 (Unicode 5.0).
        
        Uses
        ----
        
        This library is used in:
        
        - `jquast/blessed`_, a simplified wrapper around curses.
        
        - `jonathanslenders/python-prompt-toolkit`_, a Library for building powerful
          interactive command lines in Python.
        
        Additional tools for displaying and testing wcwidth are found in the `bin/
        <https://in.linkedin.com/in/chiragjog>`_ folder of this project. They are not
        distributed as a script or part of the module.
        
        .. _`jquast/blessed`: https://github.com/jquast/blessed
        .. _`jonathanslenders/python-prompt-toolkit`: https://github.com/jonathanslenders/python-prompt-toolkit
        
        
        =======
        History
        =======
        
        0.1.5 *2015-09-13 Alpha*
          * **Bugfix**:
            Resolution of "combining_ character width" issue, most especially
            those that previously returned -1 now often (correctly) return 0.
            resolved by `Philip Craig`_ via `PR #11`_.
          * **Deprecated**:
            The module path ``wcwidth.table_comb`` is no longer available,
            it has been superseded by module path ``wcwidth.table_zero``.
        
        0.1.4 *2014-11-20 Pre-Alpha*
          * **Feature**: ``wcswidth()`` now determines printable length
            for (most) combining_ characters.  The developer's tool
            `bin/wcwidth-browser.py`_ is improved to display combining_
            characters when provided the ``--combining`` option
            (`Thomas Ballinger`_ and `Leta Montopoli`_ `PR #5`_).
          * **Feature**: added static analysis (prospector_) to testing
            framework.
        
        0.1.3 *2014-10-29 Pre-Alpha*
          * **Bugfix**: 2nd parameter of wcswidth was not honored.
            (`Thomas Ballinger`_, `PR #4`_).
        
        0.1.2 *2014-10-28 Pre-Alpha*
          * **Updated** tables to Unicode Specification 7.0.0.
            (`Thomas Ballinger`_, `PR #3`_).
        
        0.1.1 *2014-05-14 Pre-Alpha*
          * Initial release to pypi, Based on Unicode Specification 6.3.0
        
        .. _`prospector`: https://github.com/landscapeio/prospector
        .. _`combining`: https://en.wikipedia.org/wiki/Combining_character
        .. _`bin/wcwidth-browser.py`: https://github.com/jquast/wcwidth/tree/master/bin/wcwidth-browser.py
        .. _`Thomas Ballinger`: https://github.com/thomasballinger
        .. _`Leta Montopoli`: https://github.com/lmontopo
        .. _`Philip Craig`: https://github.com/philipc
        .. _`PR #3`: https://github.com/jquast/wcwidth/pull/3
        .. _`PR #4`: https://github.com/jquast/wcwidth/pull/4
        .. _`PR #5`: https://github.com/jquast/wcwidth/pull/5
        .. _`PR #11`: https://github.com/jquast/wcwidth/pull/11
        
Keywords: terminal,emulator,wcwidth,wcswidth,cjk,combining,xterm,console
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Localization
Classifier: Topic :: Software Development :: Internationalization
Classifier: Topic :: Terminals
