urwid 2.6.0.post0__py3-none-any.whl

urwid/widget/container.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import abc
+import enum
+import typing
+import warnings
+
+from .constants import Sizing, WHSettings
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+    from .widget import Widget
+
+
+class _ContainerElementSizingFlag(enum.IntFlag):
+    NONE = 0
+    BOX = enum.auto()
+    FLOW = enum.auto()
+    FIXED = enum.auto()
+    WH_WEIGHT = enum.auto()
+    WH_PACK = enum.auto()
+    WH_GIVEN = enum.auto()
+
+    @property
+    def reverse_flag(self) -> tuple[frozenset(Sizing), WHSettings | None]:
+        """Get flag in public API format."""
+        sizing: set[Sizing] = set()
+
+        if self & self.BOX:
+            sizing.add(Sizing.BOX)
+        if self & self.FLOW:
+            sizing.add(Sizing.FLOW)
+        if self & self.FIXED:
+            sizing.add(Sizing.FIXED)
+
+        if self & self.WH_WEIGHT:
+            return frozenset(sizing), WHSettings.WEIGHT
+        if self & self.WH_PACK:
+            return frozenset(sizing), WHSettings.PACK
+        if self & self.WH_GIVEN:
+            return frozenset(sizing), WHSettings.GIVEN
+        return frozenset(sizing), None
+
+    @property
+    def log_string(self) -> str:
+        """Get desctiprion in public API format."""
+        sizing, render = self.reverse_flag
+        render_string = f" {render.upper()}" if render else ""
+        return "|".join(sorted(mode.upper() for mode in sizing)) + render_string
+
+
+class WidgetContainerMixin:
+    """
+    Mixin class for widget containers implementing common container methods
+    """
+
+    def __getitem__(self, position) -> Widget:
+        """
+        Container short-cut for self.contents[position][0].base_widget
+        which means "give me the child widget at position without any
+        widget decorations".
+
+        This allows for concise traversal of nested container widgets
+        such as:
+
+            my_widget[position0][position1][position2] ...
+        """
+        return self.contents[position][0].base_widget
+
+    def get_focus_path(self) -> list[int | str]:
+        """
+        Return the .focus_position values starting from this container
+        and proceeding along each child widget until reaching a leaf
+        (non-container) widget.
+        """
+        out = []
+        w = self
+        while True:
+            try:
+                p = w.focus_position
+            except IndexError:
+                return out
+            out.append(p)
+            w = w.focus.base_widget
+
+    def set_focus_path(self, positions: Iterable[int | str]) -> None:
+        """
+        Set the .focus_position property starting from this container
+        widget and proceeding along newly focused child widgets.  Any
+        failed assignment due do incompatible position types or invalid
+        positions will raise an IndexError.
+
+        This method may be used to restore a particular widget to the
+        focus by passing in the value returned from an earlier call to
+        get_focus_path().
+
+        positions -- sequence of positions
+        """
+        w = self
+        for p in positions:
+            if p != w.focus_position:
+                w.focus_position = p  # modifies w.focus
+            w = w.focus.base_widget
+
+    def get_focus_widgets(self) -> list[Widget]:
+        """
+        Return the .focus values starting from this container
+        and proceeding along each child widget until reaching a leaf
+        (non-container) widget.
+
+        Note that the list does not contain the topmost container widget
+        (i.e., on which this method is called), but does include the
+        lowest leaf widget.
+        """
+        out = []
+        w = self
+        while True:
+            w = w.base_widget.focus
+            if w is None:
+                return out
+            out.append(w)
+
+    @property
+    @abc.abstractmethod
+    def focus(self) -> Widget:
+        """
+        Read-only property returning the child widget in focus for
+        container widgets.  This default implementation
+        always returns ``None``, indicating that this widget has no children.
+        """
+
+    def _get_focus(self) -> Widget:
+        warnings.warn(
+            f"method `{self.__class__.__name__}._get_focus` is deprecated, "
+            f"please use `{self.__class__.__name__}.focus` property",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return self.focus
+
+
+class WidgetContainerListContentsMixin:
+    """
+    Mixin class for widget containers whose positions are indexes into
+    a list available as self.contents.
+    """
+
+    def __iter__(self) -> Iterator[int]:
+        """
+        Return an iterable of positions for this container from first
+        to last.
+        """
+        return iter(range(len(self.contents)))
+
+    def __reversed__(self) -> Iterator[int]:
+        """
+        Return an iterable of positions for this container from last
+        to first.
+        """
+        return iter(range(len(self.contents) - 1, -1, -1))
+
+    def __len__(self) -> int:
+        return len(self.contents)
+
+    @property
+    @abc.abstractmethod
+    def contents(self) -> list[tuple[Widget, typing.Any]]:
+        """The contents of container as a list of (widget, options)"""
+
+    @contents.setter
+    def contents(self, new_contents: list[tuple[Widget, typing.Any]]) -> None:
+        """The contents of container as a list of (widget, options)"""
+
+    def _get_contents(self) -> list[tuple[Widget, typing.Any]]:
+        warnings.warn(
+            f"method `{self.__class__.__name__}._get_contents` is deprecated, "
+            f"please use `{self.__class__.__name__}.contents` property",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.contents
+
+    def _set_contents(self, c: list[tuple[Widget, typing.Any]]) -> None:
+        warnings.warn(
+            f"method `{self.__class__.__name__}._set_contents` is deprecated, "
+            f"please use `{self.__class__.__name__}.contents` property",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.contents = c
+
+    @property
+    @abc.abstractmethod
+    def focus_position(self) -> int | None:
+        """
+        index of child widget in focus.
+        """
+
+    @focus_position.setter
+    def focus_position(self, position: int) -> None:
+        """
+        index of child widget in focus.
+        """
+
+    def _get_focus_position(self) -> int | None:
+        warnings.warn(
+            f"method `{self.__class__.__name__}._get_focus_position` is deprecated, "
+            f"please use `{self.__class__.__name__}.focus_position` property",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return self.focus_position
+
+    def _set_focus_position(self, position: int) -> None:
+        """
+        Set the widget in focus.
+
+        position -- index of child widget to be made focus
+        """
+        warnings.warn(
+            f"method `{self.__class__.__name__}._set_focus_position` is deprecated, "
+            f"please use `{self.__class__.__name__}.focus_position` property",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        self.focus_position = position

urwid/widget/divider.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import enum
+import typing
+
+from urwid.canvas import CompositeCanvas, SolidCanvas
+
+from .constants import BOX_SYMBOLS, SHADE_SYMBOLS, Sizing
+from .widget import Widget
+
+
+class DividerSymbols(str, enum.Enum):
+    """Common symbols for divider widgets."""
+
+    # Lines
+    LIGHT_HL = BOX_SYMBOLS.LIGHT.HORIZONTAL
+    LIGHT_4_DASHES = BOX_SYMBOLS.LIGHT.HORIZONTAL_4_DASHES
+    LIGHT_3_DASHES = BOX_SYMBOLS.LIGHT.HORIZONTAL_3_DASHES
+    LIGHT_2_DASHES = BOX_SYMBOLS.LIGHT.HORIZONTAL_2_DASHES
+    HEAVY_HL = BOX_SYMBOLS.HEAVY.HORIZONTAL
+    HEAVY_4_DASHES = BOX_SYMBOLS.HEAVY.HORIZONTAL_4_DASHES
+    HEAVY_3_DASHES = BOX_SYMBOLS.HEAVY.HORIZONTAL_3_DASHES
+    HEAVY_2_DASHES = BOX_SYMBOLS.HEAVY.HORIZONTAL_2_DASHES
+    DOUBLE_HL = BOX_SYMBOLS.DOUBLE.HORIZONTAL
+
+    # Full block
+    FULL_BLOCK = SHADE_SYMBOLS.FULL_BLOCK
+    DARK_SHADE = SHADE_SYMBOLS.DARK_SHADE
+    MEDIUM_SHADE = SHADE_SYMBOLS.MEDIUM_SHADE
+    LITE_SHADE = SHADE_SYMBOLS.LITE_SHADE
+
+
+class Divider(Widget):
+    """
+    Horizontal divider widget
+    """
+
+    Symbols = DividerSymbols
+
+    _sizing = frozenset([Sizing.FLOW])
+
+    ignore_focus = True
+
+    def __init__(
+        self,
+        div_char: str | bytes = " ",
+        top: int = 0,
+        bottom: int = 0,
+    ) -> None:
+        """
+        :param div_char: character to repeat across line
+        :type div_char: bytes or unicode
+
+        :param top: number of blank lines above
+        :type top: int
+
+        :param bottom: number of blank lines below
+        :type bottom: int
+
+        >>> Divider()
+        <Divider flow widget>
+        >>> Divider(u'-')
+        <Divider flow widget '-'>
+        >>> Divider(u'x', 1, 2)
+        <Divider flow widget 'x' bottom=2 top=1>
+        """
+        super().__init__()
+        self.div_char = div_char
+        self.top = top
+        self.bottom = bottom
+
+    def _repr_words(self) -> list[str]:
+        return super()._repr_words() + [repr(self.div_char)] * (self.div_char != " ")
+
+    def _repr_attrs(self) -> dict[str, typing.Any]:
+        attrs = dict(super()._repr_attrs())
+        if self.top:
+            attrs["top"] = self.top
+        if self.bottom:
+            attrs["bottom"] = self.bottom
+        return attrs
+
+    def rows(self, size: tuple[int], focus: bool = False) -> int:
+        """
+        Return the number of lines that will be rendered.
+
+        >>> Divider().rows((10,))
+        1
+        >>> Divider(u'x', 1, 2).rows((10,))
+        4
+        """
+        (_maxcol,) = size
+        return self.top + 1 + self.bottom
+
+    def render(self, size: tuple[int], focus: bool = False) -> CompositeCanvas:
+        """
+        Render the divider as a canvas and return it.
+
+        >>> Divider().render((10,)).text # ... = b in Python 3
+        [...'          ']
+        >>> Divider(u'-', top=1).render((10,)).text
+        [...'          ', ...'----------']
+        >>> Divider(u'x', bottom=2).render((5,)).text
+        [...'xxxxx', ...'     ', ...'     ']
+        """
+        (maxcol,) = size
+        canv = CompositeCanvas(SolidCanvas(self.div_char, maxcol, 1))
+        if self.top or self.bottom:
+            canv.pad_trim_top_bottom(self.top, self.bottom)
+        return canv