def test_namespaced_types(self): data = """ from typing import List, Dict, Tuple import ast def some_function(arg1: ast.AST): pass """ expected = """# simple_module ## some\\_function() ```python def some_function(arg1: ast.AST): ``` **Args** - arg1 (`ast.AST`) """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown( parse_module_file('simple_module.py', '', hide_undoc=False)) assert md.strip() == expected.strip()
def test_pass_class_args_to_construcor(self): data = """ class SomeClass: ''' Args: arg1: I am in the wrong place but can be moved ''' def __init__(self, arg1): ''' I am a method ''' pass """ expected = """# simple_module ## class SomeClass ### SomeClass.\\_\\_init\\_\\_() I am a method ```python def __init__(self, arg1): ``` **Args** - arg1: I am in the wrong place but can be moved """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown(parse_module_file('simple_module.py', '')) assert md.strip() == expected.strip()
def test_multiple_decorators(self): data = """ from pyramid.view import ( view_config, ) from pyramid.security import ( NO_PERMISSION_REQUIRED ) @view_config(route_name='swagger', renderer='lims:templates/swagger.mak', permission=NO_PERMISSION_REQUIRED) @view_config(route_name='swagger.json', renderer='json', permission=NO_PERMISSION_REQUIRED) def swagger(request): '''I am a docstring''' pass """ expected = """ # simple_module ## swagger() I am a docstring ```python @view_config(route_name='swagger', renderer='lims:templates/swagger.mak', permission=NO_PERMISSION_REQUIRED) @view_config(route_name='swagger.json', renderer='json', permission=NO_PERMISSION_REQUIRED) def swagger(request): ``` **Args** - request """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown(parse_module_file('simple_module.py', '')) assert md.strip() == expected.strip()
def test_overwrite_docstring_with_annotations(self): data = """ def simple_function(arg1: str, arg2: int): ''' this function does stuff Args: arg1 (int): this is the first argument ''' pass """ expected = """# simple_module ## simple\\_function() this function does stuff ```python def simple_function(arg1: str, arg2: int): ``` **Args** - arg1 (`str`): this is the first argument - arg2 (`int`) """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown(parse_module_file('simple_module.py', '')) assert md.strip() == expected.strip()
def test_simple_module(self): data = """ def simple_function(arg1: str, arg2: int): ''' this function does stuff ''' pass """ expected = """# simple_module ## simple\\_function() this function does stuff ```python def simple_function(arg1: str, arg2: int): ``` **Args** - arg1 (`str`) - arg2 (`int`) """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown(parse_module_file('simple_module.py', '')) assert md.strip() == expected.strip()
def test_snippets(name): base_dir = os.path.join(os.path.dirname(__file__), 'snippets') file_prefix = os.path.join(base_dir, name) with open(file_prefix + '.md', 'r') as fh: md_expected = fh.read() parsed = parse_module_file(file_prefix + '.py', base_dir, hide_undoc=False) md_actual = module_to_markdown(parsed) assert md_actual == md_expected
def test_class_desc(self): data = """ class SomeClass: ''' say something Attributes: attr1 (int): an thing on a class instance ''' pass """ expected_md = """# simple_module ## class SomeClass say something **Attributes** - attr1 (`int`): an thing on a class instance """ expected_parse = { 'name': 'simple_module', 'hidden': False, 'functions': [], 'description': '', 'variables': [], 'classes': [{ 'name': 'SomeClass', 'description': 'say something', 'inherits': [], 'hidden': False, 'functions': [], 'examples': [], 'attributes': [{ 'hidden': False, 'name': 'attr1', 'type': 'int', 'description': 'an thing on a class instance', }], }], } with patch('builtins.open', mock_open(read_data=data)): parsed = parse_module_file('simple_module.py', '') assert parsed == expected_parse md = module_to_markdown(parsed) assert md.strip() == expected_md.strip()
def test_module_constant(self): data = """ CONSTANT_THING = 'some constant thing' """ expected = """# simple_module ## CONSTANT_THING ```python CONSTANT_THING = 'some constant thing' ``` """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown( parse_module_file('simple_module.py', '', hide_undoc=False)) assert md.strip() == expected.strip()
def test_multiline_docstring_desc(self): data = """ def prefix_split(text): ''' Split the input text into a prefix and suffix, according to the following patterns: If the input string is letters followed by numbers, return them separately in a tuple. If the input string is only letters, return a tuple of ({letters}, None). If the input string is only numbers, return a tuple of (None, {numbers}). Otherwise return a tuple of Nones. Args: text (str): the input to split. ''' pass """ expected = """# simple_module ## prefix\\_split() Split the input text into a prefix and suffix, according to the following patterns: If the input string is letters followed by numbers, return them separately in a tuple. If the input string is only letters, return a tuple of ({letters}, None). If the input string is only numbers, return a tuple of (None, {numbers}). Otherwise return a tuple of Nones. ```python def prefix_split(text): ``` **Args** - text (`str`): the input to split. """ with patch('builtins.open', mock_open(read_data=data)): parsed = parse_module_file('simple_module.py', '', hide_undoc=False) md = module_to_markdown(parsed) assert md.strip() == expected.strip()
def test_callable(self): data = """ class ResourceFieldDef(_ResourceFieldDefReq, total=False): update: Callable[[Any, Union[int, str]], None] deprecated: bool """ expected = """# simple_module ## class ResourceFieldDef **inherits** `_ResourceFieldDefReq` **Attributes** - update (`Callable[[Any, Union[int, str]], None]`) - deprecated (`bool`) """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown( parse_module_file('simple_module.py', '', hide_undoc=False)) assert md.strip() == expected.strip()
def test_examples_from_docstring(self): data = """ def simple_function(arg1: str, arg2: int): ''' this function does stuff Args: arg1 (int): this is the first argument Example: >>> simple_function('1', 2) 'something' ''' pass """ expected = """# simple_module ## simple\\_function() this function does stuff ```python def simple_function(arg1: str, arg2: int): ``` **Args** - arg1 (`str`): this is the first argument - arg2 (`int`) **Examples** ```python >>> simple_function('1', 2) 'something' ``` """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown(parse_module_file('simple_module.py', '')) assert md.strip() == expected.strip()
def test_nested_return_type_annotation(self): data = """ def some_function() -> List[Dict]: pass """ expected = """# simple_module ## some\\_function() ```python def some_function() -> List[Dict]: ``` **Returns** - `List[Dict]` """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown( parse_module_file('simple_module.py', '', hide_undoc=False)) assert md.strip() == expected.strip()
def test_module_constant_pulled_when_any_docstring(self): data = """ ''' this is a docstring for the module ''' CONSTANT_THING = 'some constant thing' """ expected = """# simple_module this is a docstring for the module ## CONSTANT_THING ```python CONSTANT_THING = 'some constant thing' ``` """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown(parse_module_file('simple_module.py', '')) assert md.strip() == expected.strip()
def test_parses_raise(self): data = """ def simple_function(arg1: str, arg2: int): ''' this function does stuff Args: arg1 (int): this is the first argument Raises: NotImplementedError: stuff ''' pass """ expected = """# simple_module ## simple\\_function() this function does stuff ```python def simple_function(arg1: str, arg2: int): ``` **Args** - arg1 (`str`): this is the first argument - arg2 (`int`) **Raises** - `NotImplementedError`: stuff """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown(parse_module_file('simple_module.py', '')) assert md.strip() == expected.strip()
def test_class_methods(self): data = """ class SomeClass: def some_method_on_a_class(self): ''' I am a method ''' pass """ expected = """# simple_module ## class SomeClass ### SomeClass.some\\_method\\_on\\_a\\_class() I am a method ```python def some_method_on_a_class(self): ``` """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown(parse_module_file('simple_module.py', '')) assert md.strip() == expected.strip()
def test_complex_types(self): data = """ from typing import List, Dict, Tuple def some_function() -> Tuple[List, Dict[str,int]]: pass """ expected = """# simple_module ## some\\_function() ```python def some_function() -> Tuple[List, Dict[str,int]]: ``` **Returns** - `Tuple[List, Dict[str, int]]` """ with patch('builtins.open', mock_open(read_data=data)): md = module_to_markdown( parse_module_file('simple_module.py', '', hide_undoc=False)) assert md.strip() == expected.strip()
def test_typed_dict_with_docstring(self): data = """ from typings import TypedDict class SomeType(TypedDict): ''' Attributes: parent: the name of the parent ''' name: str parent: str grandparent: str """ expected = """# simple_module ## class SomeType **inherits** `TypedDict` **Attributes** - name (`str`) - parent (`str`): the name of the parent - grandparent (`str`) """ expect_parsed = { 'name': 'simple_module', 'hidden': False, 'variables': [], 'functions': [], 'description': '', 'classes': [{ 'name': 'SomeType', 'description': '', 'inherits': ['TypedDict'], 'examples': [], 'hidden': False, 'functions': [], 'attributes': [ { 'name': 'name', 'type': 'str', 'source_code': 'name: str' }, { 'name': 'parent', 'type': 'str', 'source_code': 'parent: str', 'description': 'the name of the parent', 'hidden': False, }, { 'name': 'grandparent', 'type': 'str', 'source_code': 'grandparent: str' }, ], }], } with patch('builtins.open', mock_open(read_data=data)): parsed = parse_module_file('simple_module.py', '', hide_undoc=False) assert parsed == expect_parsed md = module_to_markdown(parsed) assert md.strip() == expected.strip()