streamlit-record-views 0.1.0__py3-none-any.whl

record_views/__init__.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from record_views import card_config
+from record_views.cards.card import CardView, card
+from record_views.cards.config import CardSize
+from record_views.frames import RecordStyle, records_from_frame
+from record_views.lineage import (
+    LineageEdge,
+    LineageGraph,
+    lineage_flow,
+    lineage_graph,
+    lineage_sankey,
+    lineage_split,
+    lineage_steps,
+    lineage_strip,
+    lineage_timeline,
+    lineage_trail,
+    lineage_tree,
+)
+from record_views.link import Link
+from record_views.record import Color, EntityRef, Record, RecordField
+
+__all__ = [
+    "card",
+    "card_config",
+    "CardView",
+    "LineageEdge",
+    "LineageGraph",
+    "Link",
+    "CardSize",
+    "Color",
+    "EntityRef",
+    "Record",
+    "RecordField",
+    "RecordStyle",
+    "lineage_flow",
+    "lineage_graph",
+    "lineage_sankey",
+    "lineage_split",
+    "lineage_steps",
+    "lineage_strip",
+    "lineage_timeline",
+    "lineage_trail",
+    "lineage_tree",
+    "records_from_frame",
+]

record_views/card_config.py

@@ -0,0 +1,292 @@
+"""Configurations that say how a record looks as a card."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any, ClassVar, Literal
+
+from record_views.cards.checks import (
+    check_choice,
+    check_currency,
+    check_hide,
+    check_max_fields,
+)
+from record_views.cards.config import (
+    HEADER_SLOTS,
+    STATUS_DISPLAYS,
+    HeaderSlot,
+    StatusDisplay,
+)
+from record_views.cards.payload import (
+    LEDGER_FIELDS,
+    PROPERTY_FIELDS,
+    STANDARD_FIELDS,
+    FieldLimits,
+    color_name,
+)
+from record_views.record import Color, RecordField
+
+__all__ = ["LedgerCard", "PropertyCard", "RecordCard", "TileCard"]
+
+_PROPERTY_LAYOUTS = ("sheet", "chip", "split")
+_LEDGER_LAYOUTS = ("statement", "metric", "split")
+
+
+@dataclass(frozen=True, kw_only=True)
+class _CardConfig:
+    """Holds the options every card configuration shares."""
+
+    variant: ClassVar[str]
+    field_limits: ClassVar[FieldLimits] = STANDARD_FIELDS
+
+    border: bool = True
+    background: bool = False
+    status_display: StatusDisplay = "full"
+    status_badge: bool = False
+    header: HeaderSlot = "status"
+    hide: Iterable[str] = ()
+    max_fields: int | None = None
+    color: Color | str | None = None
+    icon: str | None = None
+    status_color: Color | str | None = None
+    headline: str | RecordField | tuple[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        check_choice("header", self.header, HEADER_SLOTS)
+        check_choice("status_display", self.status_display, STATUS_DISPLAYS)
+        check_max_fields(self.max_fields)
+        object.__setattr__(self, "hide", check_hide(self.hide))
+        for color in (self.color, self.status_color):
+            if color is not None:
+                color_name(color)
+        headline = self.headline
+        if isinstance(headline, tuple):
+            object.__setattr__(self, "headline", RecordField(*headline))
+        elif headline is not None and not isinstance(
+            headline, (str, RecordField)
+        ):
+            raise TypeError(
+                "headline must be a field name, a RecordField, or a "
+                f"(label, value) pair, not {headline!r}."
+            )
+
+
+@dataclass(frozen=True, kw_only=True)
+class RecordCard(_CardConfig):
+    """Describes a full card with a header, a body, and a footer.
+
+    Attributes:
+        border: Whether to outline the card with a border.
+        background: Whether to fill the card with the secondary background
+            color.
+        status_display: "full" for the dot and the text, or the badge, which
+            reduce to the dot when space runs out; "dot" for only the dot; or
+            None to omit the status, as hide=["status"] does.
+        status_badge: Whether to render status as a filled badge instead of a
+            dot.
+        header: Which item ("status", "caption", or None) sits at the right
+            of the header. The other moves to the footer, and None puts both
+            there. Small cards always draw the caption in their row. At
+            compact size, "status" keeps the status on the first line, and
+            "caption" or None moves it to the last line.
+        hide: Names of elements to omit, any of "status", "subtitle",
+            "caption", and "note". Any iterable of names, kept as a tuple.
+        max_fields: The number of fields at medium and large size. None shows
+            2 at medium size and all at large size. Compact and small sizes
+            ignore it and show none.
+        color: Overrides the record's color.
+        icon: Overrides the record's icon.
+        status_color: Overrides the record's status color.
+        headline: The field to lead with, or None. A str names a field of the
+            record, a RecordField or (label, value) pair gives the field
+            itself, and a name that matches no field leads with nothing. At
+            small and compact size the headline sits beside the status, and
+            beside the last line, showing only its value for a str and its
+            label and value for a RecordField. At medium and large size it
+            is the first field, which moves to the front of the fields if
+            the record has it and is added in front if not.
+
+    Raises:
+        TypeError: If hide is a string, or headline is not a string, a
+            RecordField, a (label, value) pair, or None.
+        ValueError: If header or status_display is not a supported value,
+            max_fields is negative or not an integer, hide contains an
+            unknown name, or color or status_color is not a supported color.
+    """
+
+    variant: ClassVar[str] = "record"
+
+
+@dataclass(frozen=True, kw_only=True)
+class TileCard(_CardConfig):
+    """Describes a list-row card led by an accent icon avatar.
+
+    Attributes:
+        border: Whether to outline the card with a border.
+        background: Whether to fill the card with the secondary background
+            color.
+        status_display: "full" for the dot and the text, or the badge, which
+            reduce to the dot when space runs out; "dot" for only the dot; or
+            None to omit the status, as hide=["status"] does.
+        status_badge: Whether to render status as a filled badge instead of a
+            dot.
+        header: Which item ("status", "caption", or None) sits at the right
+            of the title line. The other moves to the footer, and None puts
+            both there. Small cards always draw the caption in their row.
+        hide: Names of elements to omit, any of "status", "subtitle",
+            "caption", and "note". Any iterable of names, kept as a tuple.
+        max_fields: The number of fields at medium and large size. None shows
+            2 at medium size and all at large size. Compact and small sizes
+            ignore it and show none.
+        color: Overrides the record's color.
+        icon: Overrides the record's icon.
+        status_color: Overrides the record's status color.
+        headline: The field to lead with, or None. A str names a field of the
+            record, a RecordField or (label, value) pair gives the field
+            itself, and a name that matches no field leads with nothing. At
+            small and compact size the headline sits beside the status, and
+            beside the last line, showing only its value for a str and its
+            label and value for a RecordField. At medium and large size it
+            is the first field, which moves to the front of the fields if
+            the record has it and is added in front if not.
+
+    Raises:
+        TypeError: If hide is a string, or headline is not a string, a
+            RecordField, a (label, value) pair, or None.
+        ValueError: If header or status_display is not a supported value,
+            max_fields is negative or not an integer, hide contains an
+            unknown name, or color or status_color is not a supported color.
+    """
+
+    variant: ClassVar[str] = "tile"
+
+
+@dataclass(frozen=True, kw_only=True)
+class PropertyCard(_CardConfig):
+    """Describes an attribute-forward card that lays fields out as a grid.
+
+    Attributes:
+        border: Whether to outline the card with a border.
+        background: Whether to fill the card with the secondary background
+            color.
+        status_display: "full" for the dot and the text, or the badge, which
+            reduce to the dot when space runs out; "dot" for only the dot; or
+            None to omit the status, as hide=["status"] does.
+        status_badge: Whether to render status as a filled badge instead of a
+            dot.
+        header: Which item ("status", "caption", or None) sits at the right
+            of the type line. The other moves to the footer, and None puts
+            both there. Small cards always draw the caption in their row. At
+            compact size, "status" keeps the status on the first line, and
+            "caption" or None moves it to the last line.
+        hide: Names of elements to omit, any of "status", "subtitle",
+            "caption", and "note". Any iterable of names, kept as a tuple.
+        max_fields: The number of fields at medium and large size. None shows
+            4 at medium size and all at large size. Compact size ignores it
+            and shows the first field; small size shows none.
+        color: Overrides the record's color.
+        icon: Overrides the record's icon.
+        status_color: Overrides the record's status color.
+        headline: The field to lead with, or None. A str names a field of the
+            record, a RecordField or (label, value) pair gives the field
+            itself, and a name that matches no field leads with nothing. At
+            small and compact size the headline sits beside the status, and
+            beside the last line, showing only its value for a str and its
+            label and value for a RecordField. At medium and large size it
+            is the first field, which moves to the front of the fields if
+            the record has it and is added in front if not.
+        layout: Arrangement of the card at medium and large size. "sheet"
+            leads with the title over a muted type and status line, "chip"
+            leads with a colored type chip, and "split" places the identity
+            beside the spec grid when there is room, with the description
+            filling the space beside the specs.
+        description: Long-form text such as a memo, shown at medium and large
+            size in a block cut to a few lines that fades when there is more.
+
+    Raises:
+        TypeError: If hide is a string, or headline is not a string, a
+            RecordField, a (label, value) pair, or None.
+        ValueError: If header, status_display, or layout is not a supported
+            value, max_fields is negative or not an integer, hide contains
+            an unknown name, or color or status_color is not a supported
+            color.
+    """
+
+    variant: ClassVar[str] = "property"
+    field_limits: ClassVar[FieldLimits] = PROPERTY_FIELDS
+
+    layout: Literal["sheet", "chip", "split"] = "sheet"
+    description: str | None = None
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        check_choice("layout", self.layout, _PROPERTY_LAYOUTS)
+
+
+@dataclass(frozen=True, kw_only=True)
+class LedgerCard(_CardConfig):
+    """Describes a quantified card led by a headline figure.
+
+    Attributes:
+        border: Whether to outline the card with a border.
+        background: Whether to fill the card with the secondary background
+            color.
+        status_display: "full" for the dot and the text, or the badge, which
+            reduce to the dot when space runs out; "dot" for only the dot; or
+            None to omit the status, as hide=["status"] does.
+        status_badge: Whether to render status as a filled badge instead of a
+            dot.
+        header: Which item ("status", "caption", or None) sits at the right
+            of the type line. The other moves to the footer, and None puts
+            both there. Small cards always draw the caption in their row. At
+            compact size, "status" keeps the status on the first line, and
+            "caption" or None moves it to the last line.
+        hide: Names of elements to omit, any of "status", "subtitle",
+            "caption", and "note". Any iterable of names, kept as a tuple.
+        max_fields: The number of itemized fields at medium and large size.
+            None shows 3 at medium size and all at large size. Compact and
+            small sizes ignore it and show none.
+        color: Overrides the record's color.
+        icon: Overrides the record's icon.
+        status_color: Overrides the record's status color.
+        headline: The figure the card leads with, or None for no figure. A
+            str names a field of the record, a RecordField or (label, value)
+            pair gives the figure itself, and a name that matches no field
+            leads with nothing. Medium and large cards draw it as a large
+            figure taken out of the itemized fields, which are the numeric
+            fields; text fields are listed below them. Small and compact
+            cards place it beside the status and on the last line, showing
+            only its value for a str and its label and value for a
+            RecordField.
+        layout: Arrangement of the card at medium and large size.
+            "statement" itemizes fields as receipt lines, "metric" shows them
+            as stat blocks under the headline, and "split" places the
+            itemization beside the headline when there is room.
+        currency: An ISO 4217 code, such as "USD", that formats numeric
+            values as currency in the viewer's locale. None formats them as
+            plain numbers.
+        accounting: Whether to present numeric values in accounting style:
+            currency symbols and amounts in aligned columns, and negatives in
+            parentheses.
+
+    Raises:
+        TypeError: If hide is a string, or headline is not a string, a
+            RecordField, a (label, value) pair, or None.
+        ValueError: If header, status_display, or layout is not a supported
+            value, max_fields is negative or not an integer, hide contains
+            an unknown name, color or status_color is not a supported color,
+            or currency is not a three-letter code.
+    """
+
+    variant: ClassVar[str] = "ledger"
+    field_limits: ClassVar[FieldLimits] = LEDGER_FIELDS
+
+    layout: Literal["statement", "metric", "split"] = "statement"
+    currency: str | None = None
+    accounting: bool = False
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        check_choice("layout", self.layout, _LEDGER_LAYOUTS)
+        object.__setattr__(self, "currency", check_currency(self.currency))

record_views/cards/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from record_views.cards.config import CardSize
+
+__all__ = ["CardSize"]

record_views/cards/card.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import KW_ONLY, dataclass
+from typing import Any
+
+from record_views.cards.checks import check_choice, check_width
+from record_views.cards.config import (
+    CARD_SIZES,
+    HOVER_SIZES,
+    ON_HOVER,
+    CardSize,
+    OnHover,
+    Width,
+)
+from record_views.cards.view import (
+    CardConfig,
+    CardSpec,
+    render_view,
+    resolve_config,
+    view_payload,
+)
+from record_views.record import Record
+
+
+@dataclass(frozen=True)
+class CardView:
+    """Defines a card: the record, how it looks, its size, and its hover.
+
+    A CardView only describes the card. card() renders it.
+
+    Attributes:
+        record: The record metadata and fields to display.
+        card_config: How the record looks: a card_config.RecordCard,
+            TileCard, PropertyCard, or LedgerCard object; one of the names
+            "record", "tile", "property", and "ledger", which mean that class
+            with its defaults; or None for RecordCard(). Kept as the
+            configuration object.
+        size: Presentation size: "compact", "small", "medium", or "large".
+            "compact" is a fixed card that does not adapt to its width;
+            lineage components draw records with it.
+        on_hover: What hovering or focusing the card shows above the page.
+            None shows the same card in full when its content is cut off,
+            and nothing otherwise. "small", "medium", or "large" always shows
+            the same card at that size. A CardView always shows that card,
+            which can have its own record, configuration, and size. "disabled"
+            shows nothing.
+
+    Raises:
+        TypeError: If card_config is not a supported value.
+        ValueError: If size or on_hover is not a supported value, or on_hover
+            is a CardView whose size is "compact" or whose own on_hover is not
+            None.
+    """
+
+    record: Record
+    card_config: CardSpec = None
+    _: KW_ONLY
+    size: CardSize = "medium"
+    on_hover: OnHover | CardView = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, "card_config", resolve_config(self.card_config)
+        )
+        check_choice("size", self.size, CARD_SIZES)
+        hover = self.on_hover
+        if not isinstance(hover, CardView):
+            check_choice("on_hover", hover, ON_HOVER)
+        elif hover.size not in HOVER_SIZES:
+            raise ValueError(
+                f"A hover CardView's size must be one of {HOVER_SIZES}."
+            )
+        elif hover.on_hover is not None:
+            raise ValueError("A hover CardView cannot have its own on_hover.")
+
+
+def _drawn(
+    config: CardConfig, record: Record, size: CardSize, disabled: bool
+) -> dict[str, Any]:
+    """Builds the payload of one card, with the variant that draws it."""
+    payload = view_payload(config, record, size, disabled=disabled)
+    payload["variant"] = config.variant
+    return payload
+
+
+def card(
+    view: CardView,
+    *,
+    key: str | None = None,
+    width: Width = "stretch",
+    on_click: Callable[..., Any] | None = None,
+    args: tuple[Any, ...] | None = None,
+    kwargs: dict[str, Any] | None = None,
+    disabled: bool = False,
+    help: str | None = None,
+) -> bool:
+    """Renders a card.
+
+    Args:
+        view: The card to render: its record, configuration, size, and what
+            hovering it shows.
+        key: A unique component key. Defaults to one derived from the card
+            type and the record's id, and is required when the record has no
+            id.
+        width: "stretch" to fill the container, "content" to fit the card's
+            content, or a width in pixels.
+        on_click: Callback executed when the card is clicked.
+        args: Positional arguments passed to on_click.
+        kwargs: Keyword arguments passed to on_click.
+        disabled: When True, renders the card, and its hover card, in an
+            inactive non-interactive state.
+        help: Plain text shown in a tooltip when hovering or focusing the
+            card. Newlines are preserved.
+
+    Returns:
+        True if the card was clicked in the current script run, False otherwise.
+
+    Raises:
+        TypeError: If view is not a CardView.
+        ValueError: If width is not a supported value, or key is omitted for
+            a record without an id.
+    """
+    if not isinstance(view, CardView):
+        raise TypeError(
+            f"view must be a CardView, such as CardView(record), not {view!r}."
+        )
+    config, record = view.card_config, view.record
+    check_width(width)
+    if key is None:
+        if record.id is None:
+            raise ValueError("key is required when the record has no id.")
+        key = f"card-{config.variant}:{record.id}"
+
+    hover = view.on_hover
+    if isinstance(hover, CardView):
+        # A hover card always shows, as a hover size does.
+        mode = hover.size
+        shown = _drawn(hover.card_config, hover.record, hover.size, disabled)
+    else:
+        mode = hover
+        shown = (
+            _drawn(config, record, hover, disabled)
+            if hover in HOVER_SIZES
+            else None
+        )
+    payload = _drawn(config, record, view.size, disabled)
+    payload.update(
+        help=help,
+        contentWidth=width == "content",
+        onHover=mode,
+        hover=shown,
+    )
+    return render_view(
+        payload,
+        key=key,
+        width=width,
+        on_click=on_click,
+        args=args,
+        kwargs=kwargs,
+    )

record_views/cards/checks.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from typing import Any
+
+from record_views.cards.config import HIDEABLE, Width
+
+
+def check_choice(name: str, value: Any, choices: tuple[Any, ...]) -> None:
+    """Validates that an argument is one of a fixed set of values.
+
+    Args:
+        name: The argument name, for the error message.
+        value: The value given.
+        choices: The accepted values.
+
+    Raises:
+        ValueError: If value is not one of choices.
+    """
+    if value not in choices:
+        raise ValueError(f"{name} must be one of {choices}.")
+
+
+def check_width(width: Width) -> None:
+    """Validates a Streamlit-style width.
+
+    Args:
+        width: "stretch", "content", or a positive number of pixels.
+
+    Raises:
+        ValueError: If width is none of those.
+    """
+    if width in ("stretch", "content"):
+        return
+    if isinstance(width, bool) or not isinstance(width, int) or width <= 0:
+        raise ValueError(
+            f'width must be "stretch", "content", or a positive integer, '
+            f"not {width!r}."
+        )
+
+
+def check_hide(hide: Iterable[str]) -> tuple[str, ...]:
+    """Validates the names of elements to omit from a card.
+
+    Args:
+        hide: Names of elements to omit.
+
+    Returns:
+        The names as a tuple.
+
+    Raises:
+        TypeError: If hide is a string.
+        ValueError: If hide contains an unknown name.
+    """
+    if isinstance(hide, str):
+        raise TypeError(
+            f"hide must be a list of names, such as [{hide!r}], not a string."
+        )
+    names = tuple(hide)
+    if unknown := frozenset(names) - HIDEABLE:
+        raise ValueError(
+            f"Cannot hide {sorted(unknown)}; choose from {sorted(HIDEABLE)}."
+        )
+    return names
+
+
+def check_max_fields(max_fields: int | None) -> None:
+    """Validates the number of fields a card shows.
+
+    Args:
+        max_fields: None, or a count of 0 or more.
+
+    Raises:
+        ValueError: If max_fields is negative or not an integer.
+    """
+    if max_fields is not None and (
+        isinstance(max_fields, bool)
+        or not isinstance(max_fields, int)
+        or max_fields < 0
+    ):
+        raise ValueError(
+            f"max_fields must be None or an integer of 0 or more, not "
+            f"{max_fields!r}."
+        )
+
+
+def check_currency(currency: str | None) -> str | None:
+    """Validates and normalizes an ISO 4217 currency code.
+
+    Args:
+        currency: A three-letter code, or None.
+
+    Returns:
+        The code in uppercase, or None.
+
+    Raises:
+        ValueError: If currency is not a three-letter code.
+    """
+    if currency is None:
+        return None
+    if not isinstance(currency, str) or not re.fullmatch(
+        r"[A-Za-z]{3}", currency
+    ):
+        raise ValueError(
+            f"currency must be an ISO 4217 code such as 'USD', not "
+            f"{currency!r}."
+        )
+    return currency.upper()

record_views/cards/config.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Literal, get_args
+
+CardSize = Literal["compact", "small", "medium", "large"]
+HeaderSlot = Literal["status", "caption"] | None
+StatusDisplay = Literal["full", "dot"] | None
+Width = Literal["stretch", "content"] | int
+OnHover = Literal["small", "medium", "large", "disabled"] | None
+CARD_SIZES = get_args(CardSize)
+HEADER_SLOTS = ("status", "caption", None)
+STATUS_DISPLAYS = ("full", "dot", None)
+HOVER_SIZES = ("small", "medium", "large")
+ON_HOVER = (*HOVER_SIZES, "disabled", None)
+HIDEABLE = frozenset({"status", "subtitle", "caption", "note"})