Skip to content

Commit 9e63458

Browse files
PierreRaybautPierreRaybaut
committed
API break: moved update_dataset/restore_dataset
1 parent 645353a commit 9e63458

29 files changed

+401
-388
lines changed

‎CHANGELOG.md‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,34 @@
22

33
## Version 3.1.0 ##
44

5-
New features:
5+
⚠ Exceptionnally, this release contains the following API breaking changes:
6+
7+
* Moved `utils.update_dataset` to `dataset.conv.update_dataset`
8+
* Moved `utils.restore_dataset` to `dataset.conv.restore_dataset`
9+
10+
✔ API simplification (backward compatible):
11+
12+
* Dataset items may now be imported from `guidata.dataset` instead of `guidata.dataset.dataitems`
13+
* Dataset types may now be imported from `guidata.dataset` instead of `guidata.dataset.datatypes`
14+
* Examples:
15+
* `from guidata.dataset.dataitems import FloatItem` becomes `from guidata.dataset import FloatItem`
16+
* `from guidata.dataset.datatypes import DataSet` becomes `from guidata.dataset import DataSet`
17+
* Or you may now write:
618

7-
* New `utils.conv.create_dataset_from_dict`: create a dataset from a dictionary,
19+
```python
20+
import guidata.dataset as gds
21+
22+
class MyParameters(gds.DataSet):
23+
"""My parameters"""
24+
freq = gds.FloatItem("Frequency", default=1.0, min=0.0, nonzero=True)
25+
amp = gds.FloatItem("Amplitude", default=1.0, min=0.0)
26+
```
27+
28+
💥 New features:
29+
30+
* New `dataset.create_dataset_from_dict`: create a dataset from a dictionary,
831
using keys and values to create the dataset items
9-
* New `utils.conv.create_dataset_from_func`: create a dataset from a function signature,
32+
* New `dataset.create_dataset_from_func`: create a dataset from a function signature,
1033
using type annotations and default values to create the dataset items
1134
* `dataset.dataitems.StringItem`:
1235
* Added argument `password` to hide text (useful for passwords)
@@ -17,12 +40,12 @@ New features:
1740
* `dataset.dataitems.DictItem`: added support for HDF5 and JSON serialization
1841
* `dataset.io.h5fmt` and `dataset.io.jsonfmt`: added support for lists and dictionnaries serialization
1942

20-
New PlotPyStack internal features:
43+
♻ New PlotPyStack internal features:
2144

2245
* `widgets.about`: handle about dialog box informations (Python, Qt, Qt bindings, ...)
2346
* Renamed development environment variable `GUIDATA_PYTHONEXE` to `PPSTACK_PYTHONEXE`
2447

25-
Bug fixes:
48+
🧹 Bug fixes:
2649

2750
* Fixed Qt6 compatibility issue with `QFontDatabase`
2851

‎doc/basic_example.py‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,18 @@
11
# -*- coding: utf-8 -*-
22

33
import guidata
4-
import guidata.dataset.dataitems as di
5-
import guidata.dataset.datatypes as dt
4+
import guidata.dataset as gds
65

76
# Note: the following line is not required if a QApplication has already been created
87
_app = guidata.qapplication()
98

109

11-
class Processing(dt.DataSet):
10+
class Processing(gds.DataSet):
1211
"""Example"""
1312

14-
a = di.FloatItem("Parameter #1", default=2.3)
15-
b = di.IntItem("Parameter #2", min=0, max=10, default=5)
16-
type = di.ChoiceItem("Processing algorithm", ("type 1", "type 2", "type 3"))
13+
a = gds.FloatItem("Parameter #1", default=2.3)
14+
b = gds.IntItem("Parameter #2", min=0, max=10, default=5)
15+
type = gds.ChoiceItem("Processing algorithm", ("type 1", "type 2", "type 3"))
1716

1817

1918
param = Processing()

‎doc/dev/v2_to_v3.csv‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ Version 2,Version 3
1515
``.encoding``,``.utils.encoding``
1616
``.encoding.transcode``,*removed*
1717
``.encoding.getfilesystemencoding``,*removed*
18+
``.utils.update_dataset``,``.dataset.update_dataset``
19+
``.utils.restore_dataset``,``.dataset.restore_dataset``
1820
``.utils.to_string``,``.utils.misc.to_string.misc``
1921
``.utils.decode_fs_string``,``.utils.misc.decode_fs_string.misc``
2022
``.utils.assert_interfaces_valid``,``.utils.misc.assert_interfaces_valid.misc``

‎doc/reference/dataset/conv.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. automodule:: guidata.dataset.conv

‎doc/reference/dataset/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,6 @@ Data set features
77

88
datatypes
99
dataitems
10+
conv
1011
io
1112
qtwidgets

‎doc/reference/utils.rst‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,6 @@ Utilities
33

44
.. automodule:: guidata.utils
55

6-
.. automodule:: guidata.utils.conv
7-
86
.. automodule:: guidata.utils.misc
97

108
.. automodule:: guidata.configtools

‎guidata/dataset/__init__.py‎

Lines changed: 51 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,54 @@
33
# Licensed under the terms of the BSD 3-Clause
44
# (see guidata/LICENSE for details)
55

6-
"""
7-
dataset
8-
=======
9-
10-
The ``guidata.dataset`` package provides the core features for data set
11-
display and editing with automatically generated graphical user interfaces.
12-
13-
.. automodule:: guidata.dataset.dataitems
14-
:members:
15-
16-
.. automodule:: guidata.dataset.datatypes
17-
:members:
18-
19-
.. automodule:: guidata.dataset.qtitemwidgets
20-
:members:
21-
22-
.. automodule:: guidata.dataset.qtwidgets
23-
:members:
24-
"""
6+
from .conv import (
7+
create_dataset_from_dict,
8+
create_dataset_from_func,
9+
restore_dataset,
10+
update_dataset,
11+
)
12+
from .dataitems import (
13+
BoolItem,
14+
ButtonItem,
15+
ChoiceItem,
16+
ColorItem,
17+
DateItem,
18+
DateTimeItem,
19+
DictItem,
20+
DirectoryItem,
21+
FileOpenItem,
22+
FileSaveItem,
23+
FilesOpenItem,
24+
FloatArrayItem,
25+
FloatItem,
26+
FontFamilyItem,
27+
ImageChoiceItem,
28+
IntItem,
29+
MultipleChoiceItem,
30+
StringItem,
31+
TextItem,
32+
)
33+
from .datatypes import (
34+
ActivableDataSet,
35+
BeginGroup,
36+
BeginTabGroup,
37+
DataItem,
38+
DataItemProxy,
39+
DataItemVariable,
40+
DataSet,
41+
DataSetGroup,
42+
DataSetMeta,
43+
EndGroup,
44+
EndTabGroup,
45+
FormatProp,
46+
FuncProp,
47+
GetAttrProp,
48+
GroupItem,
49+
ItemProperty,
50+
NoDefault,
51+
NotProp,
52+
Obj,
53+
ObjectItem,
54+
TabGroupItem,
55+
ValueProp,
56+
)

guidata/utils/conv.py renamed to guidata/dataset/conv.py

Lines changed: 87 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,104 @@
44
# (see guidata/LICENSE for details)
55

66
"""
7-
Conversion utilities
8-
--------------------
7+
DataSet class conversion/creation functions
8+
===========================================
9+
10+
Update and restore datasets
11+
---------------------------
12+
13+
.. autofunction:: guidata.dataset.update_dataset
14+
15+
.. autofunction:: guidata.dataset.restore_dataset
16+
17+
Create dataset classes
18+
----------------------
919
1020
.. autofunction:: guidata.dataset.create_dataset_from_func
21+
22+
.. autofunction:: guidata.dataset.create_dataset_from_dict
1123
"""
1224

1325
from __future__ import annotations
1426

1527
import inspect
16-
from typing import Any
28+
from typing import TYPE_CHECKING, Any
1729

1830
import guidata.dataset.dataitems as gdi
1931
import guidata.dataset.datatypes as gdt
2032

