:mod:`lookout.core.analyzer`
============================

.. py:module:: lookout.core.analyzer







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






.. py:class:: ReferencePointer

   Bases::class:`typing.NamedTuple()`

   

   We redefine ReferencePointer because Protocol Buffers message objects suck.


   

   

   .. staticmethod:: from_pb(refptr:ApiReferencePointer)

      
      Convert from ReferencePointer defined in protocol buffers to our own Python-friendly         pointer.

      



   

   .. method:: to_pb(self)

      
      Convert to ReferencePointer defined in protocol buffers.

      











.. data:: UnicodeFile
   

   















.. data:: UnicodeChange
   

   















.. py:class:: AnalyzerModel(log_level:int=logging.INFO, **kwargs)

   Bases::class:`modelforge.Model`

   

   All models used in `Analyzer`-s must derive from this base class.


   

   

   .. attribute:: NAME
      

      



   

   

   .. attribute:: VENDOR
      :annotation: = <unknown> 

      



   

   

   .. attribute:: DESCRIPTION
      :annotation: = <unknown> 

      



   

   

   

   .. classmethod:: generate(cls, analyzer:Type['Analyzer'], ptr:ReferencePointer)

      
      Initialize the model (`__init__` does not do the real work to allow `load()`).

      :param analyzer: Bound type of the `Analyzer`. Not instance!
      :param ptr: Git repository state pointer.
      :return: self

      



   

   .. method:: dump(self)

      
      Satisfy the upstream's abstract method.

      :return: summary text of the model.

      



   

   .. method:: save(self, output:Union[str, BinaryIO], series:Optional[str]='Lookout', deps:Iterable=tuple(), create_missing_dirs:bool=True)

      
      Serialize the model to a file.

      :param output: Path to the file or a file object.
      :param series: Name of the model series.
      :param deps: List of the dependencies.
      :param create_missing_dirs: create missing directories in output path if the output is a                                     path.
      :return: self

      



   

   









.. py:class:: DummyAnalyzerModel

   Bases::class:`lookout.core.analyzer.AnalyzerModel`

   

   Stub for stateless analyzers.


   

   

   .. attribute:: NAME
      :annotation: = dummy 

      



   

   

   .. attribute:: VENDOR
      :annotation: = public domain 

      



   

   

   .. attribute:: DESCRIPTION
      :annotation: = Model that does not contain anything is acts as a stub for stateless analyzers. 

      



   









.. py:class:: Analyzer(model:AnalyzerModel, url:str, config:Mapping[str, Any])

   Interface of all the analyzers. Each analyzer uses a model to run the analysis and generates     a model as the result of the training.

   `version` allows to version the models. It is checked in the model repository and if it does
   not match, a new model is trained.
   `model_type` points to the specific derivative of AnalyzerModel - type of the model used
   in analyze() and generated in train().


   

   

   .. attribute:: version
      

      



   

   

   .. attribute:: model_type
      

      



   

   

   .. attribute:: name
      

      



   

   

   .. attribute:: vendor
      

      



   

   

   

   .. method:: analyze(self, ptr_from:ReferencePointer, ptr_to:ReferencePointer, data_service:'lookout.core.data_requests.DataService', **data)

      
      Run the analysis on the specified Git repository state.

      This is called on Review events. It must return the list of `Comment`-s - found review         suggestions.

      :param ptr_from: The Git revision of the fork point. Exists in both the original and                          the forked repositories.
      :param ptr_to: The Git revision to analyze. Exists only in the forked repository.
      :param data_service: The channel to the data service in Lookout server to query for                              UASTs, file contents, etc.
      :param data: Extra data passed into the method. Used by the decorators to simplify                      the data retrieval.
      :return: List of found review suggestions. Refer to                  lookout/core/server/sdk/service_analyzer.proto.

      



   

   .. classmethod:: train(cls, ptr:ReferencePointer, config:Mapping[str, Any], data_service:'lookout.core.data_requests.DataService', **data)

      
      Generate a new model on top of the specified source code.

      :param ptr: Git repository state pointer.
      :param config: Configuration of the training of unspecified structure.
      :param data_service: The channel to the data service in Lookout server to query for                              UASTs, file contents, etc.
      :param data: Extra data passed into the method. Used by the decorators to simplify                      the data retrieval.
      :return: Instance of `AnalyzerModel` (`model_type`, to be precise).

      



   

   .. classmethod:: construct_model(cls, ptr:ReferencePointer)

      
      Produce a new empty model associated with this analyzer.

      :param ptr: state of Git repository which is used to generate the model.
      :return: Instance of the model.

      



   

   .. classmethod:: check_training_required(cls, old_model:AnalyzerModel, ptr:ReferencePointer, config:Mapping[str, Any], data_service:'lookout.core.data_requests.DataService', **data)

      
      Decide whether we need to train the model or re-use the old one.

      :param old_model: Previously trained model. It is never None.
      :param ptr: Git repository state pointer.
      :param config: Configuration of the training of unspecified structure.
      :param data_service: The channel to the data service in Lookout server to query for                              UASTs, file contents, etc.
      :param data: Extra data passed into the method. Used by the decorators to simplify                      the data retrieval.
      :return: True (required) or False (not required)