frontend: add --version flag to cmd line args (#1181)

RELEASE_NOTES.rst

@@ -8,7 +8,7 @@ ARTIQ-5
 
 5.0
 ***
-
+* :func:`~artiq.tools.verbosity_args` renamed to :func:`~artiq.tools.add_common_args`. New feature: adds an option to print the ARTIQ version.
 
 
 ARTIQ-4

artiq/frontend/aqctl_korad_ka3005p.py

@@ -26,7 +26,7 @@ def get_argparser():
     parser.add_argument(
         "--simulation", action="store_true",
         help="Put the driver in simulation mode, even if --device is used.")
-    verbosity_args(parser)
+    add_common_args(parser)
     return parser
 
 

artiq/frontend/aqctl_lda.py

@@ -23,7 +23,7 @@ def get_argparser():
                              "available device will be used.")
     parser.add_argument("--simulation", action="store_true",
                         help="Put the driver in simulation mode.")
-    verbosity_args(parser)
+    add_common_args(parser)
     return parser
 
 

artiq/frontend/aqctl_novatech409b.py

@@ -26,7 +26,7 @@ def get_argparser():
     parser.add_argument(
         "--simulation", action="store_true",
         help="Put the driver in simulation mode, even if --device is used.")
-    verbosity_args(parser)
+    add_common_args(parser)
     return parser
 
 

artiq/frontend/aqctl_thorlabs_tcube.py

@@ -22,7 +22,7 @@ def get_argparser():
                         help="Put the driver in simulation mode, even if "
                              "--device is used.")
     simple_network_args(parser, 3255)
-    verbosity_args(parser)
+    add_common_args(parser)
     return parser
 
 

artiq/frontend/artiq_browser.py

@@ -10,7 +10,7 @@ from PyQt5 import QtCore, QtGui, QtWidgets
 from quamash import QEventLoop
 
 from artiq import __artiq_dir__ as artiq_dir
-from artiq.tools import (verbosity_args, atexit_register_coroutine,
+from artiq.tools import (add_common_args, atexit_register_coroutine,
                          get_user_config_dir)
 from artiq.gui import state, applets, models, log
 from artiq.browser import datasets, files, experiments
@@ -38,7 +38,7 @@ def get_argparser():
         help="TCP port to use to connect to the master")
     parser.add_argument("select", metavar="SELECT", nargs="?",
                         help="directory to browse or file to load")
-    verbosity_args(parser)
+    add_common_args(parser)
     return parser
 
 

artiq/frontend/artiq_client.py

@@ -21,7 +21,7 @@ from artiq.protocols.pc_rpc import Client
 from artiq.protocols.sync_struct import Subscriber
 from artiq.protocols.broadcast import Receiver
 from artiq.protocols import pyon
-from artiq.tools import short_format, parse_arguments
+from artiq.tools import short_format, add_common_args, parse_arguments
 
 
 def clear_screen():
@@ -64,10 +64,7 @@ def get_argparser():
                                  "(defaults to head, ignored without -R)")
     parser_add.add_argument("-c", "--class-name", default=None,
                             help="name of the class to run")
