redzed 25.12.30__py3-none-any.whl

redzed/utils/time_utils.py

@@ -0,0 +1,262 @@
+"""
+Conversion routines for time periods/durations using multiple units.
+
+Example: "20h15m10" = 20 hours + 15 minutes + 10 seconds = 72910 seconds
+"""
+from __future__ import annotations
+
+__all__ = [
+    'SEC_PER_DAY', 'SEC_PER_HOUR', 'SEC_PER_MIN',
+    'fmt_period', 'parse_interval', 'time_period']
+
+from collections.abc import Callable, Sequence
+import re
+import typing as t
+
+from .data_utils import to_tuple
+
+
+SEC_PER_DAY = 86_400
+SEC_PER_HOUR = 3_600
+SEC_PER_MIN = 60
+
+
+def _fmt_parameters(seconds: float, approx: bool) -> tuple[int, int]:
+    """Internal parameters for formatting."""
+    # first value = exclusion of smallest units:
+    #   6 = include everything, 5 = exclude: MS, 4 = exclude: S+MS, 3 = exclude: M+S+MS
+    # second value = rounding unit in ms:
+    if approx:
+        if seconds >= 3 * SEC_PER_DAY:
+            return (3, 1000 * SEC_PER_HOUR)
+        if seconds >= SEC_PER_HOUR:
+            return (4, 1000 * SEC_PER_MIN)
+        if seconds >= SEC_PER_MIN:
+            return (5, 1000)
+        if seconds >= 10:
+            return (6, 100)
+        if seconds >= 3:
+            return (6, 10)
+    return (6, 1)
+
+
+_UNITS = [('w', 'd', 'h', 'm', 's', 'ms'), ('W', 'D', 'H', 'M', 'S', 'MS')]
+def fmt_period(
+        seconds: float,
+        iso8601: bool = False, sep: str = '', upper: bool = False, approx: bool = False
+        ) -> str:
+    """
+    Return seconds as a string using units w, d, h, m, s and ms.
+
+    The individual parts are separated with the 'sep' string.
+    """
+    if seconds < 0.0:
+        raise ValueError("Number of seconds cannot be negative")
+    if iso8601:
+        upper = True
+        sep = ''
+    if seconds == 0.0:
+        if iso8601:
+            return "PT0S"
+        return "0S" if upper else "0s"
+    fmt_last, fmt_rounding = _fmt_parameters(seconds, approx)
+    ms = int(1000 * seconds / fmt_rounding + 0.5) * fmt_rounding
+    if ms == 0:
+        if iso8601:
+            return "PT0.001S"
+        return "1MS" if upper else "1ms"
+    s: int|float    # float only in iso8601 mode
+    s, ms = divmod(ms, 1000)
+    d, s = divmod(s, SEC_PER_DAY)
+    if iso8601:
+        w = 0
+    else:
+        w, d = divmod(d, 7)
+    h, s = divmod(s, SEC_PER_HOUR)
+    m, s = divmod(s, SEC_PER_MIN)
+    if iso8601 and ms != 0:
+        s += ms / 1000
+        ms = 0
+    numbers = [w, d, h, m, s, ms]
+    units = _UNITS[bool(upper)]     # True == 1, False == 0
+    for idx, value in enumerate(numbers):
+        if value > 0:
+            first = idx
+            break
+    for idx in range(fmt_last, 0, -1):
+        if numbers[idx - 1] > 0:
+            last = idx
+            break
+    assert first < last
+    parts = [(str(n) + u) for n, u in zip(numbers[first:last], units[first:last], strict=True)]
+    if iso8601:
+        if last >= 3:
+            # time units are included, must prepend 'T' before the first one
+            parts.insert(max(0, 2 - first), 'T')
+        parts.insert(0, 'P')
+    return sep.join(parts)
+
+
+_NUM = r'(\d+(?:[.,]\d*)?)'     # a match group for a number with optional fractional part
+_RE_ISO_DURATION = re.compile(rf"""
+    P
+    (?: 0+Y)?
+    (?: 0+M)?
+    (?: {_NUM} W)?
+    (?: {_NUM} D)?
+    (?: T
+        (?: {_NUM} H)?
+        (?: {_NUM} M)?
+        (?: {_NUM} S)?
+    )?
+    """, flags = re.ASCII | re.VERBOSE)
+_RE_DURATION = re.compile(rf"""
+    (?: {_NUM} \s* w \s*)?
+    (?: {_NUM} \s* d \s*)?
+    (?: {_NUM} \s* h \s*)?
+    (?: {_NUM} \s* m \s*)?
+    (?: {_NUM} \s* s \s*)?
+    (?: {_NUM} \s* ms )?
+    """, flags = re.ASCII | re.IGNORECASE | re.VERBOSE)
+
+COEF = [0.001, 1, SEC_PER_MIN, SEC_PER_HOUR, SEC_PER_DAY, 7*SEC_PER_DAY]
+ISO_COEF = COEF[1:]
+def _str_to_period(tstr: str) -> float:
+    """Convert string to number of seconds."""
+    tstr = tstr.strip()
+    iso = tstr.startswith("P")
+    regex = _RE_ISO_DURATION if iso else _RE_DURATION
+    if (match := regex.fullmatch(tstr)) is None:
+        raise ValueError("Invalid time representation")
+
+    result = 0.0
+    smallest_unit = True
+    for value, scale_factor in zip(reversed(match.groups()), ISO_COEF if iso else COEF):
+        if value is None:
+            continue
+        if (decimal_comma := ',' in value) or ('.' in value):
+            if not smallest_unit:
+                raise ValueError("Only the smallest unit may have a fractional part")
+            if decimal_comma:
+                value = value.replace(',', '.', 1)
+        num = float(value)
+        smallest_unit = False
+        if num == 0.0:
+            continue
+        if scale_factor is None:
+            raise ValueError("Calendar years/months are not supported as duration units")
+        result += num * scale_factor
+    if smallest_unit:
+        raise ValueError("At least one part must be present")
+    return result
+
+
+def time_period(
+        period: t.Any,
+        passthrough:None|type[object]|Sequence[None|type[object]] = (),
+        zero_ok: bool = False) -> t.Any:
+    """
+    Convenience wrapper for convert().
+
+    Return 'period' unchanged if its type is present in the
+    'passthrough'. Otherwise convert a number or string to float.
+
+    Argument 'passthrough' can be a type or a sequence of types.
+    For convenience None is accepted as a type. Technically correct
+    is NoneType, but in typing None is widely used.
+    """
+    if passthrough != ():
+        passthrough = to_tuple(passthrough)
+        if None in passthrough:
+            if period is None:
+                return None
+            passthrough = tuple(t for t in passthrough if t is not None)
+        if isinstance(period, t.cast(tuple[type[object], ...], passthrough)):
+            return period
+    saved_period = period
+    if isinstance(period, str):
+        try:
+            period = _str_to_period(period)
+        except Exception as err:
+            err.add_note(f"Converted string was: '{period}'")
+            raise
+    elif isinstance(period, int):
+        period = float(period)
+    elif not isinstance(period, float):
+        raise TypeError(f"Invalid type for time period specification: {period!r}")
+    if period < 0:
+        raise ValueError(f"Time period cannot be negative, got {saved_period}")
+    if period == 0.0 and not zero_ok:
+        raise ValueError("Time period must be positive, zero is not allowed.")
+    return period
+
+
+# integer sequence length limits for validation
+_limits = {
+    'date': (2, 2),
+    'time': (2, 4),
+    'datetime': (5, 7),
+    None: (2, 7),   # unknown
+}
+
+
+def _sd_split(sd: str|Sequence[str], parsed_string:str) -> list[str]:
+    """
+    Choose a separator/deliemiter and split the *parsed_string*.
+
+    If there are multiple choices, use the first one
+    that is present in the *parsed_string*.
+    """
+    if not sd:
+        raise ValueError("Got an empty separator or delimiter")
+    if isinstance(sd, str):
+        return parsed_string.split(sd)
+    for try_sd in sd:
+        if try_sd in parsed_string:
+            return parsed_string.split(try_sd)
+    return [parsed_string]
+
+
+def parse_interval(
+        interval: str, *,
+        parser: Callable[[str], Sequence[int]],
+        sep: str = "/", delim: str = ";",     # endpoint separator, range delimiter
+        datatype: t.Literal['date', 'time', 'datetime'] | None = None,
+        ) -> list[list[Sequence[int]]]:
+    """
+    Parse a string representation of a time/date/timedate interval.
+
+    Intented for usage with TimeDate and TimeSpan blocks.
+    """
+    is_date = datatype == 'date'
+    try:
+        imin, imax = _limits[datatype]
+    except KeyError:
+        raise ValueError(
+            "argument 'datatype' must be one of: 'date', 'time', 'datetime' or None, "
+            + f"but got {datatype!r}") from None
+
+    # wrap the parser
+    def wparser(endpoint: str) -> Sequence[int]:
+        value = parser(endpoint)
+        if not imin <= len(value) <= imax:
+            raise ValueError(
+                f"Interval endpoint {endpoint} was not parsed correctly, "
+                "please check the parser function")
+        return value
+
+    ranges = _sd_split(delim, interval)
+    if ranges and not ranges[-1].strip():
+        del ranges[-1]
+    result = []
+    for rng in ranges:
+        elen = len(endpoints := _sd_split(sep, rng))
+        if is_date and elen == 1:
+            begin_end = wparser(rng.strip())
+            result.append([begin_end, begin_end])
+            continue
+        if elen == 2:
+            result.append([wparser(endpoints[0].strip()), wparser(endpoints[1].strip())])
+            continue
+        raise ValueError(f"A range cannot have {elen} endpoint(s): {rng}")
+    return result

