Merge pull request #37 from davidhozic/develop

* Update readthedocs-sphinx-search requirement in /requirements (#33)

Updates the requirements on [readthedocs-sphinx-search](https://github.com/readthedocs/readthedocs-sphinx-search) to permit the latest version.
- [Changelog](https://github.com/readthedocs/readthedocs-sphinx-search/blob/main/CHANGELOG.rst)
- [Commits](readthedocs/readthedocs-sphinx-search@0.3.2...0.3.2)

---
updated-dependencies:
- dependency-name: readthedocs-sphinx-search
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* 1.3.1

* feat: Literal and enum list definition (#34)

* Iterable literal and singleton definition

* docs

* Deprecated parameters support (#35)

* Deprecated parameters

* Better deprecations

* Docs

* Flag definition (#36)

---------

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

Author: davidhozic

docs/source/changelog.rst

@@ -28,6 +28,18 @@ v1.3.1
 - Fixed :func:`tkclasswiz.convert.convert_objects_to_script` not including enum imports.
 
 
+v1.4.0
+================
+- Definition of enums and literal values inside iterable types.
+- Ability to register deprecated parameters.
+- Ability to define :class:`enum.Flag` like flags.
+
+
+v1.3.1
+================
+- Fixed :func:`tkclasswiz.convert.convert_objects_to_script` not including enum imports.
+
+
 v1.3.0
 ================
 - The types will now have their subscripted type displayed alongside them.

docs/source/guide/defining.rst

@@ -172,6 +172,48 @@ This is how our frame looks after defining 4 ``Wheel`` objects:
   :width: 15cm
 
 
+Defining (enum) flags
+=======================
+Let's say that our car also needs a type designation. The ``Car`` class may contain an enum flag parameter,
+indicating this designation.
+
+.. code-block:: python
+
+  from enum import Flag, auto
+
+  class Designation(Flag):
+      FAMILIY = auto()
+      SINGLE_PERSON = auto()
+      HEAVY_TRANSPORT = auto()
+
+    class Car:
+        def __init__(
+            self,
+            ...
+            designation: Designation,
+        ):
+            ...
+
+When we try to define the ``designation`` parameter from the above example,
+the following window will be displayed.
+
+.. image:: ./images/new_define_frame_flag.png
+  :width: 15cm
+
+The flag definition frame has 4 main elements:
+
+- a placeholder for the current value,
+- a Combobox (dropdown menu) for selecting a flag
+- an add button for adding the selected (in Combobox) flag to the current flag value.
+- a remove button for removing the selected (in Combobox) flag from the current flag value.
+
+The following image shows show two added flags look inside the placeholder.
+
+.. image:: ./images/new_define_frame_flag_values.png
+  :width: 15cm
+
+The flag value can be saved like any other type. It is done by clicking on the "Save" button.
+
 Final definition
 =================
 

docs/source/guide/deprecations.rst

@@ -0,0 +1,34 @@
+========================
+Deprecations
+========================
+
+TkClassWizard allows users to deprecate different classes, class's parameters and types under a class's parameter.
+
+All the deprecations can be made with the :func:`tkclasswiz.deprecation.register_deprecated` function.
+The function has 3 modes:
+
+- Deprecate class globally (only ``cls`` parameter given)
+- Deprecate a class's parameter (``cls`` and ``parameter`` both given)
+- Deprecate a type under class's parameter (``cls``, ``parameter`` and ``types`` are all given).
+  Please note that ``types`` is a variadic parameter, which means multiple types can be passed by
+  just separating them with a comma.
+
+
+.. code-block:: python
+    :caption: Deprecate usage of type :class:`~datetime.timedelta` under parameter ``next_service`` of class ``Car``.
+
+    from datetime import timedelta, datetime
+    import tkclasswiz as wiz
+
+    class Car:
+        def __init__(self, name: str, next_service: timedelta | datetime):
+            ...  # Implementation
+
+    wiz.register_deprecated(Car, "next_service", timedelta)
+    ...  # Other needed code
+
+
+The above example will create the following definition window:
+
+.. image:: ./images/new_define_frame_struct_deprecation.png
+

docs/source/guide/images/new_define_frame_flag.png

@@ -18,3 +18,4 @@ Index:
     customrepr
     aliasing
     generics
+    deprecations

docs/source/guide/images/new_define_frame_flag_values.png

@@ -98,7 +98,7 @@
                         if manual:
                             _async_ = ":async:" if inspect.iscoroutinefunction(item) else ""
                             annotations = get_type_hints(item)
-                            return_ano = annotations.pop("return")
+                            return_ano = annotations.pop("return", None)
                             doc_str = inspect.cleandoc(item.__doc__)
                             # Replace titles with list titles
                             doc_str_titles = re.findall(r"[A-z]+\n-+", doc_str)

docs/source/guide/images/new_define_frame_struct_deprecation.png

@@ -4,5 +4,5 @@ sphinx-copybutton~=0.5.2
 furo==2023.9.10
 enum-tools[sphinx]~=0.11.0
 sphinx-design[furo]~=0.5.0
-readthedocs-sphinx-search~=0.3.1
+readthedocs-sphinx-search~=0.3.2
 sphinxcontrib-svg2pdfconverter~=1.2.2

docs/source/guide/index.rst

@@ -26,7 +26,9 @@
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 """
-__version__ = "1.3.1"
+
+__version__ = "1.4.0"
+
 
 from .object_frame import *
 from .annotations import *
@@ -37,3 +39,4 @@
 from .storage import *
 from .utilities import *
 from .aliasing import *
+from .deprecation import *