pymillis 1.0.0__tar.gz

pymillis-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT WuChenDi<https://github.com/WuChenDi>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pymillis-1.0.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: pymillis
+Version: 1.0.0
+Summary: Use this package to easily convert various time formats to milliseconds.
+Keywords: time,milliseconds,ms,duration,conversion
+Author-email: wudi <wuchendi96@gmail.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+License-File: LICENSE
+Project-URL: Bug Reports, https://github.com/WuChenDi/pymillis/issues
+Project-URL: Source, https://github.com/WuChenDi/pymillis
+
+# pymillis
+
+Use this package to easily convert various time formats to milliseconds.
+
+## Installation
+
+```bash
+pip install pymillis
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from pymillis import ms
+
+# Parse time strings to milliseconds
+ms('2 days')          # 172800000
+ms('1d')              # 86400000
+ms('10h')             # 36000000
+ms('2.5 hrs')         # 9000000
+ms('2h')              # 7200000
+ms('1m')              # 60000
+ms('5s')              # 5000
+ms('1y')              # 31557600000
+ms('100')             # 100
+ms('-3 days')         # -259200000
+ms('-1h')             # -3600000
+ms('-200')            # -200
+
+# Format milliseconds to strings
+ms(60000)             # '1m'
+ms(2 * 60000)         # '2m'
+ms(-3 * 60000)        # '-3m'
+ms(172800000)         # '2d'
+
+# Use long format
+ms(60000, long=True)           # '1 minute'
+ms(2 * 60000, long=True)       # '2 minutes'
+ms(172800000, long=True)       # '2 days'
+ms(ms('10 hours'), long=True)  # '10 hours'
+```
+
+### API
+
+#### `ms(value, *, long=False)`
+
+Parse or format the given value.
+
+**Parameters:**
+- `value` (str | int | float): The string or number to convert
+- `long` (bool, optional): Set to `True` to use verbose formatting. Defaults to `False`.
+
+**Returns:**
+- If `value` is a string, returns milliseconds as `float`
+- If `value` is a number, returns formatted string as `str`
+
+**Raises:**
+- `MSError`: If value is not a non-empty string or a number
+
+#### `parse(value)`
+
+Parse the given string and return milliseconds.
+
+**Parameters:**
+- `value` (str): A string to parse to milliseconds
+
+**Returns:**
+- `float`: The parsed value in milliseconds
+
+**Raises:**
+- `MSError`: If the string is invalid or cannot be parsed
+
+#### `format(ms_value, *, long=False)`
+
+Format the given milliseconds as a string.
+
+**Parameters:**
+- `ms_value` (int | float): Milliseconds to format
+- `long` (bool, optional): Use verbose formatting if `True`
+
+**Returns:**
+- `str`: The formatted string
+
+**Raises:**
+- `MSError`: If ms_value is not a finite number
+
+### Import Options
+
+```python
+# Import main function
+from pymillis import ms
+
+# Import specific functions
+from pymillis import parse, format, parse_strict
+
+# Import exception
+from pymillis import MSError
+
+# Import everything
+from pymillis import ms, parse, format, MSError
+```
+
+## Supported Time Units
+
+### Short Format
+
+- `ms`, `msec`, `msecs`, `millisecond`, `milliseconds` - Milliseconds
+- `s`, `sec`, `secs`, `second`, `seconds` - Seconds
+- `m`, `min`, `mins`, `minute`, `minutes` - Minutes
+- `h`, `hr`, `hrs`, `hour`, `hours` - Hours
+- `d`, `day`, `days` - Days
+- `w`, `week`, `weeks` - Weeks
+- `mo`, `month`, `months` - Months (calculated as 1/12 of a year)
+- `y`, `yr`, `yrs`, `year`, `years` - Years (calculated as 365.25 days)
+
+### Case Insensitive
+
+All units are case-insensitive, so `1D`, `1d`, `1 Day`, `1 DAY` are all equivalent.
+
+## Features
+
+- 🚀 Simple and intuitive API
+- 📦 Zero dependencies
+- 🔄 Bidirectional conversion (string ↔ milliseconds)
+- ⏱️ Supports negative time values
+- 📝 Long and short format options
+- 🎯 Type hints for better IDE support
+- ✅ Comprehensive error handling
+
+## Common Use Cases
+
+### Setting Timeouts
+
+```python
+import time
+from pymillis import ms
+
+# Convert to seconds for time.sleep()
+timeout = ms('5s') / 1000
+time.sleep(timeout)
+```
+
+### Caching
+
+```python
+import time
+from pymillis import ms
+
+# Set cache expiration
+cache_duration = ms('1h')
+expires_at = time.time() * 1000 + cache_duration
+```
+
+### Rate Limiting
+
+```python
+from pymillis import ms
+
+# Define rate limit window
+rate_limit_window = ms('1m')
+max_requests = 100
+```
+
+### Calculating Durations
+
+```python
+from pymillis import ms
+
+# Calculate time differences
+meeting_duration = ms('2h') - ms('30m')  # 5400000.0 ms (1.5 hours)
+```
+
+## Error Handling
+
+The library raises `MSError` for invalid inputs:
+
+```python
+from pymillis import ms, MSError
+
+# Invalid format
+try:
+    ms('invalid')
+except MSError as e:
+    print(f"Error: {e}")
+
+# Non-finite number
+try:
+    ms(float('nan'))
+except MSError as e:
+    print(f"Error: {e}")
+
+# Empty string
+try:
+    ms('')
+except MSError as e:
+    print(f"Error: {e}")
+
+# String too long (>100 characters)
+try:
+    ms('a' * 101)
+except MSError as e:
+    print(f"Error: {e}")
+```
+
+## Notes
+
+### Precision
+
+- Results are returned as `float` for precision
+- **Month calculation**: 1 month = 1/12 year ≈ 30.44 days (average value)
+- **Year calculation**: 1 year = 365.25 days (accounting for leap years)
+
+### Rounding
+
+When formatting, values are rounded to the nearest integer for the selected unit:
+
+```python
+ms(1500)              # '2s'  (rounded from 1.5s)
+ms(90000)             # '2m'  (rounded from 1.5m)
+```
+
+## 📜 License
+
+[MIT](./LICENSE) License &copy; 2025-PRESENT [wudi](https://github.com/WuChenDi)
+

pymillis-1.0.0/README.md

@@ -0,0 +1,226 @@
+# pymillis
+
+Use this package to easily convert various time formats to milliseconds.
+
+## Installation
+
+```bash
+pip install pymillis
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from pymillis import ms
+
+# Parse time strings to milliseconds
+ms('2 days')          # 172800000
+ms('1d')              # 86400000
+ms('10h')             # 36000000
+ms('2.5 hrs')         # 9000000
+ms('2h')              # 7200000
+ms('1m')              # 60000
+ms('5s')              # 5000
+ms('1y')              # 31557600000
+ms('100')             # 100
+ms('-3 days')         # -259200000
+ms('-1h')             # -3600000
+ms('-200')            # -200
+
+# Format milliseconds to strings
+ms(60000)             # '1m'
+ms(2 * 60000)         # '2m'
+ms(-3 * 60000)        # '-3m'
+ms(172800000)         # '2d'
+
+# Use long format
+ms(60000, long=True)           # '1 minute'
+ms(2 * 60000, long=True)       # '2 minutes'
+ms(172800000, long=True)       # '2 days'
+ms(ms('10 hours'), long=True)  # '10 hours'
+```
+
+### API
+
+#### `ms(value, *, long=False)`
+
+Parse or format the given value.
+
+**Parameters:**
+- `value` (str | int | float): The string or number to convert
+- `long` (bool, optional): Set to `True` to use verbose formatting. Defaults to `False`.
+
+**Returns:**
+- If `value` is a string, returns milliseconds as `float`
+- If `value` is a number, returns formatted string as `str`
+
+**Raises:**
+- `MSError`: If value is not a non-empty string or a number
+
+#### `parse(value)`
+
+Parse the given string and return milliseconds.
+
+**Parameters:**
+- `value` (str): A string to parse to milliseconds
+
+**Returns:**
+- `float`: The parsed value in milliseconds
+
+**Raises:**
+- `MSError`: If the string is invalid or cannot be parsed
+
+#### `format(ms_value, *, long=False)`
+
+Format the given milliseconds as a string.
+
+**Parameters:**
+- `ms_value` (int | float): Milliseconds to format
+- `long` (bool, optional): Use verbose formatting if `True`
+
+**Returns:**
+- `str`: The formatted string
+
+**Raises:**
+- `MSError`: If ms_value is not a finite number
+
+### Import Options
+
+```python
+# Import main function
+from pymillis import ms
+
+# Import specific functions
+from pymillis import parse, format, parse_strict
+
+# Import exception
+from pymillis import MSError
+
+# Import everything
+from pymillis import ms, parse, format, MSError
+```
+
+## Supported Time Units
+
+### Short Format
+
+- `ms`, `msec`, `msecs`, `millisecond`, `milliseconds` - Milliseconds
+- `s`, `sec`, `secs`, `second`, `seconds` - Seconds
+- `m`, `min`, `mins`, `minute`, `minutes` - Minutes
+- `h`, `hr`, `hrs`, `hour`, `hours` - Hours
+- `d`, `day`, `days` - Days
+- `w`, `week`, `weeks` - Weeks
+- `mo`, `month`, `months` - Months (calculated as 1/12 of a year)
+- `y`, `yr`, `yrs`, `year`, `years` - Years (calculated as 365.25 days)
+
+### Case Insensitive
+
+All units are case-insensitive, so `1D`, `1d`, `1 Day`, `1 DAY` are all equivalent.
+
+## Features
+
+- 🚀 Simple and intuitive API
+- 📦 Zero dependencies
+- 🔄 Bidirectional conversion (string ↔ milliseconds)
+- ⏱️ Supports negative time values
+- 📝 Long and short format options
+- 🎯 Type hints for better IDE support
+- ✅ Comprehensive error handling
+
+## Common Use Cases
+
+### Setting Timeouts
+
+```python
+import time
+from pymillis import ms
+
+# Convert to seconds for time.sleep()
+timeout = ms('5s') / 1000
+time.sleep(timeout)
+```
+
+### Caching
+
+```python
+import time
+from pymillis import ms
+
+# Set cache expiration
+cache_duration = ms('1h')
+expires_at = time.time() * 1000 + cache_duration
+```
+
+### Rate Limiting
+
+```python
+from pymillis import ms
+
+# Define rate limit window
+rate_limit_window = ms('1m')
+max_requests = 100
+```
+
+### Calculating Durations
+
+```python
+from pymillis import ms
+
+# Calculate time differences
+meeting_duration = ms('2h') - ms('30m')  # 5400000.0 ms (1.5 hours)
+```
+
+## Error Handling
+
+The library raises `MSError` for invalid inputs:
+
+```python
+from pymillis import ms, MSError
+
+# Invalid format
+try:
+    ms('invalid')
+except MSError as e:
+    print(f"Error: {e}")
+
+# Non-finite number
+try:
+    ms(float('nan'))
+except MSError as e:
+    print(f"Error: {e}")
+
+# Empty string
+try:
+    ms('')
+except MSError as e:
+    print(f"Error: {e}")
+
+# String too long (>100 characters)
+try:
+    ms('a' * 101)
+except MSError as e:
+    print(f"Error: {e}")
+```
+
+## Notes
+
+### Precision
+
+- Results are returned as `float` for precision
+- **Month calculation**: 1 month = 1/12 year ≈ 30.44 days (average value)
+- **Year calculation**: 1 year = 365.25 days (accounting for leap years)
+
+### Rounding
+
+When formatting, values are rounded to the nearest integer for the selected unit:
+
+```python
+ms(1500)              # '2s'  (rounded from 1.5s)
+ms(90000)             # '2m'  (rounded from 1.5m)
+```
+
+## 📜 License
+
+[MIT](./LICENSE) License © 2025-PRESENT [wudi](https://github.com/WuChenDi)

pymillis-1.0.0/pymillis/__init__.py

@@ -0,0 +1,20 @@
+"""
+pymillis - Milliseconds conversion utility
+
+A Python port of the popular JavaScript ms library.
+Convert between milliseconds and human-readable time strings.
+
+Usage:
+    >>> from pymillis import ms
+    >>> ms('2 days')
+    172800000
+    >>> ms(172800000)
+    '2d'
+    >>> ms(172800000, long=True)
+    '2 days'
+"""
+
+from .ms import ms, parse, parse_strict, format, MSError
+from ._version import __version__
+
+__all__ = ['ms', 'parse', 'parse_strict', 'format', 'MSError', '__version__']

pymillis-1.0.0/pymillis/_version.py

@@ -0,0 +1,3 @@
+"""Version information for pymillis package."""
+
+__version__ = '1.0.0'

pymillis-1.0.0/pymillis/ms.py

@@ -0,0 +1,223 @@
+"""
+pymillis.ms - Core milliseconds conversion functionality
+"""
+
+import re
+import math
+from typing import Union
+
+__all__ = ['ms', 'parse', 'parse_strict', 'format', 'MSError']
+
+# Time constants in milliseconds
+S = 1000
+M = S * 60
+H = M * 60
+D = H * 24
+W = D * 7
+Y = D * 365.25
+MO = Y / 12
+
+
+class MSError(Exception):
+    """Base exception for ms library errors."""
+    pass
+
+
+def ms(value: Union[str, int, float], *, long: bool = False) -> Union[float, str]:
+    """
+    Parse or format the given value.
+    
+    Args:
+        value: The string or number to convert
+        long: Set to True to use verbose formatting. Defaults to False.
+        
+    Returns:
+        If value is a string, returns milliseconds as number (float).
+        If value is a number, returns formatted string.
+        
+    Raises:
+        MSError: If value is not a non-empty string or a number
+        
+    Examples:
+        >>> ms('2 days')
+        172800000.0
+        >>> ms(172800000)
+        '2d'
+        >>> ms(172800000, long=True)
+        '2 days'
+    """
+    if isinstance(value, str):
+        return parse(value)
+    elif isinstance(value, (int, float)):
+        return format(value, long=long)
+    else:
+        raise MSError(
+            f"Value provided to ms() must be a string or number. value={repr(value)}"
+        )
+
+
+def parse(value: str) -> float:
+    """
+    Parse the given string and return milliseconds.
+    
+    Args:
+        value: A string to parse to milliseconds
+        
+    Returns:
+        The parsed value in milliseconds, or raises MSError if invalid
+        
+    Raises:
+        MSError: If the string is invalid or cannot be parsed
+        
+    Examples:
+        >>> parse('2d')
+        172800000.0
+        >>> parse('1.5 hours')
+        5400000.0
+        >>> parse('1y')
+        31557600000.0
+    """
+    if not isinstance(value, str):
+        raise MSError(
+            f"Value provided to ms.parse() must be a string. value={repr(value)}"
+        )
+    
+    if len(value) == 0 or len(value) > 100:
+        raise MSError(
+            f"Value provided to ms.parse() must be a string with length between 1 and 99. value={repr(value)}"
+        )
+    
+    pattern = r'^(?P<value>-?\d*\.?\d+)\s*(?P<unit>milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|months?|mo|years?|yrs?|y)?$'
+    match = re.match(pattern, value, re.IGNORECASE)
+    
+    if not match:
+        raise MSError(f"Invalid time string format. value={repr(value)}")
+    
+    groups = match.groupdict()
+    num_value = float(groups['value'])
+    unit = (groups['unit'] or 'ms').lower()
+    
+    # Years
+    if unit in ('years', 'year', 'yrs', 'yr', 'y'):
+        return num_value * Y
+    # Months
+    elif unit in ('months', 'month', 'mo'):
+        return num_value * MO
+    # Weeks
+    elif unit in ('weeks', 'week', 'w'):
+        return num_value * W
+    # Days
+    elif unit in ('days', 'day', 'd'):
+        return num_value * D
+    # Hours
+    elif unit in ('hours', 'hour', 'hrs', 'hr', 'h'):
+        return num_value * H
+    # Minutes
+    elif unit in ('minutes', 'minute', 'mins', 'min', 'm'):
+        return num_value * M
+    # Seconds
+    elif unit in ('seconds', 'second', 'secs', 'sec', 's'):
+        return num_value * S
+    # Milliseconds
+    elif unit in ('milliseconds', 'millisecond', 'msecs', 'msec', 'ms'):
+        return num_value
+    else:
+        raise MSError(
+            f'Unknown unit "{unit}" provided to ms.parse(). value={repr(value)}'
+        )
+
+
+def parse_strict(value: str) -> float:
+    """
+    Parse the given string and return milliseconds (strict version).
+    
+    This is an alias for parse() provided for API compatibility.
+    
+    Args:
+        value: A string to parse to milliseconds
+        
+    Returns:
+        The parsed value in milliseconds
+    """
+    return parse(value)
+
+
+def format(ms_value: Union[int, float], *, long: bool = False) -> str:
+    """
+    Format the given milliseconds as a string.
+    
+    Args:
+        ms_value: Milliseconds to format
+        long: Use verbose formatting if True
+        
+    Returns:
+        The formatted string
+        
+    Raises:
+        MSError: If ms_value is not a finite number
+        
+    Examples:
+        >>> format(172800000)
+        '2d'
+        >>> format(172800000, long=True)
+        '2 days'
+        >>> format(3600000)
+        '1h'
+    """
+    if not isinstance(ms_value, (int, float)):
+        raise MSError('Value provided to ms.format() must be of type number.')
+    
+    # Check if the number is finite (not NaN, not Infinity)
+    if not math.isfinite(ms_value):
+        raise MSError('Value provided to ms.format() must be of type number.')
+    
+    return _fmt_long(ms_value) if long else _fmt_short(ms_value)
+
+
+def _fmt_short(ms_value: Union[int, float]) -> str:
+    """Short format for ms."""
+    ms_abs = abs(ms_value)
+    
+    if ms_abs >= Y:
+        return f"{round(ms_value / Y)}y"
+    if ms_abs >= MO:
+        return f"{round(ms_value / MO)}mo"
+    if ms_abs >= W:
+        return f"{round(ms_value / W)}w"
+    if ms_abs >= D:
+        return f"{round(ms_value / D)}d"
+    if ms_abs >= H:
+        return f"{round(ms_value / H)}h"
+    if ms_abs >= M:
+        return f"{round(ms_value / M)}m"
+    if ms_abs >= S:
+        return f"{round(ms_value / S)}s"
+    return f"{int(ms_value)}ms"
+
+
+def _fmt_long(ms_value: Union[int, float]) -> str:
+    """Long format for ms."""
+    ms_abs = abs(ms_value)
+    
+    if ms_abs >= Y:
+        return _plural(ms_value, ms_abs, Y, 'year')
+    if ms_abs >= MO:
+        return _plural(ms_value, ms_abs, MO, 'month')
+    if ms_abs >= W:
+        return _plural(ms_value, ms_abs, W, 'week')
+    if ms_abs >= D:
+        return _plural(ms_value, ms_abs, D, 'day')
+    if ms_abs >= H:
+        return _plural(ms_value, ms_abs, H, 'hour')
+    if ms_abs >= M:
+        return _plural(ms_value, ms_abs, M, 'minute')
+    if ms_abs >= S:
+        return _plural(ms_value, ms_abs, S, 'second')
+    return f"{int(ms_value)} ms"
+
+
+def _plural(ms_value: Union[int, float], ms_abs: float, n: float, name: str) -> str:
+    """Pluralization helper."""
+    is_plural = ms_abs >= n * 1.5
+    rounded = round(ms_value / n)
+    return f"{rounded} {name}{'s' if is_plural else ''}"

pymillis-1.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["flit_core >=3.11,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "pymillis"
+authors = [{name = "wudi", email = "wuchendi96@gmail.com"}]
+description = "Use this package to easily convert various time formats to milliseconds."
+readme = "README.md"
+dynamic = ["version"]
+license = {text = "MIT"}
+requires-python = ">=3.9"
+keywords = ["time", "milliseconds", "ms", "duration", "conversion"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+"Bug Reports" = "https://github.com/WuChenDi/pymillis/issues"
+"Source" = "https://github.com/WuChenDi/pymillis"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.black]
+line-length = 100
+target-version = ['py39', 'py310', 'py311', 'py312', 'py313']
+include = '\.pyi?$'
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false