feat: change comment in dictConfig json file to // from #

Emacs json mode at least will properly indent when using // as a
comment character and not #.

Author: rouilj

doc/admin_guide.txt

@@ -110,15 +110,18 @@ dictConfigs are specified in JSON format with support for comments.
 The file name in the tracker's config for the ``logging`` -> ``config``
 setting must end with ``.json`` to choose the correct processing.
 
-Comments have to be in one of two forms:
+Comments have to be in one of two forms based on javascript line
+comments:
 
-1. A ``#`` with preceding white space is considered a comment and is
-   stripped from the file before being passed to the json parser. This
-   is a "block comment".
+1. A ``//`` possibly indented with whitespace on a line is considereda
+   a comment and is stripped from the file before being passed to the
+   json parser. This is a "line comment".
 
-2. A ``#`` preceded by at least three
-   white space characters is stripped from the end of the line before
-   begin passed to the json parser. This is an "inline comment".
+2. A ``//` with at least three white space characters before it is
+   stripped from the end of the line before begin passed to the json
+   parser. This is an "inline comment".
+
+Block style comments are not supported.
 
 Other than this the file is a standard json file that matches the
 `Configuration dictionary schema
@@ -129,9 +132,12 @@ defined in the Python documentation.
 Example dictConfig Logging Config
 .................................
 
-Note that this file is not actually JSON format as it include comments.
-So you can not use tools that expect JSON (linters, formatters) to
-work with it.
+Note that this file is not actually JSON format as it include
+comments.  However by using javascript style comments, some tools that
+expect JSON (editors, linters, formatters) might work with it.  A
+command like ``sed -e 's#^\s*//.*##' -e 's#\s*\s\s\s//.*##'
+logging.json`` can be used to strip comments for programs that need
+it.
 
 The config below works with the `Waitress wsgi server
 <https://github.com/Pylons/waitress>`_ configured to use the
