Merge pull request #19 from davidhozic/develop

Develop

Author: davidhozic

.readthedocs.yml

@@ -12,7 +12,7 @@ build:
   apt_packages:
     - inkscape
   tools:
-    python: "3.8"
+    python: "3.9"
   jobs:
     pre_build:
       - pip install .[docs]

README.rst

@@ -17,7 +17,7 @@ Installation
 ----------------------
 TkClassWizard can be installed though command prompt/terminal using the bottom commands.
 
-Pre-requirement: `Python (minimum v3.8) <https://www.python.org/downloads/>`_
+Pre-requirement: `Python (minimum v3.9) <https://www.python.org/downloads/>`_
 
 
 .. code-block:: bash

docs/source/changelog.rst

@@ -24,6 +24,15 @@ Glossary
 Releases
 ---------------------
 
+v1.2.0
+================
+- Added the ability of nicknaming structured objects.
+- Generic types support (Parametric types)
+- :ref:`Type aliasing`
+- Object nicknaming
+- Tooltip when hovering over fields, which shows the full value.
+- |BREAK_CH| Minimal Python version bumped to Python 3.9
+
 
 v1.1.1
 ================

docs/source/conf.py

@@ -29,8 +29,6 @@
 
 
 # -- General configuration ---------------------------------------------------
-root_doc = 'index'
-
 numfig = True
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -80,7 +78,7 @@
 
 # Intersphinx
 intersphinx_mapping = {
-    "Python" : ("https://docs.python.org/3/", None)
+    "python" : ("https://docs.python.org/3/", None)
 }
 
 # ----------- HTML ----------- #

docs/source/guide/aliasing.rst

@@ -0,0 +1,34 @@
+========================
+Type aliasing
+========================
+
+TkClassWizard allows types to be aliased.
+Alias is an alternative name or nickname for a specific type.
+
+Type aliasing can be done within the :func:`tkclasswiz.aliasing.register_alias` function.
+An alias can be obtained through :func:`tkclasswiz.aliasing.get_aliased_name` function.
+
+For example, we can give the :class:`~datetime.timedelta` type an alternative name:
+
+.. code-block:: python
+
+    from datetime import timedelta
+    import tkclasswiz as wiz
+
+    wiz.register_alias(timedelta, "Duration")
+
+
+If we define a type alias like in the above example, then the timedelta class will look like shown in the following 2 images:
+
+
+.. figure:: ./images/type_alias_one_frame_param.png
+    :width: 15cm
+
+    :class:`~datetime.timedelta` type alias display after definition of parameters.
+
+|
+
+.. figure:: ./images/new_define_frame_struct_alias_new_timedelta.png
+    :width: 15cm
+
+    :class:`~datetime.timedelta` type alias display inside the New object menu.

docs/source/guide/defining.rst

@@ -9,7 +9,6 @@ This is how our example from the previous page looks inside a GUI:
     :width: 15cm
 
 
-
 Defining structured data (objects)
 =======================================
 
@@ -45,7 +44,22 @@ load them from a JSON file back into the GUI.
     For verification purposes, the JSON file contains the full path to the defining class.
     Changing the class path requires users to update the corresponding path within the JSON files as well.
 
-Going down further we can see multiple rows, each one of the corresponding to a parameter.
+Below the "Template" button, an entry labeled "Object nickname" is located.
+This entry can be used to give an object a nickname.
+The nickname will be displayed before the class's name,
+allowing the object to be easily recognized at a glance.
+
+.. image:: ./images/new_define_frame_struct_nickname.png
+  :width: 15cm
+
+This is how the object will look inside a Combobox, if it is given the name "David's car"
+(notice the parentheses at the beginning):
+
+.. image:: ./images/example_gui_view_defined_nickname_car.png
+  :width: 15cm
+
+
+Going down further we can see multiple rows, each one of them corresponding to a parameter.
 
 .. image:: ./images/new_define_frame_struct_parameters.png
     :width: 15cm
