Rename --profile to --os-profile

* The --profile global option is deprecated but will be supported
  through at least April 2017.
* Update man page

Closes-bug: #1571812
Change-Id: I2e623411a56096b4cc352f4eedbf770632ae2cc3

Author: Dean Troyer

doc/source/man/openstack.rst

@@ -129,11 +129,11 @@ OPTIONS
 :option:`--os-interface` <interface>
     Interface type. Valid options are `public`, `admin` and `internal`.
 
-:option: `--profile` <hmac-key>
-    HMAC key to use for encrypting context data for performance profiling of
-    requested operation. This key should be the value of one of the HMAC keys
-    defined in the configuration files of OpenStack services, user would like
-    to trace through.
+:option:`--os-profile` <hmac-key>
+    Performance profiling HMAC key for encrypting context data
+
+    This key should be the value of one of the HMAC keys defined in the
+    configuration files of OpenStack services to be traced.
 
 :option:`--log-file` <LOGFILE>
     Specify a file to log output. Disabled by default.

openstackclient/shell.py

@@ -16,6 +16,7 @@
 
 """Command-line interface to the OpenStack APIs"""
 
+import argparse
 import getpass
 import logging
 import sys
@@ -131,6 +132,16 @@ def run(self, argv):
             self.log.info("END return value: %s", ret_val)
 
     def init_profile(self):
+        # NOTE(dtroyer): Remove this 'if' block when the --profile global
+        #                option is removed
+        if osprofiler_profiler and self.options.old_profile:
+            self.log.warning(
+                'The --profile option is deprecated, '
+                'please use --os-profile instead'
+            )
+            if not self.options.profile:
+                self.options.profile = self.options.old_profile
+
         self.do_profile = osprofiler_profiler and self.options.profile
         if self.do_profile:
             osprofiler_profiler.init(self.options.profile)
@@ -144,7 +155,7 @@ def close_profile(self):
             # bigger than most big default one (CRITICAL) or something like
             # that (PROFILE = 60 for instance), but not sure we need it here.
             self.log.warning("Trace ID: %s" % trace_id)
-            self.log.warning("To display trace use next command:\n"
+            self.log.warning("Display trace with command:\n"
                              "osprofiler trace show --html %s " % trace_id)
 
     def run_subcommand(self, argv):
@@ -242,16 +253,22 @@ def build_option_parser(self, description, version):
 
         # osprofiler HMAC key argument
         if osprofiler_profiler:
-            parser.add_argument('--profile',
-                                metavar='hmac-key',
-                                help='HMAC key to use for encrypting context '
-                                'data for performance profiling of operation. '
-                                'This key should be the value of one of the '
-                                'HMAC keys configured in osprofiler '
-                                'middleware in the projects user would like '
-                                'to profile. It needs to be specified in '
-                                'configuration files of the required '
-                                'projects.')
+            parser.add_argument(
+                '--os-profile',
+                metavar='hmac-key',
+                dest='profile',
+                help='HMAC key for encrypting profiling context data',
+            )
+            # NOTE(dtroyer): This global option should have been named
+            #                --os-profile as --profile interferes with at
+            #                least one existing command option.  Deprecate
+            #                --profile and remove after Apr 2017.
+            parser.add_argument(
+                '--profile',
+                metavar='hmac-key',
+                dest='old_profile',
+                help=argparse.SUPPRESS,
+            )
 
         return clientmanager.build_plugin_option_parser(parser)
 

openstackclient/tests/test_shell.py

@@ -112,7 +112,7 @@
     '--os-default-domain': (DEFAULT_DOMAIN_NAME, True, True),
     '--os-cacert': ('/dev/null', True, True),
     '--timing': (True, True, False),
-    '--profile': ('SECRET_KEY', True, False),
+    '--os-profile': ('SECRET_KEY', True, False),
     '--os-interface': (DEFAULT_INTERFACE, True, True)
 }
 

releasenotes/notes/bug-1571812-49cdce4df5f3d481.yaml

@@ -0,0 +1,10 @@
+---
+upgrade:
+  - |
+    Deprecate global option ``--profile`` in favor of ``--os-profile``.
+
+    ``--profile`` interferes with existing command options with the same name.
+    Unfortunately it appeared in a release so we must follow the deprecation
+    process and wait one year (April 2017) before removing it.
+
+    [Bug `1571812 <https://bugs.launchpad.net/python-openstackclient/+bug/1571812>`_]