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)
