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¶
base class for reading rst files |
|
base class for reading rst files |
|
Parse the RST file and create a ModuleSourceDict |
|
Reads, parses and writes |
Attributes¶
- 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:
- read_file(filename: pathlib.Path)¶
- Parameters:
filename (pathlib.Path) –
- write_file(filename: pathlib.Path) bool ¶
- Parameters:
filename (pathlib.Path) –
- Return type:
- 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:
- docstring_anchors = ['.. note::', '.. data:: Arguments:', '.. data:: Options:', '.. data:: Returns:', '.. data::...¶
- read_file(filename: pathlib.Path)¶
- Parameters:
filename (pathlib.Path) –
- 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.
- static add_link_to_docsstr(block: List[str])¶
Add clickable hyperlinks to CPython docpages
- Parameters:
block (List[str]) –
- get_rst_hint()¶
parse the ‘.. <rst hint>:: ‘ from the current line
- 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
- 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:
- prepare_output()¶
Remove trailing spaces and commas from the output.