stubber.rst.reader

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 or Incomplete 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

FileReadWriter

base class for reading rst files

RSTReader

base class for reading rst files

RSTParser

Parse the RST file and create a ModuleSourceDict

RSTWriter

Reads, parses and writes

Attributes

SEPERATOR

stubber.rst.reader.SEPERATOR = '::'
class stubber.rst.reader.FileReadWriter

base class for reading rst files

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

read_file(filename: pathlib.Path)
Parameters:

filename (pathlib.Path) –

write_file(filename: pathlib.Path) → bool
Parameters:

filename (pathlib.Path) –

Return type:

bool

static is_balanced(s: str) → bool

Check if a string has balanced parentheses

Parameters:

s (str) –

Return type:

bool

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

class stubber.rst.reader.RSTReader

Bases: FileReadWriter

base class for reading rst files

property module_names: List[str]

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

Return type:

List[str]

property at_anchor: bool

and ..data:: should be added)

Type:

Stop at anchor ‘..something’ ( however .. note

Return type:

bool

docstring_anchors = ['.. note::', '.. data:: Arguments:', '.. data:: Options:', '.. data:: Returns:', '.. data::...
read_file(filename: pathlib.Path)
Parameters:

filename (pathlib.Path) –

at_heading(large=False) → bool

stop at heading

Return type:

bool

read_docstring(large: bool = False) → 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.

Parameters:

large (bool) –

Return type:

List[str]

static clean_docstr(block: List[str])

Clean up a docstring

Parameters:

block (List[str]) –

Add clickable hyperlinks to CPython docpages

Parameters:

block (List[str]) –

get_rst_hint()

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

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) –

class stubber.rst.reader.RSTParser(v_tag: str)

Bases: RSTReader

Parse the RST file and create a ModuleSourceDict most methods have side effects

Parameters:

v_tag (str) –

target = '.py'
PARAM_RE_FIXES
leave_class()
fix_parameters(params: str, name: str = '') → str

Patch / correct the documentation parameter notation to a supported format that works for linting. - params is the string containing the parameters as documented in the rst file - name is the name of the function or method or Class

Parameters:

  • params (str) –

  • name (str) –

Return type:

str

static apply_fix(fix: stubber.rst.lookup.Fix, params: str, name: str = '')
Parameters:

  • fix (stubber.rst.lookup.Fix) –

  • params (str) –

  • name (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()
parse_method()
parse_exception()
parse_name(line: str | None = 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()

process ..data:: lines ( one or more) Note: some data islands are included in the docstring of the module/class/function as the ESPNow documentation started to use this pattern.

parse()
class stubber.rst.reader.RSTWriter(v_tag='v1.xx')

Bases: RSTParser

Reads, parses and writes

write_file(filename: pathlib.Path) → bool
Parameters:

filename (pathlib.Path) –

Return type:

bool

prepare_output()

Remove trailing spaces and commas from the output.