def test_contains(self):
range_a = TextRange.from_values(1, 1, 1, 19)
range_b = TextRange.from_values(1, 1, 1, 20)
self.assertIn(range_a, range_b)
range_a = TextRange.from_values(1, 1, 1, 21)
range_b = TextRange.from_values(1, 1, 1, 20)
self.assertNotIn(range_a, range_b)
range_a = TextRange.from_values(1, 5, 1, 5)
range_b = TextRange.from_values(1, 1, 1, 20)
self.assertIn(range_a, range_b)
range_a = TextRange.from_values(1, 1, 1, 18)
range_b = TextRange.from_values(1, 14, 1, 20)
self.assertNotIn(range_a, range_b)
range_a = TextRange.from_values(1, 1, 1, 20)
range_b = TextRange.from_values(1, 1, 1, 20)
self.assertIn(range_a, range_b)
def test_extract_documentation_CPP(self):
data = DocumentationExtractionTest.load_testdata("data.cpp")
# No built-in documentation for C++.
with self.assertRaises(KeyError):
tuple(extract_documentation(data, "CPP", "default"))
docstyle_CPP_doxygen = DocstyleDefinition.load("CPP", "doxygen")
self.assertEqual(
tuple(extract_documentation(data, "CPP", "doxygen")),
(DocumentationComment(("\n"
" This is the main function.\n"
" @returns Exit code.\n"
" Or any other number.\n"),
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(4, 1, 8, 4)),
DocumentationComment(
(" foobar\n"
" @param xyz\n"), docstyle_CPP_doxygen.markers[0],
TextRange.from_values(15, 1, 17, 4)),
DocumentationComment(" Some alternate style of documentation\n",
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(22, 1, 23, 1)),
DocumentationComment(" ends instantly",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(26, 5, 26, 26)),
DocumentationComment((" Should work\n"
"\n"
" even without a function standing below.\n"
"\n"
" @param foo WHAT PARAM PLEASE!?\n"),
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(32, 1, 37, 1))))
def test_contains(self):
range_a = TextRange.from_values(1, 1, 1, 19)
range_b = TextRange.from_values(1, 1, 1, 20)
self.assertIn(range_a, range_b)
range_a = TextRange.from_values(1, 1, 1, 21)
range_b = TextRange.from_values(1, 1, 1, 20)
self.assertNotIn(range_a, range_b)
range_a = TextRange.from_values(1, 5, 1, 5)
range_b = TextRange.from_values(1, 1, 1, 20)
self.assertIn(range_a, range_b)
range_a = TextRange.from_values(1, 1, 1, 18)
range_b = TextRange.from_values(1, 14, 1, 20)
self.assertNotIn(range_a, range_b)
range_a = TextRange.from_values(1, 1, 1, 20)
range_b = TextRange.from_values(1, 1, 1, 20)
self.assertIn(range_a, range_b)
def test_properties(self):
uut = TextRange(TextPosition(7, 2), TextPosition(7, 3))
self.assertEqual(uut.start, TextPosition(7, 2))
self.assertEqual(uut.end, TextPosition(7, 3))
uut = TextRange(TextPosition(70, 20), None)
self.assertEqual(uut.start, TextPosition(70, 20))
self.assertEqual(uut.end, TextPosition(70, 20))
self.assertIs(uut.start, uut.end)
def test_no_overlap(self):
uut1 = TextRange.from_values(2, None, 3)
uut2 = TextRange.from_values(4, None, 5)
self.assertFalse(uut1.overlaps(uut2))
self.assertFalse(uut2.overlaps(uut1))
uut1 = TextRange.from_values(2, None, 3, 6)
uut2 = TextRange.from_values(3, 7, 5)
self.assertFalse(uut1.overlaps(uut2))
self.assertFalse(uut2.overlaps(uut1))
def test_no_overlap(self):
uut1 = TextRange.from_values(2, None, 3)
uut2 = TextRange.from_values(4, None, 5)
self.assertFalse(uut1.overlaps(uut2))
self.assertFalse(uut2.overlaps(uut1))
uut1 = TextRange.from_values(2, None, 3, 6)
uut2 = TextRange.from_values(3, 7, 5)
self.assertFalse(uut1.overlaps(uut2))
self.assertFalse(uut2.overlaps(uut1))
def test_fail_instantation(self):
with self.assertRaises(ValueError):
TextRange(TextPosition(3, 4), TextPosition(2, 8))
with self.assertRaises(ValueError):
TextRange(TextPosition(0, 10), TextPosition(0, 7))
with self.assertRaises(TypeError):
TextRange(None, TextPosition(20, 80))
with self.assertRaises(TypeError):
TextRange("string", TextPosition(200, 800))
with self.assertRaises(TypeError):
TextRange(TextPosition(5, 0), "schtring")
def test_fail_instantiation(self):
with self.assertRaises(ValueError):
TextRange(TextPosition(3, 4), TextPosition(2, 8))
with self.assertRaises(ValueError):
TextRange(TextPosition(1, 10), TextPosition(1, 7))
with self.assertRaises(TypeError):
TextRange(None, TextPosition(20, 80))
with self.assertRaises(TypeError):
TextRange('string', TextPosition(200, 800))
with self.assertRaises(TypeError):
TextRange(TextPosition(5, 1), 'schtring')
def test_fails(self):
# need to pass ranges
with self.assertRaises(TypeError):
TextRange.join(self.pos[0], self.pos[1])
with self.assertRaises(TypeError):
TextRange.join(TextRange(self.pos[0], self.pos[1]), self.pos[1])
# ranges must overlap
with self.assertRaises(ValueError):
TextRange.join(TextRange(self.pos[0], self.pos[1]),
TextRange(self.pos[3], self.pos[4]))
def generate_diff(file, doc_comment, new_comment):
"""
Generates diff between the original doc_comment and its fix
new_comment which are instances of DocumentationComment.
:param doc_comment:
Original instance of DocumentationComment.
:param new_comment:
Fixed instance of DocumentationComment.
:return:
Diff instance.
"""
diff = Diff(file)
# We need to update old comment positions, as `assemble()`
# prepends indentation for first line.
old_range = TextRange.from_values(doc_comment.range.start.line, 1,
doc_comment.range.end.line,
doc_comment.range.end.column)
# Clearing cached assemble() so a fresh one is fetched.
new_comment.assemble.cache_clear()
diff.replace(old_range, new_comment.assemble())
return diff
def __init__(self, documentation, docstyle_definition,
indent, marker, position):
"""
Instantiates a new DocumentationComment.
:param documentation:
The documentation text.
:param docstyle_definition:
The ``DocstyleDefinition`` instance that defines what docstyle is
being used in the documentation.
:param indent:
The string of indentation used in front of the first marker of the
documentation.
:param marker:
The three-element tuple with marker strings, that identified this
documentation comment.
:param position:
The starting ``TextPosition`` of the documentation.
"""
self.documentation = documentation
self.docstyle_definition = docstyle_definition
self.indent = '' if indent is None else indent
self.marker = ('', '', '') if marker is None else marker
self.position = position
self.range = None if position is None else TextRange.from_values(
position.line,
position.column,
position.line + self.assemble().count('\n'),
len(self.assemble()) - self.assemble().rfind('\n'))
def __init__(self,
file=None,
index=None,
language=None,
start: NlSectionPosition,
end: (NlSectionPosition, None) = None,
temp_file=None):
"""
Creates a new NlSection.
:param start: A NlSectionPosition indicating the start of the
section in original file.
:param end: A NlSectionPosition indicating the end of the
section in the original file.
If ``None`` is given, the start object will be used
here. end must be in the same file and be greater
than start as negative ranges are not allowed.
:param language: The programming language of the lines.
:param index: The index of the nl_section.
:param file: The name of the original file
:param temp_file: The name of the temporary segregated file
:raises TypeError: Raised when
- start is not of type NlSectionPosition.
- end is neither of type NlSectionPosition, nor
is it None.
:raises ValueError: Raised when file of start and end mismatch.
"""
TextRange.__init__(self, start, end)
self.index = index
self.language = language
self.file = file
"""
:linted_start: The start of the section in the linted file.Initially it
is same as that of the start of the original file. It
changes only when any patches are applied on that line.
:linted_end: The end of the section in the linted file.Initially it
is same as that of the end of the original file. It
changes only when any patches are applied on that line.
"""
self.linted_start = NlSectionPosition(file, start.line, start.column)
if end:
self.linted_end = NlSectionPosition(file, end.line, end.column)
else:
end = None
if self.start.file != self.end.file:
raise ValueError('File of start and end position do not match.')
def test_join(self):
# overlap
self.assertEqual(TextRange.join(TextRange(self.pos[0], self.pos[2]),
TextRange(self.pos[1], self.pos[3])),
TextRange(self.pos[0], self.pos[3]))
self.assertEqual(TextRange.join(TextRange(self.pos[1], self.pos[3]),
TextRange(self.pos[2], self.pos[4])),
TextRange(self.pos[1], self.pos[4]))
# embrace
self.assertEqual(TextRange.join(TextRange(self.pos[0], self.pos[3]),
TextRange(self.pos[1], self.pos[2])),
TextRange(self.pos[0], self.pos[3]))
# touch
self.assertEqual(TextRange.join(TextRange(self.pos[1], self.pos[2]),
TextRange(self.pos[2], self.pos[3])),
TextRange(self.pos[1], self.pos[3]))
def test_extract_documentation_C(self):
data = load_testdata("data.c")
# No built-in documentation for C.
with self.assertRaises(KeyError):
tuple(extract_documentation(data, "C", "default"))
docstyle_C_doxygen = DocstyleDefinition.load("C", "doxygen")
expected_results = (DocumentationComment(
("\n"
" This is the main function.\n"
"\n"
" @returns Your favorite number.\n"),
docstyle_C_doxygen, "",
docstyle_C_doxygen.markers[0],
TextRange.from_values(3, 1, 7, 4)),
DocumentationComment(
("\n"
" Preserves alignment\n"
" - Main item\n"
" - sub item\n"
" - sub sub item\n"),
docstyle_C_doxygen, "",
docstyle_C_doxygen.markers[2],
TextRange.from_values(15, 1, 20, 4)),
DocumentationComment(
(" ABC\n"
" Another type of comment\n"
"\n"
" ..."),
docstyle_C_doxygen, "",
docstyle_C_doxygen.markers[1],
TextRange.from_values(23, 1, 26, 11)),
DocumentationComment(
(" foobar = barfoo.\n"
" @param x whatever...\n"),
docstyle_C_doxygen, "",
docstyle_C_doxygen.markers[0],
TextRange.from_values(28, 1, 30, 4)))
self.assertEqual(tuple(
extract_documentation(data, "C", "doxygen")),
expected_results)
def test_extract_documentation_C(self):
data = load_testdata('data.c')
# No built-in documentation for C.
with self.assertRaises(KeyError):
tuple(extract_documentation(data, 'C', 'default'))
docstyle_C_doxygen = DocstyleDefinition.load('C', 'doxygen')
expected_results = (DocumentationComment(
('\n'
' This is the main function.\n'
'\n'
' @returns Your favorite number.\n'),
docstyle_C_doxygen, '',
docstyle_C_doxygen.markers[0],
TextRange.from_values(3, 1, 7, 4)),
DocumentationComment(
('\n'
' Preserves alignment\n'
' - Main item\n'
' - sub item\n'
' - sub sub item\n'),
docstyle_C_doxygen, '',
docstyle_C_doxygen.markers[2],
TextRange.from_values(15, 1, 20, 4)),
DocumentationComment(
(' ABC\n'
' Another type of comment\n'
'\n'
' ...'),
docstyle_C_doxygen, '',
docstyle_C_doxygen.markers[1],
TextRange.from_values(23, 1, 26, 11)),
DocumentationComment(
(' foobar = barfoo.\n'
' @param x whatever...\n'),
docstyle_C_doxygen, '',
docstyle_C_doxygen.markers[0],
TextRange.from_values(28, 1, 30, 4)))
self.assertEqual(tuple(
extract_documentation(data, 'C', 'doxygen')),
expected_results)
def test_extract_documentation_CPP(self):
data = load_testdata('data.cpp')
# No built-in documentation for C++.
with self.assertRaises(KeyError):
tuple(extract_documentation(data, 'CPP', 'default'))
docstyle_CPP_doxygen = DocstyleDefinition.load('CPP', 'doxygen')
self.assertEqual(tuple(extract_documentation(data, 'CPP', 'doxygen')),
(DocumentationComment(
('\n'
' This is the main function.\n'
' @returns Exit code.\n'
' Or any other number.\n'),
docstyle_CPP_doxygen, '',
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(4, 1, 8, 4)),
DocumentationComment(
(' foobar\n'
' @param xyz\n'),
docstyle_CPP_doxygen, '',
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(15, 1, 17, 4)),
DocumentationComment(
' Some alternate style of documentation\n',
docstyle_CPP_doxygen, '',
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(22, 1, 23, 1)),
DocumentationComment(
' ends instantly',
docstyle_CPP_doxygen, '\t',
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(26, 2, 26, 23)),
DocumentationComment(
(' Should work\n'
'\n'
' even without a function standing below.\n'
'\n'
' @param foo WHAT PARAM PLEASE!?\n'),
docstyle_CPP_doxygen, '',
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(32, 1, 37, 1))))
def __init__(self, start: SourcePosition, end: (SourcePosition, None) = None):
"""
Creates a new SourceRange.
:param start: A SourcePosition indicating the start of the range.
:param end: A SourcePosition indicating the end of the range.
If ``None`` is given, the start object will be used
here. end must be in the same file and be greater
than start as negative ranges are not allowed.
:raises TypeError: Raised when
- start is not of type SourcePosition.
- end is neither of type SourcePosition, nor is it
None.
:raises ValueError: Raised when file of start and end mismatch.
"""
TextRange.__init__(self, start, end)
if self.start.file != self.end.file:
raise ValueError("File of start and end position do not match.")
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_extract_documentation_CPP(self):
data = load_testdata("data.cpp")
# No built-in documentation for C++.
with self.assertRaises(KeyError):
tuple(extract_documentation(data, "CPP", "default"))
docstyle_CPP_doxygen = DocstyleDefinition.load("CPP", "doxygen")
self.assertEqual(tuple(extract_documentation(data, "CPP", "doxygen")),
(DocumentationComment(
("\n"
" This is the main function.\n"
" @returns Exit code.\n"
" Or any other number.\n"),
docstyle_CPP_doxygen, "",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(4, 1, 8, 4)),
DocumentationComment(
(" foobar\n"
" @param xyz\n"),
docstyle_CPP_doxygen, "",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(15, 1, 17, 4)),
DocumentationComment(
" Some alternate style of documentation\n",
docstyle_CPP_doxygen, "",
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(22, 1, 23, 1)),
DocumentationComment(
" ends instantly",
docstyle_CPP_doxygen, "\t",
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(26, 2, 26, 23)),
DocumentationComment(
(" Should work\n"
"\n"
" even without a function standing below.\n"
"\n"
" @param foo WHAT PARAM PLEASE!?\n"),
docstyle_CPP_doxygen, "",
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(32, 1, 37, 1))))
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_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", "C",
"doxygen", "", docstyle_C_doxygen.markers[0],
TextRange.from_values(1, 1, 2, 21))
])
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_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 = 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, '',
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(1, 1, 3, 4)), ))
def __init__(self,
start: SourcePosition,
end: (SourcePosition, None) = None):
"""
Creates a new SourceRange.
:param start: A SourcePosition indicating the start of the range.
:param end: A SourcePosition indicating the end of the range.
If ``None`` is given, the start object will be used
here. end must be in the same file and be greater
than start as negative ranges are not allowed.
:raises TypeError: Raised when
- start is no SourcePosition or None.
- end is no SourcePosition.
:raises ValueError: Raised when file of start and end mismatch.
"""
TextRange.__init__(self, start, end)
if self.start.file != self.end.file:
raise ValueError("File of start and end position do not match.")
def test_extract_documentation_CPP_2(self):
data = 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, '',
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(1, 1, 3, 4)),))
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_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_extract_documentation_PYTHON3(self):
data = DocumentationExtractionTest.load_testdata("data.py")
docstyle_PYTHON3_default = DocstyleDefinition.load(
"PYTHON3", "default")
docstyle_PYTHON3_doxygen = DocstyleDefinition.load(
"PYTHON3", "doxygen")
expected = (DocumentationComment(("\n"
"Module description.\n"
"\n"
"Some more foobar-like text.\n"),
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(1, 1, 5, 4)),
DocumentationComment(
("\n"
"A nice and neat way of documenting code.\n"
":param radius: The explosion radius.\n"),
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(8, 5, 11, 8)),
DocumentationComment(
("\n"
"Docstring with layouted text.\n"
"\n"
" layouts inside docs are preserved for these "
"documentation styles.\n"
"this is intended.\n"),
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(14, 1, 19, 4)),
DocumentationComment(
(" Docstring directly besides triple quotes.\n"
" Continues here. "),
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(21, 1, 22, 24)),
DocumentationComment(("super\n"
" nicely\n"
"short"),
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(35, 1, 37, 9)))
self.assertEqual(
tuple(extract_documentation(data, "PYTHON3", "default")), expected)
# Change only the docstyle in expected results.
expected = list(
DocumentationComment(r.documentation, r.marker, r.range)
for r in expected)
expected.insert(
4,
DocumentationComment(
(" Alternate documentation style in doxygen.\n"
" Subtext\n"
" More subtext (not correctly aligned)\n"
" sub-sub-text\n"
"\n"), docstyle_PYTHON3_doxygen.markers[1],
TextRange.from_values(25, 1, 30, 1)))
self.assertEqual(
list(extract_documentation(data, "PYTHON3", "doxygen")), expected)
def test_extract_documentation_C(self):
data = load_testdata('data.c')
# No built-in documentation for C.
with self.assertRaises(KeyError):
tuple(extract_documentation(data, 'C', 'default'))
docstyle_C_doxygen = DocstyleDefinition.load('C', 'doxygen')
expected_results = (DocumentationComment(
('\n'
' This is the main function.\n'
'\n'
' @returns Your favorite number.\n'), docstyle_C_doxygen, '',
docstyle_C_doxygen.markers[0], TextRange.from_values(3, 1, 7, 4)),
DocumentationComment(
('\n'
' Preserves alignment\n'
' - Main item\n'
' - sub item\n'
' - sub sub item\n'), docstyle_C_doxygen,
'', docstyle_C_doxygen.markers[2],
TextRange.from_values(15, 1, 20, 4)),
DocumentationComment(
(' ABC\n'
' Another type of comment\n'
'\n'
' ...'), docstyle_C_doxygen, '',
docstyle_C_doxygen.markers[1],
TextRange.from_values(23, 1, 26, 11)),
DocumentationComment(
(' foobar = barfoo.\n'
' @param x whatever...\n'),
docstyle_C_doxygen, '',
docstyle_C_doxygen.markers[0],
TextRange.from_values(28, 1, 30, 4)))
self.assertEqual(tuple(extract_documentation(data, 'C', 'doxygen')),
expected_results)
def test_extract_documentation_CPP(self):
data = load_testdata('data.cpp')
# No built-in documentation for C++.
with self.assertRaises(KeyError):
tuple(extract_documentation(data, 'CPP', 'default'))
docstyle_CPP_doxygen = DocstyleDefinition.load('CPP', 'doxygen')
self.assertEqual(
tuple(extract_documentation(data, 'CPP', 'doxygen')),
(DocumentationComment(
('\n'
' This is the main function.\n'
' @returns Exit code.\n'
' Or any other number.\n'), docstyle_CPP_doxygen, '',
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(4, 1, 8, 4)),
DocumentationComment((' foobar\n'
' @param xyz\n'), docstyle_CPP_doxygen, '',
docstyle_CPP_doxygen.markers[0],
TextRange.from_values(15, 1, 17, 4)),
DocumentationComment(' Some alternate style of documentation\n',
docstyle_CPP_doxygen, '',
docstyle_CPP_doxygen.markers[4],
TextRange.from_values(22, 1, 23, 1)),
DocumentationComment(' ends instantly', docstyle_CPP_doxygen,
'\t', docstyle_CPP_doxygen.markers[0],
TextRange.from_values(26, 2, 26, 23)),
DocumentationComment(
(' Should work\n'
'\n'
' even without a function standing below.\n'
'\n'
' @param foo WHAT PARAM PLEASE!?\n'), docstyle_CPP_doxygen,
'', docstyle_CPP_doxygen.markers[4],
TextRange.from_values(32, 1, 37, 1))))
def test_fails(self):
# need to pass ranges
with self.assertRaises(TypeError):
TextRange.join(self.pos[0], self.pos[1])
with self.assertRaises(TypeError):
TextRange.join(TextRange(self.pos[0], self.pos[1]), self.pos[1])
# ranges must overlap
with self.assertRaises(ValueError):
TextRange.join(TextRange(self.pos[0], self.pos[1]), TextRange(self.pos[3], self.pos[4]))
def _extract_doc_comment_from_line(content, line, column, regex, marker_dict):
begin_match = regex.search(content[line], column)
if begin_match:
column = begin_match.end()
for marker in marker_dict[begin_match.group()]:
doc_comment = _extract_doc_comment(content, line, column, marker)
if doc_comment is not None:
end_line, end_column, documentation = doc_comment
rng = TextRange.from_values(line + 1,
begin_match.start() + 1,
end_line + 1, end_column + 1)
doc = DocumentationComment(documentation, marker, rng)
return end_line, end_column, doc
return line + 1, 0, None
def expand(self, file_contents):
"""
Passes a new SourceRange that covers the same area of a file as this
one would. All values of None get replaced with absolute values.
values of None will be interpreted as follows:
self.start.line is None: -> 1
self.start.column is None: -> 1
self.end.line is None: -> last line of file
self.end.column is None: -> last column of self.end.line
:param file_contents: File contents of the applicable file
:return: TextRange with absolute values
"""
tr = TextRange.expand(self, file_contents)
return SourceRange.from_values(self.file, tr.start.line, tr.start.column, tr.end.line, tr.end.column)
def _extract_doc_comment_from_line(content, line, column, regex, marker_dict):
begin_match = regex.search(content[line], column)
if begin_match:
column = begin_match.end()
for marker in marker_dict[begin_match.group()]:
doc_comment = _extract_doc_comment(content, line, column, marker)
if doc_comment is not None:
end_line, end_column, documentation = doc_comment
rng = TextRange.from_values(line + 1,
begin_match.start() + 1,
end_line + 1,
end_column + 1)
doc = DocumentationComment(documentation, marker, rng)
return end_line, end_column, doc
return line + 1, 0, None
def test_overlap(self):
uut1 = TextRange.from_values(2, None, 3)
uut2 = TextRange.from_values(3, None, 5)
self.assertTrue(uut1.overlaps(uut2))
self.assertTrue(uut2.overlaps(uut1))
uut1 = TextRange.from_values(2, None, 3, 6)
uut2 = TextRange.from_values(3, 6, 5)
self.assertTrue(uut1.overlaps(uut2))
self.assertTrue(uut2.overlaps(uut1))
uut1 = TextRange.from_values(2, None, 7)
uut2 = TextRange.from_values(3, None, 5)
self.assertTrue(uut1.overlaps(uut2))
self.assertTrue(uut2.overlaps(uut1))
uut1 = TextRange.from_values(5, None, 7)
uut2 = TextRange.from_values(3, None, 6)
self.assertTrue(uut1.overlaps(uut2))
self.assertTrue(uut2.overlaps(uut1))
def test_overlap(self):
uut1 = TextRange.from_values(2, None, 3)
uut2 = TextRange.from_values(3, None, 5)
self.assertTrue(uut1.overlaps(uut2))
self.assertTrue(uut2.overlaps(uut1))
uut1 = TextRange.from_values(2, None, 3, 6)
uut2 = TextRange.from_values(3, 6, 5)
self.assertTrue(uut1.overlaps(uut2))
self.assertTrue(uut2.overlaps(uut1))
uut1 = TextRange.from_values(2, None, 7)
uut2 = TextRange.from_values(3, None, 5)
self.assertTrue(uut1.overlaps(uut2))
self.assertTrue(uut2.overlaps(uut1))
uut1 = TextRange.from_values(5, None, 7)
uut2 = TextRange.from_values(3, None, 6)
self.assertTrue(uut1.overlaps(uut2))
self.assertTrue(uut2.overlaps(uut1))
def expand(self, file_contents):
"""
Passes a new SourceRange that covers the same area of a file as this
one would. All values of None get replaced with absolute values.
values of None will be interpreted as follows:
self.start.line is None: -> 1
self.start.column is None: -> 1
self.end.line is None: -> last line of file
self.end.column is None: -> last column of self.end.line
:param file_contents: File contents of the applicable file
:return: TextRange with absolute values
"""
tr = TextRange.expand(self, file_contents)
return SourceRange.from_values(self.file, tr.start.line,
tr.start.column, tr.end.line,
tr.end.column)
def insert(self, position, text):
r"""
Inserts (multiline) text at arbitrary position.
>>> from coalib.results.TextPosition import TextPosition
>>> test_text = ['123\n', '456\n', '789\n']
>>> def insert(position, text):
... diff = Diff(test_text)
... diff.insert(position, text)
... return diff.modified
>>> insert(TextPosition(2, 3), 'woopy doopy')
['123\n', '45woopy doopy6\n', '789\n']
>>> insert(TextPosition(1, 1), 'woopy\ndoopy')
['woopy\n', 'doopy123\n', '456\n', '789\n']
>>> insert(TextPosition(2, 4), '\nwoopy\ndoopy\n')
['123\n', '456\n', 'woopy\n', 'doopy\n', '\n', '789\n']
:param position: The ``TextPosition`` where to insert text.
:param text: The text to insert.
"""
self.replace(TextRange(position, position), text)
def test_generate_diff(self):
data_old = ['\n', '""" documentation in single line """\n']
for doc_comment in DocBaseClass.extract(data_old, 'PYTHON3',
'default'):
old_doc_comment = doc_comment
old_range = TextRange.from_values(old_doc_comment.range.start.line, 1,
old_doc_comment.range.end.line,
old_doc_comment.range.end.column)
data_new = ['\n', '"""\n documentation in single line\n"""\n']
for doc_comment in DocBaseClass.extract(data_new, 'PYTHON3',
'default'):
new_doc_comment = doc_comment
diff = DocBaseClass.generate_diff(data_old, old_doc_comment,
new_doc_comment)
diff_expected = Diff(data_old)
diff_expected.replace(old_range, new_doc_comment.assemble())
self.assertEqual(diff, diff_expected)
def test_generate_diff(self):
data_old = ['\n', '""" documentation in single line """\n']
for doc_comment in DocBaseClass.extract(
data_old, 'PYTHON3', 'default'):
old_doc_comment = doc_comment
old_range = TextRange.from_values(
old_doc_comment.range.start.line,
1,
old_doc_comment.range.end.line,
old_doc_comment.range.end.column)
data_new = ['\n', '"""\n documentation in single line\n"""\n']
for doc_comment in DocBaseClass.extract(
data_new, 'PYTHON3', 'default'):
new_doc_comment = doc_comment
diff = DocBaseClass.generate_diff(
data_old, old_doc_comment, new_doc_comment)
diff_expected = Diff(data_old)
diff_expected.replace(old_range, new_doc_comment.assemble())
self.assertEqual(diff, diff_expected)
def test_from_values(self):
# Check if invalid ranges still fail.
with self.assertRaises(ValueError):
TextRange.from_values(0, 10, 0, 7)
uut = TextRange.from_values(1, 0, 7, 3)
self.assertEqual(uut.start, TextPosition(1, 0))
self.assertEqual(uut.end, TextPosition(7, 3))
uut = TextRange.from_values(1, 0, None, 88)
self.assertEqual(uut.start, TextPosition(1, 0))
self.assertEqual(uut.end, TextPosition(1, 0))
uut = TextRange.from_values(1, 0, 7, None)
self.assertEqual(uut.start, TextPosition(1, 0))
self.assertEqual(uut.end, TextPosition(7, None))
# Test defaults.
uut = TextRange.from_values()
self.assertEqual(uut.start, TextPosition(None, None))
self.assertEqual(uut.end, TextPosition(None, None))
def test_from_values(self):
# Check if invalid ranges still fail.
with self.assertRaises(ValueError):
TextRange.from_values(0, 10, 0, 7)
uut = TextRange.from_values(1, 0, 7, 3)
self.assertEqual(uut.start, TextPosition(1, 0))
self.assertEqual(uut.end, TextPosition(7, 3))
uut = TextRange.from_values(1, 0, None, 88)
self.assertEqual(uut.start, TextPosition(1, 0))
self.assertEqual(uut.end, TextPosition(1, 0))
uut = TextRange.from_values(1, 0, 7, None)
self.assertEqual(uut.start, TextPosition(1, 0))
self.assertEqual(uut.end, TextPosition(7, None))
# Test defaults.
uut = TextRange.from_values()
self.assertEqual(uut.start, TextPosition(None, None))
self.assertEqual(uut.end, TextPosition(None, None))
def extract_documentation_with_markers(content, docstyle_definition):
"""
Extracts all documentation texts inside the given source-code-string.
: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 docstyle_definition:
The ``DocstyleDefinition`` instance that defines what docstyle is
being used in the documentation.
:return:
An iterator returning each DocumentationComment found in the content.
"""
# Prepare marker-tuple dict that maps a begin pattern to the corresponding
# marker_set(s). This makes it faster to retrieve a marker-set from a
# begin sequence we initially want to search for in source code. Then
# the possible found documentation match is processed further with the
# rest markers.
markers = docstyle_definition.markers
marker_dict = {}
for marker_set in markers:
if marker_set[0] not in marker_dict:
marker_dict[marker_set[0]] = [marker_set]
else:
marker_dict[marker_set[0]].append(marker_set)
# Using regexes to perform a variable match is faster than finding each
# substring with ``str.find()`` choosing the lowest match.
begin_regex = _compile_multi_match_regex(
marker_set[0] for marker_set in markers)
line = 0
column = 0
while line < len(content):
line, column, doc = _extract_doc_comment_from_line(
content,
line,
column,
begin_regex,
marker_dict,
docstyle_definition)
if doc and isinstance(doc, MalformedComment):
yield doc
elif doc:
# Ignore string literals
ignore_regex = re.compile(
'^\s*r?(?P<marker>' +
('|'.join(re.escape(s) for s in doc.marker[0])) +
')')
# Starting line of doc_string where marker is present
start_line = doc.range.start.line - 1
ignore_string_match = ignore_regex.search(content[start_line])
# Instantiate padding
top_padding = 0
bottom_padding = 0
# minus 2 because we want to check the line before the marker.
start_index = doc.range.start.line - 2
end_index = doc.range.end.line
while start_index >= 0 and not content[start_index].strip():
top_padding += 1
start_index -= 1
# If the end_index is instantiated above the len(content) i.e.
# In case where ending marker of docstring is at the last line.
# Then the doc.bottom_padding will be default to 0. This will also
# prevent IndexError raised by content[end_index].
while end_index < len(content) and not content[end_index].strip():
# This condition will take place if theres an inline docstring
# following documentation.
if ((doc.marker[2]+'\n') != content[end_index-1][-4:]
and bottom_padding == 0):
break
bottom_padding += 1
end_index += 1
class_regex = re.compile(
doc.docstyle_definition.docstring_type_regex.class_sign)
function_regex = re.compile(
doc.docstyle_definition.docstring_type_regex.func_sign)
# End line differs when mid marker and end marker is different
if doc.marker[1] == doc.marker[2]:
end_index = end_index - 1
# Check for docstring_position and then check for class regex
# and function regex to define the type of docstring.
if doc.docstyle_definition.docstring_position == 'top':
if class_regex.search(content[start_index]):
doc.docstring_type = 'class'
elif function_regex.search(content[start_index]):
doc.docstring_type = 'function'
elif doc.docstyle_definition.docstring_position == 'bottom':
if (end_index < len(content) and
class_regex.search(content[end_index])):
doc.docstring_type = 'class'
elif (end_index < len(content) and
function_regex.search(content[end_index])):
doc.docstring_type = 'function'
# Disabled automatic padding for docstring_type='others' as this
# will cause overlapping of range in consecutive docstrings. Which
# diff.replace() is unable to handle.
if doc.docstring_type != 'others':
doc.top_padding = top_padding
doc.bottom_padding = bottom_padding
doc.range = TextRange.from_values(
start_index + 2,
1 if top_padding > 0 else doc.range.start.column,
end_index,
1 if bottom_padding > 0 else doc.range.end.column)
if ignore_string_match:
yield doc
def test_expand_full(self):
empty_position = TextPosition()
file = ["abc\n", "def\n", "ghi\n"]
empty_range = TextRange(empty_position, empty_position)
full_range = TextRange.from_values(1, 1, 3, 4)
self.assertEqual(empty_range.expand(file), full_range)
def test_expand_none(self):
start_position = TextPosition(2, 2)
end_position = TextPosition(3, 2)
file = ["abc\n", "def\n", "ghi\n"]
text_range = TextRange(start_position, end_position)
self.assertEqual(text_range.expand(file), text_range)
def test_expand_semi(self):
file = ["abc\n", "defg\n", "hijkl\n", "mnopqr\n"]
semi_range = TextRange.from_values(2, None, 3, None)
full_range = TextRange.from_values(2, 1, 3, 6)
self.assertEqual(semi_range.expand(file), full_range)
def test_expand_none(self):
start_position = TextPosition(2, 2)
end_position = TextPosition(3, 2)
file = ["abc\n", "def\n", "ghi\n"]
text_range = TextRange(start_position, end_position)
self.assertEqual(text_range.expand(file), text_range)
def test_join(self):
# overlap
self.assertEqual(
TextRange.join(TextRange(self.pos[0], self.pos[2]),
TextRange(self.pos[1], self.pos[3])),
TextRange(self.pos[0], self.pos[3]))
self.assertEqual(
TextRange.join(TextRange(self.pos[1], self.pos[3]),
TextRange(self.pos[2], self.pos[4])),
TextRange(self.pos[1], self.pos[4]))
# embrace
self.assertEqual(
TextRange.join(TextRange(self.pos[0], self.pos[3]),
TextRange(self.pos[1], self.pos[2])),
TextRange(self.pos[0], self.pos[3]))
# touch
self.assertEqual(
TextRange.join(TextRange(self.pos[1], self.pos[2]),
TextRange(self.pos[2], self.pos[3])),
TextRange(self.pos[1], self.pos[3]))
def test_expand_semi(self):
file = ["abc\n", "defg\n", "hijkl\n", "mnopqr\n"]
semi_range = TextRange.from_values(2, None, 3, None)
full_range = TextRange.from_values(2, 1, 3, 6)
self.assertEqual(semi_range.expand(file), full_range)
def test_extract_documentation_PYTHON3(self):
data = DocumentationExtractionTest.load_testdata("data.py")
docstyle_PYTHON3_default = DocstyleDefinition.load("PYTHON3",
"default")
docstyle_PYTHON3_doxygen = DocstyleDefinition.load("PYTHON3",
"doxygen")
expected = (DocumentationComment(
("\n"
"Module description.\n"
"\n"
"Some more foobar-like text.\n"),
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(1, 1, 5, 4)),
DocumentationComment(
("\n"
"A nice and neat way of documenting code.\n"
":param radius: The explosion radius.\n"),
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(8, 5, 11, 8)),
DocumentationComment(
("\n"
"Docstring with layouted text.\n"
"\n"
" layouts inside docs are preserved for these "
"documentation styles.\n"
"this is intended.\n"),
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(14, 1, 19, 4)),
DocumentationComment(
(" Docstring directly besides triple quotes.\n"
" Continues here. "),
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(21, 1, 22, 24)),
DocumentationComment(
("super\n"
" nicely\n"
"short"),
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(35, 1, 37, 9)))
self.assertEqual(
tuple(extract_documentation(data, "PYTHON3", "default")),
expected)
# Change only the docstyle in expected results.
expected = list(DocumentationComment(r.documentation,
r.marker,
r.range)
for r in expected)
expected.insert(4, DocumentationComment(
(" Alternate documentation style in doxygen.\n"
" Subtext\n"
" More subtext (not correctly aligned)\n"
" sub-sub-text\n"
"\n"),
docstyle_PYTHON3_doxygen.markers[1],
TextRange.from_values(25, 1, 30, 1)))
self.assertEqual(
list(extract_documentation(data, "PYTHON3", "doxygen")),
expected)
def test_extract_documentation_PYTHON3(self):
data = load_testdata('data.py')
docstyle_PYTHON3_default = DocstyleDefinition.load('PYTHON3',
'default')
docstyle_PYTHON3_doxygen = DocstyleDefinition.load('PYTHON3',
'doxygen')
expected = (DocumentationComment(
('\n'
'Module description.\n'
'\n'
'Some more foobar-like text.\n'),
docstyle_PYTHON3_default, '',
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(1, 1, 5, 4)),
DocumentationComment(
('\n'
'A nice and neat way of documenting code.\n'
':param radius: The explosion radius.\n'),
docstyle_PYTHON3_default, ' ' * 4,
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(8, 5, 11, 8)),
DocumentationComment(
'\nA function that returns 55.\n',
docstyle_PYTHON3_default, ' ' * 8,
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(13, 9, 15, 12)),
DocumentationComment(
('\n'
'Docstring with layouted text.\n'
'\n'
' layouts inside docs are preserved for these '
'documentation styles.\n'
'this is intended.\n'),
docstyle_PYTHON3_default, '',
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(19, 1, 24, 4)),
DocumentationComment(
(' Docstring directly besides triple quotes.\n'
' Continues here. '),
docstyle_PYTHON3_default, '',
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(26, 1, 27, 24)),
DocumentationComment(
('super\n'
' nicely\n'
'short'),
docstyle_PYTHON3_default, '',
docstyle_PYTHON3_default.markers[0],
TextRange.from_values(40, 1, 42, 9)))
self.assertEqual(
tuple(extract_documentation(data, 'PYTHON3', 'default')),
expected)
# Change only the docstyle in expected results.
expected = list(DocumentationComment(r.documentation,
docstyle_PYTHON3_doxygen,
r.indent,
r.marker,
r.range)
for r in expected)
expected.insert(5, DocumentationComment(
(' Alternate documentation style in doxygen.\n'
' Subtext\n'
' More subtext (not correctly aligned)\n'
' sub-sub-text\n'
'\n'),
docstyle_PYTHON3_doxygen, '',
docstyle_PYTHON3_doxygen.markers[1],
TextRange.from_values(30, 1, 35, 1)))
self.assertEqual(
list(extract_documentation(data, 'PYTHON3', 'doxygen')),
expected)
def test_expand_full(self):
empty_position = TextPosition()
file = ["abc\n", "def\n", "ghi\n"]
empty_range = TextRange(empty_position, empty_position)
full_range = TextRange.from_values(1, 1, 3, 4)
self.assertEqual(empty_range.expand(file), full_range)
