hmscalc 0.1.0__tar.gz

hmscalc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 M0209
+
+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.

hmscalc-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.3
+Name: hmscalc
+Version: 0.1.0
+Summary: A Python library for performing arithmetic with HH:MM[:SS] formatted time strings.
+License: MIT
+Author: M0209
+Author-email: masanorimurakoshi0209@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Description-Content-Type: text/markdown
+
+# hmscalc
+
+A lightweight Python library for performing arithmetic on time values formatted as `HH:MM` or `HH:MM:SS`.
+
+## 🚀 Features
+
+- Supports time addition and subtraction
+- Accepts `HH:MM` and `HH:MM:SS` formatted strings
+- Handles negative durations gracefully
+- Converts time to seconds, minutes, hours, and dictionary/tuple formats
+- Fully testable across multiple Python versions via Docker
+
+## 🐳 Quick Start (Docker-based)
+
+```bash
+# Build the image
+docker build -t hmscalc .
+
+# Run tests across multiple Python versions
+docker run --rm hmscalc ./runtests.sh
+
+# Run lint
+docker run --rm hmscalc ./lint.sh
+```
+
+## 📦 Project Structure
+
+```
+hmscalc/
+├── Dockerfile         # Docker setup with pyenv and poetry
+├── runtests.sh        # Runs tests on multiple Python versions
+├── hmscalc/           # Source code
+│   └── hms_time.py
+├── tests/             # Pytest-based unit tests
+├── pyproject.toml     # Poetry config
+├── README.md          # This file
+└── LICENSE            # MIT license
+```
+
+## 📚 Usage (inside container)
+
+```python
+from hmscalc import HMSTime
+
+a = HMSTime("1:30:15")
+b = HMSTime("2:15:45")
+
+print(a + b)            # "3:46:00"
+print(a - b)            # "-0:45:30"
+print(a.to_seconds())   # 5415
+print(a.to_tuple())     # (1, 30, 15)
+print(a.to_dict())      # {'hh': 1, 'mm': 30, 'ss': 15}
+```
+
+## 🔍 Examples
+
+```python
+HMSTime("2:30") + HMSTime("1:45")     # "4:15:00"
+HMSTime("1:00:30") - HMSTime("0:30")  # "0:30:30"
+HMSTime("0:00") - HMSTime("0:01")     # "-0:01:00"
+```
+
+## 🧪 Running tests locally via Docker
+
+```bash
+# Build image
+docker build -t hmscalc .
+
+# Run matrix tests via pyenv + poetry
+docker run --rm hmscalc ./runtests.sh
+```
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).
+

hmscalc-0.1.0/README.md

@@ -0,0 +1,75 @@
+# hmscalc
+
+A lightweight Python library for performing arithmetic on time values formatted as `HH:MM` or `HH:MM:SS`.
+
+## 🚀 Features
+
+- Supports time addition and subtraction
+- Accepts `HH:MM` and `HH:MM:SS` formatted strings
+- Handles negative durations gracefully
+- Converts time to seconds, minutes, hours, and dictionary/tuple formats
+- Fully testable across multiple Python versions via Docker
+
+## 🐳 Quick Start (Docker-based)
+
+```bash
+# Build the image
+docker build -t hmscalc .
+
+# Run tests across multiple Python versions
+docker run --rm hmscalc ./runtests.sh
+
+# Run lint
+docker run --rm hmscalc ./lint.sh
+```
+
+## 📦 Project Structure
+
+```
+hmscalc/
+├── Dockerfile         # Docker setup with pyenv and poetry
+├── runtests.sh        # Runs tests on multiple Python versions
+├── hmscalc/           # Source code
+│   └── hms_time.py
+├── tests/             # Pytest-based unit tests
+├── pyproject.toml     # Poetry config
+├── README.md          # This file
+└── LICENSE            # MIT license
+```
+
+## 📚 Usage (inside container)
+
+```python
+from hmscalc import HMSTime
+
+a = HMSTime("1:30:15")
+b = HMSTime("2:15:45")
+
+print(a + b)            # "3:46:00"
+print(a - b)            # "-0:45:30"
+print(a.to_seconds())   # 5415
+print(a.to_tuple())     # (1, 30, 15)
+print(a.to_dict())      # {'hh': 1, 'mm': 30, 'ss': 15}
+```
+
+## 🔍 Examples
+
+```python
+HMSTime("2:30") + HMSTime("1:45")     # "4:15:00"
+HMSTime("1:00:30") - HMSTime("0:30")  # "0:30:30"
+HMSTime("0:00") - HMSTime("0:01")     # "-0:01:00"
+```
+
+## 🧪 Running tests locally via Docker
+
+```bash
+# Build image
+docker build -t hmscalc .
+
+# Run matrix tests via pyenv + poetry
+docker run --rm hmscalc ./runtests.sh
+```
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

