stdl 0.6.7__tar.gz → 0.6.8__tar.gz

{stdl-0.6.7 → stdl-0.6.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stdl
-Version: 0.6.7
+Version: 0.6.8
 Summary: Extended Python Standard Library
 Project-URL: Repository, https://github.com/zigai/stdl
 Project-URL: Issues, https://github.com/zigai/stdl/issues
@@ -28,7 +28,7 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
 License-File: LICENSE
-Keywords: ANSI colors,color formats,filesystem,lazy import,list utils,logging configuration,python lazy import,python utilities,standard library,stdl,string utils,terminal links,terminal output
+Keywords: ansi-colors,color-formats,filesystem,lazy-import,list-utils,python-utilities,standard-library,stdl,terminal-links,text-processing
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -41,6 +41,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: python-dateutil>=2.8.2

{stdl-0.6.7 → stdl-0.6.8}/mkdocs.yml

@@ -24,7 +24,6 @@ theme:
     - navigation.instant.prefetch
     - navigation.instant.preview
     - navigation.instant.progress
-    - search.highlight
     - search.share
     - search.highlight
     - search.suggest

{stdl-0.6.7 → stdl-0.6.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stdl"
-version = "0.6.7"
+version = "0.6.8"
 description = "Extended Python Standard Library"
 authors = [{ name = "Žiga Ivanšek", email = "ziga.ivansek@gmail.com" }]
 license = { file = "LICENSE" }
@@ -19,6 +19,9 @@ classifiers = [
     "Operating System :: OS Independent",
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+    "Topic :: System :: Filesystems",
+    "Topic :: Text Processing :: General",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
@@ -31,21 +34,17 @@ classifiers = [
 
 keywords = [
     "stdl",
-    "standard library",
-    "python utilities",
+    "standard-library",
+    "python-utilities",
     "filesystem",
-    "list utils",
-    "string utils",
-    "logging configuration",
-    "ANSI colors",
-    "color formats",
-    "terminal output",
-    "terminal links",
-    "lazy import",
-    "python lazy import",
+    "list-utils",
+    "ansi-colors",
+    "color-formats",
+    "terminal-links",
+    "lazy-import",
+    "text-processing",
 ]
 
-
 [project.optional-dependencies]
 full = ["tqdm>=4.67.1"]
 dev = [

{stdl-0.6.7 → stdl-0.6.8}/stdl/dt.py

@@ -233,6 +233,40 @@ def date_range(start: date, end: date) -> Generator[date, None, None]:
         yield start + timedelta(n)
 
 
+def datetime_range(
+    start: datetime,
+    end: datetime,
+    step: timedelta,
+) -> Generator[datetime, None, None]:
+    """
+    Returns a generator for datetimes between ``start`` and ``end`` with a given ``step``.
+
+    Example:
+        ```python
+        >>> for dt in datetime_range(
+        ...     datetime(2026, 1, 27, 0, 0),
+        ...     datetime(2026, 1, 27, 3, 0),
+        ...     timedelta(hours=1)
+        ... ):
+        ...     print(dt)
+        2026-01-27 00:00:00
+        2026-01-27 01:00:00
+        2026-01-27 02:00:00
+        ```
+    """
+    current = start
+    if step.total_seconds() == 0:
+        raise ValueError("step cannot be zero")
+    if step.total_seconds() > 0:
+        while current < end:
+            yield current
+            current += step
+    else:
+        while current > end:
+            yield current
+            current += step
+
+
 def sleep(lo: float, hi: float | None = None) -> float:
     """
     Sleeps for a random duration within a specified range.
@@ -346,6 +380,7 @@ __all__ = [
     "time_fmt",
     "date_fmt",
     "date_range",
+    "datetime_range",
     "sleep",
     "local_timezone",
     "timezone",

{stdl-0.6.7 → stdl-0.6.8}/stdl/fs.py

@@ -1059,6 +1059,7 @@ class File(PathBase):
 
     @property
     def exists(self) -> bool:
+        """Whether the file exists."""
         return os.path.isfile(self.path)
 
     @property
@@ -1409,6 +1410,7 @@ class Directory(PathBase):
 
     @property
     def size(self) -> int:
+        """Total size of the directory and all its contents in bytes."""
         return get_dir_size(self.path, readable=False)  # type:ignore
 
     @property
@@ -1423,6 +1425,7 @@ class Directory(PathBase):
 
     @property
     def parent(self) -> Directory:
+        """The parent directory."""
         return Directory(os.path.dirname(self.path))
 
     @classmethod

{stdl-0.6.7 → stdl-0.6.8}/stdl/log.py

@@ -130,6 +130,15 @@ def br(
     *,
     newline: bool = False,
 ) -> None:
+    """
+    Print a horizontal line break across the terminal.
+
+    Args:
+        c (str): Character to repeat. Defaults to "_".
+        length (int | None): Line length. Defaults to terminal width.
+        handler (Callable[[str], None]): Function to output the line. Defaults to print.
+        newline (bool): Whether to append a newline. Defaults to False.
+    """
     if IGNORE_BREAKS:
         return
     length = length or get_terminal_size().columns

{stdl-0.6.7 → stdl-0.6.8}/stdl/net.py

@@ -22,6 +22,14 @@ else:
 
 
 class DownloadSizeExceededError(Exception):
+    """
+    Exception raised when a file download exceeds the maximum allowed size.
+
+    Attributes:
+        filesize (int): The actual file size in bytes.
+        maxsize (int): The maximum allowed size in bytes.
+    """
+
     def __init__(self, filesize: int, maxsize: int):
         self.filesize = filesize
         self.maxsize = maxsize

stdl-0.6.8/tests/test_dt.py

@@ -0,0 +1,231 @@
+from datetime import date, datetime, timedelta
+from typing import Type
+
+import pytest
+
+from stdl.dt import date_fmt, datetime_fmt, datetime_range, hms_to_seconds, seconds_to_hms, time_fmt
+
+
+@pytest.mark.parametrize(
+    "time_input, ms, expected_output",
+    [
+        (123.456, False, "00:02:03"),
+        (123.456, True, "00:02:03.456"),
+        (123, False, "00:02:03"),
+        (123.0, True, "00:02:03.000"),
+        (-123.456, False, "-00:02:03"),
+        (-123.456, True, "-00:02:03.456"),
+        (-0.5, True, "-00:00:00.500"),
+        (0, False, "00:00:00"),
+        (0.0, True, "00:00:00.000"),
+        (3600, False, "01:00:00"),
+        (3661.5, True, "01:01:01.500"),
+        (90321.789, False, "25:05:21"),
+        (90321.789, True, "25:05:21.789"),
+    ],
+)
+def test_seconds_to_hms(time_input: float, ms: bool, expected_output: Type[Exception]):
+    assert seconds_to_hms(time_input, ms) == expected_output
+
+
+@pytest.mark.parametrize(
+    "time_input, ms, expected_output, expected_exception",
+    [
+        ("00:02:03", False, 123.0, None),
+        ("1:02:03", False, 3723.0, None),
+        ("2:3", False, 123.0, None),
+        ("0:0:0", False, 0.0, None),
+        ("123", False, 123.0, None),
+        ("-1:02:03", False, -3723.0, None),  # Negative time
+        ("00:02:03.456", True, 123.456, None),
+        ("00:02:03.4", True, 123.4, None),
+        ("00:02:03.45", True, 123.45, None),
+        ("00:02:03.045", True, 123.045, None),
+        ("23:59:59.999", True, 23 * 3600 + 59 * 60 + 59.999, None),
+        ("12:34.567", True, 12 * 60 + 34.567, None),  # Valid m:s.ms format
+        ("00:00:00", False, 0.0, None),
+        ("0:0", False, 0.0, None),
+        ("1:60", False, None, ValueError),  # Invalid seconds
+        ("1:02:60", False, None, ValueError),  # Invalid seconds
+        ("invalid_time", False, None, ValueError),
+        ("1:2:3:4", False, None, ValueError),  # Too many parts
+        ("12:34:56.789x", True, None, ValueError),  # Invalid characters in ms
+    ],
+)
+def test_hms_to_seconds(
+    time_input: str,
+    ms: bool,
+    expected_output: str,
+    expected_exception: Type[Exception],
+):
+    if expected_exception:
+        with pytest.raises(expected_exception):
+            x = hms_to_seconds(time_input, ms)
+            print(time_input, ms, x)
+    else:
+        result = hms_to_seconds(time_input, ms)
+        assert result == pytest.approx(expected_output, abs=1e-9)
+
+
+def test_documentation_examples():
+    assert seconds_to_hms(123.456) == "00:02:03"
+    assert seconds_to_hms(123.456, ms=True) == "00:02:03.456"
+    assert hms_to_seconds("00:02:03.456", ms=True) == pytest.approx(123.456)
+    assert hms_to_seconds("2:3", ms=True) == pytest.approx(123.0)
+    assert hms_to_seconds("-00:02:03", ms=False) == -123.0
+    assert hms_to_seconds("00:02:03", ms=False) == 123.0
+    assert hms_to_seconds("-1:02:03", ms=False) == pytest.approx(-3723.0)
+
+
+def test_millisecond_padding():
+    assert hms_to_seconds("00:00:00.1", ms=True) == pytest.approx(0.1)
+    assert hms_to_seconds("00:00:00.01", ms=True) == pytest.approx(0.01)
+    assert hms_to_seconds("00:00:00.001", ms=True) == pytest.approx(0.001)
+
+
+def test_negative_time_roundtrip():
+    original_seconds = -123.456
+    time_str = seconds_to_hms(original_seconds, ms=True)
+    parsed_seconds = hms_to_seconds(time_str, ms=True)
+    assert parsed_seconds == original_seconds
+
+
+def test_time_fmt():
+    assert time_fmt(0) == "00:00:00"
+    assert time_fmt(0, ms=True) == "00:00:00.000"
+    assert time_fmt(1, ms=True) == "00:00:01.000"
+
+
+def test_datetime_fmt():
+    assert datetime_fmt(0.0, utc=True) == "1970-01-01 00:00:00"
+    assert datetime_fmt(0) == "1970-01-01 00:00:00"
+    assert datetime_fmt(0, fmt="dmY") == "01-01-1970 00:00:00"
+    assert datetime_fmt(0, fmt="dmY", dsep="/") == "01/01/1970 00:00:00"
+    assert datetime_fmt(0, fmt="dmY", dsep="/", tsep=".") == "01/01/1970 00.00.00"
+
+
+def test_date_fmt():
+    assert date_fmt(date(1970, 1, 1)) == "1970-01-01"
+    assert date_fmt(0) == "1970-01-01"
+
+
+class TestDatetimeRange:
+    def test_basic_positive_step(self):
+        """Test datetime_range with positive step."""
+        start = datetime(2026, 1, 27, 0, 0)
+        end = datetime(2026, 1, 27, 3, 0)
+        step = timedelta(hours=1)
+        result = list(datetime_range(start, end, step))
+        expected = [
+            datetime(2026, 1, 27, 0, 0),
+            datetime(2026, 1, 27, 1, 0),
+            datetime(2026, 1, 27, 2, 0),
+        ]
+        assert result == expected
+
+    def test_basic_negative_step(self):
+        """Test datetime_range with negative step (going backwards)."""
+        start = datetime(2026, 1, 27, 3, 0)
+        end = datetime(2026, 1, 27, 0, 0)
+        step = timedelta(hours=-1)
+        result = list(datetime_range(start, end, step))
+        expected = [
+            datetime(2026, 1, 27, 3, 0),
+            datetime(2026, 1, 27, 2, 0),
+            datetime(2026, 1, 27, 1, 0),
+        ]
+        assert result == expected
+
+    def test_zero_step_raises(self):
+        """Test that zero step raises ValueError."""
+        start = datetime(2026, 1, 27, 0, 0)
+        end = datetime(2026, 1, 27, 3, 0)
+        step = timedelta(0)
+        with pytest.raises(ValueError, match="step cannot be zero"):
+            list(datetime_range(start, end, step))
+
+    def test_empty_range_positive_step(self):
+        """Test when start >= end with positive step."""
+        start = datetime(2026, 1, 27, 3, 0)
+        end = datetime(2026, 1, 27, 0, 0)
+        step = timedelta(hours=1)
+        result = list(datetime_range(start, end, step))
+        assert result == []
+
+    def test_empty_range_negative_step(self):
+        """Test when start <= end with negative step."""
+        start = datetime(2026, 1, 27, 0, 0)
+        end = datetime(2026, 1, 27, 3, 0)
+        step = timedelta(hours=-1)
+        result = list(datetime_range(start, end, step))
+        assert result == []
+
+    def test_minute_step(self):
+        """Test with minute-level precision."""
+        start = datetime(2026, 1, 27, 0, 0)
+        end = datetime(2026, 1, 27, 0, 5)
+        step = timedelta(minutes=1)
+        result = list(datetime_range(start, end, step))
+        expected = [
+            datetime(2026, 1, 27, 0, 0),
+            datetime(2026, 1, 27, 0, 1),
+            datetime(2026, 1, 27, 0, 2),
+            datetime(2026, 1, 27, 0, 3),
+            datetime(2026, 1, 27, 0, 4),
+        ]
+        assert result == expected
+
+    def test_second_step(self):
+        """Test with second-level precision."""
+        start = datetime(2026, 1, 27, 0, 0, 0)
+        end = datetime(2026, 1, 27, 0, 0, 3)
+        step = timedelta(seconds=1)
+        result = list(datetime_range(start, end, step))
+        expected = [
+            datetime(2026, 1, 27, 0, 0, 0),
+            datetime(2026, 1, 27, 0, 0, 1),
+            datetime(2026, 1, 27, 0, 0, 2),
+        ]
+        assert result == expected
+
+    def test_day_step(self):
+        """Test with day-level step across multiple days."""
+        start = datetime(2026, 1, 27)
+        end = datetime(2026, 1, 30)
+        step = timedelta(days=1)
+        result = list(datetime_range(start, end, step))
+        expected = [
+            datetime(2026, 1, 27),
+            datetime(2026, 1, 28),
+            datetime(2026, 1, 29),
+        ]
+        assert result == expected
+
+    def test_partial_step(self):
+        """Test when end is not exactly reachable by step."""
+        start = datetime(2026, 1, 27, 0, 0)
+        end = datetime(2026, 1, 27, 2, 30)
+        step = timedelta(hours=1)
+        result = list(datetime_range(start, end, step))
+        expected = [
+            datetime(2026, 1, 27, 0, 0),
+            datetime(2026, 1, 27, 1, 0),
+            datetime(2026, 1, 27, 2, 0),
+        ]
+        assert result == expected
+
+    def test_documentation_example(self):
+        """Test the exact example from the docstring."""
+        result = list(
+            datetime_range(
+                datetime(2026, 1, 27, 0, 0),
+                datetime(2026, 1, 27, 3, 0),
+                timedelta(hours=1),
+            )
+        )
+        expected = [
+            datetime(2026, 1, 27, 0, 0),
+            datetime(2026, 1, 27, 1, 0),
+            datetime(2026, 1, 27, 2, 0),
+        ]
+        assert result == expected

stdl-0.6.7/tests/test_dt.py

@@ -1,109 +0,0 @@
-from datetime import date
-from typing import Type
-
-import pytest
-
-from stdl.dt import date_fmt, datetime_fmt, hms_to_seconds, seconds_to_hms, time_fmt
-
-
-@pytest.mark.parametrize(
-    "time_input, ms, expected_output",
-    [
-        (123.456, False, "00:02:03"),
-        (123.456, True, "00:02:03.456"),
-        (123, False, "00:02:03"),
-        (123.0, True, "00:02:03.000"),
-        (-123.456, False, "-00:02:03"),
-        (-123.456, True, "-00:02:03.456"),
-        (-0.5, True, "-00:00:00.500"),
-        (0, False, "00:00:00"),
-        (0.0, True, "00:00:00.000"),
-        (3600, False, "01:00:00"),
-        (3661.5, True, "01:01:01.500"),
-        (90321.789, False, "25:05:21"),
-        (90321.789, True, "25:05:21.789"),
-    ],
-)
-def test_seconds_to_hms(time_input: float, ms: bool, expected_output: Type[Exception]):
-    assert seconds_to_hms(time_input, ms) == expected_output
-
-
-@pytest.mark.parametrize(
-    "time_input, ms, expected_output, expected_exception",
-    [
-        ("00:02:03", False, 123.0, None),
-        ("1:02:03", False, 3723.0, None),
-        ("2:3", False, 123.0, None),
-        ("0:0:0", False, 0.0, None),
-        ("123", False, 123.0, None),
-        ("-1:02:03", False, -3723.0, None),  # Negative time
-        ("00:02:03.456", True, 123.456, None),
-        ("00:02:03.4", True, 123.4, None),
-        ("00:02:03.45", True, 123.45, None),
-        ("00:02:03.045", True, 123.045, None),
-        ("23:59:59.999", True, 23 * 3600 + 59 * 60 + 59.999, None),
-        ("12:34.567", True, 12 * 60 + 34.567, None),  # Valid m:s.ms format
-        ("00:00:00", False, 0.0, None),
-        ("0:0", False, 0.0, None),
-        ("1:60", False, None, ValueError),  # Invalid seconds
-        ("1:02:60", False, None, ValueError),  # Invalid seconds
-        ("invalid_time", False, None, ValueError),
-        ("1:2:3:4", False, None, ValueError),  # Too many parts
-        ("12:34:56.789x", True, None, ValueError),  # Invalid characters in ms
-    ],
-)
-def test_hms_to_seconds(
-    time_input: str,
-    ms: bool,
-    expected_output: str,
-    expected_exception: Type[Exception],
-):
-    if expected_exception:
-        with pytest.raises(expected_exception):
-            x = hms_to_seconds(time_input, ms)
-            print(time_input, ms, x)
-    else:
-        result = hms_to_seconds(time_input, ms)
-        assert result == pytest.approx(expected_output, abs=1e-9)
-
-
-def test_documentation_examples():
-    assert seconds_to_hms(123.456) == "00:02:03"
-    assert seconds_to_hms(123.456, ms=True) == "00:02:03.456"
-    assert hms_to_seconds("00:02:03.456", ms=True) == pytest.approx(123.456)
-    assert hms_to_seconds("2:3", ms=True) == pytest.approx(123.0)
-    assert hms_to_seconds("-00:02:03", ms=False) == -123.0
-    assert hms_to_seconds("00:02:03", ms=False) == 123.0
-    assert hms_to_seconds("-1:02:03", ms=False) == pytest.approx(-3723.0)
-
-
-def test_millisecond_padding():
-    assert hms_to_seconds("00:00:00.1", ms=True) == pytest.approx(0.1)
-    assert hms_to_seconds("00:00:00.01", ms=True) == pytest.approx(0.01)
-    assert hms_to_seconds("00:00:00.001", ms=True) == pytest.approx(0.001)
-
-
-def test_negative_time_roundtrip():
-    original_seconds = -123.456
-    time_str = seconds_to_hms(original_seconds, ms=True)
-    parsed_seconds = hms_to_seconds(time_str, ms=True)
-    assert parsed_seconds == original_seconds
-
-
-def test_time_fmt():
-    assert time_fmt(0) == "00:00:00"
-    assert time_fmt(0, ms=True) == "00:00:00.000"
-    assert time_fmt(1, ms=True) == "00:00:01.000"
-
-
-def test_datetime_fmt():
-    assert datetime_fmt(0.0, utc=True) == "1970-01-01 00:00:00"
-    assert datetime_fmt(0) == "1970-01-01 00:00:00"
-    assert datetime_fmt(0, fmt="dmY") == "01-01-1970 00:00:00"
-    assert datetime_fmt(0, fmt="dmY", dsep="/") == "01/01/1970 00:00:00"
-    assert datetime_fmt(0, fmt="dmY", dsep="/", tsep=".") == "01/01/1970 00.00.00"
-
-
-def test_date_fmt():
-    assert date_fmt(date(1970, 1, 1)) == "1970-01-01"
-    assert date_fmt(0) == "1970-01-01"