* Compiled code uses optimized, type-specific primitives for many

Python standard library features. The :ref:`librt <librt>` package

also provides optimized alternatives for certain standard library

features.

.. _librt:

Librt overview

The `librt <https://pypi.org/project/librt/>`_ package defines fast

primitive operations that are optimized for code compiled

using mypyc. It has carefully selected efficient alternatives for

certain Python standard library features.

``librt`` is a small, focused library. The goal is not to reimplement

the Python standard library, but to address specific gaps or

bottlenecks.

Librt contents

Follow submodule links in the table to a detailed description of each submodule.

.. list-table::

:header-rows: 1

:widths: 30 70

:width: 100%

* - Module

- Description

* - :doc:`librt.base64 <librt_base64>`

- Fast Base64 encoding and decoding

Installing librt

When you install mypy, it will also install a compatible version of librt as a

dependency. If you distribute compiled wheels or install compiled modules in

environments without mypy installed, install librt explicitly or depend on it

with a version constraint (but it's only needed if your code explicitly imports

``librt``), e.g. ``python -m pip install librt>=X.Y``.

If you don't have a recent enough librt installed, importing librt will fail.

Compiled code often needs a version of librt that is not much older than the

mypyc being used.

Backward compatibility

We aim to keep librt backward compatible. It's recommended that you allow users

of your published projects that use librt to update to a more recent version. For

example, use a ``>=`` version constraint in your ``requirements.txt``.

Using librt in non-compiled code

Using librt in code that is *not* compiled with mypyc is fully supported. However,

some librt features may have significantly degraded performance when used from

interpreted code. We will document the most notable such cases, but it's always

recommended to measure the performance impact when considering a switch from Python

standard library functionality to librt in a non-compiled use case.

.. _librt-base64:

librt.base64

The ``librt.base64`` module is part of the ``librt`` package on PyPI, and it includes

base64 encoding and decoding functions that use SIMD (Single Instruction, Multiple Data)

for high efficiency. It is a wrapper around

`Alfred Klomp's base64 library <https://github.com/aklomp/base64>`_.

These functions are mostly compatible with the corresponding functions in the

Python standard library ``base64`` module but are significantly faster,

especially in code compiled with mypyc. For larger inputs, these are much

faster than the standard library alternatives even when used from interpreted code.

.. note::

The decode functions don't behave identically when data is malformed.

Only commonly used functionality is provided. The supported arguments may be

restricted compared to the stdlib functions: the optional ``altchars`` and

``validate`` arguments are not supported.

Functions

.. function:: b64encode(s: bytes) -> bytes

Encode a bytes object using Base64 and return the encoded bytes.

This is equivalent to ``base64.b64encode(s)`` in the standard library.

.. function:: b64decode(s: bytes | str) -> bytes

Decode a Base64 encoded bytes object or ASCII string and return

the decoded bytes.

Non-base64-alphabet characters are ignored. This is compatible

with the default behavior of standard library ``base64.b64decode``.

Raise ``ValueError`` if the padding is incorrect. The standard

library raises ``binascii.Error`` (a subclass of ``ValueError``)

instead.

.. function:: urlsafe_b64encode(s: bytes) -> bytes

Encode a bytes object using the URL and filesystem safe Base64

alphabet (using ``-`` instead of ``+`` and ``_`` instead of ``/``),

and return the encoded bytes.

This is equivalent to ``base64.urlsafe_b64encode(s)`` in the

standard library.

.. function:: urlsafe_b64decode(s: bytes | str) -> bytes

Decode a bytes object or ASCII string using the URL and filesystem

safe Base64 alphabet (using ``-`` instead of ``+`` and ``_`` instead

of ``/``), and return the decoded bytes.

This is an alternative to ``base64.urlsafe_b64decode(s)`` in the

standard library.

Raise ``ValueError`` if the padding is incorrect. The standard

library raises ``binascii.Error`` (a subclass of ``ValueError``)

instead.

Second, the :doc:`librt <librt>` package provides optimized

alternatives for certain standard library features that are designed

for mypyc-compiled code.

Third, you may be able to avoid the library altogether, or use an

* Many :ref:`integer operations <int-ops>`

* Many :ref:`float operations <float-ops>`

* All features in the :doc:`librt <librt>` package, which are optimized

for compiled code

* Native :ref:`str <str-ops>` and :ref:`bytes <bytes-ops>` operations