-    parser_add.add_argument("-v", "--verbose", default=0, action="count",
+    add_common_args(parser)
-                            help="increase logging level of the experiment")
-    parser_add.add_argument("-q", "--quiet", default=0, action="count",
-                            help="decrease logging level of the experiment")
     parser_add.add_argument("file", metavar="FILE",
                             help="file containing the experiment to run")
     parser_add.add_argument("arguments", metavar="ARGUMENTS", nargs="*",

artiq/frontend/artiq_compile.py

@@ -15,7 +15,7 @@ logger = logging.getLogger(__name__)
 def get_argparser():
     parser = argparse.ArgumentParser(description="ARTIQ static compiler")
 
-    verbosity_args(parser)
+    add_common_args(parser)
     parser.add_argument("--device-db", default="device_db.py",
                         help="device database file (default: '%(default)s')")
     parser.add_argument("--dataset-db", default="dataset_db.pyon",

artiq/frontend/artiq_coreanalyzer.py

@@ -3,7 +3,7 @@
 import argparse
 import sys
 
-from artiq.tools import verbosity_args, init_logger
+from artiq.tools import add_common_args, init_logger
 from artiq.master.databases import DeviceDB
 from artiq.master.worker_db import DeviceManager
 from artiq.coredevice.comm_analyzer import (get_analyzer_dump,
@@ -14,7 +14,7 @@ def get_argparser():
     parser = argparse.ArgumentParser(description="ARTIQ core device "
                                                  "RTIO analysis tool")
 
-    verbosity_args(parser)
+    add_common_args(parser)
     parser.add_argument("--device-db", default="device_db.py",
                         help="device database file (default: '%(default)s')")
 

artiq/frontend/artiq_coremgmt.py

@@ -3,7 +3,7 @@
 import argparse
 import struct
 
-from artiq.tools import verbosity_args, init_logger
+from artiq.tools import add_common_args, init_logger
 from artiq.master.databases import DeviceDB
 from artiq.coredevice.comm_kernel import CommKernel
 from artiq.coredevice.comm_mgmt import CommMgmt
@@ -14,7 +14,7 @@ def get_argparser():
     parser = argparse.ArgumentParser(description="ARTIQ core device "
                                                  "management tool")
 
-    verbosity_args(parser)
+    add_common_args(parser)
     parser.add_argument("--device-db", default="device_db.py",
                        help="device database file (default: '%(default)s')")
     parser.add_argument("-D", "--device", default=None,

artiq/frontend/artiq_ctlmgr.py

@@ -10,18 +10,14 @@ import platform
 from artiq.protocols.pc_rpc import Server
 from artiq.protocols.logging import LogForwarder, SourceFilter
 from artiq.tools import (simple_network_args, atexit_register_coroutine,
-                         bind_address_from_args)
+                         bind_address_from_args, add_common_args)
 from artiq.devices.ctlmgr import ControllerManager
 
 
 def get_argparser():
     parser = argparse.ArgumentParser(description="ARTIQ controller manager")
 
-    group = parser.add_argument_group("verbosity")
+    add_common_args(parser)
-    group.add_argument("-v", "--verbose", default=0, action="count",
-                       help="increase logging level of the manager process")
-    group.add_argument("-q", "--quiet", default=0, action="count",
-                       help="decrease logging level of the manager process")
 
     parser.add_argument(
         "-s", "--server", default="::1",

artiq/frontend/artiq_dashboard.py

@@ -10,7 +10,7 @@ from PyQt5 import QtCore, QtGui, QtWidgets
 from quamash import QEventLoop
 
 from artiq import __artiq_dir__ as artiq_dir, __version__ as artiq_version
-from artiq.tools import (atexit_register_coroutine, verbosity_args,
+from artiq.tools import (atexit_register_coroutine, add_common_args,
                          get_user_config_dir)
 from artiq.protocols.pc_rpc import AsyncioClient, Client
 from artiq.protocols.broadcast import Receiver
@@ -39,7 +39,7 @@ def get_argparser():
         help="database file for local GUI settings, "
              "by default in {} and dependant on master hostname".format(
                                                         get_user_config_dir()))
-    verbosity_args(parser)
+    add_common_args(parser)
     return parser
 
 

artiq/frontend/artiq_devtool.py

@@ -16,7 +16,7 @@ import shutil
 import re
 import shlex
 
-from artiq.tools import verbosity_args, init_logger
+from artiq.tools import add_common_args, init_logger
 from artiq.remoting import SSHClient
 from artiq.coredevice.comm_mgmt import CommMgmt
 
@@ -28,7 +28,7 @@ def get_argparser():
         description="ARTIQ core device development tool",
         formatter_class=argparse.ArgumentDefaultsHelpFormatter)
 
-    verbosity_args(parser)
+    add_common_args(parser)
 
     parser.add_argument("-t", "--target", metavar="TARGET",
                         type=str, default="kasli",

artiq/frontend/artiq_flash.py

@@ -11,7 +11,7 @@ from functools import partial
 from collections import defaultdict
 
 from artiq import __artiq_dir__ as artiq_dir
-from artiq.tools import verbosity_args, init_logger
+from artiq.tools import add_common_args, init_logger
 from artiq.remoting import SSHClient, LocalClient
 from artiq.frontend.bit2bin import bit2bin
 
@@ -41,7 +41,7 @@ Prerequisites:
       plugdev group: 'sudo adduser $USER plugdev' and re-login.
 """)
 
-    verbosity_args(parser)
+    add_common_args(parser)
 
     parser.add_argument("-n", "--dry-run",
                         default=False, action="store_true",

artiq/frontend/artiq_influxdb.py

@@ -63,7 +63,7 @@ def get_argparser():
              "If the file is not found, no patterns are loaded "
              "(everything is logged).")
     simple_network_args(parser, [("control", "control", 3248)])
-    verbosity_args(parser)
+    add_common_args(parser)
     return parser
 
 

artiq/frontend/artiq_run.py

@@ -126,7 +126,7 @@ def get_argparser(with_file=True):
     parser = argparse.ArgumentParser(
         description="Local experiment running tool")
 
-    verbosity_args(parser)
+    add_common_args(parser)
     parser.add_argument("--device-db", default="device_db.py",
                         help="device database file (default: '%(default)s')")
     parser.add_argument("--dataset-db", default="dataset_db.pyon",

artiq/tools.py

@@ -1,22 +1,21 @@
+import asyncio
+import atexit
+import collections
 import importlib.machinery
 import logging
-import sys
-import asyncio
-import collections
-import atexit
-import string
 import os
+import string
+import sys
 
 import numpy as np
 
+from artiq import __version__ as artiq_version
+from artiq.appdirs import user_config_dir
 from artiq.language.environment import is_experiment
 from artiq.protocols import pyon
-from artiq.appdirs import user_config_dir
-from artiq import __version__ as artiq_version
-
 
 __all__ = ["parse_arguments", "elide", "short_format", "file_import",
-           "get_experiment", "verbosity_args", "simple_network_args",
+           "get_experiment", "add_common_args", "simple_network_args",
            "multiline_log_config", "init_logger", "bind_address_from_args",
            "atexit_register_coroutine", "exc_to_warning",
            "asyncio_wait_or_cancel", "TaskObject", "Condition",
@@ -105,12 +104,22 @@ def get_experiment(module, experiment=None):
     return exps[0][1]
 
 
-def verbosity_args(parser):
+def add_common_args(parser):
-    group = parser.add_argument_group("verbosity")
+    """Add common utility arguments to the cmd parser.
+    
+    Arguments added:
+        * `-v`/`-q`: increase or decrease the default logging levels. 
+            Repeat for higher levels.
+        * `--version`: print the ARTIQ version
+    """
+    group = parser.add_argument_group("common")
     group.add_argument("-v", "--verbose", default=0, action="count",
                        help="increase logging level")
     group.add_argument("-q", "--quiet", default=0, action="count",
                        help="decrease logging level")
+    group.add_argument("--version", action="version",
+                       version="ARTIQ v{}".format(artiq_version),
+                       help="print the ARTIQ version number")
 
 
 def simple_network_args(parser, default_port):
@@ -127,7 +136,7 @@ def simple_network_args(parser, default_port):
                            help="TCP port to listen on (default: %(default)d)")
     else:
         for name, purpose, default in default_port:
-            h = ("TCP port to listen on for {} connections (default: {})"
+            h = ("TCP port for {} connections (default: {})"
                  .format(purpose, default))
             group.add_argument("--port-" + name, default=default, type=int,
                                help=h)

doc/manual/developing_a_ndsp.rst

@@ -132,14 +132,14 @@ We suggest that you define a function ``get_argparser`` that returns the argumen
 Logging
 -------
 
-For the debug, information and warning messages, use the ``logging`` Python module and print the log on the standard error output (the default setting). The logging level is by default "WARNING", meaning that only warning messages and more critical messages will get printed (and no debug nor information messages). By calling the ``verbosity_args()`` with the parser as argument, you add support for the ``--verbose`` (``-v``) and ``--quiet`` (``-q``) arguments in the parser. Each occurence of ``-v`` (resp. ``-q``) in the arguments will increase (resp. decrease) the log level of the logging module. For instance, if only one ``-v`` is present in the arguments, then more messages (info, warning and above) will get printed. If only one ``-q`` is present in the arguments, then only errors and critical messages will get printed. If ``-qq`` is present in the arguments, then only critical messages will get printed, but no debug/info/warning/error.
+For the debug, information and warning messages, use the ``logging`` Python module and print the log on the standard error output (the default setting). The logging level is by default "WARNING", meaning that only warning messages and more critical messages will get printed (and no debug nor information messages). By calling :func:`artiq.tools.add_common_args` with the parser as argument, you add support for the ``--verbose`` (``-v``) and ``--quiet`` (``-q``) arguments in the parser. Each occurence of ``-v`` (resp. ``-q``) in the arguments will increase (resp. decrease) the log level of the logging module. For instance, if only one ``-v`` is present in the arguments, then more messages (info, warning and above) will get printed. If only one ``-q`` is present in the arguments, then only errors and critical messages will get printed. If ``-qq`` is present in the arguments, then only critical messages will get printed, but no debug/info/warning/error.
 
 The program below exemplifies how to use logging: ::
 
     import argparse
     import logging
 
-    from artiq.tools import verbosity_args, init_logger
+    from artiq.tools import add_common_args, init_logger
 
 
     # get a logger that prints the module name
@@ -151,7 +151,7 @@ The program below exemplifies how to use logging: ::
         parser.add_argument("--someargument",
                             help="some argument")
         # [...]
-        verbosity_args(parser) # This adds the -q and -v handling
+        add_common_args(parser) # This adds the -q and -v handling
         return parser