.. _lblQuickStart:

Quick Start
===========
.. contents::
   :depth: 1
   :local:
   :backlinks: none

Installation
------------
The best way to install ``ExceptionControl`` is to install it via **pip**:

.. code-block:: bash
   :caption: Installation of ExceptionControl from a linux prompt

   $ python3 -m pip install ExceptionControl

It can also be cloned from Gitlab and installed locally:

.. code-block:: bash
   :caption: Cloning ExceptionControl from Gitlab

   $ git clone https://gitlab.com/semantik-software/code/python/ExceptionControl.git
   $ cd ExceptionControl
   $ python3 -m pip install .


Running the Examples
--------------------
Once installed, you can go to the *Examples* directory and run the examples:

.. code-block:: bash

   $ cd examples
   $ python3 ExceptionControl-Example-00.py
   ...


Using ExceptionControl
----------------------
The first step is to include the ExceptionControl class:

.. literalinclude:: ../examples/ExceptionControl-Example-00.py
    :language: python
    :lines: 1-3
    :linenos:


Examples
--------
These examples demonstrate how we might use ExceptionControl to 
add events to our code that can optionally raise warnings or events
based on the parameter ``exception_control_level`` for a given class.


Basic ExceptionControl Examples
++++++++++++++++++++++++++++++++++++++

Example 0: Simple Start
%%%%%%%%%%%%%%%%%%%%%%%
This is the 'hello world' example of ExceptionControl and shows a simple
class construction with a method that has an ``exception_control_event``.
In this case it's a **WARNING** event which should just print out a warning
message.

Here is the code for this example:

.. literalinclude:: ../examples/ExceptionControl-Example-00.py
    :language: python
    :linenos:
    
When run the output looks like:    
    
.. literalinclude:: ../examples/_test-example-00.log
    :linenos:

Here we see the general format of a warning message. Warning messages have the 
following characteristics:

* Warning message lines are prefixed with a double-exclamation point 
  ``!!`` which is useful for searching for them in log files as well 
  as calling attention to the lines which is what you want to do when 
  flagging a warning.
* It notes that an exception is skipped (i.e. not raised). Also handy 
  as a search key.
* The *Event Type* is noted, which is the level of this event 
  (WARNING, MINOR, MAJOR, etc.)
* The *Exceptin* type is shown. In this case we used a ``TypeError``. 
  This is the kind of exception that is raised if ``exceptin_control_level``
  is set to a value that would raise this exception.
* The *message* is printed out.
* A stack trace is also printed showing the location of the *event* 
  within the code.
* A note is added indicating the value ``exception_control_level`` 
  would need to be to cause this event to raise the associated 
  exception.
    

Example 1: Kitchen Sink
%%%%%%%%%%%%%%%%%%%%%%%
    
For this example we create a slightly more expansive test class 
that creates a stub method for each of the different event levels.
    
.. literalinclude:: ../examples/ExceptionControl-Example-01.py
    :language: python
    :pyobject: MyClass
    :linenos:
    
We can then test this using the following function:

.. literalinclude:: ../examples/ExceptionControl-Example-01.py
    :language: python
    :pyobject: main
    :linenos:
    
The output of this example is here:
    
.. literalinclude:: ../examples/_test-example-01.log
    :linenos: