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

class time_hdr.StartStopHeader(func_name)¶

Supports the time_box decorator.

Provides:

a place to store the start time and end time

method print_start_msg to print the start header with the start time

method print_end_msg to print the end trailer with end time and elapsed time

While there might be some standalone uses for this class and its methods, its intended use is by the time_box decorator described later in this module.

print_end_msg(dt_format='%a %b %d %Y %H:%M:%S', end='\\n', file=None, flush=False)¶

Issue end time message in a flower box.

The end message includes the current datetime and elapsed time (calculated as the difference between the end time and the saved start time - see the print_start_msg method).

Parameters

dt_format (NewType()(DT_Format, str)) – Specifies the datetime format to use in the end time message. The default is StartStopHeader.default_dt_format.
end (str) – Specifies the argument to use on the print statement end parameter for the end time message. The default is ‘\n’.
file (Optional[TextIO]) – Specifies the argument to use on the print statement file parameter for the end time message. The default is sys.stdout (via None).
flush (bool) – Specifies the argument to use on the print statement flush parameter for the end time message. The default is False.

Return type

None

print_start_msg(dt_format='%a %b %d %Y %H:%M:%S', end='\\n', file=None, flush=False)¶

Issue start time message in a flower box.

The start message includes the current datetime which is also saved to be used later to calculate the elapsed time for the print_end_msg invocation.

Parameters

dt_format (NewType()(DT_Format, str)) – Specifies the datetime format to use in the start time message. The default is StartStopHeader.default_dt_format.
end (str) – Specifies the argument to use on the print statement end parameter for the start time message. The default is ‘\n’.
file (Optional[TextIO]) – Specifies the argument to use on the print statement file parameter for the start time message. The default is sys.stdout (via None).
flush (bool) – Specifies the argument to use on the print statement flush parameterfor the start time messsage. The default is False.

Example

Using StartStopHeader with start and end messages.

>>> from scottbrian_utils.time_hdr import StartStopHeader

>>> def func3() -> None:
...      print('2 + 2 =', 2+2)

>>> hdr = StartStopHeader('func3')
>>> hdr.print_start_msg()

**********************************************
* Starting func3 on Mon Jun 29 2020 18:22:48 *
**********************************************
>>> func3()
2 + 2 = 4
>>> hdr.print_end_msg()

********************************************
* Ending func3 on Mon Jun 29 2020 18:22:50 *
* Elapsed time: 0:00:00.001842             *
********************************************

Return type: None

time_hdr.time_box(wrapped: F, *, dt_format: DT_Format = 'StartStopHeader.default_dt_format', end: str = "'\\n'", file: Optional[TextIO] = 'None', flush: bool = 'False', time_box_enabled: Union[bool, Callable[[…], bool]] = 'True') → F¶

time_hdr.time_box(*, dt_format: DT_Format = 'StartStopHeader.default_dt_format', end: str = "'\\n'", file: Optional[TextIO] = 'None', flush: bool = 'False', time_box_enabled: Union[bool, Callable[[…], bool]] = 'True') → Callable[[F], F]

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[~F]) – 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.
end (str) – Specifies the argument to use on the print statement end parameter for the start time and end time messages issued by the StartStopHeader methods . The default is ‘\n’.
file (Optional[TextIO]) – Specifies the argument to use on the print statement file parameter for the start time and end time messages issued by the StartStopHeader methods . The default is sys.stdout (via None).
flush (bool) – Specifies the argument to use on the print statement flush parameterfor the start time and end time messages issued by the StartStopHeader methods . The default is False.
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.

Return type

~F

Returns

A callable function that issues a starting time message, calls the wrapped function, issues the ending time message, and finally returns the return value from the wrapped function, if one.

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      *
*************************************