feat: add password field (#515)

* feat: add password field

* docs: add docs

* docs: fix protocols

* docs remove old chapter

* docs: add label

docs/_toc.yml

@@ -1,9 +1,6 @@
 format: jb-book
 root: index
 parts:
-- caption: How it Works
-  chapters:
-  - file: how_works/
 - caption: Usage
   chapters:
   - file: usage/installation

docs/api/protocols.md

@@ -1,7 +1,7 @@
-# magicgui.widgets._protocols
+# magicgui.widgets.protocols
 
 ```{eval-rst}
-.. automodule:: magicgui.widgets._protocols
+.. automodule:: magicgui.widgets.protocols
 
 .. autosummary::
    :nosignatures:

docs/api/widgets.md

@@ -25,6 +25,7 @@ Value Widgets
    Label
    LineEdit
    LiteralEvalLineEdit
+   Password
    TextEdit
    FileEdit
    RangeEdit

docs/requirements.txt

@@ -4,3 +4,4 @@ jupytext==1.13.8
 numpy
 imageio
 sphinx-autodoc-typehints==1.18.3
+pint

docs/usage/widget_overview.md

@@ -124,6 +124,7 @@ following `ValueWidgets` track some `value`:
    Label
    LineEdit
    LiteralEvalLineEdit
+   Password
    TextEdit
    FileEdit
    RangeEdit
@@ -170,6 +171,7 @@ import datetime
 wdg_list = [
     widgets.Label(value="label value", label="Label:"),
     widgets.LineEdit(value="line edit value", label="LineEdit:"),
+    widgets.Password(value="super-secret!", label="Password:"),
     widgets.TextEdit(value="text edit value...", label="TextEdit:"),
     widgets.FileEdit(value="/home", label="FileEdit:"),
     widgets.RangeEdit(value=range(0, 10, 2), label="RangeEdit:"),
@@ -179,6 +181,7 @@ wdg_list = [
     ),
     widgets.DateEdit(value=datetime.date(81, 2, 18), label="DateEdit:"),
     widgets.TimeEdit(value=datetime.time(12, 20), label="TimeEdit:"),
+    widgets.QuantityEdit(value='12 seconds', label="Quantity:")
 ]
 container = widgets.Container(widgets=wdg_list)
 container.max_height = 300

examples/login.py

@@ -0,0 +1,14 @@
+from magicgui import magicgui
+
+
+# note that "password" is a special keyword argument
+# it will create a password field in the gui by default
+# (unless you override "widget_type")
+# whereas "password2" will be a normal text field
+# (unless you override "widget_type")
+@magicgui(password2={"widget_type": "Password"})
+def login(username: str, password: str, password2: str):
+    ...
+
+
+login.show(run=True)

src/magicgui/backends/_ipynb/__init__.py

@@ -11,6 +11,7 @@
     Label,
     LineEdit,
     LiteralEvalLineEdit,
+    Password,
     PushButton,
     RadioButton,
     Select,
@@ -38,6 +39,7 @@
     "Label",
     "LineEdit",
     "LiteralEvalLineEdit",
+    "Password",
     "PushButton",
     "RadioButton",
     "Select",

src/magicgui/backends/_ipynb/widgets.py

@@ -293,6 +293,10 @@ class LineEdit(_IPyStringWidget):
     _ipywidget: ipywdg.Text
 
 
+class Password(_IPyStringWidget):
+    _ipywidget: ipywdg.Password
+
+
 class LiteralEvalLineEdit(_IPyStringWidget):
     _ipywidget: ipywdg.Text
 

src/magicgui/backends/_qtpy/__init__.py

@@ -15,6 +15,7 @@
     LineEdit,
     LiteralEvalLineEdit,
     MainWindow,
+    Password,
     ProgressBar,
     PushButton,
     QuantityEdit,
@@ -49,6 +50,7 @@
     "LineEdit",
     "LiteralEvalLineEdit",
     "MainWindow",
+    "Password",
     "ProgressBar",
     "PushButton",
     "QuantityEdit",

src/magicgui/backends/_qtpy/widgets.py

@@ -293,6 +293,12 @@ def __init__(self, **kwargs):
         super().__init__(QtW.QLineEdit, "text", "setText", "textChanged", **kwargs)
 
 
+class Password(LineEdit):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._qwidget.setEchoMode(QtW.QLineEdit.Password)
+
+
 class LiteralEvalLineEdit(QBaseStringWidget):
     _qwidget: QtW.QLineEdit
 

src/magicgui/types.py

@@ -13,7 +13,7 @@
     from magicgui.widgets.protocols import WidgetProtocol
 
 #: A :class:`~magicgui.widgets._bases.Widget` class or a
-#: :class:`~magicgui.widgets._protocols.WidgetProtocol`
+#: :class:`~magicgui.widgets.protocols.WidgetProtocol`
 WidgetClass = Union[Type["Widget"], Type["WidgetProtocol"]]
 #: A generic reference to a :attr:`WidgetClass` as a string, or the class itself.
 WidgetRef = Union[str, WidgetClass]

src/magicgui/widgets/__init__.py

@@ -29,6 +29,7 @@
     LiteralEvalLineEdit,
     LogSlider,
     MainWindow,
+    Password,
     ProgressBar,
     PushButton,
     QuantityEdit,
@@ -91,6 +92,7 @@
     "LogSlider",
     "MainFunctionGui",
     "MainWindow",
+    "Password",
     "PushButton",
     "ProgressBar",
     "QuantityEdit",

src/magicgui/widgets/_concrete.py

@@ -232,6 +232,11 @@ class LineEdit(ValueWidget):
     """A one-line text editor."""
 
 
+@backend_widget
+class Password(ValueWidget):
+    """A one-line text editor that obscures input."""
+
+
 @backend_widget
 class LiteralEvalLineEdit(ValueWidget):
     """A one-line text editor that evaluates strings as python literals."""

src/magicgui/widgets/bases/__init__.py

@@ -4,7 +4,7 @@
 exported in :mod:`magicgui.widgets`.
 
 All magicgui :class:`Widget` bases comprise a backend widget that implements one of the
-widget protocols defined in :mod:`magicgui.widgets._protocols`.  The basic composition
+widget protocols defined in :mod:`magicgui.widgets.protocols`.  The basic composition
 pattern is as follows:
 
 .. code-block:: python

src/magicgui/widgets/bases/_container_widget.py

@@ -36,7 +36,7 @@ class ContainerWidget(Widget, _OrientationMixin, MutableSequence[WidgetVar]):
     """Widget that can contain other widgets.
 
     Wraps a widget that implements
-    :class:`~magicgui.widgets._protocols.ContainerProtocol`.
+    :class:`~magicgui.widgets.protocols.ContainerProtocol`.
 
     A ``ContainerWidget`` behaves like a python list of :class:`Widget` objects.
     Subwidgets can be accessed using integer or slice-based indexing (``container[0]``),

src/magicgui/widgets/bases/_create_widget.py

@@ -89,6 +89,14 @@ def create_widget(
 
         if widget_type:
             options["widget_type"] = widget_type
+        # special case parameters named "password" with annotation of str
+        if (
+            not options.get("widget_type")
+            and (name or "").lower() == "password"
+            and annotation is str
+        ):
+            options["widget_type"] = "Password"
+
         wdg_class, opts = get_widget_class(
             value, annotation, options, is_result, raise_on_unknown
         )