magicgui 0.6.0

build GUIs from functions, using magic

build GUIs from type annotations, using magic.

📖 Docs

https://napari.org/magicgui

Installation

magicgui uses qtpy to support both pyside2 and pyqt5 backends. However, you must have one of those installed for magicgui to work.

install with pip

pip install magicgui[pyqt5]
# or
pip install magicgui[pyside2]

or with conda:

conda install -c conda-forge magicgui pyqt  # or pyside2 instead of pyqt

:information_source: If you'd like to help us extend support to a different backend, please open an issue.

Basic usage

from magicgui import magicgui
from enum import Enum

class Medium(Enum):
    Glass = 1.520
    Oil = 1.515
    Water = 1.333
    Air = 1.0003

# decorate your function with the @magicgui decorator
@magicgui(call_button="calculate", result_widget=True)
def snells_law(aoi=30.0, n1=Medium.Glass, n2=Medium.Water, degrees=True):
    import math

    aoi = math.radians(aoi) if degrees else aoi
    try:
        result = math.asin(n1.value * math.sin(aoi) / n2.value)
        return math.degrees(result) if degrees else result
    except ValueError:
        return "Total internal reflection!"

# your function is now capable of showing a GUI
snells_law.show(run=True)

But that's just the beginning! Please see Documentation for many more details and usage examples.

Contributing

Contributions are welcome!

Please note: magicgui attempts to adhere to strict coding rules and employs the following static analysis tools to prevent errors from being introduced into the codebase:

• black - code formatting
• flake8 - linting
• pydocstyle - docstring conventions
• mypy - static type anaylsis
• codecov - test coverage

To prevent continuous integration failures when contributing, please consider installing pre-commit in your environment to run all of these checks prior to checking in new code.

pre-commit install

Changelog

0.6.0 (2022-10-26)

Full Changelog

Merged pull requests:

• docs: add doi to readme #479 (tlambert03)

v0.6.0rc2 (2022-10-25)

Full Changelog

Merged pull requests:

• [pre-commit.ci] pre-commit autoupdate #477 (pre-commit-ci[bot])
• Enable option to raise excpetion if magicgui cannot determine widget for provided value/annotation #476 (Czaki)
• docs: fix word in slice edit docs #472 (tlambert03)

v0.6.0rc1 (2022-10-22)

Full Changelog

Implemented enhancements:

• feat: add context manager for register_type #470 (tlambert03)
• feat: click on button return #468 (tlambert03)

Fixed bugs:

• fix: Fix persist on magicgui method decorator #469 (tlambert03)
• fix: handle case of bad parameter cache file read #467 (tlambert03)
• use math.ceil to ensure get_text_width returns int #465 (psobolewskiPhD)
• Fix ipynb PushButton #464 (hanjinliu)

Merged pull requests:

• docs: changelog v0.6.0rc1 #471 (tlambert03)

v0.6.0rc0 (2022-10-21)

Full Changelog

Implemented enhancements:

• Support Literal type #458 (hanjinliu)
• feat: add range slider (take 2) #455 (tlambert03)
• feat: Pass parent to backend widget #440 (tlambert03)
• Add ipywidgets backend #87 (tlambert03)

Fixed bugs:

• fix: fix deprecation warning from matplotib about accessing colormaps from mpl.cm #451 (tlambert03)
• Fix FunctionGui behavior as a class method #443 (hanjinliu)
• Expose QScrollArea as native widget #429 (dstansby)
• Turn off adaptive step if "step" option is given #425 (hanjinliu)

Tests & CI:

• tests: add test for magic-class #447 (tlambert03)
• test: change pytest testing plugin #438 (tlambert03)

Documentation:

• docs: changelog v0.6.0 #462 (tlambert03)
• Fix links in documentation #433 (Czaki)
• fix docs build #428 (tlambert03)
• Bump jupyter-book to 0.12.x #427 (dstansby)

Merged pull requests:

• build: pin pyside6 extra #460 (tlambert03)

v0.5.1 (2022-06-14)

Full Changelog

Fixed bugs:

• Emit signal only if value of caterogical widget changed #422 (Czaki)

Merged pull requests:

• add changelog for v0.5.1 #423 (tlambert03)

v0.5.0 (2022-06-13)

Full Changelog

Implemented enhancements:

• feat: add request_values convenience, shows modal dialog to request values #416 (tlambert03)
• Change to use adaptive step is SpinBox and FloatSpinBox #403 (Czaki)
• Make call_button public #391 (dstansby)
• Add scrollable widgets #388 (dstansby)

Fixed bugs:

• Return empty tuple for no selected files #415 (aeisenbarth)
• Block event emits during choices batch update #407 (aeisenbarth)
• Bug fix of type check in ListEdit #404 (hanjinliu)
• Fix bug with small default range in SpinBox #397 (Czaki)
• Fix bug in creation of RangeEdit using create_widget #396 (Czaki)
• Fix insertion of Container widget #394 (hanjinliu)

Tests & CI:

• fix napari CI test #417 (tlambert03)
• ci(dependabot): bump actions/setup-python from 1 to 3 #414 (dependabot[bot])
• ci(dependabot): bump codecov/codecov-action from 2 to 3 #413 (dependabot[bot])
• ci(dependabot): bump actions/checkout from 2 to 3 #412 (dependabot[bot])
• ci: add dependabot #411 (tlambert03)
• Fix typesafety tests #399 (tlambert03)

Merged pull requests:

• add changelog for v0.5.0 #418 (tlambert03)

v0.4.0 (2022-03-25)

Full Changelog

Documentation:

• Fix pyqt conda install instruction #386 (dstansby)

v0.4.0rc1 (2022-03-18)

Full Changelog

Implemented enhancements:

• Support sequences #342 (hanjinliu)

Fixed bugs:

• Use empty string as null value for FileEdit #384 (brisvag)
• fix register_widget with widget subclass #376 (tlambert03)

Deprecated:

• Remove event deprecations strategy (for release 0.4.0) #368 (tlambert03)

Tests & CI:

• Check out napari repo instead of git+https #378 (jni)
• Test that bound values don't get called greedily upon widget creation #371 (tlambert03)

v0.3.7 (2022-02-12)

Full Changelog

Merged pull requests:

• bump psygnal dep to 0.3.0 #369 (tlambert03)

v0.3.6 (2022-02-11)

Full Changelog

Fixed bugs:

• Fix _normalize_slot private attr access, and fix annotation setter forward ref resolution #367 (tlambert03)

v0.3.5 (2022-02-07)

Full Changelog

Implemented enhancements:

• Create return matcher for extensible return widget creation #355 (gselzer)

Fixed bugs:

• Add new type normalization TypeWrapper, fix builtin and optional ForwardRefs #362 (tlambert03)
• Fix changing choices on ComboBox #352 (tlambert03)

Tests & CI:

• fix tests in xvfb-action #366 (tlambert03)

Documentation:

• update napari examples #357 (tlambert03)

Merged pull requests:

• Do not package tests #365 (jaimergp)
• Make Table a ValueWidget #360 (tlambert03)
• Update build workflow #344 (tlambert03)

v0.3.4 (2022-01-01)

Full Changelog

Implemented enhancements:

• support Qt6 #324 (tlambert03)
• Support partials and tz.curry #316 (tlambert03)

Fixed bugs:

• Fix buttons on PySide2 #343 (tlambert03)
• fix py3.10 test #339 (tlambert03)
• Skip bad parameter names in inject tooltip #336 (tlambert03)
• Relay signals from Container to Container #331 (hanjinliu)
• Fix readout visibility on slider __init__ #329 (tlambert03)
• Fix bug in Select widget value setter in direct API usage #326 (tlambert03)

Tests & CI:

• Pre commit ci update config #338 (tlambert03)
• Fixing a few test things #325 (tlambert03)

Documentation:

• adds waveform generator exemple #322 (glyg)
• add example of adding mpl FigureCanvas to widget #321 (tlambert03)

v0.3.3 (2021-11-08)

Full Changelog

Implemented enhancements:

• Add update, asdict, and update_widget to FunctionGui #309 (tlambert03)
• Add support for python 3.10 #294 (tlambert03)

Fixed bugs:

• Fix deprecation events for psygnal 0.2 #311 (tlambert03)

v0.3.2 (2021-10-22)

Full Changelog

Fixed bugs:

• Fix unbound variable in format_number #303 (tlambert03)

v0.3.1 (2021-10-21)

Full Changelog

Implemented enhancements:

• Add stacklevel to provide better information about place of problem #302 (Czaki)
• Table widget updates #301 (hanjinliu)

v0.3.0 (2021-10-10)

Full Changelog

Implemented enhancements:

• Return type from register_type, so that it can be used as a decorator #297 (tlambert03)

Deprecated:

• Remove choices deprecation warning from 0.2.0 #298 (tlambert03)

Documentation:

• add v0.3.0 migration guide #299 (tlambert03)

v0.3.0rc2 (2021-10-10)

Full Changelog

Fixed bugs:

• Allow Signal.sender() to work regardless of importing from magicgui or Psygnal #296 (tlambert03)
• Catch kwargs in event emitter (backwards compatibility with old event emitter) #295 (tlambert03)

v0.3.0rc1 (2021-10-04)

Full Changelog

Implemented enhancements:

• Use psygnal instead of EventEmitter (callbacks receive value directly). Add deprecation strategy #253 (tlambert03)

Fixed bugs:

• Replace underscore with spaces in checkbox label #293 (tlambert03)

Tests & CI:

• misc typing fixes and changlelog generator config #292 (tlambert03)

Merged pull requests:

• [pre-commit.ci] pre-commit autoupdate #291 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #289 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #287 (pre-commit-ci[bot])

v0.2.11 (2021-09-11)

Full Changelog

Implemented enhancements:

• Add close method #283 (tlambert03)
• Make show_file_dialog function public #274 (tlambert03)
• Add button.clicked alias for button.changed #271 (tlambert03)
• Add multi-Selection widget #265 (tlambert03)
• Add copy, paste, cut, delete keyboard shortcuts to Table widget #264 (tlambert03)

Fixed bugs:

• Fix call button text and and param options when using decorator on class method #276 (tlambert03)
• Fix check for Optional Type #270 (tlambert03)
• Change comparison to null_value in ValueWidget from == to is #267 (tlambert03)
• Fix missing event emission when nullable widget is set to null value. #263 (tlambert03)
• Fix optional annotation affecting later widgets #262 (tlambert03)
• Fix RangeWidget with implicit optional type #257 (tlambert03)

Tests & CI:

• Fix typesafety tests #282 (tlambert03)

Documentation:

• Fix docs build again #286 (tlambert03)
• Fix docs build, add Select widget #285 (tlambert03)

Merged pull requests:

• update master to main #280 (tlambert03)
• [pre-commit.ci] pre-commit autoupdate #278 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #272 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #268 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #258 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #256 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #254 (pre-commit-ci[bot])

v0.2.10 (2021-07-11)

Full Changelog

Implemented enhancements:

• Add tracking property to sliders. When False, changed only emits on release. #248 (tlambert03)
• Add ValueWidget._nullable, and enable for categorical widgets #227 (tlambert03)

Fixed bugs:

• Fix labels remaining after popping widgets from container #245 (tlambert03)
• Fix default value of None being ignored #244 (tlambert03)
• Fix reuse of magic factory #224 (tlambert03)
• Fix EventEmitter loop when event is blocked #215 (tlambert03)

Documentation:

• Small change to improve repr of sentinel in docs #251 (tlambert03)
• Minor docstring change for tracking #250 (tlambert03)
• Specify XDG_RUNTIME_DIR to avoid warnings showing up in the docs #249 (hmaarrfk)
• Fix FunctionGui docstring parameter name #247 (tlambert03)
• fix-docs #231 (tlambert03)
• Widget overview docs #213 (tlambert03)

Merged pull requests:

• [pre-commit.ci] pre-commit autoupdate #235 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #228 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #223 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #221 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #219 (pre-commit-ci[bot])

v0.2.9 (2021-04-05)

Full Changelog

Implemented enhancements:

• Display current slider value (editable) #211 (tlambert03)
• Add table.changed event emitter #209 (tlambert03)
• Coerce RadioButton with Enum/choices to RadioButtons #202 (tlambert03)
• Compute correct widget width for rich text labels #199 (maweigert)

Fixed bugs:

• Fix tests when both pyside2 and pyqt5 are installed #210 (tlambert03)
• Disconnect filedialog button from value.changed events #208 (tlambert03)
• Fix persist issue with cached parameter that has been removed #203 (uschmidt83)
• fix enum choices in radiobuttons #201 (tlambert03)
• Delete button when removing from qt RadioGroup #198 (tlambert03)

Documentation:

• skip docutils 0.17 #207 (tlambert03)
• Add cache location hint to persist option documentation #200 (maweigert)

Merged pull requests:

• [pre-commit.ci] pre-commit autoupdate #212 (pre-commit-ci[bot])

v0.2.8 (2021-03-24)

Full Changelog

v0.2.8rc0 (2021-03-24)

Full Changelog

Implemented enhancements:

• Update call button to default True when auto_call is False #194 (jni)
• add RadioButtons widget #183 (tlambert03)

Fixed bugs:

• Fix RadioButtons double event emissions #189 (tlambert03)
• don't ever change the call_button text silly #180 (tlambert03)
• Fix extreme float values for slider and spinbox #178 (tlambert03)
• Fix FileEdit events #176 (tlambert03)
• fix nested functiongui show #175 (tlambert03)
• Fail gracefully with persistence errors, better debounce #170 (tlambert03)

Documentation:

• docs reorg #193 (tlambert03)

Merged pull requests:

• Replace turbo with magma colormap in tests #195 (jni)
• [pre-commit.ci] pre-commit autoupdate #191 (pre-commit-ci[bot])
• fix mypy errors #185 (tlambert03)
• [pre-commit.ci] pre-commit autoupdate #184 (pre-commit-ci[bot])
• Add typing to events.py #181 (tlambert03)
• [pre-commit.ci] pre-commit autoupdate #171 (pre-commit-ci[bot])

v0.2.7 (2021-02-28)

Full Changelog

Implemented enhancements:

• improve error message for bad kwargs #167 (tlambert03)
• Persist parameter values across sessions #160 (tlambert03)
• Add widget_init parameter to magic_factory #159 (tlambert03)
• Allow magicgui.types.PathLike annotation #151 (tlambert03)
• allow label to be alias for text in button widgets #150 (tlambert03)
• Image widget #140 (tlambert03)

Fixed bugs:

• fix range/slice edits #166 (tlambert03)
• Work without numpy #164 (tlambert03)
• Fix FileEdit with directory mode #158 (tlambert03)
• fix function with no params and callbutton #149 (tlambert03)
• Fix typesafety checks with numpy 1.20 #141 (tlambert03)
• Disable call button while function is running #139 (tlambert03)

Documentation:

• Fix napari return annotations #154 (sofroniewn)

Merged pull requests:

• [pre-commit.ci] pre-commit autoupdate #157 (pre-commit-ci[bot])
• [pre-commit.ci] pre-commit autoupdate #148 (pre-commit-ci[bot])
• Move return_annotation from container to FunctionGui #143 (tlambert03)
• [pre-commit.ci] pre-commit autoupdate #142 (pre-commit-ci[bot])
• Remove pre 0.2.0 deprecation warnings #138 (tlambert03)
• update changelog #137 (tlambert03)
• [pre-commit.ci] pre-commit autoupdate #136 (pre-commit-ci[bot])

v0.2.6rc0 (2021-01-25)

Full Changelog

v0.2.6 (2021-01-25)

Full Changelog

Merged pull requests:

• Add magicgui.* objectName to qt widgets #134 (tlambert03)
• remove _qt module #133 (tlambert03)
• Improve fallback behavior of tqdm iterator inside of *hidden* magicgui widget #131 (tlambert03)
• Improve issues with widget visibility #130 (tlambert03)
• add attribute error to magicgui.__getattr__ #129 (tlambert03)
• Make _magicgui.pyi stubs #126 (tlambert03)
• Fix @magic_factory usage in local scopes #125 (tlambert03)
• Make vertical layout the default #124 (tlambert03)
• fix date topython #123 (tlambert03)
• Remove deprecated "result" param to magicgui #122 (tlambert03)
• Fix tooltips for multiple params names on one line #120 (tlambert03)
• Fix bug in tooltip parsing #119 (tlambert03)
• More docs for main_window flag #118 (HagaiHargil)
• Magic factory #117 (tlambert03)
• Add more sizing options (min/max width/height) #116 (tlambert03)
• Move FunctionGui into widgets #115 (tlambert03)
• Split widget bases into files #114 (tlambert03)
• User internal model for Container, simplify ContainerWidgetProtocol #113 (tlambert03)
• setup.cfg updates #112 (tlambert03)
• Add MainWindow variant on Container, and MainFunctionGui #110 (tlambert03)
• Parse the entire docstring for the tooltip #108 (HagaiHargil)
• improved labeled widgets #106 (tlambert03)
• Progress bar tqdm wrapper, and manual control #105 (tlambert03)
• Add ProgressBar widget #104 (tlambert03)
• Use (hidden) EmptyWidget for unrecognized types #103 (tlambert03)
• Add manual and docstring-parsed tooltips #100 (tlambert03)
• Add Table Widget #61 (tlambert03)

v0.2.5 (2021-01-13)

Full Changelog

Merged pull requests:

• Fix reset_choices recursion #96 (tlambert03)
• better bound values #95 (tlambert03)

v0.2.4 (2021-01-12)

Full Changelog

Merged pull requests:

• Extend combobox api with set_choice, get_choice, del_choice #92 (tlambert03)

