Merge branch 'main' into progress-indeterminate

.github/workflows/deploy_docs.yml

@@ -10,13 +10,17 @@ on:
 
 jobs:
   docs:
-    runs-on: macos-latest  # for the screenshots
+    runs-on: macos-latest # for the screenshots
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.x'
-      - run: pip install -e .[docs]
+          python-version: "3.x"
+      - run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[docs]
 
       - name: Deploy docs to GitHub Pages
         if: github.event_name == 'push'

.github/workflows/test_and_deploy.yml

@@ -37,7 +37,7 @@ jobs:
             backend: pyside2
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4
         with:
@@ -61,7 +61,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: "3.11"
@@ -84,8 +84,8 @@ jobs:
     name: napari tests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
           repository: napari/napari
           path: napari-from-github
@@ -111,8 +111,8 @@ jobs:
     name: magic-class tests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
           repository: hanjinliu/magic-class
           path: magic-class
@@ -139,8 +139,8 @@ jobs:
     name: stardist tests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
           repository: stardist/stardist-napari
           path: stardist-napari
@@ -167,8 +167,8 @@ jobs:
     name: partseg tests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
           repository: 4DNucleome/PartSeg
           path: PartSeg
@@ -192,7 +192,7 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ github.repository == 'pyapp-kit/magicgui' && contains(github.ref, 'tags') }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - name: Set up Python

.gitignore

@@ -121,6 +121,7 @@ venv.bak/
 
 # mkdocs documentation
 /site
+docs/generated*
 
 # mypy
 .mypy_cache/

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
 
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.282
+    rev: v0.0.287
     hooks:
       - id: ruff
         args: ["--fix"]
@@ -25,12 +25,12 @@ repos:
       - id: black
 
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.13
+    rev: v0.14
     hooks:
       - id: validate-pyproject
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.4.1
+    rev: v1.5.1
     hooks:
       - id: mypy
         files: "^src/"

docs/examples/README.md

@@ -0,0 +1,3 @@
+# Getting started
+
+A gallery of examples for magicgui.

docs/examples/applications/README.md

@@ -0,0 +1,3 @@
+# Demo applications
+
+Example applications built with magicgui.

examples/callable.py → docs/examples/applications/callable.py

@@ -1,20 +1,28 @@
+"""# Callable functions demo
+
+This example demonstrates handling callable functions with magicgui.
+"""
 from magicgui import magicgui
 
 
 def f(x: int, y="a string") -> str:
+    """Example function F."""
     return f"{y} {x}"
 
 
 def g(x: int = 6, y="another string") -> str:
+    """Example function G."""
     return f"{y} asdfsdf {x}"
 
 
 @magicgui(call_button=True, func={"choices": ["f", "g"]})
 def example(func="f"):
+    """Ëxample function."""
     pass
 
 
 def update(f: str):
+    """Update function."""
     if len(example) > 2:
         del example[1]
     example.insert(1, magicgui(globals()[f]))

examples/chaining.py → docs/examples/applications/chaining.py

@@ -1,14 +1,20 @@
+"""# Chaining functions together
+
+This example demonstrates chaining multiple functions together.
+"""
 from magicgui import magicgui, widgets
 
 
 @magicgui(auto_call=True)
 def func_a(x: int = 64, y: int = 64):
+    """Callable function A."""
     print("calling func_a")
     return x + y
 
 
 @magicgui(auto_call=True, input={"visible": False, "label": " ", "max": 100000})
 def func_b(input: int, mult=1.0):
+    """Callable function B."""
     print("calling func_b")
     result = input * mult
     # since these function defs live in globals(), you can update them directly
@@ -30,6 +36,7 @@ def _on_func_a(value: str):
     labels=False,
 )
 def func_c(input: int, format: str = "({} + {}) * {} is {}") -> str:
+    """Callable function C."""
     print("calling func_c\n")
     return format.format(func_a.x.value, func_a.y.value, func_b.mult.value, input)
 

examples/main_window.py → docs/examples/applications/hotdog.py

@@ -1,11 +1,15 @@
+"""# Hotdog or not app
+
+Demo app to upload an image and classify if it's an hotdog or not.
+"""
 import pathlib
 from enum import Enum
 
 from magicgui import magicgui
 
 
 class HotdogOptions(Enum):
-    """All hotdog possibilities"""
+    """All hotdog possibilities."""
 
     Hotdog = 1
     NotHotdog = 0

docs/examples/applications/pint_quantity.py

@@ -0,0 +1,20 @@
+"""# Quantities with pint
+
+Pint is a Python package to define, operate and manipulate physical quantities:
+the product of a numerical value and a unit of measurement.
+It allows arithmetic operations between them and conversions
+from and to different units.
+https://pint.readthedocs.io/en/stable/
+"""
+from pint import Quantity
+
+from magicgui import magicgui
+
+
+@magicgui
+def widget(q=Quantity("1 ms")):
+    """Widget allowing users to input quantity measurements."""
+    print(q)
+
+
+widget.show(run=True)

examples/snells_law.py → docs/examples/applications/snells_law.py

@@ -1,4 +1,7 @@
-"""Simple demonstration of magicgui."""
+"""# Snell's law demonstration using magicgui
+
+Demo app for calculating angles of refraction according to Snell's law.
+"""
 
 import math
 from enum import Enum

docs/examples/applications/values_dialog.py

@@ -0,0 +1,21 @@
+"""# Input values dialog
+
+A basic example of a user input dialog.
+
+This will pause code execution until the user responds.
+
+# ![Values input dialog](../../images/values_input.png){ width=50% }
+
+```python linenums="1"
+from magicgui.widgets import request_values
+
+vals = request_values(
+    age=int,
+    name={"annotation": str, "label": "Enter your name:"},
+    title="Hi, who are you?",
+)
+print(repr(vals))
+```
+"""
+
+# %%

examples/basic.py → docs/examples/basic_example.py

@@ -1,8 +1,13 @@
+"""# Basic example
+
+A basic example using magicgui.
+"""
 from magicgui import magicgui
 
 
 @magicgui
 def example(x: int, y="hi"):
+    """Basic example function."""
     return x, y
 
 

examples/widget_demo.py → docs/examples/basic_widgets_demo.py

@@ -1,5 +1,10 @@
-"""Widget demonstration of magicgui."""
+"""# Basic widgets demo
 
+Widget demonstration with magicgui.
+
+This code demonstrates a few of the widget types that magicgui can create
+based on the parameter types in your function.
+"""
 import datetime
 from enum import Enum
 from pathlib import Path

docs/examples/demo_widgets/README.md

@@ -0,0 +1,3 @@
+# Demo widget types
+
+Example gallery demonstrating the available widget types in magicgui.

examples/change_label.py → docs/examples/demo_widgets/change_label.py

@@ -1,9 +1,14 @@
+"""# Custom text labels for widgets
+
+An example showing how to create custom text labels for your widgets.
+"""
 from magicgui import magicgui
 
 
 # use a different label than the default (the parameter name) in the UI
 @magicgui(x={"label": "widget to set x"})
 def example(x=1, y="hi"):
+    """Example function."""
     return x, y