# TQuota
`tquota.Quota` is a lightweight processing timer module designed to monitor time effectively when running code on cloud platforms with quota limitations, such as [Kaggle](https://www.kaggle.com/) and [Google Colab](https://colab.research.google.com/). These platforms impose a limit of `x` hours of processing per session, the `Quota` class allows users to set a processing quota time and a buffer time before the quota limit ends, ensuring efficient resource management.
## Features
- **Quota Management**: Easily track and manage session time to avoid overuse of limited resources on platforms with quota restrictions.
- **Dynamic Gap Timing**: Automatically adjusts the buffer time (`gap_time`) based on the remaining session time when set to `'auto'`.
- **Auto Gap Calculation**: When `gap_time` is set to `'auto'`, the system dynamically calculates the optimal gap before the session ends, ensuring efficient timing without the need for manual setup.
- **Simple Interface**: The class provides Easy-to-use and intuitive methods to check whether time is still available or if the session has reached its limit.
- **Optional Logging**: Enable logging to track quota usage and gap timing for debugging or monitoring purposes.
- **Compatibility**: It can work with Python versions 2.7 and 3.0+.
---
## Quota Class
The package `tquota` includes a single class, `Quota`, which has two main parameters and an optional one:
* **quota_time**: (str) Default value: `6h`. Represents the maximum processing time for the session.
* **gap_time**: (str) Default value: `'auto'`. Represents the buffer time before the session closes, adjusted dynamically based on elapsed time.
* **enable_logging**: (bool, optional) Default value: `False`. Whether to enable logging or not.
### Time Format
The time should be specified in a strict format, consisting of two parts: *`dw`*, where:
- **d**: Represents the time as digits
- **w**: Represents the time unit with one character:
[ s: Seconds, m: Minutes, h: Hours, d: Days]
## Functions
The `Quota` class provides the following key methods:
**`time_up`**:
- **Description**: This method checks whether the processing time has reached or exceeded its quota limit.
- **Returns**:
- `True`: If the process has reached or exceeded the defined quota time.
- `False`: If there is still time remaining within the quota limit.
- **Usage**:
```python
if qt.time_up():
print('Time limit reached.')
```
**`hastime`**:
- **Description**: This method checks whether there is still time left before the process reaches the quota limit.
- **Returns**:
- `True`: If there is still time remaining before reaching the quota.
- `False`: If the process has exceeded the quota time or is within the gap buffer.
- **Usage**:
```python
if qt.hastime():
print('There’s still time to process.')
```
**`remaining_time`**:
- **Description**: This method returns the remaining time before the quota limit is reached in a human-readable format.
- **Returns**: A string representing the remaining time formatted as `"xh:xm:xs"` (e.g., `"0h:10m:15s"` for 10 minutes and 15 seconds remaining).
- **Usage**:
```python
remaining = qt.remaining_time()
print(f'Remaining time: {remaining}')
```
---
## Installation
You can install the package from [PyPI](https://pypi.org/project/tquota) using the following command:
```bash
pip install tquota
```
Alternatively, you can clone the repository and install the package directly:
```bash
git clone https://github.com/aljbri/tquota.git
cd tquota
pip install .
```
---
## Usage
Import the `Quota` class as follows:
```python
from tquota import Quota
```
### Example Usage
- Using the **time_up** function:
```python
from tquota import Quota
import time
# Quota time is set for 1 minute and gap time is auto-adjusted
qt = Quota('1m')
# Set quota_time for 1 minute and gap_time for 30 seconds
# qt = Quota('1m', '30s')
for i in range(1000):
time.sleep(1)
if qt.time_up():
print('The process has reached the limited time.')
break
```
- Using the **hastime** function:
```python
from tquota import Quota
import time
# Quota time is set for 1 minute and gap time is auto-adjusted
# qt = Quota('1m')
# Set quota_time for 1 minute and gap_time for 30 seconds
qt = Quota('1m', '30s')
for i in range(1000):
time.sleep(1)
if not qt.hastime():
print('The process has reached the limited time.')
break
```
---
## Error Handling
The `Quota` class may raise the following exceptions:
- `ValueError`: Raised for invalid time formats or non-positive time values.
- `TypeError`: Raised if non-string values are provided for time parameters.
- `AttributeError`: Raised if internal properties are accessed incorrectly.
---
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
---
## Updates
### v0.0.1
- Initial implementation of the `quota` class.
### v0.0.2
- Major error fix `quota` class.
### v0.0.3
- **Auto Gap Time**: Added support for automatic calculation of `gap_time` when it is set to `'auto'`, dynamically adjusting the buffer time based on the session duration.
- **Error Handling Enhancements**: Improved validation for time formats, with clearer exceptions raised (`ValueError`, `TypeError`, `AttributeError`) for invalid inputs or improper usage.
- **Optimized Logging**: Added an optional logging feature that provides detailed output for quota time, gap time, and overall usage when enabled.
- **Performance Improvements**: Optimized the time-tracking logic for smoother integration into various cloud platforms.
- **Python Compatibility**: Compatible with Python versions 2.7 and 3.0+.
---
## Contributing
Contributions are welcome! If you have suggestions or improvements, please feel free to submit a pull request or open an issue.
---
## Contact
For inquiries or feedback, please contact the author at [mr.aljbri@gmail.com](mailto:mr.aljbri@gmail.com).
Raw data
{
"_id": null,
"home_page": "https://github.com/aljbri/tquota",
"name": "tquota",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=2.7",
"maintainer_email": "Abdussalam Aljbri <mr.aljbri@gmail.com>",
"keywords": "quota, cloud, timer, kaggle, colab, session, management, monitor",
"author": "Abdussalam Aljbri",
"author_email": "Abdussalam Aljbri <mr.aljbri@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/07/04/dac529cce835c1bfa44e7739d6dc8d37ad5515a863d9a2e2d2771a0c3f5f/tquota-0.0.3.tar.gz",
"platform": null,
"description": "# TQuota\r\n`tquota.Quota` is a lightweight processing timer module designed to monitor time effectively when running code on cloud platforms with quota limitations, such as [Kaggle](https://www.kaggle.com/) and [Google Colab](https://colab.research.google.com/). These platforms impose a limit of `x` hours of processing per session, the `Quota` class allows users to set a processing quota time and a buffer time before the quota limit ends, ensuring efficient resource management.\r\n\r\n## Features\r\n\r\n- **Quota Management**: Easily track and manage session time to avoid overuse of limited resources on platforms with quota restrictions.\r\n- **Dynamic Gap Timing**: Automatically adjusts the buffer time (`gap_time`) based on the remaining session time when set to `'auto'`.\r\n- **Auto Gap Calculation**: When `gap_time` is set to `'auto'`, the system dynamically calculates the optimal gap before the session ends, ensuring efficient timing without the need for manual setup.\r\n- **Simple Interface**: The class provides Easy-to-use and intuitive methods to check whether time is still available or if the session has reached its limit.\r\n- **Optional Logging**: Enable logging to track quota usage and gap timing for debugging or monitoring purposes.\r\n- **Compatibility**: It can work with Python versions 2.7 and 3.0+.\r\n\r\n---\r\n## Quota Class\r\n\r\nThe package `tquota` includes a single class, `Quota`, which has two main parameters and an optional one:\r\n\r\n* **quota_time**: (str) Default value: `6h`. Represents the maximum processing time for the session.\r\n* **gap_time**: (str) Default value: `'auto'`. Represents the buffer time before the session closes, adjusted dynamically based on elapsed time.\r\n* **enable_logging**: (bool, optional) Default value: `False`. Whether to enable logging or not.\r\n\r\n### Time Format\r\n\r\nThe time should be specified in a strict format, consisting of two parts: *`dw`*, where: \r\n- **d**: Represents the time as digits\r\n- **w**: Represents the time unit with one character:\r\n\r\n [ s: Seconds, m: Minutes, h: Hours, d: Days]\r\n\r\n## Functions\r\n\r\nThe `Quota` class provides the following key methods:\r\n\r\n**`time_up`**:\r\n - **Description**: This method checks whether the processing time has reached or exceeded its quota limit.\r\n - **Returns**: \r\n - `True`: If the process has reached or exceeded the defined quota time.\r\n - `False`: If there is still time remaining within the quota limit.\r\n - **Usage**:\r\n ```python\r\n if qt.time_up():\r\n print('Time limit reached.')\r\n ```\r\n\r\n**`hastime`**:\r\n - **Description**: This method checks whether there is still time left before the process reaches the quota limit.\r\n - **Returns**: \r\n - `True`: If there is still time remaining before reaching the quota.\r\n - `False`: If the process has exceeded the quota time or is within the gap buffer.\r\n - **Usage**:\r\n ```python\r\n if qt.hastime():\r\n print('There\u2019s still time to process.')\r\n ```\r\n\r\n**`remaining_time`**:\r\n - **Description**: This method returns the remaining time before the quota limit is reached in a human-readable format.\r\n - **Returns**: A string representing the remaining time formatted as `\"xh:xm:xs\"` (e.g., `\"0h:10m:15s\"` for 10 minutes and 15 seconds remaining).\r\n - **Usage**:\r\n ```python\r\n remaining = qt.remaining_time()\r\n print(f'Remaining time: {remaining}')\r\n ```\r\n---\r\n## Installation\r\n\r\nYou can install the package from [PyPI](https://pypi.org/project/tquota) using the following command:\r\n\r\n```bash\r\npip install tquota\r\n```\r\n\r\nAlternatively, you can clone the repository and install the package directly:\r\n\r\n```bash\r\ngit clone https://github.com/aljbri/tquota.git\r\ncd tquota\r\npip install .\r\n```\r\n---\r\n## Usage\r\n\r\nImport the `Quota` class as follows:\r\n\r\n```python\r\nfrom tquota import Quota\r\n```\r\n\r\n### Example Usage\r\n\r\n- Using the **time_up** function:\r\n\r\n```python\r\nfrom tquota import Quota\r\nimport time\r\n\r\n# Quota time is set for 1 minute and gap time is auto-adjusted\r\nqt = Quota('1m')\r\n# Set quota_time for 1 minute and gap_time for 30 seconds\r\n# qt = Quota('1m', '30s')\r\n\r\nfor i in range(1000):\r\n time.sleep(1)\r\n if qt.time_up():\r\n print('The process has reached the limited time.')\r\n break\r\n```\r\n- Using the **hastime** function:\r\n\r\n```python\r\nfrom tquota import Quota\r\nimport time\r\n\r\n# Quota time is set for 1 minute and gap time is auto-adjusted\r\n# qt = Quota('1m')\r\n\r\n# Set quota_time for 1 minute and gap_time for 30 seconds\r\nqt = Quota('1m', '30s')\r\n\r\nfor i in range(1000):\r\n time.sleep(1)\r\n if not qt.hastime():\r\n print('The process has reached the limited time.')\r\n break\r\n```\r\n\r\n---\r\n## Error Handling\r\n\r\nThe `Quota` class may raise the following exceptions:\r\n\r\n- `ValueError`: Raised for invalid time formats or non-positive time values.\r\n- `TypeError`: Raised if non-string values are provided for time parameters.\r\n- `AttributeError`: Raised if internal properties are accessed incorrectly.\r\n---\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\r\n\r\n---\r\n## Updates\r\n\r\n### v0.0.1\r\n- Initial implementation of the `quota` class.\r\n\r\n### v0.0.2\r\n- Major error fix `quota` class.\r\n\r\n### v0.0.3\r\n- **Auto Gap Time**: Added support for automatic calculation of `gap_time` when it is set to `'auto'`, dynamically adjusting the buffer time based on the session duration.\r\n- **Error Handling Enhancements**: Improved validation for time formats, with clearer exceptions raised (`ValueError`, `TypeError`, `AttributeError`) for invalid inputs or improper usage.\r\n- **Optimized Logging**: Added an optional logging feature that provides detailed output for quota time, gap time, and overall usage when enabled.\r\n- **Performance Improvements**: Optimized the time-tracking logic for smoother integration into various cloud platforms.\r\n- **Python Compatibility**: Compatible with Python versions 2.7 and 3.0+.\r\n\r\n---\r\n## Contributing\r\n\r\nContributions are welcome! If you have suggestions or improvements, please feel free to submit a pull request or open an issue.\r\n\r\n---\r\n## Contact\r\n\r\nFor inquiries or feedback, please contact the author at [mr.aljbri@gmail.com](mailto:mr.aljbri@gmail.com).\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A lightweight processing timer module for quota-based cloud environments.",
"version": "0.0.3",
"project_urls": {
"Documentation": "https://aljbri.github.io/tquota/",
"Homepage": "https://github.com/aljbri/tquota/",
"Issues": "https://github.com/aljbri/tquota/issues",
"Repository": "https://github.com/aljbri/tquota/"
},
"split_keywords": [
"quota",
" cloud",
" timer",
" kaggle",
" colab",
" session",
" management",
" monitor"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "62bca598274d07599808ac79bf64599b598e0fc65f56d2ff470fa7bfb11e2fc3",
"md5": "091e8e00dac278fbe774d615fcbf6b4d",
"sha256": "a4de02b74ea8d49e07976cf35461897ebb24c1bb23d5d17c3d62da9278701584"
},
"downloads": -1,
"filename": "tquota-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "091e8e00dac278fbe774d615fcbf6b4d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=2.7",
"size": 8168,
"upload_time": "2024-10-16T15:56:13",
"upload_time_iso_8601": "2024-10-16T15:56:13.724957Z",
"url": "https://files.pythonhosted.org/packages/62/bc/a598274d07599808ac79bf64599b598e0fc65f56d2ff470fa7bfb11e2fc3/tquota-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0704dac529cce835c1bfa44e7739d6dc8d37ad5515a863d9a2e2d2771a0c3f5f",
"md5": "196865692ffef868fbcfe13ee3d724c7",
"sha256": "aef1ce05220898f51bd4507625d25d6ef7035224833ad9fa463aa885399cd1c9"
},
"downloads": -1,
"filename": "tquota-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "196865692ffef868fbcfe13ee3d724c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=2.7",
"size": 11315,
"upload_time": "2024-10-16T15:56:15",
"upload_time_iso_8601": "2024-10-16T15:56:15.617897Z",
"url": "https://files.pythonhosted.org/packages/07/04/dac529cce835c1bfa44e7739d6dc8d37ad5515a863d9a2e2d2771a0c3f5f/tquota-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-16 15:56:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aljbri",
"github_project": "tquota",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tquota"
}
JSON
