Module time_hdr.

time_hdr

With @time_box, you can decorate a function to be sandwiched between start time and end time messages like this:

Example:: decorate a function with time_box

>>> from scottbrian_utils.time_hdr import time_box

>>> @time_box
... def func2() -> None:
...      print('2 * 3 =', 2*3)

>>> func2()

**********************************************
* Starting func2 on Mon Jun 29 2020 18:22:50 *
**********************************************
2 * 3 = 6

********************************************
* Ending func2 on Mon Jun 29 2020 18:22:51 *
* Elapsed time: 0:00:00.001204             *
********************************************

The time_hdr module contains two items:

StartStopHeader class with two functions that will repectively print a starting time and ending time messages in a flower box (see flower_box module in scottbrian_utils package).

a time_box decorator that wraps a function and uses the StartStopHeader to print the starting and ending time messages.

time_box imports functools, sys, datetime, wrapt, and types from typing

time_hdr.get_datetime_match_string(format_str)

Return a regex string to match a datetime string.

Parameters:: format_str (str) – string used to format a datetime that is to be used to create a match string

Changed in version 3.0.0: format keyword changed to format_str

Return type:: str
Returns:: string that is to be used in a regex expression to match a datetime string

time_hdr.time_box(wrapped=None, *, dt_format='%a %b %d %Y %H:%M:%S', time_box_enabled=True, **kwargs)

Decorator to wrap a function in start time and end time messages.

The time_box decorator can be invoked with or without arguments, and the function being wrapped can optionally take arguments and optionally return a value. The wrapt.decorator is used to preserve the wrapped function introspection capabilities, and functools.partial is used to handle the case where decorator arguments are specified. The examples further below will help demonstrate the various ways in which the time_box decorator can be used.

Parameters:

wrapped (Optional[TypeVar(F, bound= Callable[..., Any])]) – Any callable function that accepts optional positional and/or optional keyword arguments, and optionally returns a value. The default is None, which will be the case when the pie decorator version is used with any of the following arguments specified.
dt_format (NewType(DT_Format, str)) – Specifies the datetime format to use in the start time message. The default is StartStopHeader.default_dt_format.
time_box_enabled (Union[bool, Callable[..., bool]]) – Specifies whether the start and end messages should be issued (True) or not (False). The default is True.
kwargs (Any) – Specifies the print arguments to use on the print statement, such as end, file, or flush.

Return type:

TypeVar(F, bound= Callable[..., Any])

Returns:

A callable function that issues a starting time message, calls the wrapped function, issues the ending time message, and returns any return values that the wrapped function returns.

Example:

statically wrapping function with time_box

>>> from scottbrian_utils.time_hdr import time_box

>>> _tbe = False

>>> @time_box(time_box_enabled=_tbe)
... def func4a() -> None:
...      print('this is sample text for _tbe = False static '
...            'example')

>>> func4a()  # func4a is not wrapped by time box
this is sample text for _tbe = False static example

>>> _tbe = True

>>> @time_box(time_box_enabled=_tbe)
... def func4b() -> None:
...      print('this is sample text for _tbe = True static example')

>>> func4b()  # func4b is wrapped by time box

***********************************************
* Starting func4b on Mon Jun 29 2020 18:22:51 *
***********************************************
this is sample text for _tbe = True static example

*********************************************
* Ending func4b on Mon Jun 29 2020 18:22:51 *
* Elapsed time: 0:00:00.000133              *
*********************************************

Example:: dynamically wrapping function with time_box:

>>> from scottbrian_utils.time_hdr import time_box

>>> _tbe = True
>>> def tbe() -> bool: return _tbe

>>> @time_box(time_box_enabled=tbe)
... def func5() -> None:
...      print('this is sample text for the tbe dynamic example')

>>> func5()  # func5 is wrapped by time box

**********************************************
* Starting func5 on Mon Jun 29 2020 18:22:51 *
**********************************************
this is sample text for the tbe dynamic example

********************************************
* Ending func5 on Mon Jun 29 2020 18:22:51 *
* Elapsed time: 0:00:00.000130             *
********************************************

>>> _tbe = False
>>> func5()  # func5 is not wrapped by time_box
this is sample text for the tbe dynamic example

Example:: specifying a datetime format:

>>> from scottbrian_utils.time_hdr import time_box

>>> aDatetime_format: DT_Format = DT_Format('%m/%d/%y %H:%M:%S')
>>> @time_box(dt_format=aDatetime_format)
... def func6() -> None:
...     print('this is sample text for the datetime format example')

>>> func6()

***************************************
* Starting func6 on 06/30/20 17:07:48 *
***************************************
this is sample text for the datetime format example

*************************************
* Ending func6 on 06/30/20 17:07:48 *
* Elapsed time: 0:00:00.000073      *
*************************************