list_ports: add -n N option, doc update

2 files changed, 41 insertions, 7 deletions

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 @@ Native ports
 
 
 
-    .. 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 @@ serial.tools.list_ports``). It also contains the following functions.
     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 @@ def main():
             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 @@ def main():
     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: