unittest2doc.unittest2doc

Classes:

FLog([fargs, fkwargs, do_print, ...])

Record the function and its output, used to generate document for unittest functions

Unittest2Doc(*, testcase, name[, ref, ...])

wrapper unittests and make documentation pages for sphinx

Functions:

add_foldable_output(self, *, name, output[, ...])

add extra foldabel text at end of the doc page

all_type_json_serializer(obj)

try to use repr() to serialize objects that are not JSON serializable

docpformat(data[, indent])

docpprint(data, **kwargs)

Pretty print data for documentation purposes

expected_failure(func)

use @unittest2doc.expected_failure to mark a test as expected to fail

get_caller_func_name()

only(func)

use @unittest2doc.only to only run some unittest

skip(func)

use @unittest2doc.skip to skip some unittest

stop(func)

use @unittest2doc.stop to stop unittest before this function

stop_after(func)

use @unittest2doc.stop_after to stop unittest after this function

update_config(self, **kwargs)

update config for unittest2doc

v(toshow, l, g[, mask, doprint])

pretty print varialbes in toshow list
class unittest2doc.unittest2doc.FLog(fargs: dict[Callable] | None = None, fkwargs: dict | None = None, do_print: bool | None = True, do_print_input: bool | None = None, do_print_output: bool | None = None, input_prefix: str | None = '', input_suffix: str | None = '', output_suffix: str | None = '', input_max_width: int = 80)

Bases: object

Record the function and its output, used to generate document for unittest functions

Usage:

# in Unittest2Doc.setUp
s.flog = FLog(do_print=True, input_prefix='# call=> ', input_suffix=' ==>')
s.func=s.flog.func

# in test functions
s.r = s.func(somefunc)
s.r = s.func(somefunc, args=[], kwargs={})
s.r = s.frun(somefunc, arg1, args2, args3, kwarg0=..., kwargs1=..., kwargs2=...)

Methods:

__init__([fargs, fkwargs, do_print, ...])

frun(func, *args, **kwargs)

func(func, *[, args, kwargs, fargs, ...])

run function with give args and kwargs, return formated result
__init__(fargs: dict[Callable] | None = None, fkwargs: dict | None = None, do_print: bool | None = True, do_print_input: bool | None = None, do_print_output: bool | None = None, input_prefix: str | None = '', input_suffix: str | None = '', output_suffix: str | None = '', input_max_width: int = 80)
frun(func, *args, **kwargs)
func(func: Callable, *, args: list | tuple | None = None, kwargs: dict | None = None, fargs: dict[Callable] | None = None, fkwargs: dict | None = None, do_print: bool | None = None, do_print_input: bool | None = None, do_print_output: bool | None = None, input_prefix: str | None = None, input_suffix: str | None = None, output_suffix: str | None = None, input_max_width: int | None = None) → dict

run function with give args and kwargs, return formated result

Parameters:

  • args (list | tuple | None) – see below

  • kwargs (dict | None) – together with args, we call the function like func(*args, **kwargs)

  • fargs (dict[Callable] | None) – function to reformat args befreo we print it in the input retion section, see below

  • fkwargs (dict | None) – together with fargs, we preprocess (reformat) the input and then print them in the function input part, see the Returns for details

  • print – if true, will also print the input and output results

  • input_prefix (str | None) – add prefix for the input result

  • input_suffix (str | None) – add suffix for the input result

Returns:

dict with the keys output, input.

The output is the return value from the func call The intput is like

func(args[0], args[1], ..., args[-1], key0=value0, key1=value1, ...)

where the key<n> and value<n> are from kwargs

if fargs and fkwargs are not None, we preprocess the input data before we print them, like:

func(
    fargs[0](args[0]), fargs[1](args[1]), ..., fargs[-1](args[-1]),
    key0=fkwargs[key0](value0), key1=fkwargs[key1](value1), ...)

Return type:

dict

class unittest2doc.unittest2doc.Unittest2Doc(*, testcase: TestCase, name: str, ref: str = '', update_index=True, no_test_prefix=True, open_input=True, open_output=True, output_highlight='', doc_root=None, output_processors=None, **kwargs)

Bases: object

wrapper unittests and make documentation pages for sphinx

