python-bidi · Python Simple Repository Browser

Project Links

Meta

Author: Meir Kriheli

Requires Python: >=3.9

Classifiers

Development Status

4 - Beta

Intended Audience

Developers

Operating System

OS Independent

License

OSI Approved :: GNU Library or Lesser General Public License (LGPL)

Topic

Text Processing

Programming Language

Python :: 3
Python :: 3.9
Python :: 3.10
Python :: 3.11
Python :: 3.12
Python :: 3.13
Python :: 3.14

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

V5 of the algorithm implemented with Python.
Wrapper the unicode-bidi Rust crate.

Package documentation

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').

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

From PyPI:

pip install python-bidi

Or with uv:

uv pip install python-bidi

Development / running tests

You need Rust (for maturin), uv, and a nox session backend of uv (nox reads this from noxfile.py).

From a clone, create the environment and run the test suite:

uv sync --extra dev
uv run pytest

Or use nox (after uv sync --extra dev, or install nox with uv tool install nox / pipx install nox):

nox

Wheel compatibility matrix

Platform	CPython 3.8	CPython 3.9	CPython 3.10	CPython 3.11	CPython 3.12	CPython 3.13	CPython 3.14	CPython (additional flags: t) 3.13	CPython (additional flags: t) 3.14	PyPy 3.11 (pp73)
macosx_10_12_x86_64
macosx_11_0_arm64
manylinux1_i686
manylinux2014_aarch64
manylinux2014_armv7l
manylinux2014_ppc64le
manylinux2014_s390x
manylinux2014_x86_64
manylinux_2_17_aarch64
manylinux_2_17_armv7l
manylinux_2_17_ppc64le
manylinux_2_17_s390x
manylinux_2_17_x86_64
manylinux_2_5_i686
musllinux_1_2_aarch64
musllinux_1_2_armv7l
musllinux_1_2_i686
musllinux_1_2_x86_64
win32
win_amd64