33+
if TYPE_CHECKING: # pragma: no cover
34+
import guidata.dataset.datatypes as gdt
35+
36+
# ==============================================================================
37+
# Updating, restoring datasets
38+
# ==============================================================================
39+
40+
41+
def update_dataset(
42+
dest: gdt.DataSet, source: Any | dict[str, Any], visible_only: bool = False
43+
) -> None:
44+
"""Update `dest` dataset items from `source` dataset.
45+
46+
Args:
47+
dest (DataSet): The destination dataset object to update.
48+
source (Union[Any, Dict[str, Any]]): The source object or dictionary containing
49+
matching attribute names.
50+
visible_only (bool): If True, update only visible items. Defaults
51+
to False.
52+
53+
For each DataSet item, the function will try to get the attribute
54+
of the same name from the source.
55+
56+
If the attribute exists in the source object or the key exists in the dictionary,
57+
it will be set as the corresponding attribute in the destination dataset.
58+
59+
Returns:
60+
None
61+
"""
62+
for item in dest._items:
63+
key = item._name
64+
if hasattr(source, key):
65+
try:
66+
hide = item.get_prop_value("display", source, "hide", False)
67+
except AttributeError:
68+
# FIXME: Remove this try...except
69+
hide = False
70+
if visible_only and hide:
71+
continue
72+
setattr(dest, key, getattr(source, key))
73+
elif isinstance(source, dict) and key in source:
74+
setattr(dest, key, source[key])
75+
76+
77+
def restore_dataset(source: gdt.DataSet, dest: Any | dict[str, Any]) -> None:
78+
"""Restore `dest` dataset items from `source` dataset.
79+
80+
Args:
81+
source (DataSet): The source dataset object to restore from.
82+
dest (Union[Any, Dict[str, Any]]): The destination object or dictionary.
83+
84+
This function is almost the same as `update_dataset` but requires
85+
the source to be a DataSet instead of the destination.
86+
87+
Symmetrically from `update_dataset`, `dest` may also be a dictionary.
88+
89+
Returns:
90+
None
91+
"""
92+
for item in source._items:
93+
key = item._name
94+
value = getattr(source, key)
95+
if hasattr(dest, key):
96+
try:
97+
setattr(dest, key, value)
98+
except AttributeError:
99+
# This attribute is a property, skipping this iteration
100+
continue
101+
elif isinstance(dest, dict):
102+
dest[key] = value
103+
104+
21105
# ==============================================================================
22106
# Generating a dataset class from a function signature
23107
# ==============================================================================

‎guidata/dataset/dataitems.py‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -10,84 +10,84 @@
1010
Base class
1111
^^^^^^^^^^
1212
13-
.. autoclass:: DataItem
13+
.. autoclass:: guidata.dataset.DataItem
1414
1515
Numeric items
1616
^^^^^^^^^^^^^
1717
18-
.. autoclass:: FloatItem
18+
.. autoclass:: guidata.dataset.FloatItem
1919
:members:
2020
21-
.. autoclass:: IntItem
21+
.. autoclass:: guidata.dataset.IntItem
2222
:members:
2323
24-
.. autoclass:: FloatArrayItem
24+
.. autoclass:: guidata.dataset.FloatArrayItem
2525
:members:
2626
2727
Text items
2828
^^^^^^^^^^
2929
30-
.. autoclass:: StringItem
30+
.. autoclass:: guidata.dataset.StringItem
3131
:members:
3232
33-
.. autoclass:: TextItem
33+
.. autoclass:: guidata.dataset.TextItem
3434
:members:
3535
3636
Date and time items
3737
^^^^^^^^^^^^^^^^^^^
3838
39-
.. autoclass:: DateItem
39+
.. autoclass:: guidata.dataset.DateItem
4040
:members:
4141
42-
.. autoclass:: DateTimeItem
42+
.. autoclass:: guidata.dataset.DateTimeItem
4343
:members:
4444
4545
Color items
4646
^^^^^^^^^^^
4747
48-
.. autoclass:: ColorItem
48+
.. autoclass:: guidata.dataset.ColorItem
4949
:members:
5050
5151
File items
5252
^^^^^^^^^^
5353
54-
.. autoclass:: FileSaveItem
54+
.. autoclass:: guidata.dataset.FileSaveItem
5555
:members:
5656
57-
.. autoclass:: FileOpenItem
57+
.. autoclass:: guidata.dataset.FileOpenItem
5858
:members:
5959
60-
.. autoclass:: FilesOpenItem
60+
.. autoclass:: guidata.dataset.FilesOpenItem
6161
:members:
6262
63-
.. autoclass:: DirectoryItem
63+
.. autoclass:: guidata.dataset.DirectoryItem
6464
:members:
6565
6666
Choice items
6767
^^^^^^^^^^^^
6868
69-
.. autoclass:: BoolItem
69+
.. autoclass:: guidata.dataset.BoolItem
7070
:members:
7171
72-
.. autoclass:: ChoiceItem
72+
.. autoclass:: guidata.dataset.ChoiceItem
7373
:members:
7474
75-
.. autoclass:: MultipleChoiceItem
75+
.. autoclass:: guidata.dataset.MultipleChoiceItem
7676
:members:
7777
78-
.. autoclass:: ImageChoiceItem
78+
.. autoclass:: guidata.dataset.ImageChoiceItem
7979
:members:
8080
8181
Other items
8282
^^^^^^^^^^^
8383
84-
.. autoclass:: ButtonItem
84+
.. autoclass:: guidata.dataset.ButtonItem
8585
:members:
8686
87-
.. autoclass:: DictItem
87+
.. autoclass:: guidata.dataset.DictItem
8888
:members:
8989
90-
.. autoclass:: FontFamilyItem
90+
.. autoclass:: guidata.dataset.FontFamilyItem
9191
:members:
9292
"""
9393

0 commit comments

Comments
 (0)