magicgui 0.3.1

build GUIs from functions, using magic

magicgui: build GUIs from functions, using magic.

📖 Docs

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

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)

Merged pull requests:

• 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)

Merged pull requests:

• Fix docs build again #286 (tlambert03)
• Fix docs build, add Select widget #285 (tlambert03)
• 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)

Merged pull requests:

• 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)
• [pre-commit.ci] pre-commit autoupdate #235 (pre-commit-ci[bot])
• fix-docs #231 (tlambert03)
• [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])
• Widget overview docs #213 (tlambert03)

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)

Merged pull requests:

• [pre-commit.ci] pre-commit autoupdate #212 (pre-commit-ci[bot])
• skip docutils 0.17 #207 (tlambert03)
• Add cache location hint to persist option documentation #200 (maweigert)

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)

Merged pull requests:

• Replace turbo with magma colormap in tests #195 (jni)
• docs reorg #193 (tlambert03)
• [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)

Merged pull requests:

• [pre-commit.ci] pre-commit autoupdate #157 (pre-commit-ci[bot])
• Fix napari return annotations #154 (sofroniewn)
• [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.6 (2021-01-25)

Full Changelog

v0.2.6rc0 (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