Skip to main content

build GUIs from functions, using magic

Project description

icon

License Version conda-forge Python Version Build Status codecov

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)

snells

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:

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.2.6 (2021-01-25)

Full Changelog

v0.2.6 is a significant feature release, introducing a number of new widgets and APIs:

  • New Table Widget allowing easy creation and modification of Table UIs using a variety of pure python types as input (#61)
  • Tooltips for each widget in a @magicgui are now automatically taken from docstrings (numpy, google, and sphinx-rst format accepted)(#100)
  • New ProgressBar widget (#104) and magicgui.tqdm wrapper (#105) allow both manual and automatically-added progress bars to long-running iterator-based functions. magicgui.tqdm.tqdm acts as a drop-in replacement for tqdm.tqdm that will fall back to the standard (console output) behavior if used outside of a magicgui function, or inside of a magicgui widget that is not yet visible.
  • New MainWindow/MainFunctionGui subclasses allow creating top level "application" windows, with a basic API for adding items to the application menubar (#110).
  • The new @magic_factory decorator creates a callable that, when called, returns a FunctionGui instance (as opposed to @magicgui which immediately creates the FunctionGui instance. Think of this as returning a "class" as opposed to returning an "instance":
    @magic_factory(call_button=True)
    def my_factory(x: int, y = 'hi'):
        ...
    
    # can add to or override original factory arguments
    widget = my_factory(main_window=True)
    widget.show()
    
  • "vertical" is now the default layout for Containers and magicgui widgets.

Implemented enhancements:

  • Best way to add general docs and help menu? #107
  • Tooltips #94
  • Progress bar widget for long-running computations #25

Fixed bugs:

  • Adding stretch to a widget's native layout causes a crash #111

Closed issues:

  • Adding a stretch to the bottom of widgets #127
  • make vertical layout default #121
  • Proposal: don't instantiate widgets when no widget is defined for specific type #101

Merged pull requests:

v0.2.5 (2021-01-13)

Full Changelog

v0.2.5 greatly improves support for binding a value or a callback to a function parameter, and fixes a bug in recursively updating categorical widgets nested deeply inside of a container.

Merged pull requests:

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

v0.2.3 adds two new widgets DateEdit and TimeEdit (for datetime.date and datetime.time types respectively), in addition to the existing DateTimeEdit widget. It also continues to improve warnings and deprecation messages from the v0.2.0 release.

Fixed bugs:

  • magicgui.widgets.CategoricalWidget not found in magicgui 0.2.1 #81

Closed issues:

  • QTimeEdit widgets #78

Merged pull requests:

v0.2.2 (2021-01-02)

Full Changelog

Merged pull requests:

v0.2.1 (2020-12-29)

Full Changelog

v0.2.1 fixes some issues with the 0.2.0 release. ForwardRef annotations are now resolved automatically on both parameter and return type annotations. And the orientation parameter on Container widgets (such as those returned by the magicgui decorator) has been renamed back to layout as in <v0.2.0. Test coverage is also improved.

Fixed bugs:

  • napari examples in the docs are broken #72
  • Functions without arguments are not finding napari parent widgets #64
  • "Layout" parameter doesn't work anymore in recent dev version #54

Closed issues:

  • Should we permanently resolve ForwardRef type annotations? #65
  • Need consensus on "layout" vs "orientation" #63

Merged pull requests:

v0.2.0 (2020-12-26)

Full Changelog

v0.2.0 includes a complete rewrite of magicgui. The primary goals were as follows:

  • make a clean separation between the Qt backend and the end-use API, clarifying the interface that a backend must implement in order to work with magicgui
  • create a "direct API" that enables procedural widget creation, with the potential for subclassing and custom widget creation
  • create a more direct link between an individual widget and an inspect.Parameter object, and a collection or layout of widgets and an inspect.Signature object.

See PR #43 for full details of the rewrite.

Deprecations and possible breaking changes!

Some of the API has been deprecated or changed, though an attempt was made to make the pre-0.2.0 API still work (with warnings). Please see the v0.2.0 migration guide for details.

Lastly, we have new documentation, using the amazing jupyter-book project! Note the new url at https://napari.org/magicgui

Implemented enhancements:

  • Provide more direct "autowidget generation" without requiring function body. #7

Fixed bugs:

  • call_button not responding #44
  • Removal of docks: are widgets singletons? #28

Closed issues:

  • Enable magicgui decorator on class member functions #53
  • Recognize widget types as strings #47
  • Recognize napari layer types as strings #46
  • Widget label editable #45
  • Add support for Annotated type #34
  • Pull signature parsing code from MagicGuiBase #33

Merged pull requests:

v0.1.6 (2020-07-23)

Full Changelog

v0.1.6rc0 (2020-07-23)

Full Changelog

Implemented enhancements:

  • Use eval'd text box as fallback when type inference fails #29

Closed issues:

  • conda recipe #21
  • Feature request: support for QFileDialog (file and directory choosers) #20
  • Unable to visualize QBoxlayout nor QTable #12

Merged pull requests:

v0.1.5 (2020-05-24)

Full Changelog

Fixed bugs:

  • Error running examples #6

Closed issues:

  • Automagically add labels per field #13

v0.1.4 (2020-05-19)

Full Changelog

Merged pull requests:

v0.1.3 (2020-05-04)

Full Changelog

Merged pull requests:

v0.1.2 (2020-03-06)

Full Changelog

Closed issues:

  • Register callbacks on return types #3

Merged pull requests:

v0.1.1 (2020-02-19)

Full Changelog

Merged pull requests:

v0.1.0 (2020-02-18)

Full Changelog

Merged pull requests:

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for magicgui, version 0.2.7
Filename, size File type Python version Upload date Hashes
Filename, size magicgui-0.2.7-py2.py3-none-any.whl (116.8 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size magicgui-0.2.7.tar.gz (20.8 MB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page