update todos in readme
[ppt-control.git] / ppt_control / config.py
old mode 100644 (file)
new mode 100755 (executable)
index 74df1f3..a1e90ab
-from configparser import ConfigParser
-from pkg_resources import Requirement, resource_filename
-
-global prefs
-prefs = None
-
-defaults = {
-        'Main': {
-            'logging': 'debug',
-            'cache': r'''C:\Windows\Temp\ppt-cache''',
-            'cache_format': 'JPG',
-            'cache_timeout': 5*60,
-            'cache_init': True,
-            'blackwhite': 'both',
-            'refresh': 2,
-            'disable_protected': False
-        },
-        'HTTP': {
-            'interface': '',
-            'port': 80
-        },
-        'WebSocket': {
-            'interface': '0.0.0.0',
-            'port': 5678
-        }
-}
-
-
-def loadconf(configpaths):
-    """
-    Initial setup for a ConfigParser object. `configpaths` should be a list of
-    configuration files to load (typically only one). To use the generated
-    ConfigParser, use `import logparse.config` and then `config.prefs.get(..)`.
-    The prefs object is returned after creation as a convenience but this method
-    should only be called once per runtime.
-    """
-    prefs = ConfigParser()
-    prefs.read_dict(defaults)
-    try:
-        success = prefs.read(configpaths)
-        print("Loaded {0} config file(s): {1}".format(
-                str(len(success)), str(success)))
-    except Exception as e:
-        print("Error processing config: " + str(e))
-    return prefs
-
+from configparser import ConfigParser\r
+\r
+prefs = None\r
+\r
+defaults = {\r
+        'Main': {\r
+            # Logging level\r
+            # Options: debug, info, warning, error, critical\r
+            # (see https://docs.python.org/3/howto/logging.html#when-to-use-logging)\r
+            'logging': 'debug',\r
+\r
+            # Cache location\r
+            # Directory to store slide preview images for each presentation\r
+            'cache': r'''C:\Windows\Temp\ppt-cache''',\r
+\r
+            # Cache format\r
+            # Can be set to any image filter set in the registry, but most commonly JPG or PNG\r
+            # (see https://docs.microsoft.com/en-us/office/vba/api/powerpoint.slide.export)\r
+            'cache_format': 'JPG',\r
+\r
+            # Cache timeout\r
+            # Time after which slides should be exported again to reflect any changes made in the\r
+            # PowerPoint editor. Value is in seconds.\r
+            'cache_timeout': 5*60,\r
+\r
+            # Cache initialisation\r
+            # Whether to export all slides when a slideshow is started. Can be set to any falsy or\r
+            # truthy value.\r
+            'cache_init': True,\r
+\r
+            # Black-white behaviour\r
+            # Sets the behaviour when returning from black or white mode. Options: "both", "literal"\r
+            # In PowerPoint's presenter view, if the slideshow is in black or white screen mode,\r
+            # attempting to switch to the other mode (white/black) will result in the slideshow\r
+            # returning to a normal (visible) state, rather than white/black. This behaviour is\r
+            # also the default for ppt-control, and is set by setting the value of "blackwhite"\r
+            # to "both" (since when the slideshow is in black or white mode, requesting either\r
+            # of black or white mode will return the slideshow to normal). The more intuitive\r
+            # settings is "literal", whereby when the slideshow is in black or white mode, \r
+            # pressing the button corresponding to the mode that the slideshow is already in will\r
+            # return the slideshow to normal mode, and pressing the other button will put the \r
+            # slideshow into that mode.\r
+            'blackwhite': 'both',\r
+\r
+            # Refresh interval\r
+            # Describes the number of seconds between backend updates, which consist of:\r
+            # - synchronisation of PowerPoint's events with the internal state. \r
+            # - updating the interface (systray icon) status\r
+            # - check for PowerPoint files that have been opened in protected view\r
+            # You could set a shorter value here, but these updates don't have to be instant so\r
+            # the default value of 2 seconds should work fine.\r
+            'refresh': 2,\r
+\r
+            # Disable protecte view\r
+            # If set to a truthy value, ppt-control will attempt to disable protected view on files\r
+            # which have been opened in protected view. Obviously this introduces some security risk,\r
+            # so if you are uncomfortable with this, leave it off and you will have to disable \r
+            # protected view for each file manually to be able to control it will ppt-control.\r
+            'disable_protected': True\r
+        },\r
+        'HTTP': {\r
+            # HTTP interface\r
+            # The interface to listen for HTTP requests on. Change this if you want to restrict the\r
+            # HTTP frontend to a specific network. A blank value means all interfaces.\r
+            'interface': '',\r
+\r
+            # HTTP port\r
+            # The port to listen for HTTP requests on. The default value of 80 is the standard \r
+            # port for HTTP, so when set to this value you don't need to include the port number\r
+            # in the URL when navigating to the frontend. For all other values you will need to \r
+            # specify the port number in the web browser (except 443, but that's a bad idea).\r
+            'port': 80\r
+        },\r
+        'WebSocket': {\r
+            # WebSocket interface\r
+            # The interface to listen for WebSocket requests on. Change this if you want to restrict\r
+            # the WebSocket interface to a specific network. A value of 0.0.0.0 means all interfaces.\r
+            'interface': '0.0.0.0',\r
+\r
+            # WebSocket port\r
+            # The port to listen for WebSocket requests on. This needs to match the port specified in\r
+            # whatever frontend you are using (e.g. in the JS code for the HTTP frontend, or in the\r
+            # script settings for the OBS frontend).\r
+            'port': 5678\r
+        }\r
+}\r
+\r
+\r
+def loadconf(configpaths):\r
+    """\r
+    Initial setup for a ConfigParser object. `configpaths` should be a list of\r
+    configuration files to load (typically only one). To use the generated\r
+    ConfigParser, use `import logparse.config` and then `config.prefs.get(..)`.\r
+    The prefs object is returned after creation as a convenience but this method\r
+    should only be called once per runtime.\r
+    """\r
+    prefs = ConfigParser()\r
+    prefs.read_dict(defaults)\r
+    try:\r
+        success = prefs.read(configpaths)\r
+        print("Loaded {0} config file(s): {1}".format(\r
+                str(len(success)), str(success)))\r
+    except Exception as e:\r
+        print("Error processing config: " + str(e))\r
+    return prefs\r
+\r
+def export_defaults(file):\r
+    """\r
+    Write the default settings to a file object, including comments and with spaces around \r
+    delimeters. This function is intended to be used to populate the config file with defaults\r
+    after installation.\r
+    """\r
+    prefs = loadconf([])\r
+    prefs.write(file, space_around_delimiters=True)
\ No newline at end of file