feat(parser): add description field (#2005)

* feat(parser): add description field

cli/autocomplete.py

@@ -42,25 +42,28 @@ def _gaa(key, parser):
         'hello multimodal': ['--help', '--workdir', '--download-proxy', '--uses', '--index-data-url', '--demo-url',
                              '--port-expose', '--unblock-query-flow'],
         'hello': ['--help', 'fashion', 'chatbot', 'multimodal'],
-        'pod': ['--help', '--name', '--log-config', '--identity', '--hide-exc-info', '--port-ctrl', '--ctrl-with-ipc',
-                '--timeout-ctrl', '--ssh-server', '--ssh-keyfile', '--ssh-password', '--uses', '--py-modules',
-                '--port-in', '--port-out', '--host-in', '--host-out', '--socket-in', '--socket-out', '--dump-interval',
-                '--read-only', '--memory-hwm', '--on-error-strategy', '--num-part', '--uses-internal', '--entrypoint',
-                '--docker-kwargs', '--pull-latest', '--volumes', '--host', '--port-expose', '--silent-remote-logs',
-                '--upload-files', '--workspace-id', '--daemon', '--runtime-backend', '--runtime', '--runtime-cls',
-                '--timeout-ready', '--env', '--expose-public', '--pea-id', '--pea-role', '--noblock-on-start',
-                '--uses-before', '--uses-after', '--parallel', '--shards', '--polling', '--scheduling', '--pod-role'],
-        'flow': ['--help', '--name', '--log-config', '--identity', '--hide-exc-info', '--uses', '--inspect'],
-        'optimizer': ['--help', '--name', '--log-config', '--identity', '--hide-exc-info', '--uses', '--output-dir'],
-        'gateway': ['--help', '--name', '--log-config', '--identity', '--hide-exc-info', '--port-ctrl',
-                    '--ctrl-with-ipc', '--timeout-ctrl', '--ssh-server', '--ssh-keyfile', '--ssh-password', '--uses',
-                    '--py-modules', '--port-in', '--port-out', '--host-in', '--host-out', '--socket-in', '--socket-out',
-                    '--dump-interval', '--read-only', '--memory-hwm', '--on-error-strategy', '--num-part',
-                    '--max-message-size', '--proxy', '--prefetch', '--prefetch-on-recv', '--restful', '--rest-api',
-                    '--compress', '--compress-min-bytes', '--compress-min-ratio', '--host', '--port-expose', '--daemon',
-                    '--runtime-backend', '--runtime', '--runtime-cls', '--timeout-ready', '--env', '--expose-public',
-                    '--pea-id', '--pea-role', '--noblock-on-start'],
-        'ping': ['--help', '--timeout', '--retries', '--print-response'],
+        'pod': ['--help', '--name', '--description', '--log-config', '--quiet', '--quiet-error', '--identity',
+                '--port-ctrl', '--ctrl-with-ipc', '--timeout-ctrl', '--ssh-server', '--ssh-keyfile', '--ssh-password',
+                '--uses', '--py-modules', '--port-in', '--port-out', '--host-in', '--host-out', '--socket-in',
+                '--socket-out', '--dump-interval', '--read-only', '--memory-hwm', '--on-error-strategy', '--num-part',
+                '--uses-internal', '--entrypoint', '--docker-kwargs', '--pull-latest', '--volumes', '--host',
+                '--port-expose', '--silent-remote-logs', '--upload-files', '--workspace-id', '--daemon',
+                '--runtime-backend', '--runtime', '--runtime-cls', '--timeout-ready', '--env', '--expose-public',
+                '--pea-id', '--pea-role', '--noblock-on-start', '--uses-before', '--uses-after', '--parallel',
+                '--shards', '--polling', '--scheduling', '--pod-role'],
+        'flow': ['--help', '--name', '--description', '--log-config', '--quiet', '--quiet-error', '--identity',
+                 '--uses', '--inspect'],
+        'optimizer': ['--help', '--name', '--description', '--log-config', '--quiet', '--quiet-error', '--identity',
+                      '--uses', '--output-dir'],
+        'gateway': ['--help', '--name', '--description', '--log-config', '--quiet', '--quiet-error', '--identity',
+                    '--port-ctrl', '--ctrl-with-ipc', '--timeout-ctrl', '--ssh-server', '--ssh-keyfile',
+                    '--ssh-password', '--uses', '--py-modules', '--port-in', '--port-out', '--host-in', '--host-out',
+                    '--socket-in', '--socket-out', '--dump-interval', '--read-only', '--memory-hwm',
+                    '--on-error-strategy', '--num-part', '--max-message-size', '--proxy', '--prefetch',
+                    '--prefetch-on-recv', '--restful', '--rest-api', '--compress', '--compress-min-bytes',
+                    '--compress-min-ratio', '--host', '--port-expose', '--daemon', '--runtime-backend', '--runtime',
+                    '--runtime-cls', '--timeout-ready', '--env', '--expose-public', '--pea-id', '--pea-role',
+                    '--noblock-on-start'], 'ping': ['--help', '--timeout', '--retries', '--print-response'],
         'check': ['--help', '--summary-exec', '--summary-driver'], 'hub login': ['--help'],
         'hub new': ['--help', '--output-dir', '--template', '--type', '--overwrite'],
         'hub init': ['--help', '--output-dir', '--template', '--type', '--overwrite'],
@@ -72,13 +75,14 @@ def _gaa(key, parser):
         'hub pull': ['--help', '--username', '--password', '--registry', '--repository', '--no-overwrite'],
         'hub list': ['--help', '--name', '--kind', '--keywords', '--type', '--local-only'],
         'hub': ['--help', 'login', 'new', 'init', 'create', 'build', 'push', 'pull', 'list'],
-        'pea': ['--help', '--name', '--log-config', '--identity', '--hide-exc-info', '--port-ctrl', '--ctrl-with-ipc',
-                '--timeout-ctrl', '--ssh-server', '--ssh-keyfile', '--ssh-password', '--uses', '--py-modules',
-                '--port-in', '--port-out', '--host-in', '--host-out', '--socket-in', '--socket-out', '--dump-interval',
-                '--read-only', '--memory-hwm', '--on-error-strategy', '--num-part', '--uses-internal', '--entrypoint',
-                '--docker-kwargs', '--pull-latest', '--volumes', '--host', '--port-expose', '--silent-remote-logs',
-                '--upload-files', '--workspace-id', '--daemon', '--runtime-backend', '--runtime', '--runtime-cls',
-                '--timeout-ready', '--env', '--expose-public', '--pea-id', '--pea-role', '--noblock-on-start'],
+        'pea': ['--help', '--name', '--description', '--log-config', '--quiet', '--quiet-error', '--identity',
+                '--port-ctrl', '--ctrl-with-ipc', '--timeout-ctrl', '--ssh-server', '--ssh-keyfile', '--ssh-password',
+                '--uses', '--py-modules', '--port-in', '--port-out', '--host-in', '--host-out', '--socket-in',
+                '--socket-out', '--dump-interval', '--read-only', '--memory-hwm', '--on-error-strategy', '--num-part',
+                '--uses-internal', '--entrypoint', '--docker-kwargs', '--pull-latest', '--volumes', '--host',
+                '--port-expose', '--silent-remote-logs', '--upload-files', '--workspace-id', '--daemon',
+                '--runtime-backend', '--runtime', '--runtime-cls', '--timeout-ready', '--env', '--expose-public',
+                '--pea-id', '--pea-role', '--noblock-on-start'],
         'client': ['--help', '--request-size', '--mode', '--top-k', '--mime-type', '--continue-on-error',
                    '--return-results', '--max-message-size', '--proxy', '--prefetch', '--prefetch-on-recv', '--restful',
                    '--rest-api', '--compress', '--compress-min-bytes', '--compress-min-ratio', '--host',

jina/parsers/peapods/base.py

@@ -19,12 +19,17 @@ def mixin_base_ppr_parser(parser):
 
 This will be used in the following places:
 - how you refer to this object in Python/YAML/CLI
-- log message
+- visualization
+- log message header
+- automatics docs UI
 - ...
 
-When not given, then the default naming strategy will apply.
+When not given, then the default naming strategy will apply. 
                     ''')
 
+    gp.add_argument('--description', type=str,
+                    help='The description of this object. It will be used in automatics docs UI.')
+
     gp.add_argument('--log-config', type=str,
                     default=resource_filename('jina',
                                               '/'.join(('resources', 'logging.default.yml'))),
@@ -33,12 +38,11 @@ def mixin_base_ppr_parser(parser):
     gp.add_argument('--quiet', action='store_true', default=False,
                     help='If set, then no log will be emitted from this object.')
 
+    gp.add_argument('--quiet-error', action='store_true', default=False,
+                    help='If set, then exception stack information will not be added to the log')
+
     # hidden CLI used for internal only
 
     gp.add_argument('--identity', type=str, default=random_identity(),
                     help='A UUID string to represent the logger identity of this object'
                     if _SHOW_ALL_ARGS else argparse.SUPPRESS)
-
-    gp.add_argument('--hide-exc-info', action='store_true', default=False,
-                    help='If set, then exception stack information to be added to the logging message, '
-                         'useful in debugging')

jina/peapods/peas/__init__.py

@@ -47,9 +47,9 @@ def __init__(self, args: 'argparse.Namespace'):
             self.runtime = self._get_runtime_cls()(self.args)  # type: 'BaseRuntime'
         except Exception as ex:
             self.logger.error(f'{ex!r} during {self.runtime_cls.__init__!r}' +
-                              f'\n add "--hide-exc-info" to suppress the exception details'
-                              if not self.args.hide_exc_info else '',
-                              exc_info=not self.args.hide_exc_info)
+                              f'\n add "--quiet-error" to suppress the exception details'
+                              if not self.args.quiet_error else '',
+                              exc_info=not self.args.quiet_error)
             raise RuntimeFailToStart from ex
 
     def run(self):
@@ -68,9 +68,9 @@ def run(self):
             self.runtime.setup()
         except Exception as ex:
             self.logger.error(f'{ex!r} during {self.runtime.setup!r}' +
-                              f'\n add "--hide-exc-info" to suppress the exception details'
-                              if not self.args.hide_exc_info else '',
-                              exc_info=not self.args.hide_exc_info)
+                              f'\n add "--quiet-error" to suppress the exception details'
+                              if not self.args.quiet_error else '',
+                              exc_info=not self.args.quiet_error)
         else:
             self.is_ready.set()
             try:
@@ -81,17 +81,17 @@ def run(self):
                 self.logger.info(f'{self.runtime!r} is interrupted by user')
             except (Exception, SystemError) as ex:
                 self.logger.error(f'{ex!r} during {self.runtime.run_forever!r}' +
-                                  f'\n add "--hide-exc-info" to suppress the exception details'
-                                  if not self.args.hide_exc_info else '',
-                                  exc_info=not self.args.hide_exc_info)
+                                  f'\n add "--quiet-error" to suppress the exception details'
+                                  if not self.args.quiet_error else '',
+                                  exc_info=not self.args.quiet_error)
 
             try:
                 self.runtime.teardown()
             except Exception as ex:
                 self.logger.error(f'{ex!r} during {self.runtime.teardown!r}' +
-                                  f'\n add "--hide-exc-info" to suppress the exception details'
-                                  if not self.args.hide_exc_info else '',
-                                  exc_info=not self.args.hide_exc_info)
+                                  f'\n add "--quiet-error" to suppress the exception details'
+                                  if not self.args.quiet_error else '',
+                                  exc_info=not self.args.quiet_error)
         finally:
             self.is_shutdown.set()
             self.is_ready.clear()
@@ -122,9 +122,9 @@ def wait_start_success(self):
         if self.ready_or_shutdown.wait(_timeout):
             if self.is_shutdown.is_set():
                 # return too early and the shutdown is set, means something fails!!
-                if self.args.hide_exc_info:
+                if self.args.quiet_error:
                     self.logger.critical(f'fail to start {self!r} because {self.runtime!r} throws some exception, '
-                                         f'remove "--hide-exc-info" to see the exception stack in details')
+                                         f'remove "--quiet-error" to see the exception stack in details')
                 raise RuntimeFailToStart
             else:
                 self.logger.success(__ready_msg__)
@@ -153,9 +153,9 @@ def close(self) -> None:
                 self.is_shutdown.wait()
             except Exception as ex:
                 self.logger.error(f'{ex!r} during {self.runtime.cancel!r}' +
-                                  f'\n add "--hide-exc-info" to suppress the exception details'
-                                  if not self.args.hide_exc_info else '',
-                                  exc_info=not self.args.hide_exc_info)
+                                  f'\n add "--quiet-error" to suppress the exception details'
+                                  if not self.args.quiet_error else '',
+                                  exc_info=not self.args.quiet_error)
 
             # if it is not daemon, block until the process/thread finish work
             if not self.args.daemon:

jina/peapods/runtimes/zmq/zed.py

@@ -184,15 +184,15 @@ def _msg_callback(self, msg: 'Message') -> None:
             if isinstance(ex, ChainedPodException):
                 msg.add_exception()
                 self.logger.error(f'{ex!r}' +
-                                  f'\n add "--hide-exc-info" to suppress the exception details'
-                                  if not self.args.hide_exc_info else '',
-                                  exc_info=not self.args.hide_exc_info)
+                                  f'\n add "--quiet-error" to suppress the exception details'
+                                  if not self.args.quiet_error else '',
+                                  exc_info=not self.args.quiet_error)
             else:
                 msg.add_exception(ex, executor=getattr(self, '_executor'))
                 self.logger.error(f'{ex!r}' +
-                                  f'\n add "--hide-exc-info" to suppress the exception details'
-                                  if not self.args.hide_exc_info else '',
-                                  exc_info=not self.args.hide_exc_info)
+                                  f'\n add "--quiet-error" to suppress the exception details'
+                                  if not self.args.quiet_error else '',
+                                  exc_info=not self.args.quiet_error)
 
             self._zmqlet.send_message(msg)
 

jina/resources/executors.metas.default.yml

@@ -11,3 +11,4 @@ root_workspace: ${{root.metas.workspace}} # needed to extract the `dump path` fo
 root_name: ${{root.metas.name}} # needed to extract the `dump path` for inner executor of CompoundExecutors
 pea_id: ${{root.metas.pea_id}}  # this may result in self-referred
 read_only: false
+description: # the description of this executor. It will be used in automatics docs UI

tests/unit/peapods/pods/test_pods.py

@@ -57,18 +57,6 @@ def test_pod_naming_with_parallel(runtime):
         assert bp.peas[3].runtime.name == 'pod/2/ZEDRuntime'
 
 
-@pytest.mark.parametrize('runtime', ['process', 'thread'])
-def test_pod_remote_context(runtime):
-    args = set_pod_parser().parse_args(['--runtime-backend', runtime, '--parallel', str(2)])
-    with Pod(args) as p:
-        remote_pod_args = p.peas_args
-
-    with Pod(remote_pod_args) as remote_pod:
-        assert remote_pod.num_peas == 4  # head + tail + 2 peas
-
-    Pod(remote_pod_args).start().close()
-
-
 def test_pod_args_remove_uses_ba():
     args = set_pod_parser().parse_args([])
     with Pod(args) as p: