nezu 0.5.1a2

Elegant debuging module

Nezu

Elegant debug module

• Python Code Example

  # file.py
  from nezu import dbg
  x = 13
  dbg('x')  # Prints debug info.
  

• Bash Commands to Debug

  export NEZU_SEEK=1
  python file.py
      @4 L.. x:int  =>  13
  

• Powershell Commands to Debug

  $env:NEZU_SEEK = 1
  python file.py
      @4 L.. x:int  =>  13
  

Table of Contents

NEZU

• Table of Contents
• Installation
• Usage
  • Debuf Interpretation
  • Function dbg
  • Function say
• Config
  • Env Vars Config
  • JSON Config
  • Hardcoded Config
• Coloring output
• Hiding output

Installation

• Pip

  python -m pip install nezu
  

• Poetry

  python -m poetry add nezu
  

Usage

• Inspect variables with function dbg.
• Display literals with function say.
• Configure Nezu to show output.
• Interpret output.
• Fix bugs.

Debug Interpretation

Using debbuging function dbg will display something like:

• Example output

  @7 ..B print:function  =>  Prints the values to a stream, or to sys...
  

• Interpretation

  @7 ..B print:function  =>  Prints the values to a stream, or to sys...
  │ │   │     │             │
  │ │   │     │             └─ Value of inspected variable
  │ │   │     │
  │ │   │     └─────────────── Type of inspected variable.
  │ │   │
  │ │   └───────────────────── Name of inspected variable.
  │ │
  │ └───────────────────────── Scope of inspected variable (see bollow).
  |
  └─────────────────────────── Line number of inspection.
  

• Scope codes

  • L.. - local scope, no shadowing
  • Lg. - local scope, shadowing global
  • L.b - local scope, shadowing built-in
  • Lgb - local scope, shadowing global and built-in
  • .G. - Global scope, no shadowing
  • .Gb - Global scope, shadowing built-in
  • ..B - Built-in scope, no shadowing
  • ... - Undefined

Function dbg

To debug, use funtion dbg, it will inspect scopes and values of given keys (variable names etc.).

• Args

  • *keys:str

    Names of variables to inspect

  • hide:int = 1

    This argument is compared with Nezu.seek. If Nezu.seek >= hide this debug inspection will be displayed.

  • bp:int = 0

    This argument is compared with Nezu.flow. If Nezu.flow < bp this debug inspection will be considered breakpoint.

• Python Code Example

  # file.py
  from nezu import dbg
  
  nortius = 3
  maximus = int()
  biggus = {'dickus':'sillius'}
  
  dbg('nortius')          # Works on simple variables.
  dbg('maximus.real')     # Works on attributes.
  dbg('print')            # Works on functions and built-ins.
  dbg('biggus["dickus"]') # DOES NOT work on keys and indexes yet.
  

• Note

  Output of dbg function is hidden by default. If you want to see dbg you need to configure env var NEZU_SEEK with value of 1 or more.

Function say

Simple literal output.

• Args

  • *val

    Value to display.

  • hide:int = 1

    This argument is compared with nezu.seek. If nezu.seek >= hide this call will be displayed.

  • bp:int = 0

    This argument is compared with Nezu.flow. If Nezu.flow < bp this call will be considered breakpoint.

• Python Code Example

  # file.py
  from nezu import say
  
  biggus = 'dickus'
  
  say('biggus') # displays something like `      @5 biggus`
  say(biggus)   # displays something like `      @6 dickus`
  

• Note

  Output of dbg function is hidden by default. If you want to see dbg you need to configure env var NEZU_SEEK with value of 1 or more.

Config

Module nezu creates nezu object that has config attributes used by function dbg.

• Attributes

  • nezu.seek:int = 0

    Compared to dbg argumenthide, if nezu.seek >= hide then dbg will be printed.

  • nezu.color:bool = False

    Determines if output of dbg function should be colored.

  • nezu.lock:bool = False

    If nezu.lock = True, this config cannot be changed later, during runtime.

