Merge pull request #38 from dougransom/main

documentation/developers.rst

@@ -73,12 +73,58 @@ Setup Visual Studio Code environment
 .. |image1| image:: https://user-images.githubusercontent.com/24551569/164927468-68f101a5-9eed-4568-b251-0d09fde0394c.png
 .. |image2| image:: https://user-images.githubusercontent.com/24551569/164919729-bd4b2096-6af3-4307-ba3c-ef6ff3b98c41.png
 
+Debugging Natlink Python Code
+------------------
+Developers can debug their python natlink grammars or any
+other Python code running in natlink using a debugger supporting 
+`Debug Adapter Protocol: https://microsoft.github.io/debug-adapter-protocol/`_ (DAP).  
+
+To enable DAP, add or edit your  natlink.ini to include this section.  Change the port if you need to.
+::
+   [settings.debugadapterprotocol]
+
+   dap_enabled = True
+   dap_port = 7474
+   dap_wait_for_debugger_attach_on_startup = True
+
+You can `check if your favorite debugger supports DAP https://microsoft.github.io/debug-adapter-protocol/implementors/tools/.  Here are instructions for Visual
+Studio Code`_:  
+
+Add this section to launch.json, ensuring the port number matchines natlink.ini, and noting
+the pathMappings have been commented out:
+::
+        {
+            "name": "Natlink: Remote Attach",
+            "type": "python",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 7474
+            },
+            //DO NOT USE THE VISUAL STUDIO DEFAULTS
+            //FOR pathMappings.
+            //The defaults will not work and your breakpoints
+            //will never hit.  So delete the pathMappings
+            //section for local host debugging, or set them to 
+            //something meaningful.  
+            // "pathMappings": [
+            //     {
+            //         "localRoot": "${workspaceFolder}",
+            //         "remoteRoot": "."
+            //     }
+
+            //a good idea to set justMyCode to false.  Otherwise
+            //you may have breakpoints set that won't trigger.
+            "justMyCode": false
+        }
+
 
 Further instructions
 --------------------
 
 
 
+
 Invalid options Visual Studio
 -----------------------------
 

readme.md

@@ -52,5 +52,8 @@ Before you bump the version number in __init__.py and publish:
 a dependancy such as dtactions?  Then add or update the version # requirement in dtactions.  
 - don't publish if the tests are failing.   The `publish_natlinkcore` will prevent this, please don't work around it.
 
+## Debugging Instructions
 
+Read the detailed developer instructions for setting up the debugger.  You can look in this projects tree until 
+documentation/developers.rst.
 

src/natlinkcore/DefaultConfig/natlink.ini

@@ -41,6 +41,9 @@ instruction4 = Note: you can drop a python grammar file in any of the directorie
 instruction5 = the distinction is made for package updates, and for convenience
 natlinkuserdirectory = ~\Documents\UserDirectory
 
-
+[settings.debugadapterprotocol]
+dap_enabled = False
+dap_port = 7474
+dap_wait_for_debugger_attach_on_startup = True
 
 

src/natlinkcore/config.py

@@ -35,6 +35,9 @@ def __init__(self, directories_by_user: Dict[str, List[str]],
         # for convenience in other places:
         self.home_path = str(Path.home())
         self.documents_path = str(Path.home()/'Documents')
+
+        #defaults for DAP configuration
+        self.dap_enabled,self.dap_port,self.dap_wait_for_debugger_attach_on_startup = False,0,False
 
     def __repr__(self) -> str:
         return  f'NatlinkConfig(directories_by_user={self.directories_by_user}, ...)'
@@ -69,7 +72,18 @@ def from_config_parser(config: configparser.ConfigParser, config_path: str) -> '
         sections = config.sections()
         sp = sys.path   #handy, leave in for debugging
 
-
+        dap_enabled, dap_port, dap_wait_for_debugger_attach_on_startup = (False,0,False)
+
+        if config.has_section('settings.debugadapterprotocol'):
+            dap_settings = config['settings.debugadapterprotocol']
+            dap_enabled = dap_settings.getboolean('dap_enabled', fallback=False)
+            dap_port = dap_settings.getint('dap_port', fallback=0)
+            dap_wait_for_debugger_attach_on_startup= dap_settings.getboolean('dap_wait_for_debugger_attach_on_startup', fallback=False)
+
+        ret.dap_enabled,ret.dap_port,ret.dap_wait_for_debugger_attach_on_startup = \
+            dap_enabled, dap_port, dap_wait_for_debugger_attach_on_startup
+
+
         for section in sections:
             if section.endswith('-directories'):
                 user = section[:-len('-directories')]
@@ -103,6 +117,9 @@ def from_config_parser(config: configparser.ConfigParser, config_path: str) -> '
             ret.load_on_startup = settings.getboolean('load_on_startup', fallback=ret.load_on_startup)
             ret.load_on_user_changed = settings.getboolean('load_on_user_changed', fallback=ret.load_on_user_changed)
 
+        #default to no dap enabled.
+
+
         return ret
 
     @classmethod

src/natlinkcore/loader.py

@@ -9,6 +9,7 @@
 import sysconfig
 import time
 import traceback
+import debugpy
 import winreg
 import configparser
 from pathlib import Path
@@ -38,6 +39,8 @@
     "Italian": "ita",
     "Spanish": "esp",}
 
+python_exec= "python.exe"  #for DAP
+
 class NatlinkMain(metaclass=Singleton):
     """main class of Natlink, make it a "singleton"
     """
