bootstack 0.1.4__tar.gz → 0.1.6__tar.gz

{bootstack-0.1.4/src/bootstack.egg-info → bootstack-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootstack
-Version: 0.1.4
+Version: 0.1.6
 Summary: Build desktop GUI apps in pure Python and ship them as a standalone executable — built on Tk, no Tkinter boilerplate.
 Author-email: Israel Dryer <israel.dryer@gmail.com>
 License-Expression: MIT
@@ -66,10 +66,9 @@ Dynamic: license-file
 
 ### Desktop apps in pure Python — Tk underneath, none of the boilerplate.
 
-bootstack is built on Tk, so the install is light, there's no Qt license, and
-your app ships as a small standalone executable. But you'll never write a
-`StringVar` or call `.pack()` — the API is its own. 60+ widgets, reactive state,
-and a CLI that scaffolds and packages the whole thing.
+bootstack is built on Tk, so the install is light and your app ships as a small standalone executable. But you'll never
+write a `StringVar` or call `.pack()` — the API is its own. 60+ widgets, reactive state, and a CLI that scaffolds and
+packages the whole thing.
 
 <p align="center">
 <picture>

{bootstack-0.1.4 → bootstack-0.1.6}/README.md

@@ -13,10 +13,9 @@
 
 ### Desktop apps in pure Python — Tk underneath, none of the boilerplate.
 
-bootstack is built on Tk, so the install is light, there's no Qt license, and
-your app ships as a small standalone executable. But you'll never write a
-`StringVar` or call `.pack()` — the API is its own. 60+ widgets, reactive state,
-and a CLI that scaffolds and packages the whole thing.
+bootstack is built on Tk, so the install is light and your app ships as a small standalone executable. But you'll never
+write a `StringVar` or call `.pack()` — the API is its own. 60+ widgets, reactive state, and a CLI that scaffolds and
+packages the whole thing.
 
 <p align="center">
 <picture>

{bootstack-0.1.4 → bootstack-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bootstack"
-version = "0.1.4"
+version = "0.1.6"
 description = "Build desktop GUI apps in pure Python and ship them as a standalone executable — built on Tk, no Tkinter boilerplate."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -114,7 +114,7 @@ where = ["src"]
 ]
 
 [tool.bumpversion]
-current_version = "0.1.4"
+current_version = "0.1.6"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)((?P<pre>a|b|rc)(?P<pre_n>\\d+))?"
 serialize = [
     "{major}.{minor}.{patch}{pre}{pre_n}",

{bootstack-0.1.4 → bootstack-0.1.6}/src/bootstack/i18n/intl_format.py

@@ -12,6 +12,7 @@ import locale
 import re
 import warnings
 from dataclasses import dataclass
+from decimal import Decimal
 from datetime import date, datetime, time
 from typing import Any, Literal, Mapping, Optional, TypedDict, Union, cast
 
@@ -148,7 +149,10 @@ SUFFIXES_EN = (
     Suffix(1_000, "K"),
 )
 _SUFFIX_TO_FACTOR = {"K": 1_000, "M": 1_000_000, "B": 1_000_000_000, "T": 1_000_000_000_000}
-_NUMBERISH = (int, float)
+# Values formatted as numbers. `Decimal` is passed to Babel as-is rather than
+# coerced: Babel formats it natively, and going through `float` would round
+# away the precision a caller chose `Decimal` to keep.
+_NUMBERISH = (int, float, Decimal)
 
 
 def _locale_to_languages(loc: str) -> list[str]:
@@ -208,7 +212,7 @@ class IntlFormatter:
         if value is None:
             return ""
         if isinstance(value, _NUMBERISH):
-            return self._format_number(float(value), spec)
+            return self._format_number(value if isinstance(value, Decimal) else float(value), spec)
         if isinstance(value, datetime):
             return self._format_datetime(value, spec)
         if isinstance(value, date):
@@ -238,7 +242,7 @@ class IntlFormatter:
         return self._parse_temporal(s, spec)
 
     # ---------- Numbers ----------
-    def _format_number(self, x: float, spec: LooseSpec) -> str:
+    def _format_number(self, x: float | Decimal, spec: LooseSpec) -> str:
         opt = self._normalize_number_spec(spec)
 
         if opt["type"] == "custom":

{bootstack-0.1.4 → bootstack-0.1.6}/src/bootstack/validation/validation_rules.py

@@ -33,6 +33,16 @@ def rule_applies_to_kind(rule_type: str, kind: str) -> bool:
     return True
 
 
+def _is_empty(value: object) -> bool:
+    """Whether a field holds nothing, for rules that only shape a value.
+
+    Matches the emptiness test `range` uses: `None` or the empty string. A
+    whitespace-only entry is real input — `stringLength` should still measure
+    it — so only `required` treats blank text as absent.
+    """
+    return value is None or value == ""
+
+
 def _as_text(value: object) -> str:
     """Coerce a value to text for the string rules.
 
@@ -104,7 +114,15 @@ class ValidationRule:
             # Everything else is valid (non-empty string, number, date, etc.)
             return ValidationResult(True, "")
 
-        elif self.type == "email":
+        # A rule other than `required` describes what a value must look like,
+        # not that one must be present. An untouched optional field has nothing
+        # to check, so it passes — otherwise leaving it blank would block a
+        # submit with no way forward. Use `required` for presence, the same
+        # contract `range` states below.
+        if self.type in TEXT_RULES and _is_empty(value):
+            return ValidationResult(True, "")
+
+        if self.type == "email":
             if not re.match(r"[^@]+@[^@]+\.[^@]+", _as_text(value)):
                 return ValidationResult(False, msg)
         elif self.type == "stringLength":
@@ -119,7 +137,7 @@ class ValidationRule:
         elif self.type == "range":
             # Bounds on an ordered value (number/date/time). An empty field is
             # not out of range — use 'required' for presence.
-            if value is None or value == "":
+            if _is_empty(value):
                 return ValidationResult(True)
             lo = self.params.get("min")
             hi = self.params.get("max")

bootstack-0.1.6/src/bootstack/widgets/_core/kwargs.py

@@ -0,0 +1,85 @@
+"""Merging a caller's options dict over framework-built keyword arguments.
+
+Several widgets accept a bag of options aimed at a widget they build for you —
+`Form`'s `editor_options`, `MenuButton`'s `menu_options`, the keyword
+passthrough on `ButtonGroup.add` / `RadioGroup.add` / `Toolbar.add_widget`.
+Those bags name the built widget's own public keyword arguments, so a caller
+may name a parameter the framework also fills.
+
+Splatting both into one call raises `TypeError: got multiple values for
+keyword argument`, which names an internal class the caller never wrote.
+`merge_kwargs` gives that meeting point one rule instead:
+
+- The caller's options WIN over the framework's defaults. Naming a parameter
+  the framework also fills is how you override it.
+- A short list of keys is structural — the widget cannot do its job if they
+  are replaced (it would be parented elsewhere, or lose the command that emits
+  its events). Supplying one raises `BootstackError` naming the API you called
+  and what to use instead.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from bootstack.errors import BootstackError
+
+
+def reject_reserved(
+    user: Mapping[str, Any] | None,
+    reserved: Mapping[str, str] | None,
+    context: str,
+) -> None:
+    """Raise if the caller set a key the framework owns.
+
+    Args:
+        user: The caller's options. `None` is treated as empty.
+        reserved: Structural keys the caller may not set, mapped to the
+            guidance shown when they try.
+        context: The API the caller invoked, e.g. `'ButtonGroup.add()'`.
+
+    Raises:
+        BootstackError: If `user` contains a key listed in `reserved`.
+    """
+    if not user or not reserved:
+        return
+    for key in user:
+        if key in reserved:
+            raise BootstackError(f"{context} does not accept {key}= — {reserved[key]}")
+
+
+def merge_kwargs(
+    defaults: Mapping[str, Any],
+    user: Mapping[str, Any] | None,
+    *,
+    reserved: Mapping[str, str] | None = None,
+    context: str = "this call",
+) -> dict[str, Any]:
+    """Merge a caller's options over framework-built keyword arguments.
+
+    Args:
+        defaults: Keyword arguments the framework derived for the call. Any
+            key also present in `user` is overridden.
+        reserved: Structural keys the caller may not set, mapped to the
+            guidance shown when they try.
+        context: The API the caller invoked, used in the error message.
+        user: The caller's options. `None` is treated as empty.
+
+    Returns:
+        The merged keyword arguments.
+
+    Raises:
+        BootstackError: If `user` contains a key listed in `reserved`.
+    """
+    merged = dict(defaults)
+    if not user:
+        return merged
+    reject_reserved(user, reserved, context)
+    merged.update(user)
+    return merged
+
+
+# Structural keys a bar's widget-options passthrough may not set — a toolbar or
+# status bar places every widget it builds.
+RESERVED_BAR_KWARGS = {
+    'parent': 'the bar places the widgets it builds.',
+}

{bootstack-0.1.4 → bootstack-0.1.6}/src/bootstack/widgets/_core/selection_group.py

@@ -4,6 +4,13 @@ from typing import Any
 
 from bootstack.widgets._core.options import OptionRecord, record_to_dict, option_localize
 
+# Structural keys a per-option kwargs passthrough may not set — the group owns
+# each option's identity and tracks its own selection.
+RESERVED_OPTION_KWARGS = {
+    'text': 'set the caption with the label argument.',
+    'variable': 'the group tracks its own selection.',
+}
+
 
 class SelectionGroupMixin:
     """Shared item-management surface for the option-group widgets.

{bootstack-0.1.4 → bootstack-0.1.6}/src/bootstack/widgets/_impl/_parts/numberentry_part.py

@@ -272,9 +272,10 @@ class NumberEntryPart(TextEntryPart):
         A plain numeric field parses to a string when no display format is set,
         so coerce it the same way the public value does — validation rules and a
         `custom` func receive a real `int`/`float` (or `None` for empty/invalid
-        input), never the display string.
+        input), never the display string. A visible placeholder is not input,
+        so it reads as empty here — same rule as the text field this overrides.
         """
-        text = self.get()
+        text = '' if self._showing_placeholder else self.get()
         try:
             raw = self._parse_or_none(text)
         except Exception:

{bootstack-0.1.4 → bootstack-0.1.6}/src/bootstack/widgets/_impl/_parts/textentry_part.py

@@ -288,11 +288,17 @@ class TextEntryPart(ValidationMixin, Entry):
         last-committed value. This keeps a manual `validate()`, the automatic
         blur/key validation, and a form-level validate in agreement on the same
         live, typed input.
+
+        A visible placeholder is not input. It is inserted into the entry to
+        render it, so reading the raw text would hand the placeholder string to
+        the rules and `required` would pass on an untouched field — the field
+        reads as empty here, exactly as it does through `value`.
         """
+        text = "" if self._showing_placeholder else self.get()
         try:
-            return self._parse_or_none(self.get())
+            return self._parse_or_none(text)
         except Exception:
-            return self.get()
+            return text
 
     def text(self, value=None):
         """Get or set the raw display text without committing.

{bootstack-0.1.4 → bootstack-0.1.6}/src/bootstack/widgets/_impl/composites/dropdownbutton.py

@@ -7,8 +7,18 @@ from typing_extensions import Unpack
 from bootstack.widgets._impl.composites.contextmenu import ContextMenu, ContextMenuItem, ContextMenuItemResult
 from bootstack.widgets._impl.primitives._menubutton import MenuButton
 from bootstack.widgets._impl.mixins import configure_delegate
+from bootstack.widgets._core.kwargs import merge_kwargs
 from bootstack.widgets.types import Master, StyledKwargs, CompoundMode, WidgetState, WidgetDensity
 
+# Structural keys a menu_options bag may not set — the button owns the menu's
+# contents and the callback that emits its selection events.
+_RESERVED_MENU_OPTIONS = {
+    'items': 'pass the menu items to the button itself.',
+    'command': "use the button's on_select event.",
+    'trigger': 'the button opens its own menu when clicked.',
+    'target': 'the menu belongs to the button that opens it.',
+}
+
 if TYPE_CHECKING:
     from bootstack.signals import Signal
 
@@ -122,10 +132,13 @@ class DropdownButton(MenuButton):
             "offset": (offset_x, 0),
             "density": density,
         }