v0.2.3 (2021-01-08)

Full Changelog

Merged pull requests:

• Fix ComboBox with unhashable choice data #89 (tlambert03)
• add pyupgrade pre-commit hook #88 (tlambert03)
• add call count to function gui #86 (tlambert03)
• Add more examples (chaining, self-reference, and choices) #85 (tlambert03)
• Add date and time widgets #84 (tlambert03)
• Clarify choices callable deprecation warning #83 (tlambert03)
• Convert maximum/minimum kwargs to max/min and warn #82 (tlambert03)
• [pre-commit.ci] pre-commit autoupdate #80 (pre-commit-ci[bot])

v0.2.2 (2021-01-02)

Full Changelog

Merged pull requests:

• hotfix for signature inspection exception #79 (tlambert03)
• remove orientation method from supportsOrientation #77 (tlambert03)
• Better error on incorrect protocol #76 (tlambert03)
• save application instance #75 (tlambert03)

v0.2.1 (2020-12-29)

Full Changelog

Merged pull requests:

• Resolve ForwardRefs on return annotations #73 (tlambert03)
• [pre-commit.ci] pre-commit autoupdate #71 (pre-commit-ci[bot])
• Improve test coverage #70 (tlambert03)
• Fix parent_changed signal emission #69 (tlambert03)
• Add tests for docs and examples #68 (tlambert03)
• Change "orientation" on containers to "layout" #67 (tlambert03)
• resolve ForwardRef on widget.annotation #66 (tlambert03)

v0.2.0 (2020-12-26)

Full Changelog

Merged pull requests:

• API cleanup and unify with ipywidgets (a little) #60 (tlambert03)
• Labels update #59 (tlambert03)
• New documentation #58 (tlambert03)
• Corrected usage / example code of parameter 'choices' #57 (haesleinhuepf)
• Enable decorator to be used on methods #56 (tlambert03)
• add application_name variable #55 (tlambert03)
• add support for ForwardRef #52 (tlambert03)
• test on py39 #50 (tlambert03)
• Add a "display_name" option to modify a widget's label (#45) #48 (HagaiHargil)
• rewrite: proper widget protocols & signature objects #43 (tlambert03)
• Drop support for python 3.6 #42 (tlambert03)
• Add (slightly) strict mypy checking #41 (tlambert03)

v0.1.6 (2020-07-23)

Full Changelog

v0.1.6rc0 (2020-07-23)

Full Changelog

Merged pull requests:

• Add flake8-docstrings to dev requirements #39 (GenevieveBuckley)
• Add a logarithmic scale slider class #38 (GenevieveBuckley)
• Fix napari_param_sweep.py example by updating QDoubleSlider import #37 (GenevieveBuckley)
• Widget demo example script #36 (GenevieveBuckley)
• Reorganize _qt module #32 (tlambert03)
• add literal eval fallback widget #31 (tlambert03)
• support Sequence[Path] #27 (tlambert03)
• Make sure black reformatting is an error on CI #26 (tlambert03)
• Pin Linux Qt <5.15 #24 (tlambert03)
• Filedialog widget for magicgui #23 (GenevieveBuckley)
• Add datetime to type2widget function #22 (GenevieveBuckley)
• Must import scikit-image modules specifically #18 (GenevieveBuckley)

v0.1.5 (2020-05-24)

Full Changelog

Merged pull requests:

• Add the ability to hide a widget #17 (tlambert03)

v0.1.4 (2020-05-19)

Full Changelog

Merged pull requests:

• Update ci, version with setuptools_scm #15 (tlambert03)
• Initial support for labels #14 (tlambert03)

v0.1.3 (2020-05-04)

Full Changelog

Merged pull requests:

• pyright -> mypy #11 (tlambert03)
• Update docs #10 (tlambert03)
• update param sweep example #8 (tlambert03)

v0.1.2 (2020-03-06)

Full Changelog

Merged pull requests:

• fix call_button press for pyqt5 #5 (tlambert03)
• Register callbacks for return annotations #4 (tlambert03)

v0.1.1 (2020-02-19)

Full Changelog

Merged pull requests:

• split out deploy #2 (tlambert03)

v0.1.0 (2020-02-18)

Full Changelog

Merged pull requests:

• playing with travis #1 (tlambert03)

v0.0.8 (2020-02-11)

Full Changelog

v0.0.7 (2020-02-09)

Full Changelog

v0.0.6 (2020-02-09)

Full Changelog

* This Changelog was automatically generated by github_changelog_generator