class TopicListerDocumentEventHandler(CLIDocumentEventHandler): DESCRIPTION = ( 'This is the AWS CLI Topic Guide. It gives access to a set ' 'of topics that provide a deeper understanding of the CLI. To access ' 'the list of topics from the command line, run ``aws help topics``. ' 'To access a specific topic from the command line, run ' '``aws help [topicname]``, where ``topicname`` is the name of the ' 'topic as it appears in the output from ``aws help topics``.') def __init__(self, help_command): self.help_command = help_command self.register(help_command.session, help_command.event_class) self._topic_tag_db = TopicTagDB() self._topic_tag_db.load_json_index() def doc_breadcrumbs(self, help_command, **kwargs): doc = help_command.doc if doc.target != 'man': doc.write('[ ') doc.style.sphinx_reference_label(label='cli:aws', text='aws') doc.write(' ]') def doc_title(self, help_command, **kwargs): doc = help_command.doc doc.style.new_paragraph() doc.style.link_target_definition( refname='cli:aws help %s' % self.help_command.name, link='') doc.style.h1('AWS CLI Topic Guide') def doc_description(self, help_command, **kwargs): doc = help_command.doc doc.style.h2('Description') doc.include_doc_string(self.DESCRIPTION) doc.style.new_paragraph() def doc_synopsis_start(self, help_command, **kwargs): pass def doc_synopsis_end(self, help_command, **kwargs): pass def doc_options_start(self, help_command, **kwargs): pass def doc_options_end(self, help_command, **kwargs): pass def doc_subitems_start(self, help_command, **kwargs): doc = help_command.doc doc.style.h2('Available Topics') categories = self._topic_tag_db.query('category') topic_names = self._topic_tag_db.get_all_topic_names() # Sort the categories category_names = sorted(categories.keys()) for category_name in category_names: doc.style.h3(category_name) doc.style.new_paragraph() # Write out the topic and a description for each topic under # each category. for topic_name in sorted(categories[category_name]): description = self._topic_tag_db.get_tag_single_value( topic_name, 'description') doc.write('* ') doc.style.sphinx_reference_label( label='cli:aws help %s' % topic_name, text=topic_name ) doc.write(': %s\n' % description) # Add a hidden toctree to make sure everything is connected in # the document. doc.style.hidden_toctree() for topic_name in topic_names: doc.style.hidden_tocitem(topic_name)
class TopicListerDocumentEventHandler(CLIDocumentEventHandler): DESCRIPTION = ( 'This is the AWS CLI Topic Guide. It gives access to a set ' 'of topics that provide a deeper understanding of the CLI. To access ' 'the list of topics from the command line, run ``aws help topics``. ' 'To access a specific topic from the command line, run ' '``aws help [topicname]``, where ``topicname`` is the name of the ' 'topic as it appears in the output from ``aws help topics``.') def __init__(self, help_command): self.help_command = help_command self.register(help_command.session, help_command.event_class) self.help_command.doc.translation_map = self.build_translation_map() self._topic_tag_db = TopicTagDB() self._topic_tag_db.load_json_index() def doc_breadcrumbs(self, help_command, **kwargs): doc = help_command.doc if doc.target != 'man': doc.write('[ ') doc.style.sphinx_reference_label(label='cli:aws', text='aws') doc.write(' ]') def doc_title(self, help_command, **kwargs): doc = help_command.doc doc.style.new_paragraph() doc.style.link_target_definition( refname='cli:aws help %s' % self.help_command.name, link='') doc.style.h1('AWS CLI Topic Guide') def doc_description(self, help_command, **kwargs): doc = help_command.doc doc.style.h2('Description') doc.include_doc_string(self.DESCRIPTION) doc.style.new_paragraph() def doc_synopsis_start(self, help_command, **kwargs): pass def doc_synopsis_end(self, help_command, **kwargs): pass def doc_options_start(self, help_command, **kwargs): pass def doc_options_end(self, help_command, **kwargs): pass def doc_subitems_start(self, help_command, **kwargs): doc = help_command.doc doc.style.h2('Available Topics') categories = self._topic_tag_db.query('category') topic_names = self._topic_tag_db.get_all_topic_names() # Sort the categories category_names = sorted(categories.keys()) for category_name in category_names: doc.style.h3(category_name) doc.style.new_paragraph() # Write out the topic and a description for each topic under # each category. for topic_name in sorted(categories[category_name]): description = self._topic_tag_db.get_tag_single_value( topic_name, 'description') doc.write('* ') doc.style.sphinx_reference_label( label='cli:aws help %s' % topic_name, text=topic_name ) doc.write(': %s\n' % description) # Add a hidden toctree to make sure everything is connected in # the document. doc.style.hidden_toctree() for topic_name in topic_names: doc.style.hidden_tocitem(topic_name)
class TestTopicTagDBGeneral(TestTopicTagDB): def test_valid_tags(self): self.assertCountEqual(self.topic_tag_db.valid_tags, [ 'title', 'description', 'category', 'related command', 'related topic' ]) def test_topic_dir(self): self.topic_tag_db = TopicTagDB(topic_dir='foo') self.assertEqual(self.topic_tag_db.topic_dir, 'foo') self.topic_tag_db.topic_dir = 'bar' self.assertEqual(self.topic_tag_db.topic_dir, 'bar') def test_index_file(self): self.topic_tag_db = TopicTagDB(index_file='foo') self.assertEqual(self.topic_tag_db.index_file, 'foo') self.topic_tag_db.index_file = 'bar' self.assertEqual(self.topic_tag_db.index_file, 'bar') def test_get_all_topic_names(self): tag_dict = { 'topic-name-1': { 'title': ['My First Topic Title'], }, 'topic-name-2': { 'title': ['My Second Topic Title'], } } reference_topic_list = ['topic-name-1', 'topic-name-2'] self.topic_tag_db = TopicTagDB(tag_dict) self.assertCountEqual(self.topic_tag_db.get_all_topic_names(), reference_topic_list) def test_get_all_topic_source_files(self): source_files = [] topic_dir = self.file_creator.rootdir self.topic_tag_db = TopicTagDB(topic_dir=topic_dir) for i in range(5): topic_name = 'topic-name-' + str(i) source_files.append(self.file_creator.create_file(topic_name, '')) self.assertCountEqual(self.topic_tag_db.get_all_topic_src_files(), source_files) def test_get_all_topic_source_files_ignore_index(self): topic_filename = 'mytopic' index_filename = 'topic-tags.json' source_files = [] source_files.append(self.file_creator.create_file(topic_filename, '')) index_file = self.file_creator.create_file(index_filename, '') topic_dir = self.file_creator.rootdir self.topic_tag_db = TopicTagDB(index_file=index_file, topic_dir=topic_dir) self.assertCountEqual(self.topic_tag_db.get_all_topic_src_files(), source_files) def test_get_all_topic_source_files_ignore_hidden(self): topic_filename = 'mytopic' hidden_filename = '.' + topic_filename source_files = [] source_files.append(self.file_creator.create_file(topic_filename, '')) self.file_creator.create_file(hidden_filename, '') topic_dir = self.file_creator.rootdir self.topic_tag_db = TopicTagDB(topic_dir=topic_dir) self.assertCountEqual(self.topic_tag_db.get_all_topic_src_files(), source_files) def test_get_tag_value_all_tags(self): topic_name = 'topic-name-1' tag_dict = { topic_name: { 'title': ['My First Topic Title'], 'description': ['This describes my first topic'], 'category': ['General Topics'], 'related command': ['aws s3'], 'related topic': ['topic-name-2'] } } self.topic_tag_db = TopicTagDB(tag_dict) # Check the title get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'title') self.assertEqual(value, ['My First Topic Title']) # Check the description get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'description') self.assertEqual(value, ['This describes my first topic']) # Check the category get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'category') self.assertEqual(value, ['General Topics']) # Check the related command get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'related command') self.assertEqual(value, ['aws s3']) # Check the related topic get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'related topic') self.assertEqual(value, ['topic-name-2']) def test_get_tag_multi_value(self): topic_name = 'topic-name-1' tag_dict = {topic_name: {'related topic': ['foo', 'bar']}} self.topic_tag_db = TopicTagDB(tag_dict) # Check the related topic get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'related topic') self.assertEqual(value, ['foo', 'bar']) def test_get_tag_topic_no_exists(self): topic_name = 'topic-name-1' tag_dict = {topic_name: {'related topic': ['foo']}} self.topic_tag_db = TopicTagDB(tag_dict) value = self.topic_tag_db.get_tag_value('no-exist', 'related topic') self.assertEqual(value, None) def test_get_tag_no_exist_tag(self): topic_name = 'topic-name-1' tag_dict = {topic_name: {'related topic': ['foo']}} self.topic_tag_db = TopicTagDB(tag_dict) value = self.topic_tag_db.get_tag_value(topic_name, ':foo:') self.assertEqual(value, None) def test_get_tag_no_exist_use_default(self): topic_name = 'topic-name-1' tag_dict = {topic_name: {'related topic': ['foo']}} self.topic_tag_db = TopicTagDB(tag_dict) value = self.topic_tag_db.get_tag_value('no-exist', ':foo:', []) self.assertEqual(value, []) def test_get_tag_single_value(self): topic_name = 'topic-name-1' tag_dict = {topic_name: {'title': ['foo']}} self.topic_tag_db = TopicTagDB(tag_dict) value = self.topic_tag_db.get_tag_single_value('topic-name-1', 'title') self.assertEqual(value, 'foo') def test_get_tag_single_value_exception(self): topic_name = 'topic-name-1' tag_dict = {topic_name: {'title': ['foo', 'bar']}} self.topic_tag_db = TopicTagDB(tag_dict) with self.assertRaises(ValueError): self.topic_tag_db.get_tag_single_value('topic-name-1', 'title') def test_get_tag_single_value_no_exists(self): topic_name = 'topic-name-1' tag_dict = {topic_name: {'title': ['foo']}} self.topic_tag_db = TopicTagDB(tag_dict) value = self.topic_tag_db.get_tag_single_value('topic-name-1', ':title:') self.assertEqual(value, None) def test_load_and_save_json_index(self): tag_dict = { 'topic-name-1': { 'title': ['My First Topic Title'], 'description': ['This describes my first topic'], 'category': ['General Topics', 'S3'], 'related command': ['aws s3'], 'related topic': ['topic-name-2'] }, 'topic-name-2': { 'title': ['My Second Topic Title'], 'description': ['This describes my second topic'], 'category': ['General Topics'], 'related topic': ['topic-name-1'] } } json_index = self.file_creator.create_file('index.json', '') # Create a JSON index to be loaded. tag_json = json.dumps(tag_dict, indent=4, sort_keys=True) with open(json_index, 'w') as f: f.write(tag_json) # Load the JSON index. self.topic_tag_db = TopicTagDB(index_file=json_index) self.topic_tag_db.load_json_index() # Write the loaded json to disk and ensure it is as expected. saved_json_index = self.file_creator.create_file('index2.json', '') self.topic_tag_db.index_file = saved_json_index self.topic_tag_db.save_to_json_index() with open(saved_json_index, 'r') as f: self.assertEqual(f.read(), tag_json)
class TestTopicTagDBGeneral(TestTopicTagDB): def test_valid_tags(self): self.assertCountEqual( self.topic_tag_db.valid_tags, ['title', 'description', 'category', 'related command', 'related topic'] ) def test_topic_dir(self): self.topic_tag_db = TopicTagDB(topic_dir='foo') self.assertEqual(self.topic_tag_db.topic_dir, 'foo') self.topic_tag_db.topic_dir = 'bar' self.assertEqual(self.topic_tag_db.topic_dir, 'bar') def test_index_file(self): self.topic_tag_db = TopicTagDB(index_file='foo') self.assertEqual(self.topic_tag_db.index_file, 'foo') self.topic_tag_db.index_file = 'bar' self.assertEqual(self.topic_tag_db.index_file, 'bar') def test_get_all_topic_names(self): tag_dict = { 'topic-name-1': { 'title': ['My First Topic Title'], }, 'topic-name-2': { 'title': ['My Second Topic Title'], } } reference_topic_list = ['topic-name-1', 'topic-name-2'] self.topic_tag_db = TopicTagDB(tag_dict) self.assertCountEqual(self.topic_tag_db.get_all_topic_names(), reference_topic_list) def test_get_all_topic_source_files(self): source_files = [] topic_dir = self.file_creator.rootdir self.topic_tag_db = TopicTagDB(topic_dir=topic_dir) for i in range(5): topic_name = 'topic-name-' + str(i) source_files.append(self.file_creator.create_file(topic_name, '')) self.assertCountEqual( self.topic_tag_db.get_all_topic_src_files(), source_files ) def test_get_all_topic_source_files_ignore_index(self): topic_filename = 'mytopic' index_filename = 'topic-tags.json' source_files = [] source_files.append(self.file_creator.create_file(topic_filename, '')) index_file = self.file_creator.create_file(index_filename, '') topic_dir = self.file_creator.rootdir self.topic_tag_db = TopicTagDB(index_file=index_file, topic_dir=topic_dir) self.assertCountEqual( self.topic_tag_db.get_all_topic_src_files(), source_files ) def test_get_all_topic_source_files_ignore_hidden(self): topic_filename = 'mytopic' hidden_filename = '.' + topic_filename source_files = [] source_files.append(self.file_creator.create_file(topic_filename, '')) self.file_creator.create_file(hidden_filename, '') topic_dir = self.file_creator.rootdir self.topic_tag_db = TopicTagDB(topic_dir=topic_dir) self.assertCountEqual( self.topic_tag_db.get_all_topic_src_files(), source_files ) def test_get_tag_value_all_tags(self): topic_name = 'topic-name-1' tag_dict = { topic_name: { 'title': ['My First Topic Title'], 'description': ['This describes my first topic'], 'category': ['General Topics'], 'related command': ['aws s3'], 'related topic': ['topic-name-2'] } } self.topic_tag_db = TopicTagDB(tag_dict) # Check the title get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'title') self.assertEqual(value, ['My First Topic Title']) # Check the description get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'description') self.assertEqual(value, ['This describes my first topic']) # Check the category get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'category') self.assertEqual(value, ['General Topics']) # Check the related command get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'related command') self.assertEqual(value, ['aws s3']) # Check the related topic get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'related topic') self.assertEqual(value, ['topic-name-2']) def test_get_tag_multi_value(self): topic_name = 'topic-name-1' tag_dict = { topic_name: { 'related topic': ['foo', 'bar'] } } self.topic_tag_db = TopicTagDB(tag_dict) # Check the related topic get tag value value = self.topic_tag_db.get_tag_value(topic_name, 'related topic') self.assertEqual(value, ['foo', 'bar']) def test_get_tag_topic_no_exists(self): topic_name = 'topic-name-1' tag_dict = { topic_name: { 'related topic': ['foo'] } } self.topic_tag_db = TopicTagDB(tag_dict) value = self.topic_tag_db.get_tag_value('no-exist', 'related topic') self.assertEqual(value, None) def test_get_tag_no_exist_tag(self): topic_name = 'topic-name-1' tag_dict = { topic_name: { 'related topic': ['foo'] } } self.topic_tag_db = TopicTagDB(tag_dict) value = self.topic_tag_db.get_tag_value(topic_name, ':foo:') self.assertEqual(value, None) def test_get_tag_no_exist_use_default(self): topic_name = 'topic-name-1' tag_dict = { topic_name: { 'related topic': ['foo'] } } self.topic_tag_db = TopicTagDB(tag_dict) value = self.topic_tag_db.get_tag_value('no-exist', ':foo:', []) self.assertEqual(value, []) def test_get_tag_single_value(self): topic_name = 'topic-name-1' tag_dict = { topic_name: { 'title': ['foo'] } } self.topic_tag_db = TopicTagDB(tag_dict) value = self.topic_tag_db.get_tag_single_value('topic-name-1', 'title') self.assertEqual(value, 'foo') def test_get_tag_single_value_exception(self): topic_name = 'topic-name-1' tag_dict = { topic_name: { 'title': ['foo', 'bar'] } } self.topic_tag_db = TopicTagDB(tag_dict) with self.assertRaises(ValueError): self.topic_tag_db.get_tag_single_value('topic-name-1', 'title') def test_get_tag_single_value_no_exists(self): topic_name = 'topic-name-1' tag_dict = { topic_name: { 'title': ['foo'] } } self.topic_tag_db = TopicTagDB(tag_dict) value = self.topic_tag_db.get_tag_single_value( 'topic-name-1', ':title:') self.assertEqual(value, None) def test_load_and_save_json_index(self): tag_dict = { 'topic-name-1': { 'title': ['My First Topic Title'], 'description': ['This describes my first topic'], 'category': ['General Topics', 'S3'], 'related command': ['aws s3'], 'related topic': ['topic-name-2'] }, 'topic-name-2': { 'title': ['My Second Topic Title'], 'description': ['This describes my second topic'], 'category': ['General Topics'], 'related topic': ['topic-name-1'] } } json_index = self.file_creator.create_file('index.json', '') # Create a JSON index to be loaded. tag_json = json.dumps(tag_dict, indent=4, sort_keys=True) with open(json_index, 'w') as f: f.write(tag_json) # Load the JSON index. self.topic_tag_db = TopicTagDB(index_file=json_index) self.topic_tag_db.load_json_index() # Write the loaded json to disk and ensure it is as expected. saved_json_index = self.file_creator.create_file('index2.json', '') self.topic_tag_db.index_file = saved_json_index self.topic_tag_db.save_to_json_index() with open(saved_json_index, 'r') as f: self.assertEqual(f.read(), tag_json)