fix: final corrections and clean-up before publication

final alignment with cookiecutter-template the-hatchlor-enhanced, fix/complete type annotations and docstrings, include test_dummy.py

Author: dornech

changelog_commitizen-template.md.j2

@@ -1,16 +1,15 @@
 {% if not incremental %}
 # CHANGELOG
-
-
 {% endif %}
-{#  MACRO: Capitalize the first letter of a string only #}
-{%  macro capitalize_first_letter_only(sentence) %}
+{# Macro: Capitalize the first letter of a string only #}
+{% macro capitalize_first_letter_only(sentence) %}
 {{    (sentence[0] | upper) ~ sentence[1:] }}
-{%  endmacro %}
+{% endmacro %}
 
 {% for entry in tree %}
 
-## [{{ entry.version }}](https://github.com/dornech/pytestdornech/releases/tag/{{ entry.version }}) {% if entry.date %}({{ entry.date }}){% endif %}
+
+## [{{ entry.version }}](https://github.com/dornech/utils-COMobjects/releases/tag/{{ entry.version }}) {% if entry.date %} ({{ entry.date }}) {% endif %}
 
 {% for change_type, changes in entry.changes.items() %}
 
@@ -19,11 +18,10 @@
 {% endif %}
 {% for change in changes %}
 {% if change.scope %}
-- **{{ change.scope }}**: {{ capitalize_first_letter_only(change.message) }} (['{{ change.sha1[:7] }}'](https://github.com/dornech/pytestdornech/commit/{{ change.sha1 }}))
+- **{{ change.scope }}**: {{ capitalize_first_letter_only(change.message) }} (['{{ change.sha1[:7] }}'](https://github.com/dornech/utils-COMobjects/commit/{{ change.sha1 }}))
 {% elif change.message %}
-- {{ capitalize_first_letter_only(change.message) }}(['{{ change.sha1[:7] }}'](https://github.com/dornech/pytestdornech/commit/{{ change.sha1 }}))
+- {{ capitalize_first_letter_only(change.message) }}(['{{ change.sha1[:7] }}'](https://github.com/dornech/utils-COMobjects/commit/{{ change.sha1 }}))
 {% endif %}
-
 {% endfor %}
 {% endfor %}
 {% endfor %}

docs/index.md

@@ -227,6 +227,7 @@ if __name__ == "__main__":
     UtilsCOMobjects.UtilsCOMcheckreg.processCOMregistration(PyCOMtest_typelibClass2, gentypelib=True, testmode=True)
     UtilsCOMobjects.UtilsCOMcheckreg.processCOMregistration(PyCOMtest_typelibClass3, gentypelib=True, testmode=True)
 ```
+
 ## Navigation
 
 Documentation for specific `MAJOR.MINOR` versions can be chosen by using the dropdown on the top of every page.

src/utils_COMobjects/utils_COM_checkreg.py

@@ -56,8 +56,13 @@ class ErrorCOMregistration(Exception):
 # check COM registration readiness
 
 
-# get filename of module
-def getmodulefile():
+def getmodulefile() -> str:
+    """
+    getmodulefile - get filename of module
+
+    Returns:
+        str: filename of calling module
+    """
 
     if sys.argv[0] != "-c":
         script = sys.argv[0]
@@ -67,18 +72,37 @@ def getmodulefile():
     return os.path.basename(script).split(".")[0]
     # return pathlib.Path(script).name.split(".")[0]
 
-# check valid uuid
-# alternative: use is_uuid from validator-collection
 def is_valid_uuid(uuid_to_test: str, version=4) -> bool:
+    """
+    is_valid_uuid - check uuid is valid
+
+    alternative: use is_uuid from validator-collection
+
+    Args:
+        uuid_to_test (str): UUID to test.
+        version (int): UUID-verison. Default is 4.
+
+    Returns:
+        bool: uuid is valid or not
+    """
 
     try:
         uuid_obj = UUID(uuid_to_test, version=version)
     except ValueError:
         return False
-    return (str(uuid_obj).upper() == uuid_to_test.upper()) or (str(uuid_obj).upper() == uuid_to_test[1:-1].upper())  # type: ignore[no-any-return]
+    return (str(uuid_obj).upper() == uuid_to_test.upper()) or (str(uuid_obj).upper() == uuid_to_test[1:-1].upper())
 
-# check registry key
 def checkRegKey(regroot: int, regpath: str) -> bool:
+    """
+    checkRegKey - check registry key
+
+    Args:
+        regroot (int): registry root
+        regpath (str): registry path to check
+
+    Returns:
+        bool: chec k result if registry path exists under root (or not)
+    """
 
     try:
         with winreg.OpenKey(regroot, regpath) as regkey:
@@ -87,13 +111,24 @@ def checkRegKey(regroot: int, regpath: str) -> bool:
     except OSError:
         return False
 
-# check single COM registration attribute
 def checkCOMattrib(
     cls: type[COMclass.baseCOMclass],
     attrib: str,
     checkfunction: Union[Callable, None] = None,
     optional: bool = False
 ) -> bool:
+    """
+    checkCOMattrib - check single COM class registration attribute
+
+    Args:
+        cls (COMclass.baseCOMclass): class to be checked
+        attrib (str): attribute to be checked
+        checkfunction (Callable): specific check function
+        optional (bool): positive check result optional (i. e. if True only message is generated)
+
+    Returns:
+        bool: check result
+    """
 
     if hasattr(cls, attrib):
         attribvalue = getattr(cls, attrib)
@@ -114,7 +149,6 @@ def checkCOMattrib(
         return False or optional
 
 
-# check COM registration readiness - basic COM object attributes
 def checkAttribsCOM(cls: type[COMclass.baseCOMclass], checkpubattrib: bool = False) -> bool:
     """
     checkAttribsCOM - check COM registration readiness, basic COM object attributes
@@ -213,8 +247,6 @@ def check_attribs_COM(cls: type[COMclass.baseCOMclass], checkpubattrib: bool = F
     return checkAttribsCOM(cls, checkpubattrib)
 
 
-
-# check COM registration readiness - Typelib registration readiness;
 def checkAttribsTypeLib(
     cls: Union[type[COMclass.baseCOMclass], type[COMclass.typelibCOMclass]],
     clsmodule: Optional[types.ModuleType] = None
@@ -380,15 +412,14 @@ def check_attribs_typelib(
     return checkAttribsTypeLib(cls, clsmodule)
 
 
-
-# COM registration caller
-# to register class add following call in object module
-# if __name__ == '__main__':
-#    <import name of this module>.processCOMregistration(<classname>)
-def processCOMregistration(cls: type[COMclass.baseCOMclass], gentypelib: bool = False, testmode: bool = False):
+def processCOMregistration(cls: type[COMclass.baseCOMclass], gentypelib: bool = False, testmode: bool = False) -> None:
     """
     processCOMregistration - check and register Python COM object class as COM object
 
+    To register class add following call in object module:
+    if __name__ == '__main__':
+        <import name of this module>.processCOMregistration(<classname>)
+
     Args:
         cls (type[COMclass.baseCOMclass]): Python COM object class to be registered
         gentypelib (bool, optional): activate typelib generation. Defaults to False.
@@ -478,8 +509,7 @@ def checkRegistryTypelibID(tlbid):
         errorhandling(f"COM registration requested for instance not object class. Try registration for {cls.__class__.__name__}.", testmode)
     print()
 
-
-def process_COM_registration(cls: type[COMclass.baseCOMclass], gentypelib: bool = False, testmode: bool = False):
+def process_COM_registration(cls: type[COMclass.baseCOMclass], gentypelib: bool = False, testmode: bool = False) -> None:
     """
     process_COM_registration - check and register Python COM object class as COM object
 
@@ -491,9 +521,7 @@ def process_COM_registration(cls: type[COMclass.baseCOMclass], gentypelib: bool
     processCOMregistration(cls, gentypelib, testmode)
 
 
-
-# COM object - list of public methods
-def printCOMpublicmethods(cls: Union[COMclass.baseCOMclass, COMclass.typelibCOMclass, Any]):
+def printCOMpublicmethods(cls: Union[COMclass.baseCOMclass, COMclass.typelibCOMclass, Any]) -> None:
     """
     printCOMpublicmethods - print public methods of Python COM object class
 
@@ -510,7 +538,7 @@ def printCOMpublicmethods(cls: Union[COMclass.baseCOMclass, COMclass.typelibCOMc
                     print(f"    Signature: {inspect.signature(member[1])}")
                     print(f"    {inspect.getfullargspec(member[1])}")
 
-def print_COM_publicmethods(cls: Union[COMclass.baseCOMclass, COMclass.typelibCOMclass, object]):
+def print_COM_publicmethods(cls: Union[COMclass.baseCOMclass, COMclass.typelibCOMclass, object]) -> None:
     """
     print_COM_publicmethods - print public methods of Python COM object class
 

src/utils_COMobjects/utils_COM_classes.py

@@ -56,12 +56,9 @@
 
 import winreg
 import pythoncom
-# import win32com.server.register
-# from win32com.server.exception import COMException
 
 
 
-# base class without typelib for DesignatedWrapPolicy or EventHandlerPolicy based hereupon
 class baseCOMclass(ABC):
     """
     baseCOMclass - abstract base class for COM objects in Python
@@ -171,7 +168,6 @@ def _checkDebug(cls) -> bool:
     # https://pythonhosted.org/comtypes/server.html
 
 
-# base class with typelib
 class typelibCOMclass(baseCOMclass):
     """
     typelibCOMclass - abstract base class for COM objects with typelib in Python

src/utils_COMobjects/utils_COM_logging.py

@@ -50,7 +50,6 @@
 
 
 
-# mixin class for logging
 class mixinCOMclass_logger:
     """
     mixin class for logging

src/utils_COMobjects/utils_COM_typelib.py

@@ -70,16 +70,16 @@
 
 
 
-# typelib generation -  typelib per class or common typelib for all classes in py-file with same typelib assignment
-def generateIDL(cls, clsmodule: types.ModuleType) -> bool:
+# typelib generation - typelib per class or common typelib for all classes in py-file with same typelib assignment
+def generateIDL(cls, clsmodule: types.ModuleType) -> bool:  # docsig: disable=SIG101
 
-    def setinterface(classname, cominterfaces: list[str]) -> str:
+    def setinterface(classname, cominterfaces: list[str]) -> str:  # docsig: disable=SIG101
         if len(cominterfaces) == 0:
             return "I" + str(classname)
         else:
             return cominterfaces[0]
 
-    def PythonTypeToIDLType(annotations, argname: str) -> str:
+    def PythonTypeToIDLType(annotations, argname: str) -> str:  # docsig: disable=SIG101
         argtypeIDL = None
         try:
             if argname in annotations:
@@ -245,7 +245,7 @@ def PythonTypeToIDLType(annotations, argname: str) -> str:
     return okIDL
 
 # typelib compilation (i. e. call Microsoft IDL compiler midl.exe)
-def compileTypeLib(cls):
+def compileTypeLib(cls):  # docsig: disable=SIG101
     idl = get_filename(cls)
     tlb = os.path.splitext(idl)[0] + '.tlb'
     # tlb = pathlib.Path(idl).stem + '.tlb'
@@ -269,7 +269,7 @@ def compileTypeLib(cls):
 #        registration and unregistration (see Python code in win32com.server.register)
 
 # register typelib
-def registerTypeLib(cls):
+def registerTypeLib(cls):  # docsig: disable=SIG101
 
     def registerTypeLibfile(tlbfile: str):
         tlbfile = os.path.abspath(tlbfile)
@@ -285,7 +285,7 @@ def registerTypeLibfile(tlbfile: str):
         registerTypeLibfile(tlbfile)
 
 # unregister typelib - copy from win32com.server.register
-def unregister_typelib(cls):
+def unregister_typelib(cls):  # docsig: disable=SIG101
     tlb_guid = getattr(cls, "_typelib_guid_")
     major, minor = getattr(cls, "_typelib_version_", (1, 0))
     lcid = getattr(cls, "_typelib_lcid_", 0)
@@ -300,15 +300,16 @@ def unregister_typelib(cls):
 # utilities for typelib generation
 
 # get classes with same typelib assignment via _reg_typelib_filename_
-def get_typelib_classes(cls, clsmodule: types.ModuleType) -> list[Any]:
+def get_typelib_classes(cls, clsmodule: types.ModuleType) -> list[Any]:  # docsig: disable=SIG101
     tlbfile = cls._reg_typelib_filename_
     if tlbfile == "":
         return [cls]
     else:
         return inspect.getmembers(clsmodule, lambda clsmember: getattr(clsmember, "_reg_typelib_filename_", "") == tlbfile and inspect.isclass)
 
 # filename for typelib IDL belonging to class(es)
-def get_filename(cls, ext: str = ".idl"):
+# docsig: disable=SIG101
+def get_filename(cls, ext: str = ".idl") -> str:  # docsig: disable=SIG101
     if cls._reg_typelib_filename_ == "" or cls._reg_typelib_filename_ == cls.__name__ + ".tlb" or cls._reg_typelib_filename_ == cls.__name__:
         return os.path.join(os.path.dirname(inspect.getfile(cls)), cls.__name__ + ext)
         # return pathlib.Path(inspect.getfile(cls)).parent.joinpath(cls.__name__ + ext)
@@ -317,5 +318,5 @@ def get_filename(cls, ext: str = ".idl"):
         # return pathlib.Path(inspect.getfile(cls)).parent.joinpath(pathlib.Path(cls._reg_typelib_filename_).stem + ext)
 
 # get enum classes in module
-def get_enum_classes(clsmodule: types.ModuleType) -> list[Any]:
+def get_enum_classes(clsmodule: types.ModuleType) -> list[Any]:  # docsig: disable=SIG101
     return inspect.getmembers(clsmodule, lambda clsmember: getattr(getattr(clsmember, "__base__", ""), "__name__", "") == "Enum" and inspect.isclass)

tests/test_dummy.py

@@ -0,0 +1,18 @@
+# dummy test
+
+
+# ruff and mypy per file settings
+#
+# empty lines
+# ruff: noqa: E302, E303
+# naming conventions
+# ruff: noqa: N801, N802, N803, N806, N812, N813, N815, N816, N818, N999
+# others
+# ruff: noqa: F401
+
+
+import pytest
+
+
+def test_dummy():
+    pass