basic aliasing (#16)

davidhozic · web-flow · commit 6153da97e747 · 2024-01-09T16:37:54.000+01:00
* basic aliasing

* formatting

* Documentation

* fix

* Fix docs

* fix

* Bumpy python
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -12,7 +12,7 @@ build:
   apt_packages:
     - inkscape
   tools:
-    python: "3.8"
+    python: "3.9"
   jobs:
     pre_build:
       - pip install .[docs]
diff --git a/README.rst b/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
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -27,6 +27,8 @@ Releases
 v1.2
 ================
 - Generic types support (Parametric types)
+- :ref:`Type aliasing`
+- |BREAK_CH| Minimal Python version bumped to Python 3.9
 
 v1.1.1
 ================
diff --git a/docs/source/conf.py b/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
diff --git a/docs/source/guide/aliasing.rst b/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.
diff --git a/docs/source/guide/defining.rst b/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)
 =======================================
 
diff --git a/docs/source/guide/images/new_define_frame_struct_alias_new_timedelta.png b/docs/source/guide/images/new_define_frame_struct_alias_new_timedelta.png
diff --git a/docs/source/guide/images/type_alias_one_frame_param.png b/docs/source/guide/images/type_alias_one_frame_param.png
diff --git a/docs/source/guide/index.rst b/docs/source/guide/index.rst
@@ -15,4 +15,5 @@ Index:
     conversion
     polymorphism
     abstractclasses
-    generics
+    aliasing
+    generics
diff --git a/pyproject.toml b/pyproject.toml
@@ -13,7 +13,7 @@ authors = [
 ]
 description = "Library for graphically defining objects based on class annotations. Works with Tkinter / TTKBootstrap"
 readme = "README.rst"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 keywords = ["Tkinter", "TTKBootstrap", "Python3", "ObjectDef", "ClassWiz", "ClassWiz", "GUI"]
 classifiers = [
     "Programming Language :: Python :: 3",
diff --git a/requirements/docs.txt b/requirements/docs.txt
@@ -1,8 +1,8 @@
-sphinx==7.1.2
+sphinx~=7.2.0
 sphinx-autobuild==2021.3.14
-sphinx-copybutton==0.5.2
+sphinx-copybutton~=0.5.0
 furo==2023.9.10
-enum-tools[sphinx]==0.11.0
-sphinx-design[furo]==0.5.0
-readthedocs-sphinx-search==0.3.1
-sphinxcontrib-svg2pdfconverter==1.2.2
+enum-tools[sphinx]~=0.11.0
+sphinx-design[furo]~=0.5.0
+readthedocs-sphinx-search~=0.3.0
+sphinxcontrib-svg2pdfconverter~=1.2.0
diff --git a/tkclasswiz/__init__.py b/tkclasswiz/__init__.py
@@ -13,3 +13,4 @@
 from .messagebox import *
 from .storage import *
 from .utilities import *
+from .aliasing import *
diff --git a/tkclasswiz/aliasing.py b/tkclasswiz/aliasing.py
@@ -0,0 +1,54 @@
+"""
+Module contains functionality for managing type aliases.
+Type alias is an alternative type name.
+
+E. g., we could have an alias for timedelta -> Duration.
+"""
+from typing import Dict, Optional
+from .doc import doc_category
+
+
+__all__ = (
+    "register_alias",
+    "get_aliased_name",
+)
+
+
+ALIASES: Dict[type, str] = {}
+
+
+@doc_category("Aliasing")
+def register_alias(cls: type, alias: str):
+    """
+    Creates an alias name for type ``cls``.
+    Aliases will then be displayed in place of original name in:
+
+    - Object definition "New" menu
+    - Container values (e. g., inside Combobox)
+
+    Parameters
+    ------------
+    cls: type
+        The class (or function or type) to register an alias for.
+    alias: str
+        The alias.
+
+    Example
+    -----------
+    
+    .. code-block:: python
+
+        from datetime import timedelta
+
+        register_alias(timedelta, "Duration")
+    """
+    ALIASES[cls] = alias
+
+
+@doc_category("Aliasing")
+def get_aliased_name(class_) -> Optional[str]:
+    """
+    Returns the ``class_``'s aliased name. If class has no alias name,
+    ``None`` is returned.
+    """
+    return ALIASES.get(class_)
diff --git a/tkclasswiz/convert.py b/tkclasswiz/convert.py
@@ -11,6 +11,7 @@
 from .extensions import extendable
 from .cache import cache_result
 from .annotations import *
+from .aliasing import *
 from .doc import doc_category
 
 import datetime as dt
@@ -152,7 +153,13 @@ def __repr__(self) -> str:
         if self.__repr is not None:
             return self.__repr
 
-        _ret: str = self.class_.__name__ + "("
+        name = get_aliased_name(self.class_)
+        if name is not None:
+            name += f'({self.class_.__name__})'
+        else:
+            name = self.class_.__name__
+
+        _ret: str =  name + "("
         private_params = set()
         if hasattr(self.class_, "__passwords__"):
             private_params = private_params.union(self.class_.__passwords__)
diff --git a/tkclasswiz/object_frame/frame_base.py b/tkclasswiz/object_frame/frame_base.py
@@ -4,6 +4,7 @@
 from contextlib import suppress
 
 from ..convert import *
+from ..aliasing import *
 from ..dpi import *
 from ..utilities import *
 from ..storage import *
@@ -92,6 +93,19 @@ def __init__(
 
     @staticmethod
     def get_cls_name(cls: T) -> Union[str, T]:
+        """
+        Returns the name of the class ``cls`` or
+        the original class when the name cannot be obtained.
+        If alias exists, alias is returned instead.
+        """
+        name = NewObjectFrameBase._get_cls_unaliased_name(cls)
+        if (alias := get_aliased_name(cls)) is not None:
+            return alias + f" ({name})"
+        
+        return name
+
+    @staticmethod
+    def _get_cls_unaliased_name(cls: T) -> Union[str, T]:
         """
         Returns the name of the class ``cls`` or
         the original class when the name cannot be obtained.
@@ -100,8 +114,8 @@ def get_cls_name(cls: T) -> Union[str, T]:
             return cls.__name__
         if hasattr(cls, "_name"):
             return cls._name
-        else:
-            return cls
+
+        return cls
 
     @classmethod
     def set_origin_window(cls, window: "ObjectEditWindow"):
@@ -129,7 +143,7 @@ def cast_type(cls, value: Any, types: Iterable):
             
             return value
 
-        for type_ in filter(lambda t: cls.get_cls_name(t) in __builtins__, types):
+        for type_ in filter(lambda t: cls._get_cls_unaliased_name(t) in __builtins__, types):
             with suppress(Exception):
                 cast_funct = CAST_FUNTIONS.get(type_)
                 if cast_funct is None:

Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@ authors = [`
`13`	`13`	`]`
`14`	`14`	`description = "Library for graphically defining objects based on class annotations. Works with Tkinter / TTKBootstrap"`
`15`	`15`	`readme = "README.rst"`
`16`		`-requires-python = ">=3.8"`
	`16`	`+requires-python = ">=3.9"`
`17`	`17`	`keywords = ["Tkinter", "TTKBootstrap", "Python3", "ObjectDef", "ClassWiz", "ClassWiz", "GUI"]`
`18`	`18`	`classifiers = [`
`19`	`19`	`"Programming Language :: Python :: 3",`