@@ -56,7 +70,32 @@ The next item on the right is a Combobox (:class:`~tkclasswiz.storage.ComboBoxOb
 which is a dropdown menu used for storing the value of each defined parameter.
 This dropdown menu can contain multiple values while we are still editing,
 which we can access through the down arrow-like symbol located on the rightmost side of the Combobox.
-When the definition frame is closed all the other values that were not selected inside the Combobox get discarded.
+When the definition frame is closed, all the other (not selected) values get discarded.
+
+
+.. note::
+
+  While the dropdown menu (Combobox) can contains values manually defined through the GUI,
+  it will sometimes have some predefined values. These values can be:
+
+  - None: Parameter was annotated with :class:`typing.Optional` (``Optional[<type>]``) or
+    with :class:`typing.Union` (``Union[None, ...]``)
+  - ``True`` and ``False``: Parameter is a boolean parameter
+  - Literal string values: Parameter is a literal string, meaning it is annotated with
+    :class:`typing.Literal`. E. g, ``Literal['value1', 'value2', ...]`` annotation will produce the values 'value1' and
+    'value2' inside the Combobox.
+
+
+    .. code-block:: python
+
+      class Person:
+        def __init__(self, name: str, job_type: Literal["Science", "Technology", "Engineering", "Math"]):
+            ...
+
+    .. image:: ./images/new_define_frame_struct_literal_values.png
+      :width: 15cm
+
+
 The dropdown menu is followed by 3 buttons:
 
 - "New": is a dropdown menu button, which allows to define multiple data types that the parameter accepts. It can

docs/source/guide/generics.rst

@@ -0,0 +1,78 @@
+=========================
+Generic types (classes)
+=========================
+
+A generic type in Python is a class, that inherits the :class:`typing.Generic` class.
+It can be used to define arbitrary type parameters, which can be given a value using a subscription operator ``[]``.
+
+Arbitrary types / type variables can be created using the :class:`typing.TypeVar` class.
+
+.. note::
+    
+    Since Python 3.12, the :class:`typing.TypeVar` no longer requires manual definition
+    and can be omitted.
+
+
+.. code-block:: python
+    :linenos:
+
+    from typing import Generic, TypeVar
+
+
+    T = TypeVar('T')  # From Python 3.12 forward this is optional
+
+    class MyClass(Generic[T]):
+        def __init__(self, a: int, b: T):
+            ...
+
+
+    my_instance1: MyClass[float] = MyClass(5, 5.5)
+    my_instance2: MyClass[str] = MyClass(5, "Some text")
+    my_instance3: MyClass[int] = MyClass(5, 0)
+
+
+In the above example, the ``T`` is a type variable. It is also a type parameter inside ``MyClass``.
+When instances are created, the variables are annotated with a type subscription (e. g., ``MyClass[int]``).
+
+While Python itself doesn't care about the types given in the subscription, and just ignores incorrect types,
+TkClassWizard resolves these subscripted types into the ``__init__`` function of a class, allowing the definition
+of arbitrary types with the use of type generics.
+
+If we take the above example and pop it into TkClassWizard with ``MyClass`` having a :class:`float` annotation,
+we would get the following types in the ``New <type>`` options:
+
+.. image:: ./images/new_define_frame_struct_generics.png
+    :width: 15cm
+
+
+.. code-block:: python
+    :caption: Generic type, given :class:`float` as type parameter
+    :linenos:
+    :emphasize-lines: 21
+
+    from typing import Generic, TypeVar
+
+    import tkclasswiz as wiz
+    import tkinter as tk
+    import tkinter.ttk as ttk
+
+    T = TypeVar('T')  # From Python 3.12 forward this is optional
+
+    class MyClass(Generic[T]):
+        def __init__(self, a: int, b: T):
+            ...
+
+    root = tk.Tk("Test")
+
+    combo = wiz.ComboBoxObjects(root)
+    combo.pack(fill=tk.X, padx=5)
+
+    def open():
+        window = wiz.ObjectEditWindow()  # The object definition window / wizard
+        window.open_object_edit_frame(
+            MyClass[float],
+            combo
+        )  # Open the actual frame
+
+    ttk.Button(text="Define", command=open).pack()
+    root.mainloop()