sltcalc 0.1.0__py3-none-any.whl

sltcalc/__init__.py

@@ -0,0 +1,3 @@
+from .sltcalc import SltEval
+
+__all__ = ["SltEval"]

sltcalc/sltcalc.py

@@ -0,0 +1,155 @@
+"""Safe, deterministic expression evaluator for computing bit‑accurate
+   offsets, sizes, and field values within StructLayoutToolkit."""
+import ast
+import operator
+
+OPS = {
+    ast.Add: operator.add,
+    ast.Sub: operator.sub,
+    ast.Mult: operator.mul,
+    ast.Div: operator.truediv,
+    ast.FloorDiv: operator.floordiv,
+    ast.Pow: operator.pow,
+    ast.Mod: operator.mod,
+    ast.Eq: operator.eq,
+    ast.NotEq: operator.ne,
+    ast.Lt: operator.lt,
+    ast.LtE: operator.le,
+    ast.Gt: operator.gt,
+    ast.GtE: operator.ge,
+    ast.Is: operator.is_,
+    ast.IsNot: operator.is_not,
+    ast.In: lambda left, right: left in right,
+    ast.NotIn: lambda left, right: left not in right,
+    ast.BitAnd: operator.and_,
+    ast.BitOr: operator.or_,
+    ast.BitXor: operator.xor,
+    ast.LShift: operator.lshift,
+    ast.RShift: operator.rshift,
+}
+
+UNARY = {
+    ast.UAdd: lambda x: x,
+    ast.USub: lambda x: -x,
+    ast.Not: lambda x: not x,
+}
+
+SAFE_FUNCS = {
+    "abs": abs,
+    "all": all,
+    "any": any,
+    "len": len,
+    "min": min,
+    "max": max,
+    "round": round,
+    "sorted": sorted,
+    "sum": sum,
+}
+
+
+class SltEval:
+    """A safe, deterministic expression evaluator for computing bit‑accurate
+       offsets, sizes, and field values within StructLayoutToolkit."""
+
+    def __init__(self, env=None):
+        self.env = env or {}
+
+    def eval(self, expr: str) -> any:
+        """Evaluate a mathematical expression in a safe and deterministic
+           manner.
+        Args:
+            expr (str): The mathematical expression to evaluate.
+
+        Returns:
+            The result of the evaluated expression.
+        """
+        node = ast.parse(expr, mode="eval").body
+        return self._eval(node)
+
+    def _eval(self, node) -> any:
+        """Recursively evaluate an AST node."""
+        if isinstance(node, ast.Constant):
+            return node.value
+
+        if isinstance(node, ast.Name):
+            if node.id not in self.env:
+                raise NameError(f"Undefined variable: {node.id}")
+            return self.env[node.id]
+
+        if isinstance(node, ast.List):
+            return [self._eval(element) for element in node.elts]
+
+        if isinstance(node, ast.Tuple):
+            return tuple(self._eval(element) for element in node.elts)
+
+        if isinstance(node, ast.Dict):
+            return {
+                self._eval(key): self._eval(value)
+                for key, value in zip(node.keys, node.values)
+            }
+
+        if isinstance(node, ast.BinOp):
+            op = OPS[type(node.op)]
+            return op(self._eval(node.left), self._eval(node.right))
+
+        if isinstance(node, ast.UnaryOp):
+            op = UNARY[type(node.op)]
+            return op(self._eval(node.operand))
+
+        if isinstance(node, ast.IfExp):
+            cond = self._eval(node.test)
+            return self._eval(node.body if cond else node.orelse)
+
+        if isinstance(node, ast.BoolOp):
+            if isinstance(node.op, ast.And):
+                result = self._eval(node.values[0])
+                for value_node in node.values[1:]:
+                    if not result:
+                        return result
+                    result = self._eval(value_node)
+                return result
+
+            if isinstance(node.op, ast.Or):
+                result = self._eval(node.values[0])
+                for value_node in node.values[1:]:
+                    if result:
+                        return result
+                    result = self._eval(value_node)
+                return result
+
+            raise ValueError(f"Unsupported expression: {ast.dump(node)}")
+
+        if isinstance(node, ast.Compare):
+            left = self._eval(node.left)
+            for op_node, comparator in zip(node.ops, node.comparators):
+                op = OPS.get(type(op_node))
+                if op is None:
+                    raise ValueError(
+                        f"Unsupported expression: {ast.dump(node)}")
+                right = self._eval(comparator)
+                if not op(left, right):
+                    return False
+                left = right
+            return True
+
+        if isinstance(node, ast.Call):
+            if not isinstance(node.func, ast.Name):
+                raise ValueError(f"Unsupported expression: {ast.dump(node)}")
+
+            func = SAFE_FUNCS.get(node.func.id)
+            if func is None and node.func.id in self.env:
+                env_func = self.env[node.func.id]
+                if callable(env_func):
+                    func = env_func
+
+            if func is None:
+                raise ValueError(f"Unsafe function: {node.func.id}")
+            args = [self._eval(a) for a in node.args]
+            return func(*args)
+
+        if isinstance(node, ast.Subscript):
+            value = self._eval(node.value)
+            index = self._eval(node.slice)
+            return value[index]
+
+        raise ValueError(f"Unsupported expression: {ast.dump(node)}")

