stubber.rst
===========

.. py:module:: stubber.rst

.. autoapi-nested-parse::

   .rst processing



Submodules
----------

.. toctree::
   :maxdepth: 1

   /api/stubber/rst/classsort/index
   /api/stubber/rst/lookup/index
   /api/stubber/rst/output_dict/index
   /api/stubber/rst/reader/index
   /api/stubber/rst/report_return/index
   /api/stubber/rst/rst_utils/index


Attributes
----------

.. autoapisummary::

   stubber.rst.TYPING_IMPORT
   stubber.rst.LOOKUP_LIST
   stubber.rst.NONE_VERBS
   stubber.rst.CHILD_PARENT_CLASS
   stubber.rst.PARAM_FIXES
   stubber.rst.PARAM_RE_FIXES
   stubber.rst.MODULE_GLUE
   stubber.rst.RST_DOC_FIXES
   stubber.rst.DOCSTUB_SKIP
   stubber.rst.TYPING_IMPORT
   stubber.rst.__all__


Classes
-------

.. autoapisummary::

   stubber.rst.SourceDict
   stubber.rst.ModuleSourceDict
   stubber.rst.ClassSourceDict
   stubber.rst.FunctionSourceDict


Functions
---------

.. autoapisummary::

   stubber.rst.sort_classes
   stubber.rst.simple_candidates
   stubber.rst.compound_candidates
   stubber.rst.object_candidates
   stubber.rst.distill_return
   stubber.rst.return_type_from_context
   stubber.rst._type_from_context


Package Contents
----------------

.. py:function:: sort_classes(classes: List[str])

   sort a list of classes to respect the parent-child order


.. py:data:: TYPING_IMPORT
   :type:  List[str]
   :value: ['from __future__ import annotations', 'from _typeshed import Incomplete', 'from typing import...


.. py:data:: LOOKUP_LIST

.. py:data:: NONE_VERBS
   :value: ['Activate ', 'Build a ', 'Cancel ', 'Clear ', 'Close ', 'cancel ', 'Configure ', 'Connect ',...


.. py:data:: CHILD_PARENT_CLASS

.. py:data:: PARAM_FIXES

.. py:data:: PARAM_RE_FIXES

.. py:data:: MODULE_GLUE

.. py:data:: RST_DOC_FIXES
   :type:  List[Tuple[str, str]]

.. py:data:: DOCSTUB_SKIP
   :value: ['uasyncio.rst', 'builtins.rst', 're.rst']


   this is an list with manual overrides for function returns that could not efficiently be determined
   from their docstring description
   Format: a dictionary with :
   - key = module.[class.]function name
   - value : two-tuple with ( return type , priority )

.. py:class:: SourceDict(base: List, indent: int = 0, body: int = 0, lf: str = '\n', name='')

   Bases: :py:obj:`OrderedDict`


   (abstract) dict to store source components respecting parent child dependencies and proper definition order


   .. py:attribute:: lf
      :value: Multiline-String

      .. raw:: html

         <details><summary>Show Value</summary>

      .. code-block:: python

         """
         """

      .. raw:: html

         </details>




   .. py:attribute:: indent
      :value: 0



   .. py:attribute:: _body
      :value: 0



   .. py:attribute:: _nr
      :value: 0



   .. py:attribute:: name
      :value: ''



   .. py:method:: __str__() -> str

      convert the OD into a string ( the to be generated source code )



   .. py:method:: __add__(other: SourceDict)

      Aallows instances of the SourceDict class to be added together using the + operator or the += operator.



   .. py:method:: add_docstr(docstr: Union[str, List[str]], extra: int = 0)


   .. py:method:: add_comment(line: Union[str, List[str]])

      Add a comment, or list of comments, to this block.



   .. py:method:: add_constant(line: str, autoindent: bool = True)

      add constant to the constant scope of this block



   .. py:method:: add_constant_smart(name: str, type: str = '', docstr: Optional[List[str]] = None, autoindent: bool = True)

      add literal / constant to the constant scope of this block, or a class in this block



   .. py:method:: find(name: str) -> Union[str, None]
      :abstractmethod:



   .. py:method:: add_line(line: str, autoindent: bool = True)


   .. py:method:: index(key: str)


.. py:class:: ModuleSourceDict(name: str, indent=0, lf: str = '\n')

   Bases: :py:obj:`SourceDict`


   (abstract) dict to store source components respecting parent child dependencies and proper definition order


   .. py:method:: sort()

      make sure all classdefs are in order



   .. py:method:: __str__()

      sort in the correct parent-child order,
      then convert to string (the code)



   .. py:method:: find(name: str) -> Union[str, None]

      find a classnode based on the name with or without the superclass



   .. py:method:: classes()

      get a list of the class names in parent-child order



   .. py:method:: add_import(imports: Union[str, List[str]])

      add a [list of] imports this module



.. py:class:: ClassSourceDict(name: str, *, docstr: Optional[List[str]] = None, init: str = '', indent: int = 0, lf='\n')

   Bases: :py:obj:`SourceDict`


   (abstract) dict to store source components respecting parent child dependencies and proper definition order


.. py:class:: FunctionSourceDict(name: str, *, definition: Optional[List[str]] = None, docstr: Optional[List[str]] = None, indent: int = 0, decorators: Optional[List[str]] = None, lf='\n', is_async: bool = False)

   Bases: :py:obj:`SourceDict`


   (abstract) dict to store source components respecting parent child dependencies and proper definition order


.. py:function:: simple_candidates(type: str, match_string: str, keywords: List[str], rate: float = 0.5, exclude: Optional[List[str]] = None)

   find and rate possible types and confidence weighting for simple types.
   Case sensitive


.. py:function:: compound_candidates(type: str, match_string: str, keywords: List[str], rate: float = 0.85, exclude: Optional[List[str]] = None)

   find and rate possible types and confidence weighting for compound types that can have a subscription.
   Case sensitive


.. py:function:: object_candidates(match_string: str, rate: float = 0.81, exclude: Optional[List[str]] = None)

   find and rate possible types and confidence weighting for Object types.
   Case sensitive
   Exclude defaults to ["IRQ"]


.. py:function:: distill_return(return_text: str) -> List[Dict]

   Find return type and confidence.
   Returns a list of possible types and confidence weighting.
   {

       type :str               # the return type
       confidence: float       # the confidence between 0.0 and 1
       match: Optional[str]    # for debugging : the reason the match was made

   }



.. py:function:: return_type_from_context(*, docstring: Union[str, List[str]], signature: str, module: str, literal: bool = False)

.. py:function:: _type_from_context(*, docstring: Union[str, List[str]], signature: str, module: str, literal: bool = False)

   Determine the return type of a function or method based on:
    - the function signature
    - the terminology used in the docstring

   Logic:
   - if the signature contains a return type --> <something> then that is returned
   - use re to find phrases such as:

       - 'Returns ..... '
       - 'Gets  ..... '

   - docstring is joined without newlines to simplify parsing
   - then parses the docstring to find references to known types and give then a rating though a hand coded model ()
   - builds a list return type candidates
   - selects the highest ranking candidate
   - the default Type is 'Incomplete'


.. py:data:: TYPING_IMPORT
   :type:  List[str]
   :value: ['from __future__ import annotations', 'from _typeshed import Incomplete', 'from typing import...


.. py:data:: __all__