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 ruff and checked for validity using pyright

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

Attributes¶

`SEPARATOR`
`USE_SUBMODULES`

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

Module Contents¶

stubber.rst.reader.SEPARATOR = '::'¶

stubber.rst.reader.USE_SUBMODULES = True¶

class stubber.rst.reader.FileReadWriter¶

base class for reading rst files

filename: str = ''¶

rst_text: List[str] = []¶

max_line = 0¶

line_no: int = 0¶

last_line = ''¶

output: List[str] = []¶

read_file(filename: pathlib.Path)¶

Parameters:: filename (pathlib.Path)

write_file(target: pathlib.Path) → bool¶

Parameters:: target (pathlib.Path)
Return type:: bool

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

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

docstring_anchors = ['.. note::', '.. data:: Arguments:', '.. data:: Options:', '.. data:: Returns:', '.. data::...¶

current_module = ''¶

current_class = ''¶

current_function = ''¶

clean_rst = True¶

read_file(filename: pathlib.Path)¶

Parameters:: filename (pathlib.Path)

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

at_heading(large: bool = False) → bool¶

stop at heading

Parameters:: large (bool)
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]

clean_docstr(block: List[str])¶

Clean up a docstring

Parameters:: block (List[str])

add_link_to_docstr(block: List[str])¶

Add clickable hyperlinks to CPython docpages, and clean the docstring from rst constructs

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 beginning 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'¶

output_dict: stubber.rst.ModuleSourceDict¶

return_info: List[Tuple] = []¶

source_tag¶

source_release¶

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()¶

lstrip_self(params: str)¶

To avoid duplicate selfs, Remove self, from the start of the parameters

Parameters:: params (str)

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(target: pathlib.Path) → bool¶

Parameters:: target (pathlib.Path)
Return type:: bool

prepare_output()¶: Remove trailing spaces and commas from the output.