stubber.typing_collector
========================

.. py:module:: stubber.typing_collector

.. autoapi-nested-parse::

   helper functions for stub transformations



Attributes
----------

.. autoapisummary::

   stubber.typing_collector.MODULE_KEY
   stubber.typing_collector.MOD_DOCSTR_KEY
   stubber.typing_collector._code


Exceptions
----------

.. autoapisummary::

   stubber.typing_collector.TransformError


Classes
-------

.. autoapisummary::

   stubber.typing_collector.TypeInfo
   stubber.typing_collector.AnnoValue
   stubber.typing_collector.StubTypingCollector


Functions
---------

.. autoapisummary::

   stubber.typing_collector.is_property
   stubber.typing_collector.is_setter
   stubber.typing_collector.is_getter
   stubber.typing_collector.is_deleter
   stubber.typing_collector.update_def_docstr
   stubber.typing_collector.update_module_docstr


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

.. py:class:: TypeInfo

   contains the functionDefs and classDefs info read from the stubs source


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: decorators
      :type:  Sequence[libcst.Decorator]


   .. py:attribute:: params
      :type:  Optional[libcst.Parameters]
      :value: None



   .. py:attribute:: returns
      :type:  Optional[libcst.Annotation]
      :value: None



   .. py:attribute:: docstr_node
      :type:  Optional[libcst.SimpleStatementLine]
      :value: None



   .. py:attribute:: def_node
      :type:  Optional[Union[libcst.FunctionDef, libcst.ClassDef]]
      :value: None



   .. py:attribute:: def_type
      :type:  str
      :value: '?'



.. py:class:: AnnoValue

   The different values for the annotations


   .. py:attribute:: docstring
      :type:  Optional[str]
      :value: ''


      Module docstring or function/method docstring


   .. py:attribute:: docstring_node
      :type:  Optional[libcst.SimpleStatementLine]
      :value: None


      the docstring node for a function method to reuse with overloads


   .. py:attribute:: type_info
      :type:  Optional[TypeInfo]
      :value: None


      function/method or class definition read from the docstub source


   .. py:attribute:: overloads
      :type:  List[TypeInfo]
      :value: []


      function / method overloads read from the docstub source


   .. py:attribute:: mp_available
      :type:  List[TypeInfo]
      :value: []


      function / method `overloads` read from the docstub source


   .. py:attribute:: literal_docstrings
      :type:  Dict[str, libcst.SimpleStatementLine]

      literal/constant name -> docstring node mappings for literal docstrings


.. py:exception:: TransformError

   Bases: :py:obj:`Exception`


   Error raised upon encountering a known error while attempting to transform
   the tree.


.. py:data:: MODULE_KEY
   :value: ('__module',)


.. py:data:: MOD_DOCSTR_KEY
   :value: ('__module_docstring',)


.. py:data:: _code

.. py:function:: is_property(node: libcst.FunctionDef) -> bool

   check if the function is a property


.. py:function:: is_setter(node: libcst.FunctionDef) -> bool

   check if the function is a setter


.. py:function:: is_getter(node: libcst.FunctionDef) -> bool

   check if the function is a getter


.. py:function:: is_deleter(node: libcst.FunctionDef) -> bool

   check if the function is a deleter


.. py:class:: StubTypingCollector

   Bases: :py:obj:`libcst.CSTVisitor`


   Collect the function/method and class definitions from ta rich .py or .pyi source


   .. py:attribute:: stack
      :type:  List[str]
      :value: []



   .. py:attribute:: annotations
      :type:  Dict[Tuple[str, Ellipsis], AnnoValue]


   .. py:attribute:: comments
      :type:  List[str]
      :value: []



   .. py:method:: _collect_literal_docstrings(body: Sequence[libcst.BaseStatement]) -> Dict[str, libcst.SimpleStatementLine]

      Collect literal docstrings from a sequence of statements.
      Looks for patterns like:
      CONSTANT = value
      '''docstring for constant'''



   .. py:method:: visit_Module(node: libcst.Module) -> bool

      Store the module docstring and collect literal docstrings



   .. py:method:: visit_Comment(node: libcst.Comment) -> None

      connect comments from the source



   .. py:method:: visit_ClassDef(node: libcst.ClassDef) -> Optional[bool]

      collect info from a classdef:
      - name, decorators, docstring
      - class-level literal docstrings



   .. py:method:: leave_ClassDef(original_node: libcst.ClassDef) -> None

      remove the class name from the stack



   .. py:method:: visit_FunctionDef(node: libcst.FunctionDef) -> Optional[bool]

      collect info from a function/method
      - name, decorators, params, returns, docstring



   .. py:method:: update_append_first_node(node)

      Store the function/method docstring or function/method sig



   .. py:method:: leave_FunctionDef(original_node: libcst.FunctionDef) -> None

      remove the function/method name from the stack



.. py:function:: update_def_docstr(dest_node: Union[libcst.FunctionDef, libcst.ClassDef], src_docstr: Optional[Union[libcst.SimpleStatementLine, str]] = None, src_node=None) -> Any

   Update the docstring of a function/method or class
   The supplied `src_docstr` can be a string or a SimpleStatementLine

   for function defs ending in an ellipsis, the entire body needs to be replaced.
   in this case `src_node` is required.


.. py:function:: update_module_docstr(node: libcst.Module, doc_tree: Optional[Union[str, libcst.SimpleStatementLine, libcst.BaseCompoundStatement]]) -> Any

   Add or update the docstring of a module