list_ports: add -n N option, doc update
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index 32829dd..36293ad 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -501,7 +501,7 @@
- .. note:: The following members are deprecated nd will be removed in a
+ .. note:: The following members are deprecated and will be removed in a
future release.
.. attribute:: portstr
@@ -1192,8 +1192,36 @@
only those that match the regexp.
+Command line usage
+
+Help for ``python -m serial.tools.list_ports``::
+
+ usage: list_ports.py [-h] [-v] [-q] [-n N] [regexp]
+
+ Serial port enumeration
+
+ positional arguments:
+ regexp only show ports that match this regex
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose show more messages
+ -q, --quiet suppress all messages
+ -n N only output the N-th entry
+
+Examples:
+
+- List all ports with details::
+
+ python -m serial.tools.list_ports -v
+
+- List the 2nd port matching a USB VID:PID pattern::
+
+ python -m serial.tools.list_ports 1234:5678 -q -n 2
+
+
serial.tools.miniterm
------------------------
+---------------------
.. module:: serial.tools.miniterm
.. versionadded:: 2.6
diff --git a/serial/tools/list_ports.py b/serial/tools/list_ports.py
index 3b32b92..2a6b350 100644
--- a/serial/tools/list_ports.py
+++ b/serial/tools/list_ports.py
@@ -68,6 +68,11 @@
action='store_true',
help='suppress all messages')
+ parser.add_argument(
+ '-n',
+ type=int,
+ help='only output the N-th entry')
+
args = parser.parse_args()
hits = 0
@@ -78,11 +83,12 @@
else:
iterator = sorted(comports())
# list them
- for port, desc, hwid in iterator:
- sys.stdout.write("{:20}\n".format(port))
- if args.verbose:
- sys.stdout.write(" desc: {}\n".format(desc))
- sys.stdout.write(" hwid: {}\n".format(hwid))
+ for n, (port, desc, hwid) in enumerate(iterator, 1):
+ if args.n is None or args.n == n:
+ sys.stdout.write("{:20}\n".format(port))
+ if args.verbose:
+ sys.stdout.write(" desc: {}\n".format(desc))
+ sys.stdout.write(" hwid: {}\n".format(hwid))
hits += 1
if not args.quiet:
if hits: