hgutils 0.0.4
Utilities package while developing and implementing python tools
Requires Python: >=3.6

# hgutils

[hgutils](https://github.com/hiteshgulati/hgutils) is a python package having a repository of various utilities which come handy during python project development. 

## Current Features

* Timer - A python class to measure and print execution time of python code running over loops and in series.
* Debugger - A python class to add print and or executable statements within the code and execute only if debugger mode is on.

# Timer
This is a python class built to measure the execution time of python script. 

## Usage
Install `hgutils` to begin using timer class

```
$ pip install hgutils
```

Import `hgutils` in the python project and initiate `timer` class by assigning it to a variable while passing the project name in argument.

```
import hgutils
stopwatch = hgutils.timer("My Revolutionary Project")
```

Initiate the a new timer by calling `start` function and passing a name in argument. The new initiated timer will be child to current timer, which means current timer will continue to run and a new sub timer will be initiated.

```
stopwatch.start('New Timer')
```

To stop or end current timer simply call `stop` function. This function will end current timer, any parent timer(s) will keep on running. To end stop parent timer call the stop function again.

```
stopwatch.stop()
```

To get status of timers use `print` function. 
```
stopwatch.print()
```

`print` functions have following arguments to fine tune the required details:
* units - *millisesonds, seconds, minutes, hours, days and auto* Default - *auto*. Defines the units in which time of execution will be printed. *auto* will automatically select the best units based on the calculated time of execution.
* verbose - *0, 1, 2* Default - *0*. Determines the amount of information which will be printed. 
    - 0: Time of only current timer will be printed
    - 1: Time of current timer and its parent will be printed
    - 2: Time of all the timers used in the project will be printed

Status of timer can also be printed while stoping the timer by passing argument `print=True` in `stop` function.
```
stopwatch.stop(print=True,verbose=1)
```

To reset the timer use `reset` function. This will delete all existing timers and initiate a new timer for project.

```
stopwatch.reset()
```

## Examples

Here's a sample python project implemented using timer utility.

```
import hgutils
import time

print("Using timer utility available in hgutils")
stopwatch = hgutils.timer("hgutils timer sample project")
time.sleep(2)
stopwatch.start("Top Level Timer")
for i in range(4):
    stopwatch.start("i="+str(i))
    time.sleep(1)    
    if i==2:
        for j in range(5):
            stopwatch.start("j="+str(j))
            time.sleep(.04)
            stopwatch.stop(print=True,verbose=1)
    stopwatch.stop(print=True,verbose=1)
stopwatch.stop(print=True,verbose=1)
stopwatch.print(verbose=2)
```

**Output**
```
Using timer utility available in hgutils
	 Top Level Timer - 1.01 seconds*
		 i=0 - 1.01 seconds
	 Top Level Timer - 2.01 seconds*
		 i=1 - 1.0 seconds
		 i=2 - 1.05 seconds*
			 j=0 - 45.11 milliseconds
		 i=2 - 1.1 seconds*
			 j=1 - 45.07 milliseconds
		 i=2 - 1.14 seconds*
			 j=2 - 45.07 milliseconds
		 i=2 - 1.19 seconds*
			 j=3 - 44.15 milliseconds
		 i=2 - 1.23 seconds*
			 j=4 - 41.47 milliseconds
	 Top Level Timer - 3.24 seconds*
		 i=2 - 1.23 seconds
	 Top Level Timer - 4.24 seconds*
		 i=3 - 1.01 seconds
 hgutils timer sample project - 6.25 seconds*
	 Top Level Timer - 4.24 seconds
 hgutils timer sample project - 6.25 seconds*
	 Top Level Timer - 4.24 seconds
		 i=0 - 1.01 seconds
		 i=1 - 1.0 seconds
		 i=2 - 1.23 seconds
			 j=0 - 45.11 milliseconds
			 j=1 - 45.07 milliseconds
			 j=2 - 45.07 milliseconds
			 j=3 - 44.15 milliseconds
			 j=4 - 41.47 milliseconds
		 i=3 - 1.01 seconds
```

# Debugger
This is A python class to add print and or executable statements within the code and execute only if debugger mode is on.

## Usage
Install `hgutils` to begin using timer class

```
$ pip install hgutils
```

Import `hgutils` in the python project and initiate `debugger` class by assigning it to a variable while passing the project name in argument.

```
import hgutils
dbug = hgutils.debugger("My Revolutionary Project's Debugger")
```

Set debugging mode ON by calling `debugging_on` function and turn it OFF by calling `debugging_off` function. By default debugging mode is OFF.

```
dbug.debugging_on()
dbug.debugging_off()
```

Use `execute()` function to add printable / executable statements. These will be active only when debugger mode is ON. 

```
dbug.execute(title='Statement Title', print='This will be printed if debugger mode is ON')
```
`execute` functions have following arguments to be used as per requirements:
* title - *title for current execution* Default - *None*. This is the first line which will be printed when statement is executed in debugger mode ON. If *None* nothing will be printed.
* print - *Statement to be printed* Default - *None*. Statement which will be printed after printing title.
* execute - *function to be executed* Default - *None*. Function which will be executed. Note pass the function object here and not the executed object.
* args - *arguments to the executable function* Default - *None*. These are arguments which will be passed to the executable function.
* print_signature - *flag to determine if the signature will be printed towards the end* Default - *False*


# Authors
[@hiteshgulati](https://github.com/hiteshgulati)

[My Blog](https://hiteshgulati.com)