Docstring formats in the unittest functions:

  • the docstring of the custom Unittest2Doc class will be added to beginning of the doc page

  • the first line of the docstring can be used as config section, e.g.

    • {"open_input":false} to close the input by default

    • {"title_marker": "^"} to leveldown this test (change default title marker to ^)

    • {"title_marker": "-"} to levelup this test (change default title marker to -)

    • {"output_highlight": "python"}, {"output_highlight": "json"}

  • functions used

    • we only run functions that name startswith test

    • we only use their docstring for functions that name startswith rst

    • setUp is always called at beginning of the test and tearDown is always called at end

Usage:

t = ThisTest(
  name='unittest2doc.unittest2doc.Unittest2Doc.basic',   # required
  ref=':class:`unittest2doc.unittest2doc.Unittest2Doc`', # optional
  doc_root=Path(__file__).absolute().parent.parent / 'sphinx-docs/source/unittests', # required
)

see unittest2doc.unittest2doc.Unittest2Doc for more detailed examples

Methods:

__init__(*, testcase, name[, ref, ...])

generate_docs()

do unittest and generate docs
__init__(*, testcase: TestCase, name: str, ref: str = '', update_index=True, no_test_prefix=True, open_input=True, open_output=True, output_highlight='', doc_root=None, output_processors=None, **kwargs)
Parameters:

  • name (str) – name of the package, e.g., name=’lib.utils’

  • ref (str) – if set, will add references: {ref} at beginning. ref should be a rst link in sphinx

  • doc_root – root folder of the unittests docs folder. Usually it should be <package-folder>/docs/source/unittests

  • update_index – update all parent index files

  • output_highlight – the highlight language for the output section

  • open_input – open input section

  • open_output – open output section

  • no_test_prefix – remove the test_ function name prefix in the doc page

generate_docs()

do unittest and generate docs

unittest2doc.unittest2doc.add_foldable_output(self, *, name, output, highlight='', open=False)

add extra foldabel text at end of the doc page

params: name, output, highlight, open

usage:

# in unittest.TestCase test functions
unittest2doc.add_foldable_output(
    self,
    name="some code",
    highlight='python',
    output=textwrap.dedent('''
        # some code ...
        def func(*args, **kwargs):
        pass
    '''
    ),
    open=True,
)
unittest2doc.unittest2doc.all_type_json_serializer(obj: Any) → str

try to use repr() to serialize objects that are not JSON serializable

unittest2doc.unittest2doc.docpformat(data: any, indent=4, **kwargs)
unittest2doc.unittest2doc.docpprint(data: any, **kwargs)

Pretty print data for documentation purposes

A wrapper around rich.pretty.pprint with default settings optimized for documentation output.

Parameters:

  • data (any) – The data to pretty print

  • **kwargs – Additional arguments passed to rich.pretty.pprint

unittest2doc.unittest2doc.expected_failure(func)

use @unittest2doc.expected_failure to mark a test as expected to fail

unittest2doc.unittest2doc.get_caller_func_name() → str
unittest2doc.unittest2doc.only(func)

use @unittest2doc.only to only run some unittest

Note: it work only when you use Unittest2Doc.generate_docs(),

it does not work when you use unittest.main()

unittest2doc.unittest2doc.skip(func)

use @unittest2doc.skip to skip some unittest

unittest2doc.unittest2doc.stop(func)

use @unittest2doc.stop to stop unittest before this function

Note: it work only when you use Unittest2Doc.generate_docs(),

it does not work when you use unittest.main()

unittest2doc.unittest2doc.stop_after(func)

use @unittest2doc.stop_after to stop unittest after this function

Note: it work only when you use Unittest2Doc.generate_docs(),

it does not work when you use unittest.main()

unittest2doc.unittest2doc.update_config(self, **kwargs)

update config for unittest2doc

call this function in unittest.TestCase test functions

keys can be:

  • title_marker

  • open_input

  • open_output

  • output_highlight

  • save_stdout

  • output_processors

unittest2doc.unittest2doc.v(toshow: list[str], l: dict, g: dict, mask: list = None, doprint: bool = True) → dict

pretty print varialbes in toshow list

Parameters:

  • toshow (list[str]) – the variables to be shown

  • l (dict) – should input locals()

  • g (dict) – should input globals()

  • mask (list) – the variables that contain secret values, should be masked

  • doprint (bool) – if True, do pprint

Usages:

# in Unittest2Doc test functions
s.v(['var0', 'var1'], locals(), globals(), mask=[])

# mask some secrets
s.v(['a', 'b', 'c', 'd'], locals(), globals(), mask=[
    'c.secret',
    'c.subsecret.bad',
    'c.subsecret.sub.bad',
])