hmscalc-0.1.0/hmscalc/__init__.py

@@ -0,0 +1 @@
+"""hmscalc: A package for HMS (hours, minutes, seconds) calculations."""

hmscalc-0.1.0/hmscalc/exceptions.py

@@ -0,0 +1,23 @@
+"""Custom exception classes for HMS time calculations."""
+
+
+class HMSTimeError(Exception):
+    """Base exception for HMS time errors."""
+
+    pass
+
+
+class InvalidTimeFormatError(HMSTimeError):
+    """Exception raised for invalid time format strings."""
+
+    def __init__(self, time_str: str):
+        """Initialize with the invalid time string."""
+        super().__init__(f"Invalid time format: '{time_str}'")
+
+
+class NotTimeStringError(HMSTimeError):
+    """Exception raised when a non-string is provided as a time input."""
+
+    def __init__(self, value):  # type: ignore[no-untyped-def]
+        """Initialize with the invalid value type."""
+        super().__init__(f"Time input must be a string, got: {type(value).__name__}")

hmscalc-0.1.0/hmscalc/hms_time.py

@@ -0,0 +1,174 @@
+"""Module for handling time in hours, minutes, and seconds (HMS) format."""
+
+import re
+
+from .exceptions import InvalidTimeFormatError, NotTimeStringError
+
+
+class HMSTime:
+    """Class to represent and manipulate time in hours, minutes, and seconds (HMS) format.
+
+    Args:
+    ----
+        time_str (str): Time string to parse.
+
+    """
+
+    def __init__(self, time_str: str):
+        """Initialize HMSTime from a time string in 'HH:MM:SS' or 'HH:MM' format.
+
+        Args:
+        ----
+            time_str (str): Time string to parse.
+
+        """
+        self.total_seconds = self._parse_time_string(time_str)
+
+    def __add__(self, other: "HMSTime") -> "HMSTime":
+        """Add two HMSTime objects and return a new HMSTime object.
+
+        Args:
+        ----
+            other (HMSTime): The other HMSTime object to add.
+
+        Returns:
+        -------
+            HMSTime: The sum of the two times.
+
+        """
+        return HMSTime.from_seconds(self.total_seconds + other.total_seconds)
+
+    def __sub__(self, other: "HMSTime") -> "HMSTime":
+        """Subtract another HMSTime object from this one and return a new HMSTime object.
+
+        Args:
+        ----
+            other (HMSTime): The other HMSTime object to subtract.
+
+        Returns:
+        -------
+            HMSTime: The difference of the two times.
+
+        """
+        return HMSTime.from_seconds(self.total_seconds - other.total_seconds)
+
+    def __str__(self) -> str:
+        """Return the string representation of the HMSTime object in 'HH:MM:SS' format.
+
+        Returns
+        -------
+            str: The string representation of the HMSTime object.
+
+        """
+        total = abs(self.total_seconds)
+        hh = total // 3600
+        mm = (total % 3600) // 60
+        ss = total % 60
+        sign = "-" if self.total_seconds < 0 else ""
+        return f"{sign}{hh}:{mm:02}:{ss:02}"
+
+    def __repr__(self) -> str:
+        """Return the official string representation of the HMSTime object."""
+        return f"HMSTime('{self}')"
+
+    def __eq__(self, other: object) -> bool:
+        """Check if two HMSTime objects are equal."""
+        if not isinstance(other, HMSTime):
+            return NotImplemented
+        return self.total_seconds == other.total_seconds
+
+    def __lt__(self, other: "HMSTime") -> bool:
+        """Check if this HMSTime object is less than another."""
+        return self.total_seconds < other.total_seconds
+
+    def __le__(self, other: "HMSTime") -> bool:
+        """Check if this HMSTime object is less than or equal to another."""
+        return self.total_seconds <= other.total_seconds
+
+    def __gt__(self, other: "HMSTime") -> bool:
+        """Check if this HMSTime object is greater than another."""
+        return self.total_seconds > other.total_seconds
+
+    def __ge__(self, other: "HMSTime") -> bool:
+        """Check if this HMSTime object is greater than or equal to another."""
+        return self.total_seconds >= other.total_seconds
+
+    def __ne__(self, other: object) -> bool:
+        """Check if two HMSTime objects are not equal."""
+        if not isinstance(other, HMSTime):
+            return NotImplemented
+        return self.total_seconds != other.total_seconds
+
+    @classmethod
+    def from_seconds(cls, total_seconds: int) -> "HMSTime":
+        """Create an HMSTime object from a total number of seconds.
+
+        Args:
+        ----
+            total_seconds (int): The total number of seconds.
+
+        Returns:
+        -------
+            HMSTime: The corresponding HMSTime object.
+
+        """
+        instance = cls.__new__(cls)
+        instance.total_seconds = total_seconds
+        return instance
+
+    @staticmethod
+    def _parse_time_string(time_str: str) -> int:
+        """Parse a time string and return the total number of seconds.
+
+        Args:
+        ----
+            time_str (str): Time string to parse.
+
+        Returns:
+        -------
+            int: Total number of seconds represented by the string.
+
+        Raises:
+        ------
+            NotTimeStringError: If input is not a string.
+            InvalidTimeFormatError: If the string format is invalid.
+
+        """
+        if not isinstance(time_str, str):
+            raise NotTimeStringError(time_str)
+
+        match = re.fullmatch(r"(-)?(\d+):(\d{1,2})(?::(\d{1,2}))?", time_str)
+        if not match:
+            raise InvalidTimeFormatError(time_str)
+        neg, hh, mm, ss = match.groups()
+        hh = int(hh)
+        mm = int(mm)
+        ss = int(ss) if ss is not None else 0
+
+        total = hh * 3600 + mm * 60 + ss
+        return -total if neg else total
+
+    def to_seconds(self) -> int:
+        """Return the total number of seconds represented by this HMSTime object."""
+        return self.total_seconds
+
+    def to_minutes(self) -> float:
+        """Return the total number of minutes represented by this HMSTime object."""
+        return self.total_seconds / 60
+
+    def to_hours(self) -> float:
+        """Return the total number of hours represented by this HMSTime object."""
+        return self.total_seconds / 3600
+
+    def to_tuple(self) -> tuple[int, int, int]:
+        """Return the time as a tuple of (hours, minutes, seconds)."""
+        total = abs(self.total_seconds)
+        hh = total // 3600
+        mm = (total % 3600) // 60
+        ss = total % 60
+        return (hh, mm, ss)
+
+    def to_dict(self) -> dict[str, int]:
+        """Return the time as a dictionary with keys 'hh', 'mm', and 'ss'."""
+        hh, mm, ss = self.to_tuple()
+        return {"hh": hh, "mm": mm, "ss": ss}

hmscalc-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[tool.poetry]
+name = "hmscalc"
+version = "0.1.0"
+description = "A Python library for performing arithmetic with HH:MM[:SS] formatted time strings."
+authors = ["M0209 <masanorimurakoshi0209@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "hmscalc" }]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+black = "^24.0.0"
+isort = "^5.12.0"
+mypy = "^1.9.0"
+ruff = "^0.4.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["D211", "D212", "E", "F", "I", "N", "B", "D"]
+ignore = ["D203", "D213"]
+
+[tool.black]
+line-length = 88
+target-version = ['py311']
+
+[tool.isort]
+profile = "black"
+
+[tool.mypy]
+python_version = 3.11
+strict = true
+disallow_untyped_defs = true
+ignore_missing_imports = true