Metadata-Version: 2.1
Name: TimePoints
Version: 1.0.0
Summary: Easily measure durations between time points in a code
Home-page: https://github.com/htarnacki/TimePoints
Author: Hubert Tarnacki
Author-email: hubert.tarnacki@gmail.com
License: MIT
Project-URL: Code, https://github.com/htarnacki/TimePoints
Project-URL: Issue tracker, https://github.com/htarnacki/TimePoints/issues
Description: # TimePoints
        
        [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
        
        Easly save and collect different, dynamic time points in your application and print durations between any of them.
        
        
        ### Install with pip
        
        ```bash
        $ pip install TimePoints
        $ pip install TimePoints[reports]  # if you want to use "summary" functionality
        ```
        
        ### Usage
        
        ```python
        >>> import time
        >>> from TimePoints import Measure
        >>> Measure.sleep  # point 0
        >>> time.sleep(1)
        >>> Measure.sleep()  # point 1
        Duration of "sleep[0]->sleep[1]": 1 second
        
        >>> import time
        >>> from TimePoints import Measure
        >>> sleep = Measure.sleep  # point 0
        >>> time.sleep(1)
        >>> Measure.sleep  # point 1
        >>> print(str(sleep.duration))
        1.0011622839956544
        
        >>> import time
        >>> from TimePoints import Measure
        >>> sleep = Measure.sleep  # point 0
        >>> time.sleep(1)
        >>> Measure.sleep  # point 1
        >>> time.sleep(1.5)
        >>> Measure.sleep  # point 2
        >>> print(str(sleep[0].duration))
        >>> time.sleep(1)
        >>> print(str(Measure.sleep[0].duration))  # point 3
        2.5062046920002103
        3.5122546620302118
        
        >>> import time
        >>> from TimePoints import Measure
        >>> some_operation_stats = Measure.some_operation  # point 0
        >>> time.sleep(1)
        >>> Measure.some_operation  # point 1
        >>> time.sleep(1)
        >>> Measure.some_operation  # point 2
        >>> some_operation_stats.summary()
        ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
        ┃ Measurement    ┃ Points count ┃ Average duration ┃      First point ┃       Last point ┃
        ┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
        │ some_operation │            3 │         1 second │ 133321.685088924 │ 133323.687620218 │
        └────────────────┴──────────────┴──────────────────┴──────────────────┴──────────────────┘
        
        >>> import time
        >>> from TimePoints import Measure
        >>> Measure.Building  # point 0 of "Building"
        >>> time.sleep(2)
        >>> Measure.Building(format='{name} last: {humanized_duration}')  # point 1 of "Building"
        >>> Measure.Deploying  # point 0 of "Deploying"
        >>> time.sleep(1)
        >>> Measure.Deploying(format='{name} last: {humanized_duration}')  # point 1 of "Deploying"
        >>> Measure.summary()
        Building last: 2.0 seconds
        Deploying last: 1 second
        ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
        ┃ Measurement ┃ Points count ┃ Average duration ┃      First point ┃       Last point ┃
        ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
        │ Building    │            2 │      2.0 seconds │ 133067.569995202 │ 133069.571433436 │
        │ Deploying   │            2 │         1 second │ 133069.571682702 │ 133070.572820608 │
        └─────────────┴──────────────┴──────────────────┴──────────────────┴──────────────────┘
        
        >>> import time
        >>> from TimePoints import Measure
        >>> some_operation_stats = Measure.some_operation  # point 0
        >>> time.sleep(1)
        >>> Measure.some_operation  # point 1
        >>> time.sleep(1)
        >>> Measure.some_operation  # point 2
        >>> time.sleep(1)
        >>> Measure.some_operation  # point 3
        >>> some_operation_stats[0](format='Duration of {name} from point 0: {hduration}')
        >>> some_operation_stats[1](format='Duration of {name} from point 1: {hduration}')
        >>> some_operation_stats[2](format='Duration of {name} from point 2: {hduration}')
        Duration of some_operation from point 0: 3.0 seconds
        Duration of some_operation from point 1: 2.0 seconds
        Duration of some_operation from point 2: 1 second
        
        >>> import time
        >>> from TimePoints import Measure
        >>> for i in range(5):
        >>>     Measure.loop()
        >>>     time.sleep(1)
        Duration of "loop[0]->loop[0]": 0.0 seconds
        Duration of "loop[0]->loop[1]": 1 second
        Duration of "loop[1]->loop[2]": 1 second
        Duration of "loop[2]->loop[3]": 1 second
        Duration of "loop[3]->loop[4]": 1 second
        
        >>> import time
        >>> from TimePoints import Measure
        >>> for i in range(5):
        >>>     Measure.loop()
        >>>     time.sleep(1)
        >>> Measure.loop[0]()
        Duration of "loop[0]->loop[0]": 0.0 seconds
        Duration of "loop[0]->loop[1]": 1 second
        Duration of "loop[1]->loop[2]": 1 second
        Duration of "loop[2]->loop[3]": 1 second
        Duration of "loop[3]->loop[4]": 1 second
        Duration of "loop[0]->loop[5]": 5.01 seconds
        
        >>> import time
        >>> from TimePoints import Measure
        >>> for i in range(5):
        >>>     Measure.loop
        >>>     time.sleep(1)
        >>> for i in range(5):
        >>>     Measure.loop2
        >>>     time.sleep(1)
        >>> Measure.summary()
        ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
        ┃ Measurement ┃ Points count ┃ Average duration ┃      First point ┃       Last point ┃
        ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
        │ loop        │            5 │         1 second │ 133960.331337131 │ 133964.334118174 │
        │ loop2       │            5 │         1 second │ 133965.335290972 │ 133969.338710931 │
        └─────────────┴──────────────┴──────────────────┴──────────────────┴──────────────────┘
        
        >>> import time
        >>> from TimePoints import Measure
        >>> for i in range(5):
        >>>     Measure.loop
        >>>     time.sleep(1)
        >>> Measure.loop.summary().squeeze().summary()
        ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
        ┃ Measurement ┃ Points count ┃ Average duration ┃      First point ┃     Last point ┃
        ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
        │ loop        │            6 │         1 second │ 135384.873706028 │ 135389.8791503 │
        └─────────────┴──────────────┴──────────────────┴──────────────────┴────────────────┘
        ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
        ┃ Measurement ┃ Points count ┃ Average duration ┃      First point ┃     Last point ┃
        ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
        │ loop        │            2 │     5.01 seconds │ 135384.873706028 │ 135389.8791503 │
        └─────────────┴──────────────┴──────────────────┴──────────────────┴────────────────┘
        ```
        
        ### Custom formatting placeholders:
            - `name`: name of a measurement eg. "a"
            - `name_range`: name of a measurement followed by time point comparison range eg. "a[992]->a[993]"
            - `duration`: duration beetween last measured time point and the one set as current comparison point eg. "0.36081594599818345"
            - `humanized_duration`: humanized duration beetween last measured time point and the one set as current comparison point eg. "6 minutes and 47.53 seconds"
            - `hduration`: the same as `humanized_duration`
            - `idx_a`: integer number of index for time point against which we make a comparison
            - `idx_b`: integer number of index for last time point
        
        For example:
        
        ```python
        # Return string representation of this measurement with one time custom formatting
        >>> import time
        >>> from logging import warning
        >>> from TimePoints import Measure
        >>> Measure.a
        >>> time.sleep(1)
        >>> warning(Measure.a.to_string(format='Why "{name}" took so long: {hduration}!'))
        WARNING:root:Why "a" took so long: 1 second!
        
        # Print this measurement with one time custom formatting
        >>> import time
        >>> from TimePoints import Measure
        >>> Measure.building
        >>> time.sleep(1)
        >>> Measure.building(format='How long was the {name} process: {hduration}')
        How long was the building process: 1 second
        
        # Set custom formatting for one measurement
        >>> import time
        >>> from TimePoints import Measure
        >>> Measure.building.set_format(format='How long was the {name} process: {hduration}')
        >>> time.sleep(1)
        >>> Measure.building()
        >>> time.sleep(1)
        >>> Measure.building()
        How long was the building process: 1 second
        How long was the building process: 1 second
        
        # Set custom formatting globally
        >>> import time
        >>> from TimePoints import Measure
        >>> Measure.set_format(format='How long was the {name} process: {hduration}')
        >>> Measure.building
        >>> time.sleep(1)
        >>> Measure.building()
        >>> Measure.deploying
        >>> time.sleep(1)
        >>> Measure.deploying()
        How long was the building process: 1 second
        How long was the deploying process: 1 second
        
        # Pass additional dynamic args to custom formatting
        >>> import time
        >>> from TimePoints import Measure
        >>> Measure.set_format(format='Stage {stage_number} of {name} process: {hduration}')
        >>> Measure.building
        >>> time.sleep(1)
        >>> Measure.building(stage_number=1)
        >>> time.sleep(1)
        >>> Measure.building(stage_number=2)
        Stage 1 of building process: 1 second
        Stage 2 of building process: 1 second
        ```
        
        ### Other APIs:
            - `Measure.delete('a')` -> delete 'a' measurement
            - `Measure.clear()` -> clear all measurements
        
Keywords: time,duration,time points,measure,debug
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Logging
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.7.0
Description-Content-Type: text/markdown
Provides-Extra: reports