-        options.update(self._popdown_options)
         # DropdownButton manages its own activation (left-click, Return/
         # KP_Enter via show_menu), so opt out of ContextMenu's auto-trigger.
-        cm = ContextMenu(self, target=self, items=self._items, trigger=None, command=self._command, **options)
+        options["trigger"] = None
+        options = merge_kwargs(options, self._popdown_options,
+                               reserved=_RESERVED_MENU_OPTIONS,
+                               context='MenuButton menu_options')
+        cm = ContextMenu(self, target=self, items=self._items, command=self._command, **options)
         return cm
 
     @property

{bootstack-0.1.4 → bootstack-0.1.6}/src/bootstack/widgets/_impl/composites/field.py

@@ -273,8 +273,13 @@ class Field(EntryMixin, Frame):
         self._entry.value(value)
 
     def get(self) -> str:
-        """Return the raw text from the underlying entry widget."""
-        return self._entry.get()
+        """Return the display text from the underlying entry widget.
+
+        Reads the entry's own text rather than its raw contents, so a field
+        showing only its placeholder reports an empty string — `text` and
+        `value` are a pair and must agree on whether the field is empty.
+        """
+        return self._entry.text()
 
     @property
     def entry_widget(self) -> EntryWidget:

{bootstack-0.1.4 → bootstack-0.1.6}/src/bootstack/widgets/_impl/composites/form.py

