https://github.com/meirkriheli/python-bidi

BIDI algorithm related functions
https://github.com/meirkriheli/python-bidi

Last synced: about 5 hours ago
JSON representation

BIDI algorithm related functions

• Host: GitHub
• URL: https://github.com/meirkriheli/python-bidi
• Owner: MeirKriheli
• License: lgpl-3.0
• Created: 2010-05-02T08:19:36.000Z (over 14 years ago)
• Default Branch: master
• Last Pushed: 2024-10-15T16:09:27.000Z (about 1 month ago)
• Last Synced: 2024-10-17T21:28:22.666Z (about 1 month ago)
• Language: Python
• Homepage:
• Size: 220 KB
• Stars: 106
• Watchers: 6
• Forks: 16
• Open Issues: 0
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.rst
  • Contributing: CONTRIBUTING.rst
  • License: COPYING
  • Authors: AUTHORS.rst

Awesome Lists containing this project

README

        
===============================

Python BiDi

===============================

`Bi-directional`_ (BiDi) layout for Python providing 2 implementations:

* V5 of the algorithm implemented with Python.

* Wrapper the `unicode-bidi`_ Rust crate.

`Package documentation`_

.. _Bi-directional: http://en.wikipedia.org/wiki/Bi-directional_text

.. _unicode-bidi: https://crates.io/crates/unicode-bidi

.. _Package documentation: http://python-bidi.readthedocs.org/en/latest/

For the python implementation, and compatible with previous versions, use::

    from bidi.algorithm import get_display

For the newer Rust based one, which seems to implement higher version of

the algorithm (albeit with some missing see #25), use the top level import::

    from bidi import get_display

API

----

The algorithm starts with a single entry point `get_display` (see above for selecting the implementaion).

**Required arguments:**

* ``str_or_bytes``: The string or bytes (i.e.: storage). If it's bytes

  use the optional argument ``encoding`` to specify it's encoding.

**Optional arguments:**

* ``encoding``: If unicode_or_str is a string, specifies the encoding. The

  algorithm uses unicodedata_ which requires unicode. This encoding will be

  used to decode and encode back to string before returning

  (default: "utf-8").

* ``base_dir``:  ``'L'`` or ``'R'``, override the calculated base_level.

* ``debug``: ``True`` to display the Unicode levels as seen by the algorithm

  (default: ``False``).

The Python implementaion adds one more optional argument:

* ``upper_is_rtl``: True to treat upper case chars as strong 'R' for

  debugging (default: False).

It returns the display layout, either as ``str`` or ``encoding`` encoded ``bytes``

(depending on the type of ``str_or_bytes'``).

.. _unicodedata: http://docs.python.org/library/unicodedata.html

Example::

    >>> from bidi import get_display

    >>> # keep as list with char per line to prevent browsers from changing display order

    >>> HELLO_HEB = "".join([

    ...     "ש",

    ...     "ל",

    ...     "ו",

    ...     "ם"

    ... ])

    >>>

    >>> HELLO_HEB_DISPLAY = "".join([

    ...     "ם",

    ...     "ו",

    ...     "ל",

    ...     "ש",

    ... ])

    >>>

    >>> get_display(HELLO_HEB) == HELLO_HEB_DISPLAY

    True

CLI

----

``pybidi`` is a command line utility (calling  ``bidi.main``) for running the

display algorithm. The script can get a string as a parameter or read text from

`stdin`.

Usage::

    $ pybidi -h

    usage: pybidi [-h] [-e ENCODING] [-u] [-d] [-b {L,R}] [-r] [-v]

    options:

    -h, --help            show this help message and exit

    -e ENCODING, --encoding ENCODING

                            Text encoding (default: utf-8)

    -u, --upper-is-rtl    Treat upper case chars as strong 'R' for debugging (default: False), Ignored in Rust algo

    -d, --debug           Output to stderr steps taken with the algorithm

    -b {L,R}, --base-dir {L,R}

                            Override base direction [L|R]

    -r, --rust            Use the Rust unicode-bidi implemention instead of the Python one

    -v, --version         show program's version number and exit

Examples::

    $ pybidi -u 'Your string here'

    $ cat ~/Documents/example.txt | pybidi

Installation

-------------

At the command line (assuming you're using some virtualenv)::

    pip install python-bidi

Running tests

--------------

To run the tests::

    pip install nox

    nox