remove 3.x compatibility interface

improve manpage

Author: anon

doc/manpages/qvm-ls.rst

@@ -8,8 +8,8 @@ Synopsis
 
 :command:`qvm-ls` [--verbose] [--quiet] [--help] [--all]
                   [--exclude *EXCLUDE*] [--spinner] [--no-spinner]
-                  [--format *FORMAT* | --fields *FIELD* [*FIELD* ...] | --disk | --network | --kernel]
-                  [--tree] [--raw-data] [--raw-list] [--help-formats]
+                  [--format *FORMAT* | --fields *FIELD*[,*FIELD* ...]]
+                  [--tree] [--raw-data] [--help-formats]
                   [--help-columns] [--class *CLASS* [*CLASS* ...]]
                   [--label *LABEL* [*LABEL* ...]] [--tags *TAG* [*TAG* ...]]
                   [--exclude-tags *TAG* [*TAG* ...]] [--running] [--paused]
@@ -75,9 +75,10 @@ Formatting options
 
 .. option:: --fields=FIELD,..., -O FIELD,...
 
-   Sets format to specified set of columns. This gives more control over
-   :option:`--format`. All columns along with short descriptions can be listed
-   with :option:`--help-columns`.
+   Sets format to a comma-separated list of columns. This gives more control
+   over :option:`--format`. All predefined columns can be listed with
+   :option:`--help-columns`. In addition, any VM property name (as shown by
+   :program:`qvm-prefs --help-properties`) may be used as a column.
 
 .. option:: --tree, -t
 
@@ -89,23 +90,6 @@ Formatting options
    Output data in easy to parse format. Table header is skipped and columns are
    separated by `|` character.
 
-.. option:: --raw-list
-
-   Give plain list of VM names, without header or separator. Useful in scripts.
-   Same as --raw-data --fields=name
-
-.. option:: --disk, -d
-
-   Same as --format=disk, for compatibility with Qubes 3.x
-
-.. option:: --network, -n
-
-   Same as --format=network, for compatibility with Qubes 3.x
-
-.. option:: --kernel, -k
-
-   Same as --format=kernel, for compatibility with Qubes 3.x
-
 .. option:: --help-columns
 
    List all available columns with short descriptions and exit.
@@ -160,13 +144,15 @@ Filtering options
 
 .. option:: --features FEATURE=VALUE ...
 
-   Filter results to qubes that match all specified features. Omitted VALUE
-   means None (unset). Empty value means "" or '' (blank)
+   Filter results to qubes that match all specified features. ``KEY=``
+   matches qubes where the feature is unset. ``KEY=''`` or
+   ``KEY=""`` matches qubes where the feature is set to a blank string.
 
 .. option:: --prefs PREFERENCE=VALUE ...
 
-   Filter results to qubes that match all specified preferences. Omitted VALUE
-   means None (unset). Empty value means "" or '' (blank)
+   Filter results to qubes that match all specified preferences. ``KEY=``
+   matches qubes where the preference is unset. ``KEY=''`` or ``KEY=""`` matches
+   qubes where the preference is set to a blank string.
 
 Sorting options
 ---------------

qubesadmin/tests/tools/qvm_ls.py

@@ -117,14 +117,6 @@ def test_102_list_selected(self):
             'NAME     STATE    CLASS   LABEL  TEMPLATE  NETVM\n'
             'test-vm  Running  TestVM  green  template  sys-net\n')
 
-    def test_102_raw_list(self):
-        app = TestApp()
-        with qubesadmin.tests.tools.StdoutBuffer() as stdout:
-            qubesadmin.tools.qvm_ls.main(['--raw-list'], app=app)
-        self.assertEqual(stdout.getvalue(),
-            'dom0\n'
-            'test-vm\n')
-
     def test_103_list_all(self):
         app = TestApp()
         with qubesadmin.tests.tools.StdoutBuffer() as stdout:
@@ -150,28 +142,28 @@ def test_104_wildcards(self):
             ]
         )
         with qubesadmin.tests.tools.StdoutBuffer() as stdout:
-            qubesadmin.tools.qvm_ls.main(['--raw-list', 'fedora*'], app=app)
+            qubesadmin.tools.qvm_ls.main(['--raw-data', '--fields=name', 'fedora*'], app=app)
         self.assertEqual(stdout.getvalue(),
         'fedora-41\nfedora-41-minimal\nfedora-41-xfce\nfedora-rawhide\n')
 
         with qubesadmin.tests.tools.StdoutBuffer() as stdout:
-            qubesadmin.tools.qvm_ls.main(['--raw-list', '*minimal'], app=app)
+            qubesadmin.tools.qvm_ls.main(['--raw-data', '--fields=name', '*minimal'], app=app)
         self.assertEqual(stdout.getvalue(),
         'debian-13-minimal\nfedora-41-minimal\n')
 
         with qubesadmin.tests.tools.StdoutBuffer() as stdout:
-            qubesadmin.tools.qvm_ls.main(['--raw-list', '????'], app=app)
+            qubesadmin.tools.qvm_ls.main(['--raw-data', '--fields=name', '????'], app=app)
         self.assertEqual(stdout.getvalue(),
         'dom0\n')
 
         with qubesadmin.tests.tools.StdoutBuffer() as stdout:
-            qubesadmin.tools.qvm_ls.main(['--raw-list', '??????-[rs]*'],
+            qubesadmin.tools.qvm_ls.main(['--raw-data', '--fields=name', '??????-[rs]*'],
                                          app=app)
         self.assertEqual(stdout.getvalue(),
         'debian-sid\nfedora-rawhide\n')
 
         with qubesadmin.tests.tools.StdoutBuffer() as stdout:
-            qubesadmin.tools.qvm_ls.main(['--raw-list', '??????-[!14s]*'],
+            qubesadmin.tools.qvm_ls.main(['--raw-data', '--fields=name', '??????-[!14s]*'],
                                          app=app)
         self.assertEqual(stdout.getvalue(),
         'fedora-rawhide\n')

qubesadmin/tools/qvm_ls.py

@@ -446,6 +446,7 @@ def tree_append_child(self, parent, level):
     def sort_to_tree(self, domains):
         '''Sort the domains as a network tree. It returns a list of sets. Each
         tuple stores the insertion of the cell name and the vm object.
+        Note: mutates `domains` to an empty list
 
         :param list() domains: The domains which will be sorted
         :return list(tuple()) tree: returns a list of tuple(insertion, vm)
@@ -527,13 +528,12 @@ def sort_numeric(field: str) -> int:
                     continue
 
 
-#: Available formats. Feel free to plug your own one.
+# Available formats
 formats = {
     'simple': ('name', 'state', 'class', 'label', 'template', 'netvm'),
     'network': ('name', 'state', 'netvm', 'ip', 'ipback', 'gateway'),
     'kernel': ('name', 'state', 'class', 'template', 'kernel', 'kernelopts'),
     'full': ('name', 'state', 'class', 'label', 'qid', 'xid', 'uuid'),
-#   'perf': ('name', 'state', 'cpu', 'memory'),
     'prefs': ('name', 'label', 'template', 'netvm',
         'vcpus', 'initialmem', 'maxmem', 'virt_mode'),
     'disk': ('name', 'state', 'disk',
@@ -632,7 +632,7 @@ def get_parser():
         epilog='available formats (see --help-formats):\n{}\n\n'
                'available columns (see --help-columns):\n{}'.format(
                 wrapper.fill(', '.join(sorted(formats.keys()))),
-                wrapper.fill(', '.join(sorted(sorted(Column.columns.keys()))))))
+                wrapper.fill(', '.join(sorted(Column.columns.keys())))))
 
     parser_format = parser.add_argument_group(title='formatting options')
     parser_format_exclusive = parser_format.add_mutually_exclusive_group()
@@ -653,7 +653,7 @@ def get_parser():
         help='Display specify data of specified VMs. Intended for '
              'bash-parsing.')
 
-    # shortcuts, compatibility with Qubes 3.2
+    # helpful shortcuts
     parser_format.add_argument('--raw-list', action='store_true',
         help='Same as --raw-data --fields=name')
 
@@ -743,10 +743,6 @@ def get_parser():
 
     parser.set_defaults(spinner=True)
 
-#   parser.add_argument('--conf', '-c',
-#       action='store', metavar='CFGFILE',
-#       help='Qubes config file')
-
     return parser
 
 
@@ -769,10 +765,6 @@ def main(args=None, app=None):
     # one call per property
     args.app.cache_enabled = True
 
-    if args.raw_list:
-        args.raw_data = True
-        args.fields = 'name'
-
     if args.fields:
         columns = [col.strip() for col in args.fields.split(',')]
     else: