sqlite

SQLite-specific column types.

Blob

Bases: Column[bytes]

Blob column type for storing binary data.

Source code in src/embar/column/sqlite.py

class Blob(Column[bytes]):
    """
    Blob column type for storing binary data.
    """

    _sql_type: str = "BLOB"
    _py_type: Type = bytes

Float

Bases: Column[float]

A floating point column type.

Source code in src/embar/column/common.py

class Float(Column[float]):
    """
    A floating point column type.
    """

    _sql_type: str = "REAL"
    _py_type: Type = float

Integer

Bases: Column[int]

An integer column type.

Source code in src/embar/column/common.py

class Integer(Column[int]):
    """
    An integer column type.
    """

    _sql_type: str = "INTEGER"
    _py_type: Type = int

Null

Bases: Column[T | None]

A nullable column type.

Use this as the annotation for columns that can be NULL in the database. The type parameter T is the underlying Python type (e.g. str, int).

At the class level, Null[str] is a :class:ColumnBase so it works in order_by, where, Annotated, etc. At the instance level, the value is typed as T | None.

Convenience aliases are provided: :data:NullText, :data:NullInteger, :data:NullFloat.

from embar.table import Table
from embar.column.common import Text, NullText, text, integer, NullInteger
class MyTable(Table):
    name: Text = text()
    email: NullText = text(default=None)      # nullable, optional
    age: NullInteger = integer(default=None)   # nullable, optional
row = MyTable(name="foo")
assert row.email is None

Source code in src/embar/column/common.py

class Null[T: PyType](Column[T | None]):
    """
    A nullable column type.

    Use this as the annotation for columns that can be ``NULL`` in the database.
    The type parameter ``T`` is the underlying Python type (e.g. ``str``, ``int``).

    At the class level, ``Null[str]`` is a :class:`ColumnBase` so it works in
    ``order_by``, ``where``, ``Annotated``, etc.  At the instance level, the
    value is typed as ``T | None``.

    Convenience aliases are provided: :data:`NullText`, :data:`NullInteger`,
    :data:`NullFloat`.

    ```python
    from embar.table import Table
    from embar.column.common import Text, NullText, text, integer, NullInteger
    class MyTable(Table):
        name: Text = text()
        email: NullText = text(default=None)      # nullable, optional
        age: NullInteger = integer(default=None)   # nullable, optional
    row = MyTable(name="foo")
    assert row.email is None
    ```
    """

    def __init__(
        self,
        sql_type: str,
        py_type: Type,
        name: str | None = None,
        default: T | None | _NoDefaultType = NO_DEFAULT,
        primary: bool = False,
        not_null: bool = False,
    ):
        self._sql_type = sql_type
        self._py_type = py_type
        super().__init__(name=name, default=default, primary=primary, not_null=not_null)

Text

Bases: Column[str]

A text column type.

Source code in src/embar/column/common.py

class Text(Column[str]):
    """
    A text column type.
    """

    _sql_type: str = "TEXT"
    _py_type: Type = str

blob(name=None, *, default=NO_DEFAULT, primary=False, not_null=False)

blob(
    name: str | None = ...,
    *,
    primary: bool = ...,
    not_null: bool = ...,
) -> Blob

blob(
    name: str | None = ...,
    *,
    default: bytes,
    primary: bool = ...,
    not_null: bool = ...,
) -> Blob

blob(
    name: str | None = ...,
    *,
    default: None,
    primary: bool = ...,
    not_null: bool = ...,
) -> NullBlob

Create a :class:Blob column.

Source code in src/embar/column/sqlite.py

def blob(
    name: str | None = None,
    *,
    default: bytes | None | _NoDefaultType = NO_DEFAULT,
    primary: bool = False,
    not_null: bool = False,
) -> Blob | NullBlob:
    """Create a :class:`Blob` column."""
    if default is None:
        return Null[bytes](
            sql_type="BLOB", py_type=bytes, name=name, default=default, primary=primary, not_null=not_null
        )
    return Blob(name=name, default=default, primary=primary, not_null=not_null)

float_col(name=None, *, default=NO_DEFAULT, primary=False, not_null=False, fk=None, on_delete=None)

float_col(
    name: str | None = ...,
    *,
    primary: bool = ...,
    not_null: bool = ...,
    fk: Callable[[], Column[float]] | None = ...,
    on_delete: OnDelete | None = ...,
) -> Float

