natlinkcore 5.4.0__tar.gz → 5.4.2.dev1__tar.gz

{natlinkcore-5.4.0 → natlinkcore-5.4.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: natlinkcore
-Version: 5.4.0
+Version: 5.4.2.dev1
 Summary: Python portion of Natlink, a compatibility module for Dragon Naturally Speaking
 Author-email: "Quintijn Hoogenboom (maintainer)" <q.hoogenboom@antenna.nl>
 Requires-Python: >=3.9
@@ -13,11 +13,11 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Dist: natlink>=5.3.4
 Requires-Dist: FreeSimpleGUI>=5.1.0
 Requires-Dist: pydebugstring >= 1.0.0.1
-Requires-Dist: dtactions>=1.6.2
+Requires-Dist: dtactions>=1.6.3
 Requires-Dist: platformdirs >= 4.2.0
+Requires-Dist: natlink ~= 5.5, >= 5.5.7
 Requires-Dist: pyenvutils ; extra == "dev"
 Requires-Dist: entry-point-inspector ; extra == "dev"
 Requires-Dist: build ; extra == "dev"
@@ -55,10 +55,52 @@ Mandy Python IDEs such as [Visual Studio Code](https://code.visualstudio.com/) h
 Publishing to PyPi is done through the [trusted publisher mechanism](https://docs.pypi.org/trusted-publishers/using-a-publisher/) when a release is created on github using github actions. 
 
 
-## Publishing checklist
-Before you bump the version number in __init__.py and publish:
-- Check the pyroject.toml file for package dependancies.  Do you need a specfic or newer version of
-a dependancy such as dtactions?  Then add or update the version # requirement in dtactions.  
+## Version Numbering and Publishing Checklist
+
+While you are developing, use a .dev release number.  When you are ready for alpha or beta or release candidate, use the appropriate version numbers.
+If you are submitting a pull request, the review should review and adjust the version number.  
+The version specificier is in pyroject.toml.
+
+
+The version number progression is explained in [PEP440](https://peps.python.org/pep-0440/#summary-of-permitted-suffixes-and-relative-ordering).  
+
+Hypothetical Progression of release numbers.  
+
+Working towards 5.4.0:
+- 5.4.0.dev1
+- 5.4.0.dev2
+- 5.4.0.dev_feature_x
+- 5.4.0a1
+- 5.4.0b1dev1
+- 5.4.0b1
+- 5.4.0rc1
+- 5.4.0rc2
+- 5.4.0
+
+Use alpha and beta specifiers (5.4a2, 5.4.b1, etc) to release alphas and betas.
+If you go through a release candidate phase, use 5.4rc1 etc.
+
+Non breaking changes, add a micro version number.  ie from version 5.4.1 to 5.4.2.
+Breaking changes, add a minor version number.
+
+*Before you publish to pypi*:
+- doublecheck the dependancies, especially on natlink.  You may want to specify a minimum natlink (i.e. 5.5.3) and 
+normally you should also specify that natlink has not had a breaking change by specifying the major and minor version numbers are as expected.  Note that this requires a release of natlinkcore if the minor version of natlink changes.  At minimum this will require an update to pyproject.toml and a release to pypi, even if no python code has changed. 
+
+
+
+This is how the version specifier should look for natlink (subsituting the version numbers appropriate).  In this case, we are saying that any natlink 5.5 is required, and that 
+we require greater than 5.5.7 as well because we are relying on a non-breaking change introduced in 5.5.7.
+`    "natlink ~= 5.5, >= 5.5.7"
+`
+Often, the natlink dependancy should just specify the major and minor version:
+`
+    "natlink ~= 5.5"
+`
+
+You could have a case where natlinkcore works with natlink 5.5 and 5.6, you could express this in pyproject.toml as
+    "natlink ~= 5.5, ~= 5.6".  
+
 
 ## Debugging Instructions
 

{natlinkcore-5.4.0 → natlinkcore-5.4.2.dev1}/pyproject.toml

@@ -5,15 +5,17 @@ build-backend = "flit_core.buildapi"
 [project]
 name = "natlinkcore"
 authors = [{name = "Quintijn Hoogenboom (maintainer)", email = "q.hoogenboom@antenna.nl"}]
-dynamic = ["version", "description"]
+version="5.4.2.dev1"
+dynamic = [ "description"]
 requires-python = ">=3.9"
 readme = "readme.md"
 dependencies= [
-    "natlink>=5.3.4",
+
     "FreeSimpleGUI>=5.1.0", 
     "pydebugstring >= 1.0.0.1",
-    "dtactions>=1.6.2",
-    "platformdirs >= 4.2.0"
+    "dtactions>=1.6.3",
+    "platformdirs >= 4.2.0",
+    "natlink ~= 5.5, >= 5.5.7"
 ]
     classifiers=[
         "Development Status :: 4 - Beta",

natlinkcore-5.4.2.dev1/readme.md

@@ -0,0 +1,81 @@
+
+# Natlinkcore 
+
+## More Information
+ Please refer to the README file in the project repository [https://github.com/dictation-toolbox/natlink](https://github.com/dictation-toolbox/natlink) for more information about natlink.
+
+## Installing from PyPi
+You can install from [The Python Package Index (PyPI)](https://pypi.org/) with 
+
+`py -m pip install natlinkcore`
+
+Note that natlinkcore will not install if you have not installed Natlink first.  Natlink is installed through running an installer.
+
+ 
+## Test Framework
+Tests use the [pytest](https://docs.pytest.org/) framework.  
+For developers, if you are developing on the project, please add tests for any new features or bug
+fixes.  
+
+Mandy Python IDEs such as [Visual Studio Code](https://code.visualstudio.com/) have build in support for test frameworks and make it easy to run and debug pytest.   see [Visual Studio Code for testing](https://code.visualstudio.com/docs/python/testing).
+
+
+## Building the Python Package Locally
+
+`py -m build` to build the Python package locally.
+
+Publishing to PyPi is done through the [trusted publisher mechanism](https://docs.pypi.org/trusted-publishers/using-a-publisher/) when a release is created on github using github actions. 
+
+
+## Version Numbering and Publishing Checklist
+
+While you are developing, use a .dev release number.  When you are ready for alpha or beta or release candidate, use the appropriate version numbers.
+If you are submitting a pull request, the review should review and adjust the version number.  
+The version specificier is in pyroject.toml.
+
+
+The version number progression is explained in [PEP440](https://peps.python.org/pep-0440/#summary-of-permitted-suffixes-and-relative-ordering).  
+
+Hypothetical Progression of release numbers.  
+
+Working towards 5.4.0:
+- 5.4.0.dev1
+- 5.4.0.dev2
+- 5.4.0.dev_feature_x
+- 5.4.0a1
+- 5.4.0b1dev1
+- 5.4.0b1
+- 5.4.0rc1
+- 5.4.0rc2
+- 5.4.0
+
+Use alpha and beta specifiers (5.4a2, 5.4.b1, etc) to release alphas and betas.
+If you go through a release candidate phase, use 5.4rc1 etc.
+
+Non breaking changes, add a micro version number.  ie from version 5.4.1 to 5.4.2.
+Breaking changes, add a minor version number.
+
+*Before you publish to pypi*:
+- doublecheck the dependancies, especially on natlink.  You may want to specify a minimum natlink (i.e. 5.5.3) and 
+normally you should also specify that natlink has not had a breaking change by specifying the major and minor version numbers are as expected.  Note that this requires a release of natlinkcore if the minor version of natlink changes.  At minimum this will require an update to pyproject.toml and a release to pypi, even if no python code has changed. 
+
+
+
+This is how the version specifier should look for natlink (subsituting the version numbers appropriate).  In this case, we are saying that any natlink 5.5 is required, and that 
+we require greater than 5.5.7 as well because we are relying on a non-breaking change introduced in 5.5.7.
+`    "natlink ~= 5.5, >= 5.5.7"
+`
+Often, the natlink dependancy should just specify the major and minor version:
+`
+    "natlink ~= 5.5"
+`
+
+You could have a case where natlinkcore works with natlink 5.5 and 5.6, you could express this in pyproject.toml as
+    "natlink ~= 5.5, ~= 5.6".  
+
+
+## Debugging Instructions
+
+Read the detailed developer instructions for setting up the debugger.  You can look in this projects tree until 
+documentation/developers.rst.
+

{natlinkcore-5.4.0 → natlinkcore-5.4.2.dev1}/src/natlinkcore/__init__.py

@@ -1,6 +1,10 @@
 '''Python portion of Natlink, a compatibility module for Dragon Naturally Speaking
 The python stuff including test modules'''
-__version__="5.4.0"
+
+import importlib.metadata
+
+__version__ = importlib.metadata.version(__package__)  #version set in pyproject.toml now.
+
 #pylint:disable=
 from pathlib import Path
 

{natlinkcore-5.4.0 → natlinkcore-5.4.2.dev1}/src/natlinkcore/config.py

@@ -1,4 +1,4 @@
-#pylint:disable=C0114, C0115, C0116, R0913, E1101, R0911, R0914, W0702
+#pylint:disable=C0114, C0115, C0116, R0913, E1101, R0911, R0914, W0702, R0912, C0209
 import sys
 import configparser
 import logging
@@ -144,20 +144,19 @@ class NatlinkConfig:
         raise NoGoodConfigFoundException('No natlink config file found, please run configure natlink program\n\t(***configurenatlink***)')
 
 def expand_path(input_path: str) -> str:
-    r"""expand path if it starts with "~" or has environment variables (%XXXX%)
+    r"""expand path if it starts with "~" or starts with an environment variable or name of python package
     
-    Paths can be:
-    
-    - the name of a python package, or a sub directory of a python package
-    - Obsolete: natlink_userdir/...: the directory where natlink.ini is is searched for, either %(NATLINK_USERDIR) or ~/.natlink
-    - ~/...: the home directory
-    - Now: natlink_settingsdir/...: the directory where natlink.ini is is searched for, either %(NATLINK_SETTINGSDIR) or ~/.natlink
-    - ~/...: the home directory
-    - some environment variable: this environment variable is expanded.
-    
-    The Documents directory can be found by "~\Documents"...
-    
-    When nothing to expand, return input
+Paths can be:
+
+- the name of a python package, or a sub directory of a python package
+- natlink_settingsdir/...: the directory where natlink.ini is is searched for, either`%(NATLINK_SETTINGSDIR)` or `~/.natlink`
+- `~/...`: the home directory
+- Obsolete: natlink_userdir/...: instead natlink_settingsdir will be searched for, and a message is thrown. In the config program things are checked more thoroughly.
+- some other environment variable: this environment variable is expanded 
+
+The Documents directory can be found by "~\Documents"...
+
+When there is nothing to expand, just return the input
     """
     expanduser, expandvars, normpath, isdir = os.path.expanduser, os.path.expandvars, os.path.normpath, os.path.isdir
     
@@ -228,10 +227,10 @@ def expand_path(input_path: str) -> str:
     return normpath(env_expanded)
 
 def expand_natlink_settingsdir():
-    """not with envvariables, but special:
+    """Return the location of the natlink config files
     
     if NATLINK_SETTINGSDIR is set: return this, but... it should end with ".natlink"
-    if NATLINK_SETTINGSDIR is NOT set: return Path.home()/'.natlink'
+    if NATLINK_SETTINGSDIR is NOT set: return `Path.home()/'.natlink'`
     """
     normpath = os.path.normpath
     nsd = os.getenv('natlink_settingsdir')

{natlinkcore-5.4.0 → natlinkcore-5.4.2.dev1}/src/natlinkcore/configure/natlinkconfig_gui.py

@@ -56,14 +56,14 @@ def collapse(layout, key, visible):
 
 #### Hidden UI Columns ####
 dragonfly2_section = [[sg.Text('Dragonfly', text_color='black')],
-                     [sg.T('Dragonfly user directory:', tooltip='The directory to dragonfly2 user scripts (UserDirectory can also be used)'), sg.Input(Status.getDragonflyUserDirectory(), key='Set_UserDir_Dragonfly2', enable_events=True, readonly=True), sg.FolderBrowse(), sg.B("Clear", key='Clear_UserDir_Dragonfly2', enable_events=True)]]
+                     [sg.T('Dragonfly user directory:', tooltip='The directory to dragonfly2 user scripts (UserDirectory can also be used)'), sg.Input(Status.getDragonflyUserDirectory(), key='Set_UserDir_Dragonfly2', enable_events=False, readonly=False), sg.FolderBrowse(), sg.B("Clear", key='Clear_UserDir_Dragonfly2', enable_events=True)]]
 
 unimacro_section = [[sg.T('Unimacro', text_color='black')],
-                    [sg.T('Unimacro user directory:', tooltip=r'Where the Unimacro user INI files are located, and several other directories (~ or %HOME% allowed)'), sg.I(Status.getUnimacroUserDirectory(), key='Set_UserDir_Unimacro', enable_events=True, readonly=True), sg.FolderBrowse(), sg.B("Clear", key='Clear_UserDir_Unimacro', enable_events=True)]]
+                    [sg.T('Unimacro user directory:', tooltip=r'Where the Unimacro user INI files are located, and several other directories (~ or %HOME% allowed)'), sg.I(Status.getUnimacroUserDirectory(), key='Set_UserDir_Unimacro', enable_events=False, readonly=False), sg.FolderBrowse(), sg.B("Clear", key='Clear_UserDir_Unimacro', enable_events=True)]]
 
 extras_section = [[sg.T('Natlink Loglevel:'),  sg.Combo(default_value=Status.getLogging(), values=("Critical",  "Fatal",  "Error", "Warning", "Info" , "Debug"), key='Set_Logging_Natlink', enable_events=True, auto_size_text=True, readonly=True)],
-                  [sg.T('Autohotkey exe dir:'), sg.I(Status.getAhkExeDir(), key='Set_Exe_Ahk', enable_events=True, readonly=True), sg.FolderBrowse(), sg.B("Clear", key='Clear_Exe_Ahk', enable_events=True)],
-                  [sg.T('Autohotkey scripts dir:'), sg.I(Status.getAhkUserDir(), key='Set_ScriptsDir_Ahk', enable_events=True, readonly=True), sg.FolderBrowse(), sg.B("Clear", key='Clear_ScriptsDir_Ahk', enable_events=True)],
+                  [sg.T('Autohotkey exe dir:'), sg.I(Status.getAhkExeDir(), key='Set_Exe_Ahk', enable_events=False, readonly=False), sg.FolderBrowse(), sg.B("Clear", key='Clear_Exe_Ahk', enable_events=False)],
+                  [sg.T('Autohotkey scripts dir:'), sg.I(Status.getAhkUserDir(), key='Set_ScriptsDir_Ahk', enable_events=False, readonly=False), sg.FolderBrowse(), sg.B("Clear", key='Clear_ScriptsDir_Ahk', enable_events=False)],
                   [sg.T('Natlink GUI Output')],
                   [sg.Output(size=(40,10), echo_stdout_stderr=True, expand_x=True, key='-OUTPUT-')]]
 

{natlinkcore-5.4.0 → natlinkcore-5.4.2.dev1}/src/natlinkcore/loader.py

@@ -19,6 +19,7 @@ import debugpy
 
 import natlink
 from natlinkcore.config import LogLevel, NatlinkConfig, expand_path
+from natlinkcore.natlinkutils import idd_reload, idd_exit
 from natlinkcore.readwritefile import ReadWriteFile
 from natlinkcore.callbackhandler import CallbackHandler
 from natlinkcore.singleton import Singleton
@@ -257,6 +258,13 @@ class NatlinkMain(metaclass=Singleton):
             if d_expanded not in sys.path:
                 sys.path.insert(0, d_expanded)
 
+    @staticmethod
+    def _del_dirs_from_path(directories: Iterable[str]) -> None:
+        for d in directories:
+            d_expanded = expand_path(d)
+            if d_expanded in sys.path:
+                sys.path.remove(d_expanded)
+
     def _call_and_catch_all_exceptions(self, fn: Callable[[], None]) -> None:
         try:
             fn()
@@ -455,6 +463,14 @@ class NatlinkMain(metaclass=Singleton):
                 value -= 1
                 self.load_on_begin_utterance = value
             self.trigger_load()
+
+    def on_message_window_callback(self, event):
+        if event == idd_reload:
+            self.trigger_load(force_load=True)
+            natlink.setBeginCallback(self.on_begin_callback)
+            natlink.setChangeCallback(self.on_change_callback)
+        elif event == idd_exit:
+            self.finish()
                 
     def get_user_language(self, DNSuserDirectory):
         """return the user language (default "enx") from Dragon inifiles
@@ -545,6 +561,17 @@ class NatlinkMain(metaclass=Singleton):
             self.trigger_load()
         natlink.setBeginCallback(self.on_begin_callback)
         natlink.setChangeCallback(self.on_change_callback)
+        natlink.setMessageWindow(self.on_message_window_callback)
+
+    def finish(self) -> None:
+        # reverse changes made by start()
+        natlink.setMessageWindow(None)
+        natlink.setChangeCallback(None)
+        natlink.setBeginCallback(None)
+        self.unload_all_loaded_modules()
+        self._del_dirs_from_path(self.config.directories)
+        natlink.active_loader = None
+        self.logger.info('Stopping natlink loader')
 
     def setup_logger(self) -> None:
         for handler in list(self.logger.handlers):

{natlinkcore-5.4.0 → natlinkcore-5.4.2.dev1}/src/natlinkcore/natlinkstatus.py

@@ -326,9 +326,10 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         uuDir = self.getUnimacroUserDirectory()
         if not uuDir:
             return False
-        # ugDir = uuDir    # only _control  self.getUnimacroGrammarsDirectory()
+        
+        # ugDir = self.getUnimacroGrammarsDirectory()
         # if not (ugDir and isdir(ugDir)):
-        #     print(f'UnimacroGrammarsDirectory ({ugDir}) not present, please create')
+        #     print(f'UnimacroGrammarsDirectory ({ugDir}) is not present, should be a subdirectory "unimacrogrammars" of {uDir}, please (re)run your pip install unimacro command, of rerun the "Configure Natlink with GUI" or "Configure Natlink with CLI"')
         #     return False
         return True            
 
@@ -362,6 +363,9 @@ class NatlinkStatus(metaclass=singleton.Singleton):
             raise OSError(f'getNatlinkIni: not a valid file: "{path}"')
         return path
     
+    getnatlinkini = getNatlinkIni
+    
+
     def getNatlink_Settingsdir(self):
         """get the directory where "natlink.ini" should be stored
         
@@ -378,6 +382,8 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         
         return str(natlink_settings_dir)
     
+    getnatlink_settingsdir = getNatlink_Settingsdir
+    
     def getUnimacroUserDirectory(self):
         isdir, abspath = os.path.isdir, os.path.abspath
         if self.UnimacroUserDirectory is not None:
@@ -400,7 +406,7 @@ class NatlinkStatus(metaclass=singleton.Singleton):
 
         self.UnimacroUserDirectory = ''
         return ''
-    
+    getunimacrouserdirectory = getUnimacroUserDirectory
     
     def getUnimacroDirectory(self):
         """return the path to the UnimacroDirectory
@@ -419,6 +425,9 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         self.UnimacroDirectory = unimacro.__path__[-1]
         return self.UnimacroDirectory
 
+    getunimacrodirectory = getUnimacroDirectory
+
+
     def getUnimacroGrammarsDirectory(self):
         """return the path to the UnimacroGrammarDirectory
         
@@ -442,6 +451,8 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         self.UnimacroGrammarsDirectory = um_grammars_dir
         return um_grammars_dir
     
+    getunimacrogrammarsdirectory = getUnimacroGrammarsDirectory
+    
     def getUnimacroDataDirectory(self):
         """return the path to the directory where grammars can store data.
         
@@ -451,6 +462,8 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         """
         if self.UnimacroDataDirectory is not None:
             return self.UnimacroDataDirectory
+        if not self.unimacroIsEnabled():
+            return ''
         
         natlink_settings_dir = self.getNatlink_Settingsdir()
         
@@ -461,16 +474,22 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         self.UnimacroDataDirectory = um_data_dir
 
         return um_data_dir
+    
+    getunimacrodatadirectory = getUnimacroDataDirectory
 
     def getNatlinkDirectory(self):
         """return the path of the NatlinkDirectory, where the _natlink_core.pyd package (C++ code) is
         """
         return self.NatlinkDirectory
 
+    getnatlinkdirectory = getNatlinkDirectory
+    
     def getNatlinkcoreDirectory(self):
         """return the path of the natlinkcore package directory, same as thisDir!
         """
         return self.NatlinkcoreDirectory
+    getnatlinkcoredirectory = getNatlinkcoreDirectory
+    
     
     def getUserDirectory(self):
         """return the path to the Natlink User directory
@@ -500,7 +519,8 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         print('invalid path for UserDirectory: "{value}"')
         self.UserDirectory = ''
         return ''
-  
+    getuserdirectory = getUserDirectory
+    
     def getDragonflyDirectory(self):
         """return the path to the DragonflyDirectory
         
@@ -519,7 +539,7 @@ class NatlinkStatus(metaclass=singleton.Singleton):
     
         self.DragonflyDirectory = str(Path(dragonfly2.__file__).parent)
         return self.DragonflyDirectory
-        
+    getdragonflydirectory = getDragonflyDirectory     
 
 
     def getDragonflyUserDirectory(self):
@@ -550,7 +570,7 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         print('invalid path for DragonflyUserDirectory: "{value}"')
         self.DragonflyUserDirectory = ''
         return ''
-    
+    getdragonflyuserdirectory = getDragonflyUserDirectory
     
     def getVocolaUserDirectory(self):
 
@@ -576,6 +596,8 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         print(f'invalid path for VocolaUserDirectory: "{value}" (expanded: "{expanded}")')
         self.VocolaUserDirectory = ''
         return ''
+    getvocolauserdirectory = getVocolaUserDirectory
+    
     
     def getVocolaDirectory(self):
         if self.VocolaDirectory is not None:
@@ -588,7 +610,7 @@ class NatlinkStatus(metaclass=singleton.Singleton):
             return ''
         self.VocolaDirectory = vocola2.__path__[-1]
         return self.VocolaDirectory
-
+    getvocoladirectory = getVocolaDirectory
     
     def getVocolaGrammarsDirectory(self):
         """return the VocolaGrammarsDirectory, but only if Vocola is enabled
@@ -611,6 +633,7 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         voc_grammars_dir = natlinkcore.config.expand_path(value)
         self.VocolaGrammarsDirectory = voc_grammars_dir
         return voc_grammars_dir
+    getvocolagrammarsdirectory = getVocolaGrammarsDirectory
     
     def getDtactionsDirectory(self):
         """dtactions directory should be found with an import (like getUnimacroDirectory)
@@ -625,10 +648,12 @@ class NatlinkStatus(metaclass=singleton.Singleton):
             return ""
         self.DtactionsDirectory = dtactions.__path__[-1]
         return self.DtactionsDirectory
+    getdtactionsdirectory = getDtactionsDirectory
+
 
     def getAhkUserDir(self):
         return self.getAhkUserDirFromIni()
-
+    getahkuserdir = getAhkUserDir
     
     def getAhkUserDirFromIni(self):
         isdir, abspath = os.path.isdir, os.path.abspath
@@ -655,7 +680,7 @@ class NatlinkStatus(metaclass=singleton.Singleton):
         if not self.AhkExeDir is None:
             return self.AhkExeDir
         return self.getAhkExeDirFromIni()
-
+    getahkexedir = getAhkExeDir
     
     def getAhkExeDirFromIni(self):
         isdir, abspath = os.path.isdir, os.path.abspath

{natlinkcore-5.4.0 → natlinkcore-5.4.2.dev1}/src/natlinkcore/natlinkutils.py

@@ -6,11 +6,8 @@ Python Macro Language for Dragon NaturallySpeaking
 
   This file contains utility classes and functions for grammar files.
 
-  Documentation
-
-  This file contains three base classes and some useful constants and
-    utility functions:
-
+Grammar classes
+===============
   GrammarBase - base class for all command and control grammars.
       See documentation below just before the class definition.
 
@@ -20,18 +17,24 @@ Python Macro Language for Dragon NaturallySpeaking
   SelectGramBase - base class for all selection grammars.
       See documentation below just before the class definition.
 
+
+Functions
+==========
+
+among others, see below:
+
   buttonClick( btnName='left',count=1 )
       This function simulates a button click or button double click.  Pass
       in the button name ('left','right' or 'middle') and the count (1 or
       2)
 
+  
   matchWindow( moduleInfo, modName, wndText )
       A utility function which determines whether moduleInfo matches a
       specified module name and window title.  Returns window handle on
       match and None on mismatch. Note that moduleInfo may be ("","",0)
       which we should handle cleanly.
 
-
 """
 #pylint:disable=C0116, C0209, C0302, R0902, W0702, E1101, W0703, R1735
 #pylint:disable=W0237    # inconsistent calling sequences for different classes 
@@ -121,6 +124,11 @@ dgnwordflag_title_mode		= 0x02000000
 dgnwordflag_space_bar		= 0x08000000
 dgnwordflag_topicadded		= 0x40000000
 dgnwordflag_DNS8newwrdProp  = 0x20000000
+
+# The following constants define the window message codes which are passed
+# to the message window callback on menu command activation.
+idd_reload = 32768
+idd_exit = 32769
  
 ## temporary fix, remove as soon as natlinkmain is more secure QH (Febr 2021) 
  
@@ -179,7 +187,7 @@ def matchWindow(moduleInfo, modName, wndText):
        
        Returns window handle on match and None on mismatch.
 
-       Note that moduleInfo may be ("","",0) which we should handle cleanly.
+       Note that moduleInfo may be `("", "", 0)` which we should handle cleanly.
     """
     if len(moduleInfo) < 3 or not moduleInfo[0]:
         return None
@@ -288,16 +296,33 @@ def getModifierKeyCodes(modifiers):
     return [modifier_dict[m] for m in modifiers]
 
 def playString(keys, hooks=None):
-    """Deprecated.
+    """natlink.playString was deprecated, but is repaired via a python function with version 5.4.0
     
-    natlink.playString, but sometimes has a drop or double of the first character it plays on the screen.
+Therefore this function in natlinkutils is obsolete.
     
-    dtactions has a sendkeys function, which can replace playSting most of the time...
+`playString` outputs a string of (keyboard) characters, including
+control characters (like `{ctrl+c}` or `{right 3}`)
+to the foreground window.
+
+It is implemented via the `sendkeys` function in repository `dtactions`.
+
+::
+
+    So you can either do:
+
     from dtactions.sendkeys import sendkeys
     (...)
     sendkeys('hello world')
+
+    or:
+    
+    from natlink import playString
+    (...)
+    playString('hello world again')
+    
+And forget about `natlinkutils.playString`!!
     """
-    raise DeprecationWarning('use natlink.playString or another sendkeys or sendinput function...')
+    natlink.playString(keys)
  
 #Classes--------------------------------------------------------------------
 
@@ -630,24 +655,25 @@ And assume that {list} contains the words "good" and "bad".
 
 Now if "this big red object is good" is recognized, the following callbacks
 will be made (in the order indicated).  
-
-(Note: The second parameter to gotResults_XXX and gotResults is the same as
-the second parameter to gotResultsInit.  The example has been abbreviated
-to save space.)
-
-  gotBegin( ??? )
-  gotResultsObject( 'self', resObj )
-  gotResultsInit( 
-      ['this','big','red','object','is','good'],
-      [('this','start'),('big','ruleOne'),('red','RuleTwo'),
-          ('object','ruleOne'),('is','start'),('good','start')] )
-  gotResults_start( ['this'], ... )
-  gotResults_ruleOne( ['big'], ... )
-  gotResults_ruleTwo( ['red'], ... )
-  gotResults_ruleOne( ['object'], ... )
-  gotResults_start( ['is','good'], ... )
-  gotResults( ['this','big','red','object','is','good'], ... )
-    """
+"""
+# 
+# (Note: The second parameter to gotResults_XXX and gotResults is the same as
+# the second parameter to gotResultsInit.  The example has been abbreviated
+# to save space.)
+# 
+#   gotBegin( ??? )
+#   gotResultsObject( 'self', resObj )
+#   gotResultsInit( 
+#       ['this','big','red','object','is','good'],
+#       [('this','start'),('big','ruleOne'),('red','RuleTwo'),
+#           ('object','ruleOne'),('is','start'),('good','start')] )
+#   gotResults_start( ['this'], ... )
+#   gotResults_ruleOne( ['big'], ... )
+#   gotResults_ruleTwo( ['red'], ... )
+#   gotResults_ruleOne( ['object'], ... )
+#   gotResults_start( ['is','good'], ... )
+#   gotResults( ['this','big','red','object','is','good'], ... )
+#     """
 
     def __init__(self):
         GramClassBase.__init__(self)
@@ -1139,7 +1165,9 @@ make default select and through words "select" and "through" (lower case)
 Quintijn december 2010
 adapt to throughWords as well, for future enhancement VoiceCode
 Quintijn August, 2009
+
   load( selectWords=['Select'], throughWord='Through', throughWords=None, allResults=0, hypothesis=0 )
+
       selectWords is a list of words or phrases which can introduce a
           comand of this type.  For example, you can pass in a list like
           ['Select','Correct','Insert Before','Insert After'] to simulate
@@ -1202,17 +1230,21 @@ results.  The following callback functions can be defined:
   gotResults( words, start, end )
       called when results are available for this grammar.
 
-      words = list of recognized words; the first word will be one of
+      words = list of recognized words
+          the first word will be one of
           the words or phrases in selectWords (passed in when the grammar
           was created).
+
       start = index into getSelectText of the start of the selection
+
       end = index into getSelectText of the end of the selection
 
+ 
   gotHypothesis( words )
       only called when the hypothesis flag is set on load, this callback
       contains the partial recognition hypothesis during recognition.
-
-
+  
+  
     """
     def load( self, selectWords=None, throughWord='through',
               throughWords=None,allResults=0, hypothesis=0 ):
@@ -1269,9 +1301,10 @@ results.  The following callback functions can be defined:
     def makeGrammar(self, selectWords, throughWords):
         """make a selection grammar, which is similar to a Microsoft SAPI grammar.
         
-    Use the routines in gramparser.py to build the grammar just like with
+    Uses the routines in `gramparser.py` to build the grammar just like with
     command grammars.
-    selectWords and throughWords are lists or words
+    
+    `selectWords` and `throughWords` are lists or words.
         """
         output = []
         output.append(struct.pack("LL", 10, 0))
@@ -1294,14 +1327,16 @@ results.  The following callback functions can be defined:
         
 #---------------------------------------------------------------------------        
 
-# Utility subroutine.  This returns the base module name from a complete path
 
 def getBaseName(name):
+    """Utility subroutine.  This returns the base module name from a complete path
+    """
     return os.path.splitext(os.path.split(name)[1])[0]
 
 
 def convertResults(fullResults):
     """This utility routine converts a fullResults parameter into a dictionary
+::
 
    [ ('red','color'), ('flower','object'), ('and','conj'), ('green','color') ]
    Becomes:

natlinkcore-5.4.0/readme.md

@@ -1,39 +0,0 @@
-
-# Natlinkcore 
-
-## More Information
- Please refer to the README file in the project repository [https://github.com/dictation-toolbox/natlink](https://github.com/dictation-toolbox/natlink) for more information about natlink.
-
-## Installing from PyPi
-You can install from [The Python Package Index (PyPI)](https://pypi.org/) with 
-
-`py -m pip install natlinkcore`
-
-Note that natlinkcore will not install if you have not installed Natlink first.  Natlink is installed through running an installer.
-
- 
-## Test Framework
-Tests use the [pytest](https://docs.pytest.org/) framework.  
-For developers, if you are developing on the project, please add tests for any new features or bug
-fixes.  
-
-Mandy Python IDEs such as [Visual Studio Code](https://code.visualstudio.com/) have build in support for test frameworks and make it easy to run and debug pytest.   see [Visual Studio Code for testing](https://code.visualstudio.com/docs/python/testing).
-
-
-## Building the Python Package Locally
-
-`py -m build` to build the Python package locally.
-
-Publishing to PyPi is done through the [trusted publisher mechanism](https://docs.pypi.org/trusted-publishers/using-a-publisher/) when a release is created on github using github actions. 
-
-
-## Publishing checklist
-Before you bump the version number in __init__.py and publish:
-- Check the pyroject.toml file for package dependancies.  Do you need a specfic or newer version of
-a dependancy such as dtactions?  Then add or update the version # requirement in dtactions.  
-
-## Debugging Instructions
-
-Read the detailed developer instructions for setting up the debugger.  You can look in this projects tree until 
-documentation/developers.rst.
-