sltcodec 2.6.1__tar.gz → 2.7.0__tar.gz

{sltcodec-2.6.1 → sltcodec-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sltcodec
-Version: 2.6.1
+Version: 2.7.0
 Summary: Decode and encode bytearrays according to struct layout definitions using sltcore.
 Project-URL: Homepage, https://github.com/fangface-hub/StructLayoutToolkitCodec
 Project-URL: Documentation, https://readthedocs.org

{sltcodec-2.6.1 → sltcodec-2.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sltcodec"
-version = "2.6.1"
+version = "2.7.0"
 description = "Decode and encode bytearrays according to struct layout definitions using sltcore."
 readme = "README_pypi.md"
 requires-python = ">=3.12"

{sltcodec-2.6.1 → sltcodec-2.7.0}/src/sltcodec/codec.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import json
 import re
+import time
 from pathlib import Path
 from typing import Any, Callable
 
@@ -29,16 +30,34 @@ _DEFAULT_PADDING_ALIGNMENT_BITS = 32
 
 ProgressCallback = Callable[[float], None]
 
-
-def _notify_progress(progress_callback: ProgressCallback | None,
-                     offset: InfoSize, size: InfoSize, total_bits: int) -> None:
-    """Notify caller of top-level encode/decode progress."""
-    if progress_callback is None or total_bits <= 0:
-        return
-    progress = min((offset + size).bits / total_bits, 1.0)
-    progress_callback(progress)
-
-
+_PROGRESS_MIN_INTERVAL_SEC = 0.1
+_PROGRESS_MIN_DELTA = 0.01
+
+
+def _notify_progress(progress_callback: ProgressCallback | None,
+                     progress_state: dict[str, float],
+                     offset: InfoSize, size: InfoSize, total_bits: int) -> None:
+    """Notify caller of top-level encode/decode progress.
+
+    Calls are throttled: the callback fires on the first call, at most once
+    per 100 ms, or when progress changed by more than 0.01 since the last
+    notification. Completion (1.0) is always notified. ``progress_state`` is a
+    per-run dict holding the last notification time and progress.
+    """
+    if progress_callback is None or total_bits <= 0:
+        return
+    progress = min((offset + size).bits / total_bits, 1.0)
+    now = time.monotonic()
+    last_time = progress_state.get("time")
+    if (last_time is not None and progress < 1.0
+            and now - last_time < _PROGRESS_MIN_INTERVAL_SEC
+            and abs(progress - progress_state["progress"]) <=
+            _PROGRESS_MIN_DELTA):
+        return
+    progress_state["time"] = now
+    progress_state["progress"] = progress
+    progress_callback(progress)
+
 def _estimate_encode_total_bits(struct_instance: StructInstance,
                                 initial_size_bits: int,
                                 env: dict[str, Any] | None = None) -> int:
@@ -410,6 +429,7 @@ def encode(
         raise ValueError("StructLayout.type_dict is required for encode()")
 
     type_dict = struct_layout.type_dict
+    progress_state: dict[str, float] = {}
     env = env if env is not None else {}
     has_padding = False
     total_bits = _estimate_encode_total_bits(struct_instance, len(buf) * 8, env)
@@ -438,7 +458,7 @@ def encode(
                 resolved_size = _resolve_info_size(field_def_repeat.size, env)
                 encode_field(field_def_repeat, values[i], buf, env, type_dict,
                              padding_alignment_bits)
-                _notify_progress(progress_callback, current_offset,
+                _notify_progress(progress_callback, progress_state, current_offset,
                                  resolved_size, total_bits)
                 env[field_def_repeat.name] = values[i]
                 if isinstance(current_offset, InfoSize):
@@ -449,7 +469,7 @@ def encode(
         resolved_size = _resolve_info_size(field_def.size, env)
         encode_field(field_def, value, buf, env, type_dict,
                      padding_alignment_bits)
-        _notify_progress(progress_callback, resolved_offset, resolved_size,
+        _notify_progress(progress_callback, progress_state, resolved_offset, resolved_size,
                          total_bits)
         env[field_def.name] = value
 
@@ -608,9 +628,10 @@ def decode(
     if struct_layout.type_dict is None:
         raise ValueError("StructLayout.type_dict is required for decode()")
 
+    progress_state: dict[str, float] = {}
     env = env if env is not None else {}
     type_dict = struct_layout.type_dict
-    struct_def_obj = type_dict.struct_dict[struct_layout.struct_def_name]
+    struct_def_obj =  type_dict.struct_dict[struct_layout.struct_def_name]
     result = StructInstance(struct_def=struct_def_obj)
     current_position = InfoSize(0, 0)
     padding_index = 0
@@ -682,7 +703,7 @@ def decode(
             if field_instance is not None:
                 env[field_instance.field_def.name] = field_instance.value
                 result.append_field_instance(field_instance)
-                _notify_progress(progress_callback, resolved_offset,
+                _notify_progress(progress_callback, progress_state, resolved_offset,
                                  field_instance.field_def.size, data_bits)
                 current_position = (resolved_offset +
                                     _resolve_info_size(field_def.size, env))
@@ -723,7 +744,7 @@ def decode(
                     env[field_instance.field_def.name] = field_instance.value
                     result.append_field_instance(field_instance)
                     actual_size = field_instance.field_def.size
-                    _notify_progress(progress_callback, current_offset,
+                    _notify_progress(progress_callback, progress_state, current_offset,
                                      actual_size, data_bits)
                 else:
                     actual_size = resolved_size
@@ -770,7 +791,7 @@ def decode(
                 env[field_instance.field_def.name] = field_instance.value
                 result.append_field_instance(field_instance)
                 actual_size = field_instance.field_def.size
-                _notify_progress(progress_callback, current_offset, actual_size,
+                _notify_progress(progress_callback, progress_state, current_offset, actual_size,
                                  data_bits)
             else:
                 actual_size = _resolve_info_size(field_def_repeat.size, env)

{sltcodec-2.6.1 → sltcodec-2.7.0}/tests/test_codec.py

@@ -7,7 +7,9 @@ from sltcore import InfoSize
 from sltcodec import (PRIMITIVE_TYPES, EnumDef, FieldDef, FieldInstance,
                       ProgressCallback, StructDef, StructInstance, StructLayout,
                       TypeDict, decode, encode)
-from sltcodec.codec import _resolve_info_size, decode_field
+from sltcodec import codec as codec_module
+from sltcodec.codec import (_notify_progress, _resolve_info_size,
+                           decode_field)
 
 
 def layout_for(struct_def):
@@ -968,3 +970,37 @@ def test_encode_without_padding_does_not_extend_buf_to_struct_size():
 
     assert encoded is buf
     assert encoded == bytearray(b"\x7f\x00\x00\x00")
+
+
+def _run_notify(monkeypatch, steps):
+    """Feed (time, bits) steps through _notify_progress; return reported."""
+    clock = {"now": 0.0}
+    monkeypatch.setattr(codec_module.time, "monotonic", lambda: clock["now"])
+    reported = []
+    state = {}
+    for now, bits in steps:
+        clock["now"] = now
+        _notify_progress(reported.append, state, InfoSize(0, 0),
+                         InfoSize(0, bits), 10000)
+    return reported
+
+
+def test_notify_progress_throttles_by_progress_delta(monkeypatch):
+    """Test small changes within 100 ms are skipped, >0.01 changes pass."""
+    reported = _run_notify(monkeypatch, [(0.0, 100), (0.01, 150),
+                                         (0.02, 300), (0.03, 301),
+                                         (0.04, 500)])
+    assert reported == [0.01, 0.03, 0.05]
+
+
+def test_notify_progress_throttles_by_time(monkeypatch):
+    """Test tiny changes are reported once 100 ms have elapsed."""
+    reported = _run_notify(monkeypatch, [(0.0, 100), (0.05, 101),
+                                         (0.1, 102), (0.15, 103)])
+    assert reported == [0.01, 0.0102]
+
+
+def test_notify_progress_always_reports_completion(monkeypatch):
+    """Test 1.0 is reported even if throttling conditions are not met."""
+    reported = _run_notify(monkeypatch, [(0.0, 9995), (0.01, 10000)])
+    assert reported == [0.9995, 1.0]

{sltcodec-2.6.1 → sltcodec-2.7.0}/uv.lock

@@ -74,7 +74,7 @@ wheels = [
 
 [[package]]
 name = "sltcodec"
-version = "2.6.0"
+version = "2.6.1"
 source = { editable = "." }
 dependencies = [
     { name = "sltcalc" },