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

.. py:module:: stubber.rst.rst_utils

.. autoapi-nested-parse::

   Work in Progress
   ----------------

   Tries to determine the return type by parsing the docstring and the function signature
    - if the signature contains a return type --> <something> then that is returned
    - check a lookup dictionary of type overrides,
       if the functionnae is listed, then use the override
    - 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 'Any'


   to do:

       - regex :
           - 'With no arguments the frequency in Hz is returned.'
           - 'Get or set' --> indicates overloaded/optional return Union[None|...]
           - add regex for 'Query' ` Otherwise, query current state if no argument is provided. `

       - regex :
           - 'With no arguments the frequency in Hz is returned.'
           - 'Get or set' --> indicates overloaded/optional return Union[None|...]
           - add regex for 'Query' ` Otherwise, query current state if no argument is provided. `

       - try if an Azure Machine Learning works as well
           https://docs.microsoft.com/en-us/azure/machine-learning/quickstart-create-resources
       -



Attributes
----------

.. autoapisummary::

   stubber.rst.rst_utils.TYPING_IMPORT


Functions
---------

.. autoapisummary::

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


Module Contents
---------------

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


.. 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'