float_col(
    name: str | None = ...,
    *,
    default: float,
    primary: bool = ...,
    not_null: bool = ...,
    fk: Callable[[], Column[float]] | None = ...,
    on_delete: OnDelete | None = ...,
) -> Float

float_col(
    name: str | None = ...,
    *,
    default: None,
    primary: bool = ...,
    not_null: bool = ...,
    fk: Callable[[], Column[float]] | None = ...,
    on_delete: OnDelete | None = ...,
) -> NullFloat

Create a :class:Float column (field specifier for @dataclass_transform).

Source code in src/embar/column/common.py

def float_col(
    name: str | None = None,
    *,
    default: float | None | _NoDefaultType = NO_DEFAULT,
    primary: bool = False,
    not_null: bool = False,
    fk: Callable[[], Column[float]] | None = None,
    on_delete: OnDelete | None = None,
) -> Float | NullFloat:
    """Create a :class:`Float` column (field specifier for ``@dataclass_transform``)."""
    col: Float | Null[float]
    if default is None:
        col = Null[float](
            sql_type="REAL", py_type=float, name=name, default=default, primary=primary, not_null=not_null
        )
    else:
        col = Float(name=name, default=default, primary=primary, not_null=not_null)
    if fk is not None:
        col.fk(fk, on_delete)
    return col

integer(name=None, *, default=NO_DEFAULT, primary=False, not_null=False, fk=None, on_delete=None)

integer(
    name: str | None = ...,
    *,
    primary: bool = ...,
    not_null: bool = ...,
    fk: Callable[[], Column[int]] | None = ...,
    on_delete: OnDelete | None = ...,
) -> Integer

integer(
    name: str | None = ...,
    *,
    default: int,
    primary: bool = ...,
    not_null: bool = ...,
    fk: Callable[[], Column[int]] | None = ...,
    on_delete: OnDelete | None = ...,
) -> Integer

integer(
    name: str | None = ...,
    *,
    default: None,
    primary: bool = ...,
    not_null: bool = ...,
    fk: Callable[[], Column[int]] | None = ...,
    on_delete: OnDelete | None = ...,
) -> NullInteger

Create an :class:Integer column (field specifier for @dataclass_transform).

Source code in src/embar/column/common.py

def integer(
    name: str | None = None,
    *,
    default: int | None | _NoDefaultType = NO_DEFAULT,
    primary: bool = False,
    not_null: bool = False,
    fk: Callable[[], Column[int]] | None = None,
    on_delete: OnDelete | None = None,
) -> Integer | NullInteger:
    """Create an :class:`Integer` column (field specifier for ``@dataclass_transform``)."""
    col: Integer | Null[int]
    if default is None:
        col = Null[int](sql_type="INTEGER", py_type=int, name=name, default=default, primary=primary, not_null=not_null)
    else:
        col = Integer(name=name, default=default, primary=primary, not_null=not_null)
    if fk is not None:
        col.fk(fk, on_delete)
    return col

text(name=None, *, default=NO_DEFAULT, primary=False, not_null=False, fk=None, on_delete=None)

text(
    name: str | None = ...,
    *,
    primary: bool = ...,
    not_null: bool = ...,
    fk: Callable[[], Column[str]] | None = ...,
    on_delete: OnDelete | None = ...,
) -> Text

text(
    name: str | None = ...,
    *,
    default: str,
    primary: bool = ...,
    not_null: bool = ...,
    fk: Callable[[], Column[str]] | None = ...,
    on_delete: OnDelete | None = ...,
) -> Text

text(
    name: str | None = ...,
    *,
    default: None,
    primary: bool = ...,
    not_null: bool = ...,
    fk: Callable[[], Column[str]] | None = ...,
    on_delete: OnDelete | None = ...,
) -> NullText

Create a :class:Text column (field specifier for @dataclass_transform).

Source code in src/embar/column/common.py

def text(
    name: str | None = None,
    *,
    default: str | None | _NoDefaultType = NO_DEFAULT,
    primary: bool = False,
    not_null: bool = False,
    fk: Callable[[], Column[str]] | None = None,
    on_delete: OnDelete | None = None,
) -> Text | NullText:
    """Create a :class:`Text` column (field specifier for ``@dataclass_transform``)."""
    col: Text | Null[str]
    if default is None:
        col = Null[str](sql_type="TEXT", py_type=str, name=name, default=default, primary=primary, not_null=not_null)
    else:
        col = Text(name=name, default=default, primary=primary, not_null=not_null)
    if fk is not None:
        col.fk(fk, on_delete)
    return col