Python DocstyleDefinition.DocstyleDefinition类代码示例

    def test_fields(self):
        c_doxygen = DocstyleDefinition.load('C', 'doxygen')
        uut = DocumentationComment('my doc',
                                   c_doxygen,
                                   ' ',
                                   ('/**', '*', '*/'),
                                   (25, 45))

        self.assertEqual(uut.documentation, 'my doc')
        self.assertEqual(uut.language, 'c')
        self.assertEqual(uut.docstyle, 'doxygen')
        self.assertEqual(uut.indent, ' ')
        self.assertEqual(str(uut), 'my doc')
        self.assertEqual(uut.marker, ('/**', '*', '*/'))
        self.assertEqual(uut.range, (25, 45))

        python_doxygen = DocstyleDefinition.load('python', 'doxygen')

        python_doxygen_metadata = self.Metadata('@param ', ' ', '@return ')

        uut = DocumentationComment('qwertzuiop',
                                   python_doxygen,
                                   '\t',
                                   ('##', '#', '#'),
                                   None)

        self.assertEqual(uut.documentation, 'qwertzuiop')
        self.assertEqual(uut.language, 'python')
        self.assertEqual(uut.docstyle, 'doxygen')
        self.assertEqual(uut.indent, '\t')
        self.assertEqual(str(uut), 'qwertzuiop')
        self.assertEqual(uut.marker, ('##', '#', '#'))
        self.assertEqual(uut.range, None)
        self.assertEqual(uut.metadata, python_doxygen_metadata)

