[Python-checkins] GH-88597: Rename uuid's new CLI args to be in line with uuidgen. (#101248)

[gpshead]

https://github.com/python/cpython/commit/952a1d9cc970508b280af475c0be1809692f0c76
commit: 952a1d9cc970508b280af475c0be1809692f0c76
branch: main
author: achhina <aman.s.chhina at gmail.com>
committer: gpshead <greg at krypto.org>
date: 2023-01-25T09:39:42-08:00
summary:

GH-88597: Rename uuid's new CLI args to be in line with uuidgen. (#101248)

this way they match an existing uuidgen command line tool.

files:
M Doc/library/uuid.rst
M Lib/test/test_uuid.py
M Lib/uuid.py

diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst
index 804884dee0a2..38b6434f467f 100644
--- a/Doc/library/uuid.rst
+++ b/Doc/library/uuid.rst
@@ -272,7 +272,7 @@ The :mod:`uuid` module can be executed as a script from the command line.
 
 .. code-block:: sh
 
-   python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5}] [-ns NAMESPACE] [-n NAME]
+   python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5}] [-n NAMESPACE] [-N NAME]
 
 The following options are accepted:
 
@@ -288,13 +288,14 @@ The following options are accepted:
    Specify the function name to use to generate the uuid. By default :func:`uuid4`
    is used.
 
-.. cmdoption:: -ns <namespace>
+.. cmdoption:: -n <namespace>
                --namespace <namespace>
 
-   The namespace used as part of generating the uuid. Only required for
-   :func:`uuid3` / :func:`uuid5` functions.
+   The namespace is a ``UUID``, or ``@ns`` where ``ns`` is a well-known predefined UUID
+   addressed by namespace name. Such as ``@dns``, ``@url``, ``@oid``, and ``@x500``.
+   Only required for :func:`uuid3` / :func:`uuid5` functions.
 
-.. cmdoption:: -n <name>
+.. cmdoption:: -N <name>
                --name <name>
 
    The name used as part of generating the uuid. Only required for
@@ -351,12 +352,12 @@ Here are some examples of typical usage of the :mod:`uuid` command line interfac
 
 .. code-block:: shell
 
-    # generate a random uuid - by default uuid4() is used
-    $ python -m uuid
+   # generate a random uuid - by default uuid4() is used
+   $ python -m uuid
 
-    # generate a uuid using uuid1()
-    $ python -m uuid -u uuid1
+   # generate a uuid using uuid1()
+   $ python -m uuid -u uuid1
 
-    # generate a uuid using uuid5
-    $ python -m uuid -u uuid5 -ns NAMESPACE_URL -n example.com
+   # generate a uuid using uuid5
+   $ python -m uuid -u uuid5 -n @url -N example.com
 
diff --git a/Lib/test/test_uuid.py b/Lib/test/test_uuid.py
index 61ae2567c90d..b2c229cd634e 100755
--- a/Lib/test/test_uuid.py
+++ b/Lib/test/test_uuid.py
@@ -675,7 +675,7 @@ def test_uuid_weakref(self):
         weak = weakref.ref(strong)
         self.assertIs(strong, weak())
 
-    @mock.patch.object(sys, "argv", ["", "-u", "uuid3", "-ns", "NAMESPACE_DNS"])
+    @mock.patch.object(sys, "argv", ["", "-u", "uuid3", "-n", "@dns"])
     def test_cli_namespace_required_for_uuid3(self):
         with self.assertRaises(SystemExit) as cm:
             self.uuid.main()
@@ -683,7 +683,7 @@ def test_cli_namespace_required_for_uuid3(self):
         # Check that exception code is the same as argparse.ArgumentParser.error
         self.assertEqual(cm.exception.code, 2)
 
-    @mock.patch.object(sys, "argv", ["", "-u", "uuid3", "-n", "python.org"])
+    @mock.patch.object(sys, "argv", ["", "-u", "uuid3", "-N", "python.org"])
     def test_cli_name_required_for_uuid3(self):
         with self.assertRaises(SystemExit) as cm:
             self.uuid.main()
@@ -705,7 +705,7 @@ def test_cli_uuid4_outputted_with_no_args(self):
         self.assertEqual(uuid_output.version, 4)
 
     @mock.patch.object(sys, "argv",
-                       ["", "-u", "uuid3", "-ns", "NAMESPACE_DNS", "-n", "python.org"])
+                       ["", "-u", "uuid3", "-n", "@dns", "-N", "python.org"])
     def test_cli_uuid3_ouputted_with_valid_namespace_and_name(self):
         stdout = io.StringIO()
         with contextlib.redirect_stdout(stdout):
@@ -719,7 +719,7 @@ def test_cli_uuid3_ouputted_with_valid_namespace_and_name(self):
         self.assertEqual(uuid_output.version, 3)
 
     @mock.patch.object(sys, "argv",
-                       ["", "-u", "uuid5", "-ns", "NAMESPACE_DNS", "-n", "python.org"])
+                       ["", "-u", "uuid5", "-n", "@dns", "-N", "python.org"])
     def test_cli_uuid5_ouputted_with_valid_namespace_and_name(self):
         stdout = io.StringIO()
         with contextlib.redirect_stdout(stdout):
diff --git a/Lib/uuid.py b/Lib/uuid.py
index 2904b9c4af64..1c5578bf1f05 100644
--- a/Lib/uuid.py
+++ b/Lib/uuid.py
@@ -731,16 +731,18 @@ def uuid5(namespace, name):
 
 def main():
     """Run the uuid command line interface."""
-    uuid_funcs = {"uuid1": uuid1,
-                  "uuid3": uuid3,
-                  "uuid4": uuid4,
-                  "uuid5": uuid5}
+    uuid_funcs = {
+        "uuid1": uuid1,
+        "uuid3": uuid3,
+        "uuid4": uuid4,
+        "uuid5": uuid5
+    }
     uuid_namespace_funcs = ("uuid3", "uuid5")
     namespaces = {
-        "NAMESPACE_DNS": NAMESPACE_DNS,
-        "NAMESPACE_URL": NAMESPACE_URL,
-        "NAMESPACE_OID": NAMESPACE_OID,
-        "NAMESPACE_X500": NAMESPACE_X500
+        "@dns": NAMESPACE_DNS,
+        "@url": NAMESPACE_URL,
+        "@oid": NAMESPACE_OID,
+        "@x500": NAMESPACE_X500
     }
 
     import argparse
@@ -748,11 +750,13 @@ def main():
         description="Generates a uuid using the selected uuid function.")
     parser.add_argument("-u", "--uuid", choices=uuid_funcs.keys(), default="uuid4",
                         help="The function to use to generate the uuid. "
-                             "By default uuid4 function is used.")
-    parser.add_argument("-ns", "--namespace",
-                        help="The namespace used as part of generating the uuid. "
+                        "By default uuid4 function is used.")
+    parser.add_argument("-n", "--namespace",
+                        help="The namespace is a UUID, or '@ns' where 'ns' is a "
+                        "well-known predefined UUID addressed by namespace name. "
+                        "Such as @dns, @url, @oid, and @x500. "
                         "Only required for uuid3/uuid5 functions.")
-    parser.add_argument("-n", "--name",
+    parser.add_argument("-N", "--name",
                         help="The name used as part of generating the uuid. "
                         "Only required for uuid3/uuid5 functions.")