def test_read_invalid(self, tmpdir):
source = tmpdir.join('config.json')
source.write(trim_docstring("""
one: 1
two: xxx
""", as_string=True))
with pytest.raises(ValueError):
read_config_file(str(source))
source = tmpdir.join('config.yaml')
source.write(trim_docstring("""
{
"one": 1,
"two": "xxx"
}
""", as_string=True))
# YAML is a JSON superset so can read it.
data = read_config_file(str(source))
assert data == dict(one=1, two='xxx')
source = tmpdir.join('config.yaml')
source.write(trim_docstring("""
<bla></bla>
""", as_string=True))
# NOTE: yaml parser returns string as is.
with pytest.raises(ValueError):
read_config_file(str(source))
def test_empty(self):
lines = trim_docstring("""
""")
assert lines == ['', '', '']
lines = trim_docstring('')
assert lines == ['']
def test_patch_empty(self):
content = trim_docstring("""
""",
strip_leading=True,
as_string=False)
patcher = LinePatcher()
assert patcher.patch(content) is content
def test_read_json_file(self, tmpdir):
source = tmpdir.join('config.json')
source.write(trim_docstring("""
{
"one": 1,
"two": "xxx"
}
""", as_string=True))
data = read_config_file(str(source))
assert data == dict(one=1, two='xxx')
def assert_py_doc(text, expected=None, **kwargs):
"""Compare input docstring with the one created by the given style.
Args:
text: Docstring to parse.
expected: Expected docstring. ``docstring`` is used if not set.
**kwargs: Parameters for the ``parse_py_doc``.
Returns:
Processing environment.
"""
__tracebackhide__ = True
text = trim_docstring(text)
env = parse_py_doc('\n'.join(text), **kwargs)
actual = env['definition'].doc_block.docstring.decode('utf-8').split('\n')
expected = text if expected is None else trim_docstring(expected)
assert_lines(actual, expected)
return env
def test_read_yaml(self):
source = StringIO(trim_docstring("""
one: 1
two: xxx
""", as_string=True))
# Format is not set.
with pytest.raises(ValueError) as e:
read_config_file(source)
assert str(e.value) == 'Configuration format is not set.'
data = read_config_file(source, fmt='yaml')
assert data == dict(one=1, two='xxx')
def test_as_string(self):
lines = trim_docstring("""
More bla bla.
First parameter.
Second parameter.
Sum
""", strip_leading=True, strip_trailing=True, as_string=True)
lst = ['More bla bla.',
'',
' First parameter.',
' Second parameter.',
'Sum']
assert '\n'.join(lst) == lines
def test_read_yaml_file(self, tmpdir):
content = trim_docstring("""
one: 1
two: xxx
""", as_string=True)
source = tmpdir.join('config.yml')
source.write(content)
data = read_config_file(str(source))
assert data == dict(one=1, two='xxx')
source = tmpdir.join('config.yaml')
source.write(content)
data = read_config_file(str(source))
assert data == dict(one=1, two='xxx')
def test_list(self):
lines = trim_docstring([''
' More bla bla.',
' ',
' First parameter.',
' Second parameter.',
' Sum'],
strip_leading=True, strip_trailing=True,
as_string=False)
lst = ['More bla bla.',
'',
' First parameter.',
' Second parameter.',
'Sum']
assert lines == lst
def test_strip_leading(self):
lines = trim_docstring("""
More bla bla.
First parameter.
Second parameter.
Sum
""", strip_leading=True)
lst = ['More bla bla.',
'',
' First parameter.',
' Second parameter.',
'Sum',
'']
assert lst == lines
def test_first_empty(self):
lines = trim_docstring("""
More bla bla.
First parameter.
Second parameter.
Sum
""")
lst = ['',
'More bla bla.',
'',
' First parameter.',
' Second parameter.',
'Sum',
'']
assert lst == lines
def test_first_nonempty(self):
lines = trim_docstring("""Bla bla.
More bla bla.
:param a: First parameter.
:param b: Second parameter.
:return: Sum
""")
lst = ['Bla bla.', '',
'More bla bla.',
'',
':param a: First parameter.',
':param b: Second parameter.',
':return: Sum',
'']
assert lst == lines
def parse_py_doc(text,
settings=None,
style='rst',
defaultkw=None,
trim=False,
**kw):
"""Parse python docstring and convert document tree back to text.
This function is used to test how style converts document tree to
text representation.
Result docstring is stored in definition::
env['definition'].doc_block.docstring
Args:
text: Docstring to parse.
settings: Processing settings.
style: Result docstring style.
defaultkw: Default params.
trim: Trim ``text``.
**kw:
Returns:
Processing environment.
"""
if trim:
text = trim_docstring(text, as_string=True)
if defaultkw:
# Merge params.
defaultkw.update(kw)
kw = defaultkw.copy()
# Override style.
style = kw.pop('style', style)
# Merge settings.
s = kw.pop('settings', None)
if s:
if settings:
s.update(settings)
settings = s
keep_transforms = kw.pop('keep_transforms', False)
pass_lines = kw.pop('pass_lines', True)
domain = PythonDomain()
domain.reporter = TestReporter(domain)
context = TestContext()
context.register(domain)
settings_builder = SettingsBuilder(Mock())
settings_builder.collect(context)
# --- Testing defaults
settings = settings or {}
# Easier to test - None means have blank line only for multi line docstring.
settings.setdefault('first_blank_line', None)
# Set to empty to have more space for line (bigger docstring width).
settings.setdefault('docstring_quote', '')
# With this width visual end of line in docstring will be the same as for
# enclosing code.
settings.setdefault('line_width', 68)
settings_builder.add_from_dict({'py': {style: settings, 'style': style}})
context.settings = settings_builder.get_settings()
definition = create_definition(name='test_func',
kind=kw.pop('kind', MemberType.FUNCTION),
start_line=1,
start_col=1,
bodystart=1,
bodyend=3,
args=kw.get('args', ()),
filename='<string>',
compound_id=kw.pop('compound_id', None),
compound_type=kw.pop('compound_type', None),
doc_block_docstring=text)
db = Mock()
# TODO: simplify processing.
env = domain.create_env(content_db=db,
report_filename=definition.filename,
definition=definition)
with context.settings.with_settings(domain.settings_section):
with context.settings.from_key('style'):
# Make sure the style doesn't modify parsed document.
# We don't need any extra modifications, because key point is to
# test document-to-text translator.
style = domain.get_style(domain.settings['style'])
if not keep_transforms:
style.transforms = []
domain.reporter.env = env
handler = domain.definition_handler_task(domain, env)
if not keep_transforms or 'transforms' in kw:
handler.transforms = kw.pop('transforms', None)
handler.setup()
handler.build_document()
if not pass_lines:
env['source_lines'] = None
env['num_source_lines'] = 0
handler.apply_transforms()
handler.translate_document_to_docstring()
return env
