tquota 0.0.3

A lightweight processing timer module for quota-based cloud environments.

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 and Google Colab. 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:

  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:

  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:

  remaining = qt.remaining_time()
  print(f'Remaining time: {remaining}')
  

---

Installation

You can install the package from PyPI using the following command:

pip install tquota

Alternatively, you can clone the repository and install the package directly:

git clone https://github.com/aljbri/tquota.git
cd tquota
pip install .

---

Usage

Import the Quota class as follows:

from tquota import Quota

Example Usage

• Using the time_up function:

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:

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 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 [e-mail].