def parse_file(fullpath,filename):
"""Parse a single file (which we hope is a Python file).
* `fullpath` is the full path of the file
* `filename` is the name we want to use for it in the docutils tree
Returns a docutils parse tree for said file.
"""
if DEBUG: print "Parsing file",fullpath
# @@@ Should we worry about the extension of the file?
# Trying to use that to predict the contents can be a problem
# - we already know that we have to worry about ".pyw" as well
# as ".py", not to mention the possibility (e.g., on Unix) of
# having removed the extension in order to make an executable
# file "look" more like a Unix executable. On the whole, it's
# probably better to try to parse a file, and worry about it
# not parsing if/when that occurs.
module = open(fullpath)
try:
module_body = module.read()
try:
module_node = parse_module(module_body,filename)
except SyntaxError:
# OK - it wasn't Python - so what *should* we do with it?
module_node = NotPython(filename)
if DEBUG: print " (not Python)"
return module_node
finally:
module.close()
def extract_docstrings(content_raw,name):
""" extracts docstrings
## derive document strings:
## [ [line1_comment1,line2_comment1], [line1_comment2],.. ]
"""
dox2 = []
lines = content_raw.split('\n')
doctree = parse_module(content_raw, name)
doctree_list = doctree.traverse()
doctree_list = [ x for x in doctree_list if x.tagname=='docstring' ]
dox = [ [ x.parent, # What the comment is for
x[0].astext().split('\n'), # What the comment actually *is*
] \
for x in doctree_list ]
#from IPython import Shell; Shell.IPShellEmbed(argv=['-noconfirm_exit'])()
tmp = [strip_string_markers(line) for line in lines]
tmp_stripped = [x.strip() for x in tmp]
## correlate docstrings to line numbers
## [ [[lineX, line1_comment1 ], [lineX+1, line2_comment1, ], [ [lineY, line1_comment2,],.. ]
for parent, docstring in dox: # [x[-1] for x in dox]:
row = []
for line in docstring:
try:
lineno = tmp_stripped.index(strip_string_markers(line).strip())
except ValueError:
lineno='-1'
raise Exception, [strip_string_markers(line), tmp[8:12]]
if line.strip():
row.append(Comment(lineno=lineno,
text=line,
owner=parent,
full_line=True))
if row: dox2.append(row)
return dox2
def parse_file(fullpath, filename):
"""Parse a single file (which we hope is a Python file).
* `fullpath` is the full path of the file
* `filename` is the name we want to use for it in the docutils tree
Returns a docutils parse tree for said file.
"""
if DEBUG: print "Parsing file", fullpath
# @@@ Should we worry about the extension of the file?
# Trying to use that to predict the contents can be a problem
# - we already know that we have to worry about ".pyw" as well
# as ".py", not to mention the possibility (e.g., on Unix) of
# having removed the extension in order to make an executable
# file "look" more like a Unix executable. On the whole, it's
# probably better to try to parse a file, and worry about it
# not parsing if/when that occurs.
module = open(fullpath)
try:
module_body = module.read()
try:
module_node = parse_module(module_body, filename)
except SyntaxError:
# OK - it wasn't Python - so what *should* we do with it?
module_node = NotPython(filename)
if DEBUG: print " (not Python)"
return module_node
finally:
module.close()
def parse(self):
"""Parse `self.input` into a document tree."""
tree = parse_module(self.input, self.source.source_path)
self.document = document = make_document(tree)
#self.document = document = self.new_document()
#self.parser.parse(self.input, document)
document.current_source = document.current_line = None
def parse(self):
"""Parse `self.input` into a document tree."""
self.document = document = self.new_document()
module_section = moduleparser.parse_module(self.input, self.source.source_path)
module_section.walk(DocformatVisitor(self.document))
visitor = DocstringFormattingVisitor(document=document, default_parser=self.default_parser)
module_section.walk(visitor)
self.document.append(module_section)
def parse(self):
"""Parse `self.input` into a document tree."""
tree = parse_module(self.input,self.source.source_path)
self.document = document = make_document(tree)
#self.document = document = self.new_document()
#self.parser.parse(self.input, document)
document.current_source = document.current_line = None
def parse(self):
"""Parse `self.input` into a document tree."""
self.document = document = self.new_document()
module_section = moduleparser.parse_module(self.input,
self.source.source_path)
module_section.walk(DocformatVisitor(self.document))
visitor = DocstringFormattingVisitor(
document=document, default_parser=self.default_parser)
module_section.walk(visitor)
self.document.append(module_section)
def __init__(self, filename, text=None):
self.filename = filename
if text is None:
text = open(filename).read()
self.module_text = text
self.name = os.path.splitext(os.path.basename(filename))[0]
node = moduleparser.parse_module(text, filename)
Document.__init__(self, node, self)
self.imports = []
self.subber = InlineSubstitution(self)
self.process()
def __init__(self, filename, text=None):
self.filename = filename
if text is None:
text = open(filename).read()
self.module_text = text
self.name = os.path.splitext(os.path.basename(filename))[0]
node = moduleparser.parse_module(text, filename)
Document.__init__(self, node, self)
self.imports = []
self.subber = InlineSubstitution(self)
self.process()
def test_parser(self):
if self.run_in_debugger:
pdb.set_trace()
try:
import compiler
except ImportError:
# skip on Python 3
return
from docutils.readers.python import moduleparser
module = moduleparser.parse_module(self.input, 'test data').pformat()
output = str(module)
self.compare_output(self.input, output, self.expected)
def test_parser(self):
if self.run_in_debugger:
pdb.set_trace()
try:
import compiler
except ImportError:
# skip on Python 3
return
from docutils.readers.python import moduleparser
module = moduleparser.parse_module(self.input, 'test data').pformat()
output = str(module)
self.compare_output(self.input, output, self.expected)
def testTool(self):
"""Trying to think what to do for packages"""
# The Reader interface is designed to work with single test entities,
# either a string or the content of a text file (i.e., a single thing
# that can be accessed via some sort of "read" method).
# This doesn't work for packages, where one has multiple files.
# Thus I suspect that the Reader interface is not appropriate for
# what I want to do (at least, not without doing it unnecessary
# violence and making it a lot more complicated).
# So I need to do things "by hand"...
source="# A Python comment"
source_path="test.py"
# Since a body of text is a Module, not a Package, we'll go straight
# to it
nodes = parse_module(source,source_path)
# That then needs converting to a docutils tree
document = make_document(nodes)
# And *that* wants converting to the appropriate output format
from docutils.writers.pseudoxml import Writer
writer = Writer()
writer.document = document
writer.translate()
actual_result = writer.output
wanted_result = """\
<document source="Module test">
<section class="module" id="module-test" name="module test">
<title>
Module test\n"""
if wanted_result != actual_result:
print "+++++++++++++++++++++++++ WANT"
print wanted_result
print "+++++++++++++++++++++++++ GOT"
print actual_result
print "+++++++++++++++++++++++++"
self.assertEqual(actual_result,wanted_result)
def testTool(self):
"""Trying to think what to do for packages"""
# The Reader interface is designed to work with single test entities,
# either a string or the content of a text file (i.e., a single thing
# that can be accessed via some sort of "read" method).
# This doesn't work for packages, where one has multiple files.
# Thus I suspect that the Reader interface is not appropriate for
# what I want to do (at least, not without doing it unnecessary
# violence and making it a lot more complicated).
# So I need to do things "by hand"...
source="# A Python comment"
source_path="test.py"
# Since a body of text is a Module, not a Package, we'll go straight
# to it
nodes = parse_module(source,source_path)
# That then needs converting to a docutils tree
document = make_document(nodes)
# And *that* wants converting to the appropriate output format
from docutils.writers.pseudoxml import Writer
writer = Writer()
writer.document = document
writer.translate()
actual_result = writer.output
wanted_result = """\
<document source="Module test">
<section class="module" id="module-test" name="module test">
<title>
Module test\n"""
if wanted_result != actual_result:
print "+++++++++++++++++++++++++ WANT"
print wanted_result
print "+++++++++++++++++++++++++ GOT"
print actual_result
print "+++++++++++++++++++++++++"
self.assertEqual(actual_result,wanted_result)
def test_parser(self):
if self.run_in_debugger:
pdb.set_trace()
module = moduleparser.parse_module(self.input, 'test data')
output = str(module)
self.compare_output(self.input, output, self.expected)
def test_parser(self):
if self.run_in_debugger:
pdb.set_trace()
module = moduleparser.parse_module(self.input, 'test data')
output = str(module)
self.compare_output(self.input, output, self.expected)