Class BitString

lib/sqlalchemy/dialects/postgresql/bitstring.py:16–327

Represent a PostgreSQL bit string in python. This object is used by the :class:`_postgresql.BIT` type when returning values. :class:`_postgresql.BitString` values may also be constructed directly and used with :class:`_postgresql.BIT` columns:: from sqlalchemy.dialects.postgr

class BitString(str):
    """Represent a PostgreSQL bit string in python.

    This object is used by the :class:`_postgresql.BIT` type when returning
    values.   :class:`_postgresql.BitString` values may also be constructed
    directly and used with :class:`_postgresql.BIT` columns::

        from sqlalchemy.dialects.postgresql import BitString

        with engine.connect() as conn:
            conn.execute(table.insert(), {"data": BitString("011001101")})

    .. versionadded:: 2.1

    """

    _DIGITS = frozenset("01")

    def __new__(cls, _value: str, _check: bool = True) -> BitString:
        if isinstance(_value, BitString):
            return _value
        elif _check and cls._DIGITS.union(_value) > cls._DIGITS:
            raise ValueError("BitString must only contain '0' and '1' chars")
        else:
            return super().__new__(cls, _value)

    @classmethod
    def from_int(cls, value: int, length: int) -> BitString:
        """Returns a BitString consisting of the bits in the integer ``value``.
        A ``ValueError`` is raised if ``value`` is not a non-negative integer.

        If the provided ``value`` can not be represented in a bit string
        of at most ``length``, a ``ValueError`` will be raised. The bitstring
        will be padded on the left by ``'0'`` to bits to produce a
        bitstring of the desired length.
        """
        if value < 0:
            raise ValueError("value must be non-negative")
        if length < 0:
            raise ValueError("length must be non-negative")

        template_str = f"{{0:0{length}b}}" if length > 0 else ""
        r = template_str.format(value)

        if (length == 0 and value > 0) or len(r) > length:
            raise ValueError(
                f"Cannot encode {value} as a BitString of length {length}"
            )

        return cls(r)

    @classmethod
    def from_bytes(cls, value: bytes, length: int = -1) -> BitString:
        """Returns a ``BitString`` consisting of the bits in the given
        ``value`` bytes.

        If ``length`` is provided, then the length of the provided string
        will be exactly ``length``, with ``'0'`` bits inserted at the left of