---

restdoc.py

# Copyright 2012-2013 Amazon.com, Inc. or its affiliates. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"). You # may not use this file except in compliance with the License. A copy of # the License is located at # # http://aws.amazon.com/apache2.0/ # # or in the "license" file accompanying this file. This file is # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF # ANY KIND, either express or implied. See the License for the specific # language governing permissions and limitations under the License. import logging import os import re from botocore.compat import OrderedDict from botocore.docs.bcdoc.docstringparser import DocStringParser from botocore.docs.bcdoc.style import ReSTStyle DEFAULT_AWS_DOCS_LINK = 'https://docs.aws.amazon.com/index.html' DOCUMENTATION_LINK_REGEX = re.compile( r'`AWS API Documentation ' r'<https://docs.aws.amazon.com/goto/WebAPI/[a-z0-9-.]*/[a-zA-Z]*>`_' ) LARGE_SECTION_MESSAGE = """ **{}** :: # This section is too large to render. # Please see the AWS API Documentation linked below. {} """ LOG = logging.getLogger('bcdocs') SECTION_LINE_LIMIT_CONFIG = { 'response-example': {'name': 'Response Syntax', 'line_limit': 1500}, 'description': {'name': 'Response Structure', 'line_limit': 5000}, 'request-example': {'name': 'Request Syntax', 'line_limit': 1500}, 'request-params': {'name': 'Parameters', 'line_limit': 5000}, } SECTION_METHOD_PATH_DEPTH = { 'client-api': 4, 'paginator-api': 3, 'waiter-api': 3, } class ReSTDocument: def __init__(self, target='man'): self.style = ReSTStyle(self) self.target = target self.parser = DocStringParser(self) self.keep_data = True self.do_translation = False self.translation_map = {} self.hrefs = {} self._writes = [] self._last_doc_string = None def _write(self, s): if self.keep_data and s is not None: self._writes.append(s) def write(self, content): """ Write content into the document. """ self._write(content) def writeln(self, content): """ Write content on a newline. """ self._write(f'{self.style.spaces()}{content}\n') def peek_write(self): """ Returns the last content written to the document without removing it from the stack. """ return self._writes[-1] def pop_write(self): """ Removes and returns the last content written to the stack. """ return self._writes.pop() if len(self._writes) > 0 else None def push_write(self, s): """ Places new content on the stack. """ self._writes.append(s) def getvalue(self): """ Returns the current content of the document as a string. """ if self.hrefs: self.style.new_paragraph() for refname, link in self.hrefs.items(): self.style.link_target_definition(refname, link) return ''.join(self._writes).encode('utf-8') def translate_words(self, words): return [self.translation_map.get(w, w) for w in words] def handle_data(self, data): if data and self.keep_data: self._write(data) def include_doc_string(self, doc_string): if doc_string: try: start = len(self._writes) self.parser.feed(doc_string) self.parser.close() end = len(self._writes) self._last_doc_string = (start, end) except Exception: LOG.debug('Error parsing doc string', exc_info=True) LOG.debug(doc_string) def remove_last_doc_string(self): # Removes all writes inserted by last doc string if self._last_doc_string is not None: start, end = self._last_doc_string del self._writes[start:end] class DocumentStructure(ReSTDocument): def __init__(self, name, section_names=None, target='man', context=None): """Provides a Hierarichial structure to a ReSTDocument You can write to it similiar to as you can to a ReSTDocument but has an innate structure for more orginaztion and abstraction. :param name: The name of the document :param section_names: A list of sections to be included in the document. :param target: The target documentation of the Document structure :param context: A dictionary of data to store with the strucuture. These are only stored per section not the entire structure. """ super().__init__(target=target) self._name = name self._structure = OrderedDict() self._path = [self._name] self._context = {} if context is not None: self._context = context if section_names is not None: self._generate_structure(section_names) @property def name(self): """The name of the document structure""" return self._name @property def path(self): """ A list of where to find a particular document structure in the overlying document structure. """ return self._path @path.setter def path(self, value): self._path = value @property def available_sections(self): return list(self._structure) @property def context(self): return self._context def _generate_structure(self, section_names): for section_name in section_names: self.add_new_section(section_name) def add_new_section(self, name, context=None): """Adds a new section to the current document structure This document structure will be considered a section to the current document structure but will in itself be an entirely new document structure that can be written to and have sections as well :param name: The name of the section. :param context: A dictionary of data to store with the strucuture. These are only stored per section not the entire structure. :rtype: DocumentStructure :returns: A new document structure to add to but lives as a section to the document structure it was instantiated from. """ # Add a new section section = self.__class__( name=name, target=self.target, context=context ) section.path = self.path + [name] # Indent the section apporpriately as well section.style.indentation = self.style.indentation section.translation_map = self.translation_map section.hrefs = self.hrefs self._structure[name] = section return section def get_section(self, name): """Retrieve a section""" return self._structure[name] def delete_section(self, name): """Delete a section""" del self._structure[name] def flush_structure(self, docs_link=None): """Flushes a doc structure to a ReSTructed string The document is flushed out in a DFS style where sections and their subsections' values are added to the string as they are visited. """ # We are at the root flush the links at the beginning of the # document path_length = len(self.path) if path_length == 1: if self.hrefs: self.style.new_paragraph() for refname, link in self.hrefs.items(): self.style.link_target_definition(refname, link) # Clear docs_link at the correct depth to prevent passing a non-related link. elif path_length == SECTION_METHOD_PATH_DEPTH.get(self.path[1]): docs_link = None value = self.getvalue() for name, section in self._structure.items(): # Checks is the AWS API Documentation link has been generated. # If it has been generated, it gets passed as a the doc_link parameter. match = DOCUMENTATION_LINK_REGEX.search(value.decode()) docs_link = ( f'{match.group(0)}\n\n'.encode() if match else docs_link ) value += section.flush_structure(docs_link) # Replace response/request sections if the line number exceeds our limit. # The section is replaced with a message linking to AWS API Documentation. line_count = len(value.splitlines()) section_config = SECTION_LINE_LIMIT_CONFIG.get(self.name) aws_docs_link = ( docs_link.decode() if docs_link is not None else DEFAULT_AWS_DOCS_LINK ) if section_config and line_count > section_config['line_limit']: value = LARGE_SECTION_MESSAGE.format( section_config['name'], aws_docs_link ).encode() return value def getvalue(self): return ''.join(self._writes).encode('utf-8') def remove_all_sections(self): self._structure = OrderedDict() def clear_text(self): self._writes = [] def add_title_section(self, title): title_section = self.add_new_section('title') title_section.style.h1(title) return title_section def write_to_file(self, full_path, file_name): if not os.path.exists(full_path): os.makedirs(full_path) sub_resource_file_path = os.path.join(full_path, f'{file_name}.rst') with open(sub_resource_file_path, 'wb') as f: f.write(self.flush_structure())

---

docroot: /var/www/469ed2f6-4d4b-4a8a-9f5e-ee4ef04d3bc8/public_html

---

curdir: /usr/lib/python3/dist-packages/botocore/docs/bcdoc

	.		4096
	..		4096
X	__init__.py		588
	__pycache__		4096
X	docstringparser.py		10207
X	restdoc.py		9698
X	style.py		13148