Document preview services

awscli/customizations/preview.py

@@ -38,18 +38,12 @@
 
 logger = logging.getLogger(__name__)
 
-GENERAL_HELP = """
-This service is only available as a preview service.
-"""
-
 
-# Mapping of service name to help text to print
-# when a user tries to invoke a service marked as preview.
-PREVIEW_SERVICES = {
-    'cloudfront': GENERAL_HELP,
-    'sdb': GENERAL_HELP,
-    'efs': GENERAL_HELP,
-}
+PREVIEW_SERVICES = [
+    'cloudfront',
+    'sdb',
+    'efs',
+]
 
 
 def register_preview_commands(events):
@@ -61,15 +55,35 @@ def mark_as_preview(command_table, session, **kwargs):
     # explicitly enabled in the config file.
     allowed_services = _get_allowed_services(session)
     for preview_service in PREVIEW_SERVICES:
+        is_enabled = False
         if preview_service in allowed_services:
             # Then we don't need to swap it as a preview
             # service, the user has specifically asked to
             # enable this service.
             logger.debug("Preview service enabled through config file: %s",
                          preview_service)
-            continue
-        command_table[preview_service] = PreviewModeCommand(
-            preview_service, PREVIEW_SERVICES[preview_service])
+            is_enabled = True
+        original_command = command_table[preview_service]
+        preview_cls = type(
+            'PreviewCommand',
+            (PreviewModeCommandMixin, original_command.__class__), {})
+        command_table[preview_service] = preview_cls(
+            cli_name=original_command.name,
+            session=session,
+            service_name=original_command._service_name,
+            is_enabled=is_enabled)
+        # We also want to register a handler that will update the
+        # description in the docs to say that this is a preview service.
+        session.get_component('event_emitter').register_last(
+            'doc-description.%s' % preview_service,
+            update_description_with_preview)
+
+
+def update_description_with_preview(help_command, **kwargs):
+    style = help_command.doc.style
+    style.start_note()
+    style.bold("The service is currently in preview.")
+    style.end_note()
 
 
 def _get_allowed_services(session):
@@ -84,14 +98,9 @@ def _get_allowed_services(session):
     return allowed
 
 
-class PreviewModeCommand(CLICommand):
-    # This is a hidden attribute that tells the doc system
-    # not to document this command in the provider help.
-    # This is an internal implementation detail.
-    _UNDOCUMENTED = True
-
+class PreviewModeCommandMixin(object):
     ENABLE_DOCS = textwrap.dedent("""\
-    However, if you'd like to use a basic set of {service} commands with the
+    However, if you'd like to use the "aws {service}" commands with the
     AWS CLI, you can enable this service by adding the following to your CLI
     config file:
 
@@ -103,13 +112,21 @@ class PreviewModeCommand(CLICommand):
         aws configure set preview.{service} true
 
     """)
+    HELP_SNIPPET = "This service is only available as a preview service.\n"
 
-    def __init__(self, service_name, service_help):
-        self._service_name = service_name
-        self._service_help = service_help
+    def __init__(self, *args, **kwargs):
+        self._is_enabled = kwargs.pop('is_enabled')
+        super(PreviewModeCommandMixin, self).__init__(*args, **kwargs)
 
     def __call__(self, args, parsed_globals):
-        sys.stderr.write(self._service_help)
+        if self._is_enabled:
+            return super(PreviewModeCommandMixin, self).__call__(
+                args, parsed_globals)
+        else:
+            return self._display_opt_in_message()
+
+    def _display_opt_in_message(self):
+        sys.stderr.write(self.HELP_SNIPPET)
         sys.stderr.write("\n")
         # Then let them know how to enable this service.
         sys.stderr.write(self.ENABLE_DOCS.format(service=self._service_name))

tests/unit/customizations/test_preview.py

@@ -42,7 +42,7 @@ def test_invoke_preview_mode_service(self):
         self.assertIn('cloudfront', preview.PREVIEW_SERVICES)
         rc = self.driver.main('cloudfront help'.split())
         self.assertEqual(rc, 1)
-        self.assertIn(preview.PREVIEW_SERVICES['cloudfront'],
+        self.assertIn(preview.PreviewModeCommandMixin.HELP_SNIPPET,
                       self.stderr.getvalue())
 
     @mock.patch('awscli.help.get_renderer')
@@ -60,7 +60,7 @@ def test_preview_service_not_true(self):
         self.full_config['preview'] = {'cloudfront': 'false'}
         rc = self.driver.main('cloudfront help'.split())
         self.assertEqual(rc, 1)
-        self.assertIn(preview.PREVIEW_SERVICES['cloudfront'],
+        self.assertIn(preview.PreviewModeCommandMixin.HELP_SNIPPET,
                       self.stderr.getvalue())
 
     @mock.patch('awscli.help.get_renderer')

tests/unit/test_completer.py

@@ -28,22 +28,23 @@
               '--query', '--no-sign-request']
 
 COMPLETIONS = [
-    ('aws ', -1, set(['autoscaling', 'cloudformation', 'cloudhsm',
-                      'cloudsearch', 'cloudsearchdomain', 'cloudtrail',
-                      'cloudwatch', 'cognito-identity', 'cognito-sync',
-                      'configservice', 'configure', 'datapipeline', 'deploy',
-                      'directconnect', 'ds', 'dynamodb', 'glacier', 'ec2',
-                      'ecs', 'elasticache', 'elasticbeanstalk',
-                      'elastictranscoder', 'elb', 'emr', 'iam',
-                      'importexport', 'kinesis', 'kms', 'lambda', 'logs',
-                      'machinelearning', 'opsworks', 'rds', 'redshift',
-                      'route53', 'route53domains', 's3', 's3api', 'ses',
-                      'sns', 'sqs', 'storagegateway', 'sts', 'ssm', 'support',
-                      'swf', 'workspaces'])),
-    ('aws cloud', -1, set(['cloudformation', 'cloudhsm', 'cloudsearch',
-                           'cloudsearchdomain', 'cloudtrail', 'cloudwatch'])),
-    ('aws cloudf', -1, set(['cloudformation'])),
-    ('aws cloudfr', -1, set([])),
+    ('aws ', -1, set(['autoscaling', 'cloudformation', 'cloudfront',
+                      'cloudhsm', 'cloudsearch', 'cloudsearchdomain',
+                      'cloudtrail', 'cloudwatch', 'cognito-identity',
+                      'cognito-sync', 'configservice', 'configure',
+                      'datapipeline', 'deploy', 'directconnect', 'ds',
+                      'dynamodb', 'glacier', 'ec2', 'ecs', 'efs',
+                      'elasticache', 'elasticbeanstalk', 'elastictranscoder',
+                      'elb', 'emr', 'iam', 'importexport', 'kinesis', 'kms',
+                      'lambda', 'logs', 'machinelearning', 'opsworks', 'rds',
+                      'redshift', 'route53', 'route53domains', 's3', 's3api',
+                      'sdb', 'ses', 'sns', 'sqs', 'storagegateway', 'sts',
+                      'ssm', 'support', 'swf', 'workspaces'])),
+    ('aws cloud', -1, set(['cloudformation', 'cloudfront', 'cloudhsm',
+                           'cloudsearch', 'cloudsearchdomain', 'cloudtrail',
+                           'cloudwatch'])),
+    ('aws cloudf', -1, set(['cloudformation', 'cloudfront',])),
+    ('aws cloudfr', -1, set(['cloudfront'])),
     ('aws foobar', -1, set([])),
     ('aws  --', -1, set(GLOBALOPTS)),
     ('aws  --re', -1, set(['--region'])),