@@ -15,8 +15,15 @@ from bootstack.widgets._impl.primitives.label import Label
 from bootstack.widgets._impl.primitives.labelframe import LabelFrame
 from bootstack.widgets._impl.mixins import configure_delegate
 from bootstack.widgets._impl.composites.tabs.tabview import TabView
+from bootstack.widgets._core.kwargs import merge_kwargs
 from bootstack.widgets.types import EditorType, Master
 
+# Structural keys an editor_options bag may not set — the form's field
+# container owns where the editor is placed.
+_RESERVED_EDITOR_OPTIONS = {
+    'parent': 'the form places each editor in its own field container',
+}
+
 if TYPE_CHECKING:
     from bootstack.dialogs._impl.dialog import DialogButton
     ButtonInput = str | Mapping[str, Any] | DialogButton
@@ -603,10 +610,10 @@ class Form(Frame):
                     auto_col = 0
                     auto_row += 1
 
-    # Editors that accept validation kwargs (required, etc.). Boolean and slider
-    # editors validate nothing, so `required` and friends are dropped for them.
-    _VALIDATING_EDITORS = frozenset(
-        {'textfield', 'numberfield', 'passwordfield', 'datefield', 'textarea', 'select', 'spinnerfield'})
+    # Editors that render something other than a validating field, so `required`
+    # and friends are dropped for them. Anything NOT named here — including a
+    # misspelled editor name — falls back to a text field, which does validate.
+    _NON_VALIDATING_EDITORS = frozenset({'checkbox', 'switch', 'slider'})
 
     def _build_field(self, parent: Frame, item: FieldItem):
         if not item.visible:
@@ -614,7 +621,11 @@ class Form(Frame):
 
         editor = item.editor or self._default_editor_for_dtype(item.dtype, self._data.get(item.key))
         options = dict(item.editor_options or {})
-        if item.required and editor in self._VALIDATING_EDITORS:
+        # Gate on what does NOT validate, not on what does: an unrecognized
+        # editor name falls back to a text field, so testing membership of the
+        # validating set silently dropped `required` on a typo and let the form
+        # submit empty.
+        if item.required and editor not in self._NON_VALIDATING_EDITORS:
             options["required"] = True
         initial_value = self._data.get(item.key)
         label_text = item.label if item.label is not None else item.key.replace("_", " ").title()
@@ -680,45 +691,76 @@ class Form(Frame):
         for internal_only in ("show_message", "validator"):
             opts.pop(internal_only, None)
 
+        # `value` in editor_options seeds the editor when the form data carries
+        # nothing for the key; the data wins when it does. Every editor below
+        # passes `value=` positionally-by-keyword, so leaving it in `opts` would
+        # raise "got multiple values for keyword argument 'value'".
+        seed_value = opts.pop('value', None)
+        if initial is None:
+            initial = seed_value
+
+        def build(cls, *args, **defaults):
+            """Construct `cls`, letting `editor_options` override the defaults."""
+            merged = merge_kwargs(defaults, opts, reserved=_RESERVED_EDITOR_OPTIONS,
+                                  context='Form editor_options')
+            merged['parent'] = container
+            return cls(*args, **merged)
+
+        def choice_list():
+            """Pop the documented `items`/`values` aliases for the option list."""
+            choices = opts.pop('items', None)
+            if choices is None:
+                choices = opts.pop('values', None)
+            return choices
+
+        # Test against None, not truthiness: a falsy-but-real datum (0, False)
+        # is a value, not an absent one, and blanking it here would write the
+        # blank straight back into the form data. Pass the datum through as it
+        # came, too — `data` is the caller's record, and stringifying it here
+        # would flip a Decimal or a date to `str` in `form.data` before the
+        # user has edited anything.
+        text_value = initial if initial is not None else ""
+
         if editor == 'textfield':
-            return TextField(value=initial or "", label=label_text, parent=container, **opts)
+            return build(TextField, value=text_value, label=label_text)
         if editor == 'numberfield':
-            numeric_value = initial if initial is not None else 0
-            return NumberField(value=numeric_value, label=label_text, parent=container, **opts)
+            return build(NumberField, value=initial if initial is not None else 0,
+                         label=label_text)
         if editor == 'passwordfield':
-            return PasswordField(value=initial or "", label=label_text, parent=container, **opts)
+            return build(PasswordField, value=text_value, label=label_text)
         if editor == 'datefield':
-            return DateField(value=initial, label=label_text, parent=container, **opts)
+            return build(DateField, value=initial, label=label_text)
         if editor == 'textarea':
-            text = str(initial) if initial is not None else ""
-            return TextArea(value=text, label=label_text, parent=container, **opts)
+            return build(TextArea, value=text_value, label=label_text)
         if editor == 'select':
-            choices = opts.pop('items', opts.pop('values', None)) or []
-            choices = [str(i) for i in choices]
-            return Select(options=choices, value=initial if initial is not None else "",
-                          label=label_text, parent=container, **opts)
+            choices = [str(i) for i in (choice_list() or [])]
+            return build(Select, options=choices, label=label_text,
+                         value=initial if initial is not None else "")
         if editor == 'spinnerfield':
-            choices = opts.pop('items', opts.pop('values', None))
+            choices = choice_list()
             if choices is not None:
                 opts['options'] = [str(i) for i in choices]
-            return SpinnerField(value=initial if initial is not None else "",
-                                label=label_text, parent=container, **opts)
-        if editor == 'checkbox':
-            text = opts.pop('text', None) or label_text
-            return Checkbox(text, value=bool(initial) if initial is not None else False,
-                            parent=container, **opts)
-        if editor == 'switch':
-            text = opts.pop('text', None) or label_text
-            return Switch(text, value=bool(initial) if initial is not None else False,
-                          parent=container, **opts)
+            return build(SpinnerField, value=initial if initial is not None else "",
+                         label=label_text)
+        if editor in ('checkbox', 'switch'):
+            # The boolean controls call their caption `label`, so pass it by
+            # keyword — passing it positionally would collide with a `label`
+            # option instead of letting it override, and `text` is the alias a
+            # caller reaches for first.
+            caption = opts.pop('text', None) or label_text
+            # `None` stays `None` so a tristate checkbox starts indeterminate;
+            # the widget maps `None` to unchecked when tristate is off.
+            cls = Checkbox if editor == 'checkbox' else Switch
+            return build(cls, label=caption,
+                         value=bool(initial) if initial is not None else None)
         if editor == 'slider':
             # Slider has no label parameter, so render a stacked caption above it
             # (the field wrappers render their own label internally).
             if label_text:
                 Label(container, text=label_text).pack(anchor='w', pady=(0, 2))
-            return Slider(value=initial if initial is not None else 0, parent=container, **opts)
+            return build(Slider, value=initial if initial is not None else 0)
         # Fallback: treat any unknown editor as a text field.
-        return TextField(value=initial or "", label=label_text, parent=container, **opts)
+        return build(TextField, value=text_value, label=label_text)
 
     def _build_buttons(self, parent: Frame, buttons: Sequence[ButtonInput]) -> None:
         parsed = self._normalize_buttons(buttons)