sltcalc-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: sltcalc
+Version: 0.1.0
+Summary: A safe, deterministic expression evaluator for computing bit‑accurate offsets, sizes, and field values within StructLayoutToolkit.
+Project-URL: Homepage, https://github.com/fangface-hub/StructLayoutToolkitCalc
+Project-URL: Documentation, https://readthedocs.org
+Project-URL: Repository, https://github.com/fangface-hub/StructLayoutToolkitCalc
+Project-URL: Issues, https://github.com/fangface-hub/StructLayoutToolkitCalc/issues
+Author: fangface
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bit,byte,data,deserialization,layout,serialization,struct
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# StructLayoutToolkitCalc
+
+A safe, deterministic expression evaluator for computing bit‑accurate offsets, sizes, and field values within StructLayoutToolkit.
+
+## Overview
+
+sltcalc provides a safe and deterministic expression evaluator used across StructLayoutToolkit to compute bit‑accurate offsets, sizes, and derived field values.
+It parses expressions into Python’s AST and evaluates a restricted subset of operations, ensuring predictable behavior without accessing Python globals or executing arbitrary code.
+The evaluator supports arithmetic, bitwise operations, conditional expressions, and user‑defined variables supplied through an isolated environment.
+This module enables dynamic field definitions, computed offsets, variable‑length structures, and protocol‑specific formulas while maintaining strict safety and structural consistency.
+
+## Usage
+
+### Basic
+
+```python
+from sltcalc import SltEval
+
+evaluator = SltEval()
+result = evaluator.eval("1 + 2 * 3")
+print(result)  # 7
+```
+
+### With variables
+
+```python
+from sltcalc import SltEval
+
+env = {
+    "offset": 8,
+    "width": 3,
+    "flag": True,
+}
+
+evaluator = SltEval(env)
+
+print(evaluator.eval("offset + width * 2"))       # 14
+print(evaluator.eval("1 if flag else 0"))         # 1
+print(evaluator.eval("99 if offset >= 8 else -1"))  # 99
+```
+
+### Error behavior
+
+```python
+from sltcalc import SltEval
+
+evaluator = SltEval()
+
+# NameError: undefined variable
+evaluator.eval("unknown + 1")
+
+# ValueError: unsafe function
+evaluator.eval("sum(1, 2)")
+```
+
+## Supported expressions
+
+SltEval evaluates a restricted subset of Python expression AST nodes.
+
+### Literals
+
+- Numeric constants (for example: 0, 42, 3.5)
+- Boolean constants (True, False)
+- List literals (for example: [1, 2, 3])
+- Tuple literals (for example: (1, 2, 3))
+- Dict literals (for example: {"a": 1, "b": 2})
+
+### Variables
+
+- Variable lookup from the evaluator environment (SltEval(env))
+
+### Binary operators
+
+- Arithmetic: +, -, *, /, //, %, **
+- Bitwise: &, |, ^, <<, >>
+
+### Unary operators
+
+- Unary plus: +x
+- Unary minus: -x
+- Boolean negation: not x
+
+### Boolean operators
+
+- and
+- or
+
+### Comparisons
+
+- ==, !=, <, <=, >, >=, is, is not, in, not in
+- Chained comparisons are supported (for example: 1 < 2 < 3)
+
+### Conditional expression
+
+- Ternary expression: a if condition else b
+
+### Subscript access
+
+- Index/key access (for example: arr[0], mapping["key"])
+- Nested access is supported (for example: access key "items" and then index 0)
+
+### Function calls
+
+- Built-in allowlist: abs(...), all(...), any(...), len(...),
+    min(...), max(...), round(...), sorted(...), sum(...)
+- Callables passed through environment are allowed
+    (for example: SltEval({"triple": triple}) then triple(4))
+
+## Not supported
+
+- Attribute access (for example: obj.value)
+- Set literals in expressions
+- Non-name call targets (for example: (lambda x: x)(1))
+
+Unsupported constructs raise ValueError with an Unsupported expression message.

sltcalc-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+sltcalc/__init__.py,sha256=lNh3PxqV4Hkv3a-gDUer7CJrdBAR-Vv12EzlrQg-3VU,55
+sltcalc/sltcalc.py,sha256=g7sPXCMYo7NG0yb6QAMZsn-VjpJhAo9MBL7ZgIzTIX4,5100
+sltcalc-0.1.0.dist-info/METADATA,sha256=tqBa7h3Q3eRsAEcEoncm36sGv3zVRIHY5dyzixiVPE4,3663
+sltcalc-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+sltcalc-0.1.0.dist-info/licenses/LICENSE,sha256=_WBHmfGHT8uGAnHK2W-hi7O_rO8t70lubivrqYujdIw,1065
+sltcalc-0.1.0.dist-info/RECORD,,

sltcalc-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sltcalc-0.1.0.dist-info/licenses/LICENSE

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