| Name | stopstart JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | https://github.com/ReverieTides/stopstart |
| Summary | A simple timer class for tracking elapsed time across multiple sessions, with detailed statistics and formatted output. |
| upload_time | 2024-12-18 19:36:54 |
| maintainer | None |
| docs_url | None |
| author | Dan |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# stopstart
A simple and intuitive Python class for tracking elapsed time across multiple sessions. The `Timer` class offers a clean, human-readable interface to start and stop time, while providing detailed session statistics and beautifully formatted elapsed time. Whether you're measuring short intervals or long-running processes, the `Timer` class ensures you have accurate data with minimal effort.
## Features
- **Easy to Use**: No complex setup—just call `start()` to begin and `stop()` to end your time tracking. Perfect for quick and efficient use.
- **Time Formatting**: Effortlessly convert elapsed time into a human-friendly format, including days, hours, minutes, seconds, and even fractions like microseconds and nanoseconds.
- **Session Statistics**: Track total time, the number of sessions, and average session durations with just one method call.
- **Formatted Output**: Receive time statistics in an easy-to-read format that includes precise microseconds and nanoseconds.
## Methods:
- **`start(reset=True)`**: Starts the timer. If `reset=True`, it resets the timer and clears any past session history. If `reset=False`, the timer continues from where it left off.
- **`stop()`**: Stops the timer, records the elapsed time for the current session, and appends it to the history.
- **`print_snapshot(prefix="")`**: Prints a snapshot of the total elapsed time up to the current moment, appending a given prefix (optional).
- **`print(prefix="")`**: Prints the formatted total elapsed time with an optional prefix.
- **`get_stats()`**: Returns a dictionary with statistics about the timer, including total time, number of sessions, and average session time.
### Properties:
- **`days`**: The total elapsed time in days.
- **`hours`**: The total elapsed time in hours.
- **`minutes`**: The total elapsed time in minutes.
- **`seconds`**: The total elapsed time in seconds.
- **`milli`**: The total elapsed time in milliseconds (total duration in seconds * 1e3).
- **`nano`**: The total elapsed time in nanoseconds (total duration in seconds * 1e9).
- **`total_duration`**: The total accumulated duration of all actions in seconds, calculated by summing the durations of all recorded sessions.
## Installation
Install the package via `pip`:
```bash
pip install timer
```
## Usage
### Example: Typical Usecase
In this example, the timer is used to measure a single session. Starting and stopping the timer around an activity (like a 2-second wait) will give you the total duration for that period, along with a detailed human-readable output and session statistics.
```python
import time
from stopstart import Timer
# Initialize the Timer
timer = Timer()
# Start the timer (reset to 0)
timer.start()
# Wait for 2 seconds
time.sleep(2)
# Stop the timer
timer.stop()
# Get total duration in seconds
print(f"Total duration in seconds: {timer.seconds}")
# Get a nice clean formatted total duration
print(timer)
# Get stats
stats = timer.get_stats()
print(f"Stats: {stats}")
```
#### Output:
```
Total duration in seconds: 2.000082492828369
2 seconds, 82 microseconds, and 492 nanoseconds
Stats: {'total_time': 2.000082492828369, 'num_sessions': 1, 'avg_time': 2.000082492828369}
```
### Example: Session Resuming
The Timer class can resume timing without resetting the session history, allowing you to track multiple periods of time over the course of your work. This makes it easy to start new sessions without losing track of the total time across sessions.
In this example, we start a second session without resetting the timer, simulate another 2-second activity, and then stop the timer to get the updated total duration.
```python
# Start the second session (without reset)
timer.start(reset=False)
# Wait for another 2 seconds
time.sleep(2)
# Stop the timer
timer.stop()
# Get updated total duration
print(f"Total duration in seconds: {timer.seconds}")
print(timer)
```
#### Output:
```
Total duration in seconds: 4.0001797676086426
4 seconds, 179 microseconds, and 767 nanoseconds
Stats: {'total_time': 4.0001797676086426, 'num_sessions': 2, 'avg_time': 2.0000898838043213}
```
### Print snapshots
You can also print time snapshots without affecting the ongoing time tracking. This is useful for logging intermediate results or showing progress without interrupting the current session. The snapshot feature is non-intrusive and does not reset or stop the timer.
```python
time.sleep(30)
timer.print_snapshot(prefix='Snapshot Example:')
timer.print('Actual recorded time:')
```
#### Output:
```
Snapshot Example: 34 seconds, 132 microseconds, and 165 nanoseconds
Actual recorded time: 4 seconds, 179 microseconds, and 767 nanoseconds
```
### Example: Accessing Timer History
The Timer automatically preserves the history of previous sessions in the `actions` attribute. This allows you to access a complete log of all sessions, including their start and stop times, without losing any context. You can easily retrieve this history to analyze past sessions or track progress over time.
```python
import time
from stopstart import Timer
# Initialize the Timer object
timer = Timer()
# Start the first session
timer.start()
time.sleep(2)
timer.stop()
print(f"Session 1 Duration: {timer}")
# Start a second session without resetting the timer
timer.start(reset=False)
time.sleep(3)
timer.stop()
print(f"Session 2 Duration: {timer}")
# Accessing the history of all actions
print(f"Actions History: {timer.actions}")
```
#### Output:
```
Session 1 Duration: 2 seconds, 0 microseconds, and 0 nanoseconds
Session 2 Duration: 5 seconds, 0 microseconds, and 0 nanoseconds
Actions History: [
{'start': 1699392400.0, 'stop': 1699392402.0, 'duration': 2.0},
{'start': 1699392402.0, 'stop': 1699392407.0, 'duration': 5.0}
]
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ReverieTides/stopstart",
"name": "stopstart",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Dan",
"author_email": "break.a.wish@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ba/b5/090038c9b0b825967aa01f862433a9ba0ec296751c992ae4eaefa32f0baa/stopstart-0.5.0.tar.gz",
"platform": null,
"description": "# stopstart\r\n\r\nA simple and intuitive Python class for tracking elapsed time across multiple sessions. The `Timer` class offers a clean, human-readable interface to start and stop time, while providing detailed session statistics and beautifully formatted elapsed time. Whether you're measuring short intervals or long-running processes, the `Timer` class ensures you have accurate data with minimal effort.\r\n\r\n## Features\r\n\r\n- **Easy to Use**: No complex setup\u2014just call `start()` to begin and `stop()` to end your time tracking. Perfect for quick and efficient use.\r\n- **Time Formatting**: Effortlessly convert elapsed time into a human-friendly format, including days, hours, minutes, seconds, and even fractions like microseconds and nanoseconds.\r\n- **Session Statistics**: Track total time, the number of sessions, and average session durations with just one method call.\r\n- **Formatted Output**: Receive time statistics in an easy-to-read format that includes precise microseconds and nanoseconds.\r\n\r\n\r\n## Methods:\r\n- **`start(reset=True)`**: Starts the timer. If `reset=True`, it resets the timer and clears any past session history. If `reset=False`, the timer continues from where it left off.\r\n- **`stop()`**: Stops the timer, records the elapsed time for the current session, and appends it to the history.\r\n- **`print_snapshot(prefix=\"\")`**: Prints a snapshot of the total elapsed time up to the current moment, appending a given prefix (optional).\r\n- **`print(prefix=\"\")`**: Prints the formatted total elapsed time with an optional prefix.\r\n- **`get_stats()`**: Returns a dictionary with statistics about the timer, including total time, number of sessions, and average session time.\r\n\r\n\r\n### Properties:\r\n- **`days`**: The total elapsed time in days.\r\n- **`hours`**: The total elapsed time in hours.\r\n- **`minutes`**: The total elapsed time in minutes.\r\n- **`seconds`**: The total elapsed time in seconds.\r\n- **`milli`**: The total elapsed time in milliseconds (total duration in seconds * 1e3).\r\n- **`nano`**: The total elapsed time in nanoseconds (total duration in seconds * 1e9).\r\n- **`total_duration`**: The total accumulated duration of all actions in seconds, calculated by summing the durations of all recorded sessions.\r\n\r\n\r\n## Installation\r\n\r\nInstall the package via `pip`:\r\n\r\n```bash\r\npip install timer\r\n```\r\n## Usage\r\n### Example: Typical Usecase\r\nIn this example, the timer is used to measure a single session. Starting and stopping the timer around an activity (like a 2-second wait) will give you the total duration for that period, along with a detailed human-readable output and session statistics.\r\n```python\r\nimport time\r\nfrom stopstart import Timer\r\n\r\n# Initialize the Timer\r\ntimer = Timer()\r\n\r\n# Start the timer (reset to 0)\r\ntimer.start()\r\n\r\n# Wait for 2 seconds\r\ntime.sleep(2)\r\n\r\n# Stop the timer\r\ntimer.stop()\r\n\r\n# Get total duration in seconds\r\nprint(f\"Total duration in seconds: {timer.seconds}\")\r\n\r\n# Get a nice clean formatted total duration\r\nprint(timer)\r\n\r\n# Get stats\r\nstats = timer.get_stats()\r\nprint(f\"Stats: {stats}\")\r\n```\r\n#### Output:\r\n```\r\nTotal duration in seconds: 2.000082492828369 \r\n2 seconds, 82 microseconds, and 492 nanoseconds \r\nStats: {'total_time': 2.000082492828369, 'num_sessions': 1, 'avg_time': 2.000082492828369}\r\n```\r\n### Example: Session Resuming\r\nThe Timer class can resume timing without resetting the session history, allowing you to track multiple periods of time over the course of your work. This makes it easy to start new sessions without losing track of the total time across sessions.\r\n\r\nIn this example, we start a second session without resetting the timer, simulate another 2-second activity, and then stop the timer to get the updated total duration.\r\n```python\r\n# Start the second session (without reset)\r\ntimer.start(reset=False)\r\n\r\n# Wait for another 2 seconds\r\ntime.sleep(2)\r\n\r\n# Stop the timer\r\ntimer.stop()\r\n\r\n# Get updated total duration\r\nprint(f\"Total duration in seconds: {timer.seconds}\")\r\nprint(timer)\r\n```\r\n#### Output:\r\n```\r\nTotal duration in seconds: 4.0001797676086426\r\n4 seconds, 179 microseconds, and 767 nanoseconds\r\nStats: {'total_time': 4.0001797676086426, 'num_sessions': 2, 'avg_time': 2.0000898838043213}\r\n```\r\n### Print snapshots\r\nYou can also print time snapshots without affecting the ongoing time tracking. This is useful for logging intermediate results or showing progress without interrupting the current session. The snapshot feature is non-intrusive and does not reset or stop the timer.\r\n```python\r\ntime.sleep(30)\r\ntimer.print_snapshot(prefix='Snapshot Example:')\r\ntimer.print('Actual recorded time:')\r\n```\r\n#### Output:\r\n\r\n```\r\nSnapshot Example: 34 seconds, 132 microseconds, and 165 nanoseconds\r\nActual recorded time: 4 seconds, 179 microseconds, and 767 nanoseconds\r\n```\r\n\r\n### Example: Accessing Timer History\r\nThe Timer automatically preserves the history of previous sessions in the `actions` attribute. This allows you to access a complete log of all sessions, including their start and stop times, without losing any context. You can easily retrieve this history to analyze past sessions or track progress over time.\r\n```python\r\nimport time\r\nfrom stopstart import Timer\r\n\r\n# Initialize the Timer object\r\ntimer = Timer()\r\n\r\n# Start the first session\r\ntimer.start()\r\ntime.sleep(2)\r\ntimer.stop()\r\nprint(f\"Session 1 Duration: {timer}\")\r\n\r\n# Start a second session without resetting the timer\r\ntimer.start(reset=False)\r\ntime.sleep(3)\r\ntimer.stop()\r\nprint(f\"Session 2 Duration: {timer}\")\r\n\r\n# Accessing the history of all actions\r\nprint(f\"Actions History: {timer.actions}\")\r\n```\r\n#### Output:\r\n\r\n```\r\nSession 1 Duration: 2 seconds, 0 microseconds, and 0 nanoseconds \r\nSession 2 Duration: 5 seconds, 0 microseconds, and 0 nanoseconds \r\nActions History: [\r\n {'start': 1699392400.0, 'stop': 1699392402.0, 'duration': 2.0}, \r\n {'start': 1699392402.0, 'stop': 1699392407.0, 'duration': 5.0}\r\n]\r\n```\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A simple timer class for tracking elapsed time across multiple sessions, with detailed statistics and formatted output.",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/ReverieTides/stopstart"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fdc32c3717faa5f5e5315d0d76fd228cc7115a2b7cf888fc10ac5ee599076996",
"md5": "c535e15d21fdbb85c761e313be97483e",
"sha256": "5a736612f43b22b707f03844688c08d1d119a48ad8e9f051aabfd9f270897c76"
},
"downloads": -1,
"filename": "stopstart-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c535e15d21fdbb85c761e313be97483e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6570,
"upload_time": "2024-12-18T19:36:49",
"upload_time_iso_8601": "2024-12-18T19:36:49.610815Z",
"url": "https://files.pythonhosted.org/packages/fd/c3/2c3717faa5f5e5315d0d76fd228cc7115a2b7cf888fc10ac5ee599076996/stopstart-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bab5090038c9b0b825967aa01f862433a9ba0ec296751c992ae4eaefa32f0baa",
"md5": "6a1f9b222fb67b2365e08b05e4c09f3f",
"sha256": "8b0c066d76eb2bddcff51c55f2e3729c6ac3a3f5354fd8635b750b73e61286d4"
},
"downloads": -1,
"filename": "stopstart-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "6a1f9b222fb67b2365e08b05e4c09f3f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6363,
"upload_time": "2024-12-18T19:36:54",
"upload_time_iso_8601": "2024-12-18T19:36:54.323498Z",
"url": "https://files.pythonhosted.org/packages/ba/b5/090038c9b0b825967aa01f862433a9ba0ec296751c992ae4eaefa32f0baa/stopstart-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 19:36:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ReverieTides",
"github_project": "stopstart",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "stopstart"
}