def extract_documentation(content, language, docstyle):
    """
    Extracts all documentation texts inside the given source-code-string using
    the coala docstyle definition files.

    The documentation texts are sorted by their order appearing in ``content``.

    For more information about how documentation comments are identified and
    extracted, see DocstyleDefinition.doctypes enumeration.

    :param content:            The source-code-string where to extract
                               documentation from. Needs to be a list or tuple
                               where each string item is a single line
                               (including ending whitespaces like ``\\n``).
    :param language:           The programming language used.
    :param docstyle:           The documentation style/tool used
                               (e.g. doxygen).
    :raises FileNotFoundError: Raised when the docstyle definition file was not
                               found.
    :raises KeyError:          Raised when the given language is not defined in
                               given docstyle.
    :raises ValueError:        Raised when a docstyle definition setting has an
                               invalid format.
    :return:                   An iterator returning each DocumentationComment
                               found in the content.
    """
    docstyle_definition = DocstyleDefinition.load(language, docstyle)
    return extract_documentation_with_markers(content,
                                              docstyle_definition.markers)

    def test_load(self):
        # Test unregistered docstyle.
        with self.assertRaises(FileNotFoundError):
            next(DocstyleDefinition.load("PYTHON", "INVALID"))

        # Test unregistered language in existing docstyle.
        with self.assertRaises(KeyError):
            next(DocstyleDefinition.load("bake-a-cake", "default"))

        # Test python 3 default configuration and if everything is parsed
        # right.
        result = DocstyleDefinition.load("PYTHON3", "default")

        self.assertEqual(result.language, "python3")
        self.assertEqual(result.docstyle, "default")
        self.assertEqual(result.markers, (('"""', '', '"""'),))

    def test_extract_documentation_C_2(self):
        data = ['/** my main description\n', ' * continues here */']

        docstyle_C_doxygen = DocstyleDefinition.load("C", "doxygen")

        self.assertEqual(
            list(extract_documentation(data, "C", "doxygen")),
            [DocumentationComment(" my main description\n continues here",
                                  docstyle_C_doxygen.markers[0],
                                  TextRange.from_values(1, 1, 2, 21))])

    def test_load_external_coalang(self):
        with TemporaryDirectory() as directory:
            coalang_file = os.path.join(directory, "custom.coalang")
            with open(coalang_file, "w") as file:
                file.write("[COOL]\ndoc-markers = @@,@@,@@\n")

            result = DocstyleDefinition.load(
                "cool", "custom", coalang_dir=directory)
            self.assertEqual(result.language, "cool")
            self.assertEqual(result.docstyle, "custom")
            self.assertEqual(result.markers, (('@@', '@@', '@@'),))

    def test_extract_documentation_PYTHON3_2(self):
        data = ['\n', '""" documentation in single line  """\n', 'print(1)\n']

        docstyle_PYTHON3_default = DocstyleDefinition.load("PYTHON3",
                                                           "default")

        self.assertEqual(
            list(extract_documentation(data, "PYTHON3", "default")),
            [DocumentationComment(" documentation in single line  ",
                                  docstyle_PYTHON3_default.markers[0],
                                  TextRange.from_values(2, 1, 2, 38))])

    def test_extract_documentation_CPP_2(self):
        data = DocumentationExtractionTest.load_testdata("data2.cpp")

        docstyle_CPP_doxygen = DocstyleDefinition.load("CPP", "doxygen")

        self.assertEqual(tuple(extract_documentation(data, "CPP", "doxygen")),
                         (DocumentationComment(
                              ("module comment\n"
                               " hello world\n"),
                              docstyle_CPP_doxygen.markers[0],
                              TextRange.from_values(1, 1, 3, 4)),))

    def test_get_available_definitions_on_wrong_files(self,
                                                      confparser_mock,
                                                      iglob_mock):
        # Test the case when a coalang was provided with uppercase letters.
        confparser_instance_mock = confparser_mock.return_value
        confparser_instance_mock.parse.return_value = ["X"]
        iglob_mock.return_value = ['some/CUSTOMSTYLE.coalang',
                                   'SOME/xlang.coalang']

        self.assertEqual(list(DocstyleDefinition.get_available_definitions()),
                         [('xlang', 'x')])

    def test_DocBaseClass_extraction_C_2(self):
        data = ['/** my main description\n', ' * continues here */']

        docstyle_C_doxygen = DocstyleDefinition.load('C', 'doxygen')

        self.assertEqual(
            list(DocBaseClass.extract(data, 'C', 'doxygen')),
            [DocumentationComment(' my main description\n continues here',
                                  docstyle_C_doxygen, '',
                                  docstyle_C_doxygen.markers[0],
                                  TextPosition(1, 1))])

    def test_DocBaseClass_instantiate_docstring_type_PYTHON3_11(self):
        data = ['def xyz:\n',
                '   """\n',
                '   This docstring is of docstring_type function\n',
                '   """\n']

        docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3',
                                                           'default')

        for doc in DocBaseClass.extract(data, 'PYTHON3', 'default'):
            self.assertEqual(doc.docstring_type, 'function')

    def test_DocBaseClass_extraction_PYTHON3_4(self):
        data = ['\n', 'triple_quote_string_test = """\n',
                'This is not a docstring\n', '"""\n']

        docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3',
                                                           'default')

        # Nothing is yielded as triple quote string literals are being
        # ignored.
        self.assertEqual(
            list(DocBaseClass.extract(data, 'PYTHON3', 'default')),
            [])

    def test_DocBaseClass_extraction_PYTHON3_2(self):
        data = ['\n', '""" documentation in single line  """\n', 'print(1)\n']

        docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3',
                                                           'default')

        self.assertEqual(
            list(DocBaseClass.extract(data, 'PYTHON3', 'default')),
            [DocumentationComment(' documentation in single line  ',
                                  docstyle_PYTHON3_default, '',
                                  docstyle_PYTHON3_default.markers[0],
                                  TextPosition(2, 1))])

    def test_DocBaseClass_CPP_2(self):
        data = load_testdata('data2.cpp')

        docstyle_CPP_doxygen = DocstyleDefinition.load('CPP', 'doxygen')

        self.assertEqual(tuple(DocBaseClass.extract(data, 'CPP', 'doxygen')),
                         (DocumentationComment(
                          ('module comment\n'
                           ' hello world\n'),
                          docstyle_CPP_doxygen, '',
                          docstyle_CPP_doxygen.markers[0],
                          TextPosition(1, 1)),))

    def test_extract_documentation_PYTHON3_3(self):
        data = ['## documentation in single line without return at end.']

        docstyle_PYTHON3_doxygen = DocstyleDefinition.load("PYTHON3",
                                                           "doxygen")

        self.assertEqual(
            list(extract_documentation(data, "PYTHON3", "doxygen")),
            [DocumentationComment(" documentation in single line without "
                                      "return at end.",
                                  docstyle_PYTHON3_doxygen.markers[1],
                                  TextRange.from_values(1, 1, 1, 55))])

    def test_DocBaseClass_extraction_PYTHON3_5(self):
        data = ['r"""\n', 'This is a raw docstring\n', '"""\n']

        docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3',
                                                           'default')

        self.assertEqual(
            list(DocBaseClass.extract(data, 'PYTHON3', 'default')),
            [DocumentationComment('\nThis is a raw docstring\n',
                                  docstyle_PYTHON3_default, 'r',
                                  docstyle_PYTHON3_default.markers[0],
                                  TextPosition(1, 2))])