@@ -143,35 +149,35 @@ the tracker home. The tracker home is the subdirectory demo under the
 current working directory. The commented config is::
 
   {
-    "version": 1,   # only supported version
-    "disable_existing_loggers": false,      # keep the wsgi loggers
+    "version": 1,   // only supported version
+    "disable_existing_loggers": false,      // keep the wsgi loggers
 
     "formatters": {
-      # standard format for Roundup messages
+      // standard format for Roundup messages
       "standard": {
-        "format": "%(asctime)s %(levelname)s %(name)s:%(module)s %(msg)s"
+        "format": "%(asctime)s %(ctx_id)s %(levelname)s %(name)s:%(module)s %(msg)s"
       },
-      # used for waitress wsgi server to produce httpd style logs
+      // used for waitress wsgi server to produce httpd style logs
       "http": {
 	"format": "%(message)s"
       }
     },
     "handlers": {
-      # create an access.log style http log file
+      // create an access.log style http log file
       "access": {
 	"level": "INFO",
 	"formatter": "http",
 	"class": "logging.FileHandler",
 	"filename": "demo/access.log"
       },
-      # logging for roundup.* loggers
+      // logging for roundup.* loggers
       "roundup": {
 	"level": "DEBUG",
 	"formatter": "standard",
 	"class": "logging.FileHandler",
 	"filename": "demo/roundup.log"
       },
-      # print to stdout - fall through for other logging
+      // print to stdout - fall through for other logging
       "default": {
 	"level": "DEBUG",
 	"formatter": "standard",
@@ -187,30 +193,30 @@ current working directory. The commented config is::
 	"level": "DEBUG",
 	"propagate": false
       },
-      # used by roundup.* loggers
+      // used by roundup.* loggers
       "roundup": {
 	"handlers": [
 	  "roundup"
 	],
 	"level": "DEBUG",
-	"propagate": false   # note pytest testing with caplog requires
-			     # this to be true
+	"propagate": false   // note pytest testing with caplog requires
+			     // this to be true
       },
       "roundup.hyperdb": {
 	"handlers": [
 	  "roundup"
 	],
-	"level": "INFO",    # can be a little noisy use INFO for production
+	"level": "INFO",    // can be a little noisy use INFO for production
 	"propagate": false
       },
-     "roundup.wsgi": {    # using the waitress framework
+     "roundup.wsgi": {    // using the waitress framework
 	"handlers": [
 	  "roundup"
 	],
 	"level": "DEBUG",
 	"propagate": false
       },
-     "roundup.wsgi.translogger": {   # httpd style logging
+     "roundup.wsgi.translogger": {   // httpd style logging
 	"handlers": [
 	  "access"
 	],

roundup/configuration.py

@@ -2343,9 +2343,9 @@ def reset(self):
     def load_config_dict_from_json_file(self, filename):
         import json
         comment_re = re.compile(
-            r"""^\s*\#.*  # comment at beginning of line possibly indented.
+            r"""^\s*//#.*  # comment at beginning of line possibly indented.
             |  # or
-            ^(.*)\s\s\s\#.*  # comment char preceeded by at least three spaces.
+            ^(.*)\s\s\s\//.*  # comment char preceeded by at least three spaces.
             """, re.VERBOSE)
 
         config_list = []
@@ -2371,8 +2371,8 @@ def load_config_dict_from_json_file(self, filename):
             line = config_list[error_at_doc_line - 1][:-1]
 
             hint = ""
-            if line.find('#') != -1:
-                hint = "\nMaybe bad inline comment, 3 spaces needed before #."
+            if line.find('//') != -1:
+                hint = "\nMaybe bad inline comment, 3 spaces needed before //."
 
             raise LoggingConfigError(
                 'Error parsing json logging dict (%(file)s) '

test/test_config.py

@@ -1117,35 +1117,35 @@ def testDictLoggerConfigViaJson(self):
         # good base test case
         config1 = dedent("""
            {
-              "version": 1,   # only supported version
-              "disable_existing_loggers": false,      # keep the wsgi loggers
+              "version": 1,   // only supported version
+              "disable_existing_loggers": false,      // keep the wsgi loggers
 
               "formatters": {
-                # standard Roundup formatter including context id.
+                // standard Roundup formatter including context id.
                   "standard": {
                     "format": "%(asctime)s %(levelname)s %(name)s:%(module)s %(msg)s"
                 },
-                # used for waitress wsgi server to produce httpd style logs
+                // used for waitress wsgi server to produce httpd style logs
                 "http": {
                   "format": "%(message)s"
                 }
               },
               "handlers": {
-                # create an access.log style http log file
+                // create an access.log style http log file
                 "access": {
                   "level": "INFO",
                   "formatter": "http",
                   "class": "logging.FileHandler",
                   "filename": "_test_instance/access.log"
                 },
-                # logging for roundup.* loggers
+                // logging for roundup.* loggers
                 "roundup": {
                   "level": "DEBUG",
                   "formatter": "standard",
                   "class": "logging.FileHandler",
                   "filename": "_test_instance/roundup.log"
                 },
-                # print to stdout - fall through for other logging
+                // print to stdout - fall through for other logging
                 "default": {
                   "level": "DEBUG",
                   "formatter": "standard",
@@ -1156,35 +1156,35 @@ def testDictLoggerConfigViaJson(self):
               "loggers": {
                 "": {
                   "handlers": [
-                    "default"     # used by wsgi/usgi
+                    "default"     // used by wsgi/usgi
                   ],
                   "level": "DEBUG",
                   "propagate": false
                 },
-                # used by roundup.* loggers
+                // used by roundup.* loggers
                 "roundup": {
                   "handlers": [
                     "roundup"
                   ],
                   "level": "DEBUG",
-                  "propagate": false   # note pytest testing with caplog requires
-                                       # this to be true
+                  "propagate": false   // note pytest testing with caplog requires
+                                       // this to be true
                 },
                 "roundup.hyperdb": {
                   "handlers": [
                     "roundup"
                   ],
-                  "level": "INFO",    # can be a little noisy INFO for production
+                  "level": "INFO",    // can be a little noisy INFO for production
                   "propagate": false
                 },
-               "roundup.wsgi": {    # using the waitress framework
+               "roundup.wsgi": {    // using the waitress framework
                   "handlers": [
                     "roundup"
                   ],
                   "level": "DEBUG",
                   "propagate": false
                 },
-               "roundup.wsgi.translogger": {   # httpd style logging
+               "roundup.wsgi.translogger": {   // httpd style logging
                   "handlers": [
                     "access"
                   ],
@@ -1215,7 +1215,7 @@ def testDictLoggerConfigViaJson(self):
         self.assertEqual(config['version'], 1)
 
         # broken inline comment misformatted
-        test_config = config1.replace(": 1,   #", ": 1, #")
+        test_config = config1.replace(": 1,   //", ": 1, //")
         with open(log_config_filename, "w") as log_config_file:
             log_config_file.write(test_config)
 
@@ -1226,9 +1226,9 @@ def testDictLoggerConfigViaJson(self):
             cm.exception.args[0],
             ('Error parsing json logging dict '
              '(%s) near \n\n     '
-             '"version": 1, # only supported version\n\nExpecting '
+             '"version": 1, // only supported version\n\nExpecting '
              'property name enclosed in double quotes: line 3 column 18.\n'
-             'Maybe bad inline comment, 3 spaces needed before #.' %
+             'Maybe bad inline comment, 3 spaces needed before //.' %
              log_config_filename)
         )
 
@@ -1318,8 +1318,8 @@ def testDictLoggerConfigViaJson(self):
 
         # broken invalid level MANGO
         test_config = config1.replace(
-            ': "INFO",    # can',
-            ': "MANGO",    # can')
+            ': "INFO",    // can',
+            ': "MANGO",    // can')
         with open(log_config_filename, "w") as log_config_file:
             log_config_file.write(test_config)