redzed-25.12.30.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: redzed
+Version: 25.12.30
+Summary: An asyncio-based library for building small automated systems
+Author-email: Vlado Potisk <redzed@poti.sk>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/xitop/redzed
+Project-URL: repository, https://github.com/xitop/redzed
+Project-URL: documentation, https://redzed.readthedocs.io/en/latest/
+Keywords: automation,finite-state machine
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: tests
+Requires-Dist: pytest>=8.4.0; extra == "tests"
+Requires-Dist: pytest-asyncio>=0.26.0; extra == "tests"
+Requires-Dist: pytest-xdist; extra == "tests"
+Dynamic: license-file
+
+# Redzed
+
+Redzed is an asyncio-based library for building small automated systems,
+i.e. systems that control outputs according to input values,
+system’s internal state, date and time. Redzed was written in Python.
+It is free and open source.
+
+Included are pre-defined logic blocks for general use. There are memory cells,
+timers, programmable finite-state machines, outputs and many more.
+Blocks have outputs and react to events. Blocks are complemented by triggers
+running user-supplied functions when certain outputs change. Triggered functions
+evaluate outputs, make decisions and can send events to other blocks.
+
+The mutual interaction of blocks and triggers allows to build modular
+automated systems of small to middle complexity.
+
+What is not included:
+The application code must connect the system with outside world.
+
+## Documentation
+
+Please read the [online documentation](https://redzed.readthedocs.io/en/latest/)
+for more information.
+
+### Note:
+
+Redzed is intended to replace Edzed (an older library from the same author).
+It has the same capabilities, but is based on simpler concepts and that's why
+it is easier to learn and to use.

redzed-25.12.30.dist-info/RECORD

@@ -0,0 +1,28 @@
+redzed/__init__.py,sha256=eyvuX8qwxEFuiP6jOu4x1qv-AmHJAGKOziV1dKCNWWA,1098
+redzed/base_block.py,sha256=NzJhY0POAJUyfp9EcQG2RvXM472vAV5iWG5LdsScpso,5191
+redzed/block.py,sha256=0iwK8Pb5LJ0xzoOt5dkx-FeWplzUzAWHOWfah368u7s,12012
+redzed/circuit.py,sha256=VkcAZZg5HfEdboUZ_vMnElI9E4MprwaoBveN8-hUvZw,31095
+redzed/cron_service.py,sha256=f-YR0w2U0dpipX271cyUYXvsvJunpE3mywuV7SkFE_k,10581
+redzed/debug.py,sha256=QeWHpfTZADPB6nY0zrj1Aqo91Wd9HB9bAJVgq_d3hCo,2767
+redzed/formula_trigger.py,sha256=0_TVbR1wCQ0Wv7NlJtcfD-iDUbmTBlbVCSdbKDw_tX0,7516
+redzed/initializers.py,sha256=oF5Wkdu2REFdfuCEdo8kS-9N2uW2dhdzYWoibILB3ks,7804
+redzed/signal_shutdown.py,sha256=KjL6Kq9K0m_2nerjo7hryNFPhgdNTmSyTOfDi-SMsjA,2081
+redzed/undef.py,sha256=iPxcUIKBDh5wqjdr8qvs9EQkx5s52ryNDY22at-PF0c,896
+redzed/blocklib/__init__.py,sha256=au7jbjO_RUFzK5U4STk-7pc1DTVA0OVh2W_aKsx1Y3s,557
+redzed/blocklib/counter.py,sha256=XvJPOarg6RZ9H-GrWFQrt3JJnGk9YGc1B7NOpF6ju4A,1125
+redzed/blocklib/fsm.py,sha256=6Qv4pOsF-FOEBm9NQUSD6F2yLfb0chvbpvbrgg3sIk8,23492
+redzed/blocklib/inputs.py,sha256=hhfU2Id7oJfmhZB-_PoowXBfYDuw9OQyceg_AprJVVs,7218
+redzed/blocklib/outputs.py,sha256=hoBPr_978PyhR6OzD0rxou34PFukIRD1pIpK6JNgqQE,12894
+redzed/blocklib/repeat.py,sha256=hkIO7qgm4wS32dcKkkfL_DjnoKWf-l3k2DfRiRUk6iE,2500
+redzed/blocklib/timedate.py,sha256=78wqiH1mUz5zoz3ZgDOmsPaYYmQLypgt9IfmLUcH9Cw,5196
+redzed/blocklib/timeinterval.py,sha256=hxPhao1Gm9q_NOp6WdjmsStkrfwkadH5uJh-Hli9D-4,6752
+redzed/blocklib/timer.py,sha256=X3CoqwGJ46oLw0R5u0HK1a11VpcZdTWvPbWOkFjZrDI,1520
+redzed/utils/__init__.py,sha256=Yo8cj1f1HQj862UOdCsXOkMg4kfq1c5S3HJDhuiE5os,326
+redzed/utils/async_utils.py,sha256=Vknijh9rABL8GcJbYv6a7I4qO2VLerMsGTr5wiGWbjo,4486
+redzed/utils/data_utils.py,sha256=xiaVnEJF7Q9oGFqqTOyiVyzI-sG0lYHxImfyFcXjwFI,3542
+redzed/utils/time_utils.py,sha256=eCqk4T4ipn4hgzL8-4Usn1W6kkTyRCuQ9-BMSvnELww,8524
+redzed-25.12.30.dist-info/licenses/LICENSE.txt,sha256=HwuPxdAOIKlSWHESVtk6Zov7d0BZaPu74eruoZc5UN8,1086
+redzed-25.12.30.dist-info/METADATA,sha256=LiyTs38Xa48jh2ozWNw1uUICaNKrTg7xWSUd1vEHTK0,2058
+redzed-25.12.30.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+redzed-25.12.30.dist-info/top_level.txt,sha256=7Rt0BRMqaJ0AGAmrd2JDqmqSY4cmQeW--7u6KDV1gZg,7
+redzed-25.12.30.dist-info/RECORD,,

redzed-25.12.30.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

redzed-25.12.30.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vlado Potisk <redzed@poti.sk>
+
+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.

redzed-25.12.30.dist-info/top_level.txt

@@ -0,0 +1 @@
+redzed