Env Vars Config

If you want to use default config method, change your env vars in terminal and run Python script.

• Bash

  export NEZU_SEEK=1
  export NEZU_FLOW=5
  export NEZU_COLOR=1
  export NEZU_LOCK=0
  python file.py
  

• PowerShell

  $env:NEZU_SEEK = 1
  $env:NEZU_FLOW = 5
  $env:NEZU_COLOR = $True
  $env:NEZU_LOCK = $False
  python file.py
  

JSON Config

If you don't want to use env vars as config, you can call nezu.json() to read config data from json file. It will search for key nezu inside chosen file.

• Args

  • path:str = 'nezu.json' - path of config file

• Example Python Code

  from nezu import nezu, dbg
  nezu.json('my/json/file.json')
  

• Example Config File

  "nezu": {
    "seek": 1,
    "flow": 5,
    "color": true,
    "locked": false
  }
  

---

Hardcoded Config

If you don't want to use env vars as config you can also call object nezu like function to make hardcoded config.

• Args

  • seek:int = 0

    Debug level

  • flow:int = 5

    Skipping breakpoits

  • color:bool = False

    Output coloring

  • lock:bool = False

    Lock this config

• Example

  # file.py
  from nezu import nezu, dbg
  
  nezu(1, 7, True, False)
  ...
  

• Tip

  There is no built-in support for yaml, toml or .env in nezu This is so nezu can stay free of dependencies. However you can use hardcoded config to pass data from any config file.

Coloring output

By default nezu output is monochrome. If your terminal of choise support coloring you can change that.

• Example Bash Command

  export NEZU_COLOR=1
  python file.py
  

• Example PowerShell Command

  $env:NEZU_COLOR = $True
  python file.py
  

• Example JSON Config File

  "nezu": {
    "color": true,
  }
  

• Example Hardcoded Config

  from nezu import nezu, dbg
  
  nezu(color = True)
  ...
  

Hiding Output

Functions dbg() and say() can be hidden more by hide parameter. By default only calls with hide <= nezu.seek will be printed. In examples bellow only dbg hidden up to level 3 are displayed.

• Python Code Example

  #file.py
  from nezu import say
  
  say('biggus', hide=1)
  say('dickus', hide=2)
  say('nortius', hide=3)
  say('maximus', hide=4)
  say('sillius', hide=5)
  say('soddus', hide=6)
  

• Bash Example

  export NEZU_SEEK=3
  python file.py
        @4 biggus
        @5 dickus
        @6 nortius
  

• PowerShell Example

  $ENV:NEZU_SEEK = 3
  python file.py
        @4 biggus
        @5 dickus
        @6 nortius
  

• JSON File Example

  "nezu": {
      "seek": 3,
  }
  

• Example Hardcoded Config

  from nezu import nezu, dbg
  
  nezu(3)
  ...
  

Breakpoints

Functions dbg() and say() can be used as breakpoints by bp parameter. Calls with bp > nezu.flow will stop program execution. Hidden calls are never considered brerakpoints. In examples bellow only second call will behave as breakpoint.

• Python Code Example

  #file.py
  from nezu import dbg
  
  say('biggus' bp=6)
  say('dickus', bp=7)
  say('nortius', hide=2, bp=8)
  

• Bash Example

  export NEZU_SEEK=1
  export NEZU_FLOW=6
  python file.py
        @4 biggus
        @5 dickus   # Program stop execution until user press Enter
        @6 nortius
  

• PowerShell Example

  $ENV:NEZU_SEEK = 1
  $ENV:NEZU_FLOW = 6
  python file.py
        @4 biggus
        @5 dickus   # Program stop execution until user press Enter
        @6 nortius
  

• JSON File Example

  "nezu": {
      "flow": 6,
  }
  

• Example Hardcoded Config

  from nezu import nezu, dbg
  
  nezu(flow = 6)
  ...