diff --git a/RELEASE_NOTES.rst b/RELEASE_NOTES.rst index b48faa796..6e6c3c6ce 100644 --- a/RELEASE_NOTES.rst +++ b/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 diff --git a/artiq/frontend/aqctl_korad_ka3005p.py b/artiq/frontend/aqctl_korad_ka3005p.py index fb9ba6712..850e46262 100755 --- a/artiq/frontend/aqctl_korad_ka3005p.py +++ b/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 diff --git a/artiq/frontend/aqctl_lda.py b/artiq/frontend/aqctl_lda.py index cf3a36aae..429e0e6df 100755 --- a/artiq/frontend/aqctl_lda.py +++ b/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 diff --git a/artiq/frontend/aqctl_novatech409b.py b/artiq/frontend/aqctl_novatech409b.py index 3cc9ce7a4..60b6c92de 100755 --- a/artiq/frontend/aqctl_novatech409b.py +++ b/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 diff --git a/artiq/frontend/aqctl_thorlabs_tcube.py b/artiq/frontend/aqctl_thorlabs_tcube.py index e8e489c3e..dea1a0d65 100755 --- a/artiq/frontend/aqctl_thorlabs_tcube.py +++ b/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 diff --git a/artiq/frontend/artiq_browser.py b/artiq/frontend/artiq_browser.py index 692558616..5076225c7 100755 --- a/artiq/frontend/artiq_browser.py +++ b/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 diff --git a/artiq/frontend/artiq_client.py b/artiq/frontend/artiq_client.py index cc1b45858..e197d9896 100755 --- a/artiq/frontend/artiq_client.py +++ b/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", - help="increase logging level of the experiment") - parser_add.add_argument("-q", "--quiet", default=0, action="count", - help="decrease logging level of the experiment") + add_common_args(parser) parser_add.add_argument("file", metavar="FILE", help="file containing the experiment to run") parser_add.add_argument("arguments", metavar="ARGUMENTS", nargs="*", diff --git a/artiq/frontend/artiq_compile.py b/artiq/frontend/artiq_compile.py index 83cf3c079..766190200 100755 --- a/artiq/frontend/artiq_compile.py +++ b/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", diff --git a/artiq/frontend/artiq_coreanalyzer.py b/artiq/frontend/artiq_coreanalyzer.py index 96ea83ee6..2bd965004 100755 --- a/artiq/frontend/artiq_coreanalyzer.py +++ b/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')") diff --git a/artiq/frontend/artiq_coremgmt.py b/artiq/frontend/artiq_coremgmt.py index 11b75628d..270e01cc4 100755 --- a/artiq/frontend/artiq_coremgmt.py +++ b/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, diff --git a/artiq/frontend/artiq_ctlmgr.py b/artiq/frontend/artiq_ctlmgr.py index 6aeaee0f6..c16ed9b50 100755 --- a/artiq/frontend/artiq_ctlmgr.py +++ b/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") - 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") + add_common_args(parser) parser.add_argument( "-s", "--server", default="::1", diff --git a/artiq/frontend/artiq_dashboard.py b/artiq/frontend/artiq_dashboard.py index 3ee539713..98d3c2e53 100755 --- a/artiq/frontend/artiq_dashboard.py +++ b/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 diff --git a/artiq/frontend/artiq_devtool.py b/artiq/frontend/artiq_devtool.py index aacd813c7..e23f766fe 100755 --- a/artiq/frontend/artiq_devtool.py +++ b/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", diff --git a/artiq/frontend/artiq_flash.py b/artiq/frontend/artiq_flash.py index 783bc6264..bece15b71 100755 --- a/artiq/frontend/artiq_flash.py +++ b/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", diff --git a/artiq/frontend/artiq_influxdb.py b/artiq/frontend/artiq_influxdb.py index 3cc524f68..9650f5a7c 100755 --- a/artiq/frontend/artiq_influxdb.py +++ b/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 diff --git a/artiq/frontend/artiq_run.py b/artiq/frontend/artiq_run.py index 962e7a5e5..bc4f81ff5 100755 --- a/artiq/frontend/artiq_run.py +++ b/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", diff --git a/artiq/tools.py b/artiq/tools.py index 69d8351b5..e5517bebe 100644 --- a/artiq/tools.py +++ b/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): - group = parser.add_argument_group("verbosity") +def add_common_args(parser): + """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) diff --git a/doc/manual/developing_a_ndsp.rst b/doc/manual/developing_a_ndsp.rst index 4989aded6..1d786ca97 100644 --- a/doc/manual/developing_a_ndsp.rst +++ b/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