stubber.stubs_from_docs

Read the Micropython library documentation files and use them to build stubs that can be used for static typechecking using a custom-built parser to read and process the micropython RST files - generates:

  • modules

    • docstrings

  • function definitions

    • function parameters based on documentation

    • docstrings

  • classes

    • docstrings

    • __init__ method

    • parameters based on documentation for class

    • methods

      • parameters based on documentation for the method

      • docstrings

  • exceptions

  • Tries to determine the return type by parsing the docstring.

    • Imperative verbs used in docstrings have a strong correlation to return -> None

    • recognizes documented Generators, Iterators, Callable

    • Coroutines are identified based tag “This is a Coroutine”. Then if the return type was Foo, it will be transformed to : Coroutine[Foo]

    • a static Lookup list is used for a few methods/functions for which the return type cannot be determined from the docstring.

    • add NoReturn to a few functions that never return ( stop / deepsleep / reset )

    • if no type can be detected the type Any is used

The generated stub files are formatted using black and checked for validity using pyright Note: black on python 3.7 does not like some function defs def sizeof(struct, layout_type=NATIVE, /) -> int:

  • ordering of inter-dependent classes in the same module

  • Literals / constants

    • documentation contains repeated vars with the same indentation

    • Module level:

    .. data:: IPPROTO_UDP
            IPPROTO_TCP

    • class level:

    .. data:: Pin.IRQ_FALLING
        Pin.IRQ_RISING
        Pin.IRQ_LOW_LEVEL
        Pin.IRQ_HIGH_LEVEL

        Selects the IRQ trigger type.

    • literals documented using a wildcard are added as comments only

  • Add GLUE imports to allow specific modules to import specific others.

  • Repeats of definitions in the rst file for similar functions or literals

    • CONSTANTS ( module and Class level )

    • functions

    • methods

  • Child/ Parent classes

    are added based on a (manual) lookup table CHILD_PARENT_CLASS

Module Contents

Classes

RSTReader

Functions

is_balanced(→ bool)

Check if a string has balanced parentheses

generate_from_rst(→ int)

Attributes

NEW_OUTPUT

SEPERATOR

stubber.stubs_from_docs.NEW_OUTPUT = True
stubber.stubs_from_docs.SEPERATOR = ::
stubber.stubs_from_docs.is_balanced(s: str) → bool

Check if a string has balanced parentheses

Parameters

s (str) –

Return type

bool

class stubber.stubs_from_docs.RSTReader(v_tag='v1.xx')
verbose = False
gather_docs = False
target = .py
property line → str

get the current line from input, also stores this as last_line to allow for inspection and dumping the json file

Return type

str

extend_and_balance_line() → str

Append the current line + next line in order to try to balance the parentheses in order to do this the rst_test array is changed by the function and max_line is adjusted

Return type

str

property module_names → List[str]

list of possible module names [uname , name] (longest first)

Return type

List[str]

strip_prefixes(name: str, strip_mod: bool = True, strip_class: bool = False)

Remove the modulename. and or the classname. from the begining of a name

Parameters

  • name (str) –

  • strip_mod (bool) –

  • strip_class (bool) –

leave_class()
read_file(filename: pathlib.Path)
Parameters

filename (pathlib.Path) –

prepare_output()

clean up some trailing spaces and commas

write_file(filename: pathlib.Path) → bool
Parameters

filename (pathlib.Path) –

Return type

bool

at_anchor() → bool

Stop at anchor ( however .. note: should be added)

Return type

bool

at_heading() → bool

stop at heading

Return type

bool

parse_docstring() → List[str]

Read a textblock that will be used as a docstring, or used to process a toc tree The textblock is terminated at the following RST line structures/tags

– Heading == Heading ~~ Heading

The blank lines at the start and end are removed to limit the space the docstring takes up.

Return type

List[str]

fix_parameters(params: str, name: str = '') → str

Patch / correct the documentation parameter notation to a supported format that works for linting. - name is the name of the function or method or Class

Parameters

  • params (str) –

  • name (str) –

Return type

str

create_update_class(name: str, params: str, docstr: List[str])
Parameters

  • name (str) –

  • params (str) –

  • docstr (List[str]) –

parse_toc()

process table of content with additional rst files, and add / include them in the current module

parse_module()

parse a module tag and set the module’s docstring

parse_current_module()
parse_function()
parse_class()
get_rst_hint()

parse the ‘.. <rst hint>:: ‘ from the current line

parse_method()
parse_exception()
parse_name(line: Optional[str] = None)

get the constant/function/class name from a line with an identifier

Parameters

line (Optional[str]) –

parse_names(oneliner: bool = True)

get a list of constant/function/class names from and following a line with an identifier advances the linecounter

oneliner : treat a line with commas as multiple names (used for constants)

Parameters

oneliner (bool) –

parse_data()

proces ..data:: lines ( one or more)

parse()
stubber.stubs_from_docs.generate_from_rst(rst_path: pathlib.Path, dst_path: pathlib.Path, v_tag: str, release: Optional[str] = None, pattern: str = '*.rst', verbose: bool = False, suffix='.py') → int
Parameters
Return type

int