core

Create a list of symbols in a python package

Format Symbols

Once you collect symbols, you want to format it as a markdown list

---

source

format_symbol

 format_symbol (name, signature, doc, decorators=None, is_method=False)

format the information in markdown

Parse Symbols In The Module

Next we parse symbols in the module that we want to list.

---

source

log_error

 log_error (name, error)

---

source

get_decorators

 get_decorators (obj)

---

source

is_valid_method

 is_valid_method (method, method_name)

---

source

is_public_symbol

 is_public_symbol (name)

---

source

get_params

 get_params (func)

---

source

process_function

 process_function (func, name, include_no_docstring)

Parse functions

---

source

process_class

 process_class (cls, name, include_no_docstring)

Parse classes.

For example, this is how a Class will be parsed:

mock_class = extract_node('''
@decorator
class TestClass:
    """
    Class docstring
    with multiple lines
    """
    @staticmethod
    def method1(arg1):
        """
        Method1 docstring
        with multiple lines
        """
        pass
    def method2(self):
        """Single line docstring"""
        pass
''')

# Process the class
result = process_class(mock_class, "TestClass", True)

# Test equality
test_eq(result, (
    'class',
    'TestClass',
    '\n    Class docstring\n    with multiple lines\n    ',
    ['decorator'],
    [
        ('method1', 'method1(arg1)', '\n        Method1 docstring\n        with multiple lines\n        ', ['staticmethod']),
        ('method2', 'method2(self)', 'Single line docstring', [])
    ]
))

---

source

get_public_symbols

 get_public_symbols (module, include_no_docstring)

Extract all public symbols

---

source

generate_markdown

 generate_markdown (package_name, include_no_docstring, verbose=False)

Here is a preview of the fastcore library, for instance:

_md = generate_markdown('fastcore', False)
_lns = _md.splitlines()
print('\n'.join([x for x in _lns][:55]))

# fastcore Module Documentation

## fastcore.basics

> Basic functionality used in the fastai library

- `def ifnone(a, b)`
    `b` if `a` is None else `a`

- `def maybe_attr(o, attr)`
    `getattr(o,attr,o)`

- `def basic_repr(flds)`
    Minimal `__repr__`

- `def is_array(x)`
    `True` if `x` supports `__array__` or `iloc`

- `def listify(o, *rest)`
    Convert `o` to a `list`

- `def tuplify(o, use_list, match)`
    Make `o` a tuple

- `def true(x)`
    Test whether `x` is truthy; collections with >0 elements are considered `True`

- `class NullType`
    An object that is `False` and can be called, chained, and indexed

    - `def __getattr__(self, *args)`
    - `def __call__(self, *args, **kwargs)`
    - `def __getitem__(self, *args)`
    - `def __bool__(self)`

- `def tonull(x)`
    Convert `None` to `null`

- `def get_class(nm, *fld_names, **flds)`
    Dynamically create a class, optionally inheriting from `sup`, containing `fld_names`

- `def mk_class(nm, *fld_names, **flds)`
    Create a class using `get_class` and add to the caller's module

- `def wrap_class(nm, *fld_names, **flds)`
    Decorator: makes function a method of a new class `nm` passing parameters to `mk_class`

- `class ignore_exceptions`
    Context manager to ignore exceptions

    - `def __enter__(self)`
    - `def __exit__(self, *args)`

- `def exec_local(code, var_name)`
    Call `exec` on `code` and return the var `var_name`

Write markdown to file

We can generate our list of symbols as a markdown file like so:

---

source

pysym2md

 pysym2md (package_name:str<NameofthePythonpackage>,
           include_no_docstring:<Includesymbolswithoutdocstrings?>=False,
           verbose:<Turnonverboselogging?>=False,
           output_file:str<Theoutputfile>='filelist.md')

Generate a list of symbols corresponding to a python package in a markdown format.

pysym2md('fastcore')