Command doc: policy

Also tweaked a bunch of the code to not show 'blob', but 'rules'
instead.

Change-Id: I6db798d272ff416a77f169c0e912d2096fa02504

Author: Steve Martinelli

doc/source/command-objects/policy.rst

@@ -0,0 +1,95 @@
+======
+policy
+======
+
+Identity v3
+
+policy create
+-------------
+
+Create new policy
+
+.. program:: policy create
+.. code:: bash
+
+    os policy create
+        [--type <type>]
+        <filename>
+
+.. option:: --type <type>
+
+    New MIME type of the policy rules file (defaults to application/json)
+
+.. describe:: <filename>
+
+    New serialized policy rules file
+
+policy delete
+-------------
+
+Delete policy
+
+.. program:: policy delete
+.. code:: bash
+
+    os policy delete
+        <policy>
+
+.. describe:: <policy>
+
+    Policy to delete
+
+policy list
+-----------
+
+List policies
+
+.. program:: policy list
+.. code:: bash
+
+    os policy list
+        [--long]
+
+.. option:: --long
+
+    List additional fields in output
+
+policy set
+----------
+
+Set policy properties
+
+.. program:: policy set
+.. code:: bash
+
+    os policy set
+        [--type <type>]
+        [--rules <filename>]
+        <policy>
+
+.. option:: --type <type>
+
+    New MIME type of the policy rules file
+
+.. describe:: --rules <filename>
+
+    New serialized policy rules file
+
+.. describe:: <policy>
+
+    Policy to modify
+
+policy show
+-----------
+
+Display policy details
+
+.. program:: policy show
+.. code:: bash
+
+    os policy show
+        <policy>
+
+.. describe:: <policy>
+
+    Policy to display

doc/source/commands.rst

@@ -98,7 +98,7 @@ referring to both Compute and Volume quotas.
 * ``module``: internal - installed Python modules in the OSC process
 * ``network``: Network - a virtual network for connecting servers and other resources
 * ``object``: (**Object Store**) a single file in the Object Store
-* ``policy``: Identity - determines authorization
+* ``policy``: (**Identity**) determines authorization
 * ``project``: (**Identity**) owns a group of resources
 * ``quota``: (**Compute**, **Volume**) resource usage restrictions
 * ``region``: (**Identity**) a subset of an OpenStack deployment

openstackclient/identity/v3/policy.py

@@ -27,49 +27,51 @@
 
 
 class CreatePolicy(show.ShowOne):
-    """Create policy command"""
+    """Create new policy"""
 
     log = logging.getLogger(__name__ + '.CreatePolicy')
 
     def get_parser(self, prog_name):
         parser = super(CreatePolicy, self).get_parser(prog_name)
         parser.add_argument(
             '--type',
-            metavar='<policy-type>',
+            metavar='<type>',
             default="application/json",
-            help='New MIME type of the policy blob - i.e.: application/json',
+            help='New MIME type of the policy rules file '
+                 '(defaults to application/json)',
         )
         parser.add_argument(
-            'blob_file',
-            metavar='<blob-file>',
-            help='New policy rule set itself, as a serialized blob, in a file',
+            'rules',
+            metavar='<filename>',
+            help='New serialized policy rules file',
         )
         return parser
 
     def take_action(self, parsed_args):
         self.log.debug('take_action(%s)', parsed_args)
-        blob = utils.read_blob_file_contents(parsed_args.blob_file)
+        blob = utils.read_blob_file_contents(parsed_args.rules)
 
         identity_client = self.app.client_manager.identity
         policy = identity_client.policies.create(
             blob=blob, type=parsed_args.type
         )
 
         policy._info.pop('links')
+        policy._info.update({'rules': policy._info.pop('blob')})
         return zip(*sorted(six.iteritems(policy._info)))
 
 
 class DeletePolicy(command.Command):
-    """Delete policy command"""
+    """Delete policy"""
 
     log = logging.getLogger(__name__ + '.DeletePolicy')
 
     def get_parser(self, prog_name):
         parser = super(DeletePolicy, self).get_parser(prog_name)
         parser.add_argument(
             'policy',
-            metavar='<policy-id>',
-            help='ID of policy to delete',
+            metavar='<policy>',
+            help='Policy to delete',
         )
         return parser
 
@@ -81,55 +83,57 @@ def take_action(self, parsed_args):
 
 
 class ListPolicy(lister.Lister):
-    """List policy command"""
+    """List policies"""
 
     log = logging.getLogger(__name__ + '.ListPolicy')
 
     def get_parser(self, prog_name):
         parser = super(ListPolicy, self).get_parser(prog_name)
         parser.add_argument(
-            '--include-blob',
+            '--long',
             action='store_true',
             default=False,
-            help='Additional fields are listed in output',
+            help='List additional fields in output',
         )
         return parser
 
     def take_action(self, parsed_args):
         self.log.debug('take_action(%s)', parsed_args)
-        if parsed_args.include_blob:
+        if parsed_args.long:
             columns = ('ID', 'Type', 'Blob')
+            column_headers = ('ID', 'Type', 'Rules')
         else:
             columns = ('ID', 'Type')
+            column_headers = columns
         data = self.app.client_manager.identity.policies.list()
-        return (columns,
+        return (column_headers,
                 (utils.get_item_properties(
                     s, columns,
                     formatters={},
                 ) for s in data))
 
 
 class SetPolicy(command.Command):
-    """Set policy command"""
+    """Set policy properties"""
 
     log = logging.getLogger(__name__ + '.SetPolicy')
 
     def get_parser(self, prog_name):
         parser = super(SetPolicy, self).get_parser(prog_name)
         parser.add_argument(
             'policy',
-            metavar='<policy-id>',
-            help='ID of policy to change',
+            metavar='<policy>',
+            help='Policy to modify',
         )
         parser.add_argument(
             '--type',
-            metavar='<policy-type>',
-            help='New MIME Type of the policy blob - i.e.: application/json',
+            metavar='<type>',
+            help='New MIME type of the policy rules file',
         )
         parser.add_argument(
-            '--blob-file',
-            metavar='<blob_file>',
-            help='New policy rule set itself, as a serialized blob, in a file',
+            '--rules',
+            metavar='<filename>',
+            help='New serialized policy rules file',
         )
         return parser
 
@@ -138,8 +142,8 @@ def take_action(self, parsed_args):
         identity_client = self.app.client_manager.identity
         blob = None
 
-        if parsed_args.blob_file:
-            blob = utils.read_blob_file_contents(parsed_args.blob_file)
+        if parsed_args.rules:
+            blob = utils.read_blob_file_contents(parsed_args.rules)
 
         kwargs = {}
         if blob:
@@ -148,23 +152,23 @@ def take_action(self, parsed_args):
             kwargs['type'] = parsed_args.type
 
         if not kwargs:
-            sys.stdout.write("Policy not updated, no arguments present \n")
+            sys.stdout.write('Policy not updated, no arguments present \n')
             return
         identity_client.policies.update(parsed_args.policy, **kwargs)
         return
 
 
 class ShowPolicy(show.ShowOne):
-    """Show policy command"""
+    """Display policy details"""
 
     log = logging.getLogger(__name__ + '.ShowPolicy')
 
     def get_parser(self, prog_name):
         parser = super(ShowPolicy, self).get_parser(prog_name)
         parser.add_argument(
             'policy',
-            metavar='<policy-id>',
-            help='ID of policy to display',
+            metavar='<policy>',
+            help='Policy to display',
         )
         return parser
 
@@ -175,4 +179,5 @@ def take_action(self, parsed_args):
                                      parsed_args.policy)
 
         policy._info.pop('links')
+        policy._info.update({'rules': policy._info.pop('blob')})
         return zip(*sorted(six.iteritems(policy._info)))