@@ -65,6 +68,7 @@ def __init__(self, logger: Any=None, config: Any = None):
         self._on_begin_utterance_callback = CallbackHandler('on_begin_utterance')
         self.seen: Set[Path] = set()     # start empty in trigger_load
         self.bom = self.encoding = self.config_text = ''   # getconfigsetting and writeconfigsetting
+        self.dap_started=False
 
     def set_on_begin_utterance_callback(self, func: Callable[[], None]) -> None:
         self._on_begin_utterance_callback.set(func)
@@ -605,8 +609,31 @@ def run() -> None:
             os.add_dll_directory(pywin32_dir)
 
         config = NatlinkConfig.from_first_found_file(config_locations())
+        dap_started=False
+        print(f"testing dap , enabled {config.dap_enabled} port {config.dap_port}")
+        try:
+            if config.dap_enabled:
+                print(f"Debugpy.configure ...")
+                debugpy.configure(python=f"{python_exec}")
+                print(f"Debugpy.listen ...")
+
+                debugpy.listen(config.dap_port)
+                dap_started=True
+
+                print(f"DAP Started on Port {config.dap_port} in {__file__}")
+                if config.dap_wait_for_debugger_attach_on_startup:
+                    print(" waiting for debugger to attach")
+
+        except Exception as ee:
+            print(f"""
+                Exception {ee} while starting DAP in {__file__}.  Possible cause is incorrect python executable specified {python_exec}
+                """     )
+
         main = NatlinkMain(logger, config)
+        main.dap_started=dap_started
+
         main.setup_logger()
+        print(f"Dap enabled: {config.dap_enabled} port: {config.dap_port}  ")
         main.start()
     except Exception as exc:
         print(f'Exception: "{exc}" in loader.run', file=sys.stderr)

tests/config_files/dap_settings_1.ini

@@ -0,0 +1,40 @@
+
+[directories]
+made_up=fake_package1
+made_up_2 = c:\
+#made_up_3 = nonexistant   #this one should be discarded so there should be 2 directories on load.
+
+[userenglish-directories]
+#nothing to see here
+
+[userspanish-directories]
+#nothing to see here
+
+[settings]
+
+# log_level: the log level to set the Natlink logger to. 
+# Possible values are: CRITICAL, FATAL, ERROR, WARNING, INFO, DEBUG, NOTSET 
+# (default: NOTSET)
+log_level = DEBUG
+#
+# Determine when to check for new or changed scripts and then load or reload them.
+#
+# Load scripts after Dragon has loaded Natlink (default: True)
+load_on_startup = True
+#
+# At the beginning of each utterance (default: False)
+load_on_begin_utterance = False 
+
+# When the microphone state changes to "on" (default: True)
+load_on_mic_on = False
+
+# load or reload when the user profile changes.
+load_on_user_changed = True   
+
+#made up setting for test
+made_up_setting = "Made Up"   #made up comment
+[settings.debugadapterprotocol]
+
+dap_enabled = False
+dap_port = 7474
+dap_wait_for_debugger_attach_on_startup = False

tests/config_files/dap_settings_2.ini

@@ -0,0 +1,40 @@
+
+[directories]
+made_up=fake_package1
+made_up_2 = c:\
+#made_up_3 = nonexistant   #this one should be discarded so there should be 2 directories on load.
+
+[userenglish-directories]
+#nothing to see here
+
+[userspanish-directories]
+#nothing to see here
+
+[settings]
+
+# log_level: the log level to set the Natlink logger to. 
+# Possible values are: CRITICAL, FATAL, ERROR, WARNING, INFO, DEBUG, NOTSET 
+# (default: NOTSET)
+log_level = DEBUG
+#
+# Determine when to check for new or changed scripts and then load or reload them.
+#
+# Load scripts after Dragon has loaded Natlink (default: True)
+load_on_startup = True
+#
+# At the beginning of each utterance (default: False)
+load_on_begin_utterance = False 
+
+# When the microphone state changes to "on" (default: True)
+load_on_mic_on = False
+
+# load or reload when the user profile changes.
+load_on_user_changed = True   
+
+#made up setting for test
+made_up_setting = "Made Up"   #made up comment
+[settings.debugadapterprotocol]
+
+dap_enabled = True
+dap_port = 0
+dap_wait_for_debugger_attach_on_startup = True

tests/config_files/dap_settings_3.ini

@@ -0,0 +1,40 @@
+
+[directories]
+made_up=fake_package1
+made_up_2 = c:\
+#made_up_3 = nonexistant   #this one should be discarded so there should be 2 directories on load.
+
+[userenglish-directories]
+#nothing to see here
+
+[userspanish-directories]
+#nothing to see here
+
+[settings]
+
+# log_level: the log level to set the Natlink logger to. 
+# Possible values are: CRITICAL, FATAL, ERROR, WARNING, INFO, DEBUG, NOTSET 
+# (default: NOTSET)
+log_level = DEBUG
+#
+# Determine when to check for new or changed scripts and then load or reload them.
+#
+# Load scripts after Dragon has loaded Natlink (default: True)
+load_on_startup = True
+#
+# At the beginning of each utterance (default: False)
+load_on_begin_utterance = False 
+
+# When the microphone state changes to "on" (default: True)
+load_on_mic_on = False
+
+# load or reload when the user profile changes.
+load_on_user_changed = True   
+
+#made up setting for test
+made_up_setting = "Made Up"   #made up comment
+
+
+#test without this section
+#[settings.debugadapterprotocol]
+#expected False,0, False