Merge pull request #30 from develop into master

This produces a few duplicate commits that can't really be removed
without re-writing history. Lesson learnt: cherry picking should
*not* be used to selectively move commits between branches of the
same repository *if* the branch will be merged later.

.gitignore

@@ -52,7 +52,7 @@ coverage.xml
 *.log
 
 # Sphinx documentation
-docs/_build/
+documentation/build/
 
 # PyBuilder
 target/

.travis.yml

@@ -1,6 +1,5 @@
 language: python
 python:
-  - "2.6"
   - "2.7"
   - "3.4"
   - "3.5"

CHANGELOG.md

@@ -6,26 +6,45 @@ and this project will adhere to [Semantic Versioning](http://semver.org/spec/v2.
 
 Note: this project had no release versions between [0.6.6b1] and [0.7.0]. Notable changes made between these versions are documented in the commit history and will be placed under headings in this file over time.
 
-## [0.7.0] - 2017-07-10
+## [Unreleased]
 ### Added
-- Add multi-platform Clipboard class that works on Windows, Linux, Mac OS X
-- Support Unicode grammar specs and window titles
-- Support alternate keyboard layouts
-- Add additional speech recognition backend using CMU Pocket Sphinx
-- Add additional unit tests for enhancements
-- Add additional six and pyperclip dependencies in setup.py
+- Add EngineBase.grammars property for retrieving loaded grammars.
+- Add MappingRule.specs property to allow retrieval of specs after initialisation.
+- Add checks in Sphinx engine for using unknown words in grammars and keyphrases.
+- Add configurable speech and hypothesis recording to Sphinx engine for model training.
 
 ### Changed
-- Mock Windows-specific functionality for other platforms to allow importing
-- Make pywin32 only required on Windows
-- Made natlink optional in dragonfly/timer.py
-- Clean up code styling and semantic issues
-- Convert code base to support Python 3.x as well as Python 2.x
-- Update natlink links in documentation
+- Update pyjsgf submodule to version 1.5.0.
 
 ### Fixed
-- Make the Paste action work with the Unicode clipboard format @comodoro
-- Fix issues with dragonfly's monitor list and class
+- Fix a bug with CompoundRule.spec.
+- Fix translation of RuleRef without explicit name in dragonfly2jsgf (thanks [@daanzu](https://github.com/daanzu)).
+- Update virtual keyboard extended key support (thanks [@Versatilus](https://github.com/Versatilus)).
+- Add missing methods for WSR and Sphinx engines in test/element_tester.
+- Fix a few minor problems with the Sphinx engine.
+
+
+## [0.7.0] - 2018-07-10
+### Added
+- Add multi-platform Clipboard class that works on Windows, Linux, Mac OS X.
+- Support Unicode grammar specs and window titles.
+- Support alternate keyboard layouts.
+- Add additional speech recognition backend using CMU Pocket Sphinx.
+- Add optional Sphinx dependencies as pyjsgf and sphinxwrapper Git sub-modules.
+- Add additional unit tests for enhancements.
+- Add additional six and pyperclip dependencies in setup.py.
+
+### Changed
+- Mock Windows-specific functionality for other platforms to allow importing.
+- Make pywin32 only required on Windows.
+- Made natlink optional in dragonfly/timer.py.
+- Clean up code styling and semantic issues.
+- Convert code base to support Python 3.x as well as Python 2.7.
+- Update natlink links in documentation.
+
+### Fixed
+- Make the Paste action work with the Unicode clipboard format (thanks [@comodoro](https://github.com/comodoro)).
+- Fix issues with dragonfly's monitor list and class.
 
 ## [2016]
 TODO
@@ -57,6 +76,7 @@ TODO
 ## [0.6.1] - 2008-10-18
 This release is the first in the Git version control system.
 
+[Unreleased]: https://github.com/Danesprite/dragonfly/compare/0.7.0...HEAD
 [0.7.0]:      https://github.com/Danesprite/dragonfly/compare/74981c1...0.7.0
 [0.6.6b1]:    https://github.com/Danesprite/dragonfly/compare/0.6.5...0.6.6b1
 [0.6.5]:      https://github.com/Danesprite/dragonfly/compare/0.6.4-rc3...0.6.5

documentation/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = dragonfly
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

documentation/conf.py

@@ -2,7 +2,6 @@
 #
 
 import sys
-import os
 import os.path
 import re
 
@@ -22,15 +21,17 @@
 
 
 #---------------------------------------------------------------------------
-# Mock libraries that are not available on Read the Docs
+# Mock libraries that are only available on Windows platforms
+# (i.e. not on Read the Docs or *nix platforms)
 
-on_read_the_docs = (os.environ.get("READTHEDOCS", None) == "True")
-if on_read_the_docs:
+not_on_windows = not sys.platform.startswith("win")
+if not_on_windows:
     from mock import MagicMock
+
     class Mock(MagicMock):
         @classmethod
         def __getattr__(cls, name):
-            return Mock()
+            return MagicMock()
     mock_modules = ["ctypes", "ctypes.wintypes", "pythoncom",
                     "pywintypes", "win32api", "win32clipboard",
                     "win32com", "win32com.client",

documentation/make.bat

@@ -0,0 +1,37 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+        set SPHINXBUILD=python -msphinx
+)
+set SOURCEDIR=.
+set BUILDDIR=build
+set SPHINXPROJ=dragonfly
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+        echo.
+        echo.The Sphinx module was not found. Make sure you have Sphinx installed,
+        echo.then set the SPHINXBUILD environment variable to point to the full
+        echo.path of the 'sphinx-build' executable. Alternatively you may add the
+        echo.Sphinx directory to PATH.
+        echo.
+        echo.If you don't have Sphinx installed, grab it from
+        echo.http://sphinx-doc.org/
+        exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd
+

dragonfly/actions/sendinput.py

@@ -37,10 +37,16 @@ class KeyboardInput(Structure):
                 ("time", c_ulong),
                 ("dwExtraInfo", POINTER(c_ulong))]
 
-    # Nasty behavior of Win32 shift-navkey requires the navigation keys
-    #  always to to be treated as extended.  See:
-    #  http://www.xtremevbtalk.com/archive/index.php/t-203863.html
-    #  http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/winui/windowsuserinterface/userinput/keyboardinput/aboutkeyboardinput.asp
+    #  From https://docs.microsoft.com/en-us/windows/desktop/inputdev/about-keyboard-input#extended-key-flag
+    #     The extended keys consist of the ALT and CTRL keys
+    #     on the right-hand side of the keyboard; the INS, DEL, HOME,
+    #     END, PAGE UP, PAGE DOWN, and arrow keys in the clusters to
+    #     the left of the numeric keypad; the NUM LOCK key; the BREAK
+    #     (CTRL+PAUSE) key; the PRINT SCRN key; and the divide (/) and
+    #     ENTER keys in the numeric keypad.
+    #
+    #  It's unclear if the Windows keys are also "extended", so they
+    #  have been included for historical reasons.
     extended_keys = (
                      win32con.VK_UP,
                      win32con.VK_DOWN,
@@ -51,7 +57,15 @@ class KeyboardInput(Structure):
                      win32con.VK_PRIOR,
                      win32con.VK_NEXT,
                      win32con.VK_INSERT,
+                     win32con.VK_DELETE,
+                     win32con.VK_NUMLOCK,
+                     win32con.VK_RCONTROL,
+                     win32con.VK_RMENU,
+                     win32con.VK_PAUSE,
+                     win32con.VK_SNAPSHOT,
+                     win32con.VK_DIVIDE,
                      win32con.VK_LWIN,
+                     win32con.VK_RWIN,
                     )
 
     def __init__(self, virtual_keycode, down):

dragonfly/actions/typeables.py

@@ -222,19 +222,35 @@
     "delete":           Typeable(code=win32con.VK_DELETE, name='delete'),
     "del":              Typeable(code=win32con.VK_DELETE, name='del'),
 
-    # Modifier keys
+    # Main modifier keys
     "shift":            Typeable(code=win32con.VK_SHIFT, name='shift'),
     "control":          Typeable(code=win32con.VK_CONTROL, name='control'),
     "ctrl":             Typeable(code=win32con.VK_CONTROL, name='ctrl'),
     "alt":              Typeable(code=win32con.VK_MENU, name='alt'),
 
+    # Right modifier keys
+    "ralt":             Typeable(code=win32con.VK_RMENU, name='ralt'),
+    "rshift":           Typeable(code=win32con.VK_RSHIFT, name='rshift'),
+    "rcontrol":         Typeable(code=win32con.VK_RCONTROL, name='rcontrol'),
+    "rctrl":            Typeable(code=win32con.VK_RCONTROL, name='rctrl'),
+
     # Special keys
     "escape":           Typeable(code=win32con.VK_ESCAPE, name='escape'),
     "insert":           Typeable(code=win32con.VK_INSERT, name='insert'),
     "pause":            Typeable(code=win32con.VK_PAUSE, name='pause'),
     "win":              Typeable(code=win32con.VK_LWIN, name='win'),
+    "rwin":             Typeable(code=win32con.VK_RWIN, name='rwin'),
     "apps":             Typeable(code=win32con.VK_APPS, name='apps'),
     "popup":            Typeable(code=win32con.VK_APPS, name='popup'),
+    "snapshot":         Typeable(code=win32con.VK_SNAPSHOT, name='snapshot'),
+    "printscreen":      Typeable(code=win32con.VK_SNAPSHOT, name='printscreen'),
+
+    # Lock keys
+    # win32api.GetKeyState(code) could be used to toggle lock keys sensibly
+    # instead of using the up/down modifiers.
+    "scrolllock":       Typeable(code=win32con.VK_SCROLL, name='scrolllock'),
+    "numlock":          Typeable(code=win32con.VK_NUMLOCK, name='numlock'),
+    "capslock":         Typeable(code=win32con.VK_CAPITAL, name='capslock'),
 
     # Navigation keys
     "up":               Typeable(code=win32con.VK_UP, name='up'),

dragonfly/engines/backend_sphinx/config.py

@@ -15,14 +15,23 @@
 DECODER_CONFIG.set_string("-logfn", os.devnull)
 
 # Configuration for wake/sleep phrases
-# Note that the following CMU Sphinx tutorial has some advice on keyword thresholds
+# Note that the following CMU Sphinx tutorial has some advice on keyword threshold
 # values: https://cmusphinx.github.io/wiki/tutoriallm/#keyword-lists
 START_ASLEEP = True
 WAKE_PHRASE = "wake up"
 WAKE_PHRASE_THRESHOLD = 1e-20
 SLEEP_PHRASE = "go to sleep"
 SLEEP_PHRASE_THRESHOLD = 1e-40
 
+# Configuration for acoustic model training.
+# Relative directory paths will use the current working directory, i.e. where the
+# loader is.
+TRAINING_DATA_DIR = "training/"
+START_TRAINING_PHRASE = "start training session"
+START_TRAINING_THRESHOLD = 1e-48
+END_TRAINING_PHRASE = "end training session"
+END_TRAINING_THRESHOLD = 1e-45
+
 # Keyword arguments given to the PyAudio.open method for opening a stream from a
 # microphone. PyAudio streams are used by the engine to recognise speech from audio.
 # You may wish to change the values to be optimal for the models you are using;