feature: add UiField as the new intermediate object representing widget parameters

[tlambert03]

see #474 for the complete context and motivation for this PR

UiField will be the thing that all type annotations are coerced to prior to widget generation (think of it as a UI-focused variant of dataclasses.field).

this is an alternative to #446 ... it is less "heavy" in that it doesn't bring in the pydantic dependency, instead, aiming to support pydantic, attrs, dataclasses, named tuples, etc...

All of these are a set of name: annotation = 'defaut_value' .... which can be reduced to a "model" that is a collection of field objects. This PR adds that field object, and adds some tests that begin to demonstrate intended usage.

everything is private still, so this will be just one of a number of PRs moving in this direction

[tlambert03]

just some notes for myself about the mapping between any current widget parameter names and corresponding fields in UiField (if applicable):

# these params directly map to the UiField names
{
    "name",
    "visible",
    "nullable",
    "orientation",
}

# aliases
{
    "annotation": "type",
    "choices": "enum",  # CategoricalWidget
    "enabled": "NOT disabled",
    "label": "title",
    "max": "maximum",
    "min": "minimum",
    "start": "minimum",  # "RangeEdit",
    "step": "multiple_of",  # "RangedWidget" ... complicated, not true for RangeEdit
    "stop": "exclusive_maximum",  # "RangeEdit",
    "text": "title", # ButtonWidgets have "text"... confusing
    "tooltip": "description",
    # 'value': 'default',
}

# no correlate:
{
    "gui_only": "RadioButtons",
    "parent": "RadioButtons",
    "backend_kwargs": "RadioButtons",
    # used for options of child widgets ... but they should be done with annotations?
    "options": "ListEdit",
    "min_pos": "TransformedRangedWidget",
    "max_pos": "TransformedRangedWidget",
    "bind": "RadioButtons",
    "base": "LogSlider",
    "tracking": "SliderWidget",
    "readout": "SliderWidget",  # toggles editable spinbox visibility.
    # allow_multiple is used to induce a Select widget...
    # but it is most like an array type with items:
    # {
    # "type": "array",
    # "items": {
    #     "type": "string",
    #     "enum": [ "foo", "bar", "baz" ]
    # },
    # "uniqueItems": true,
    # "minItems": 1
    # }
    # DEPRECATE
    "allow_multiple": "CategoricalWidget",
    "mode": "FileEdit",
    "filter": "FileEdit",  # most like 'pattern'??
}
# Table stuff (don't map these... can be done directly with value)
{
    "index": "Table",
    "columns": "Table",
}
# container stuff
{
    "app": "FunctionGui",
    "auto_call": "FunctionGui",
    "result_widget": "FunctionGui",
    "param_options": "FunctionGui",
    "persist": "FunctionGui",
    "raise_on_unknown": "FunctionGui",
    "layout": "Container",
    "scrollable": "Container",
    "widgets": "Container",
    "labels": "Container",
    "function": "MainFunctionGui",
    "call_button": "FunctionGui",
    "tooltips": "FunctionGui",
}

[codecov]

Codecov Report

Merging #475 (e4d44c7) into main (45e053c) will increase coverage by 0.41%.
The diff coverage is 97.22%.

@@            Coverage Diff             @@
##             main     #475      +/-   ##
==========================================
+ Coverage   89.56%   89.98%   +0.41%     
==========================================
  Files          31       32       +1     
  Lines        3987     4212     +225     
==========================================
+ Hits         3571     3790     +219     
- Misses        416      422       +6     

Impacted Files	Coverage Δ
magicgui/_schema.py	96.86% <96.86%> (ø)
magicgui/_type_resolution.py	93.33% <100.00%> (+0.11%)	⬆️
magicgui/types.py	93.93% <100.00%> (+0.18%)	⬆️
magicgui/widgets/_bases/container_widget.py	91.86% <100.00%> (+0.45%)	⬆️
magicgui/widgets/_concrete.py	87.59% <100.00%> (+0.14%)	⬆️
magicgui/widgets/_function_gui.py	93.69% <100.00%> (-0.25%)	⬇️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[codecov]

Codecov Report

Base: 89.56% // Head: 89.98% // Increases project coverage by +0.41% 🎉

Coverage data is based on head (b3a6c39) compared to base (1a618e2).
Patch coverage: 97.24% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #475      +/-   ##
==========================================
+ Coverage   89.56%   89.98%   +0.41%     
==========================================
  Files          31       32       +1     
  Lines        3987     4214     +227     
==========================================
+ Hits         3571     3792     +221     
- Misses        416      422       +6     

Impacted Files	Coverage Δ
magicgui/_ui_field.py	96.88% <96.88%> (ø)
magicgui/_type_resolution.py	93.33% <100.00%> (+0.11%)	⬆️
magicgui/types.py	93.93% <100.00%> (+0.18%)	⬆️
magicgui/widgets/_bases/container_widget.py	91.86% <100.00%> (+0.45%)	⬆️
magicgui/widgets/_concrete.py	87.59% <100.00%> (+0.14%)	⬆️
magicgui/widgets/_function_gui.py	93.69% <100.00%> (-0.25%)	⬇️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.