consync 0.1.0__py3-none-any.whl

consync/models.py

@@ -0,0 +1,104 @@
+"""Core data models for consync."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class SyncDirection(Enum):
+    """Which direction to sync constants."""
+
+    SOURCE_TO_TARGET = "source_to_target"
+    TARGET_TO_SOURCE = "target_to_source"
+    BOTH = "both"
+
+
+class ConstantType(Enum):
+    """Supported constant value types."""
+
+    FLOAT = "float"
+    INT = "int"
+    STRING = "string"
+    ARRAY_INT = "array_int"
+    ARRAY_FLOAT = "array_float"
+    ARRAY_STRING = "array_string"
+
+
+@dataclass
+class Constant:
+    """A single named constant with value and metadata.
+
+    This is the universal data model — every parser produces these,
+    every renderer consumes them.
+
+    Values can be scalars (int, float, str) or typed arrays (list[int],
+    list[float], list[str]) for array constants like lookup tables.
+    """
+
+    name: str
+    value: float | int | str | list[int] | list[float] | list[str]
+    unit: str = ""
+    description: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def type(self) -> ConstantType:
+        if isinstance(self.value, list):
+            if not self.value:
+                return ConstantType.ARRAY_INT  # empty defaults to int array
+            first = self.value[0]
+            if isinstance(first, int):
+                return ConstantType.ARRAY_INT
+            elif isinstance(first, float):
+                return ConstantType.ARRAY_FLOAT
+            return ConstantType.ARRAY_STRING
+        if isinstance(self.value, int):
+            return ConstantType.INT
+        if isinstance(self.value, float):
+            return ConstantType.FLOAT
+        return ConstantType.STRING
+
+    @property
+    def is_numeric(self) -> bool:
+        if isinstance(self.value, list):
+            return self.type in (ConstantType.ARRAY_INT, ConstantType.ARRAY_FLOAT)
+        return isinstance(self.value, (int, float))
+
+    @property
+    def is_array(self) -> bool:
+        return isinstance(self.value, list)
+
+
+@dataclass
+class MappingConfig:
+    """Configuration for a single source ↔ target mapping."""
+
+    source: str
+    target: str
+    source_format: str = ""  # auto-detect from extension if empty
+    target_format: str = ""  # auto-detect from extension if empty
+    direction: SyncDirection = SyncDirection.SOURCE_TO_TARGET
+    precision: int = 17  # significant digits for floats
+    header_guard: str = ""  # C header guard name
+    namespace: str = ""  # for Rust/C++ namespacing
+    module_name: str = ""  # for Verilog/VHDL module scoping
+    prefix: str = ""  # prefix added to all constant names
+    uppercase_names: bool = True  # force UPPER_CASE names in output
+    # C/C++ specific options
+    output_style: str = "const"  # "const" | "define" — #define vs const declaration
+    static_const: bool = False  # emit "static const" to avoid linker duplicates
+    typed_ints: bool = True  # use uint32_t/int32_t instead of plain int/double for integers
+    # Validation hooks
+    validators: dict = field(default_factory=dict)  # {name: {min:, max:, type:, pattern:, ...}}
+
+
+@dataclass
+class ConsyncConfig:
+    """Root configuration loaded from .consync.yaml."""
+
+    mappings: list[MappingConfig] = field(default_factory=list)
+    state_file: str = ".consync.state.json"
+    watch_debounce: float = 2.0  # seconds
+    on_conflict: str = "source_wins"  # source_wins | target_wins | fail

consync/parsers/__init__.py

@@ -0,0 +1,40 @@
+"""Parser registry — maps format names to parser functions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+
+from consync.models import Constant
+
+# Type for parser functions: (filepath, **kwargs) -> list[Constant]
+ParserFunc = Callable[..., list[Constant]]
+
+_REGISTRY: dict[str, ParserFunc] = {}
+
+
+def register(name: str):
+    """Decorator to register a parser function."""
+    def decorator(func: ParserFunc) -> ParserFunc:
+        _REGISTRY[name] = func
+        return func
+    return decorator
+
+
+def get_parser(format_name: str) -> ParserFunc:
+    """Get a parser by format name."""
+    if format_name not in _REGISTRY:
+        available = ", ".join(sorted(_REGISTRY.keys()))
+        raise ValueError(
+            f"Unknown parser format '{format_name}'. Available: {available}"
+        )
+    return _REGISTRY[format_name]
+
+
+def list_parsers() -> list[str]:
+    """List all registered parser format names."""
+    return sorted(_REGISTRY.keys())
+
+
+# Import all parser modules to trigger registration
+from consync.parsers import xlsx, csv_parser, json_parser, toml_parser, c_header  # noqa: E402, F401

consync/parsers/c_header.py

@@ -0,0 +1,96 @@
+"""C/C++ header parser — reads const declarations from .h files.
+
+Parses lines matching:
+    const double NAME = VALUE;          /* unit | description */
+    const float NAME = VALUE;           // description
+    #define NAME VALUE                  /* unit | description */
+    static const int NAME = VALUE;
+
+Also handles:
+    const double NAME = 1.234e-07;     (scientific notation)
+    const uint32_t NAME = 0xFF;        (hex literals)
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from consync.models import Constant
+from consync.parsers import register
+from consync.precision import parse_number
+
+
+# Patterns for C constant declarations
+_CONST_PATTERN = re.compile(
+    r"^\s*(?:static\s+)?(?:const(?:expr)?)\s+"
+    r"(?:unsigned\s+|signed\s+)?"
+    r"(?:double|float|int|long|uint\d+_t|int\d+_t|size_t)\s+"
+    r"(\w+)\s*=\s*([^;]+);\s*"
+    r"(?:/[/*]\s*(.*?)(?:\*/)?)?$"
+)
+
+# #define pattern
+_DEFINE_PATTERN = re.compile(
+    r"^\s*#define\s+(\w+)\s+([^\s/]+)\s*(?:/[/*]\s*(.*?)(?:\*/)?)?$"
+)
+
+
+@register("c_header")
+def parse_c_header(filepath: str | Path, **kwargs) -> list[Constant]:
+    """Parse constants from a C/C++ header file.
+
+    Reads `const type NAME = VALUE;` and `#define NAME VALUE` declarations.
+    Extracts unit and description from trailing comments (pipe-separated).
+    """
+    filepath = Path(filepath)
+    if not filepath.exists():
+        raise FileNotFoundError(f"Header file not found: {filepath}")
+
+    text = filepath.read_text(encoding="utf-8")
+    constants: list[Constant] = []
+
+    for line in text.splitlines():
+        const = _try_parse_line(line)
+        if const is not None:
+            constants.append(const)
+
+    return constants
+
+
+def _try_parse_line(line: str) -> Constant | None:
+    """Try to parse a single line as a constant declaration."""
+    # Try const declaration first
+    m = _CONST_PATTERN.match(line)
+    if m:
+        return _build_constant(m.group(1), m.group(2), m.group(3))
+
+    # Try #define
+    m = _DEFINE_PATTERN.match(line)
+    if m:
+        return _build_constant(m.group(1), m.group(2), m.group(3))
+
+    return None
+
+
+def _build_constant(name: str, raw_value: str, comment: str | None) -> Constant | None:
+    """Build a Constant from parsed components."""
+    raw_value = raw_value.strip()
+    # Strip C type suffixes (e.g., 1.0f, 100UL) but NOT from hex literals
+    if not raw_value.startswith(("0x", "0X")):
+        raw_value = raw_value.rstrip("fFlLuU")
+
+    try:
+        value = parse_number(raw_value)
+    except (ValueError, IndexError):
+        return None  # Skip non-numeric defines
+
+    unit = ""
+    description = ""
+    if comment:
+        comment = comment.strip().rstrip("*/").strip()
+        parts = [p.strip() for p in comment.split("|", 1)]
+        unit = parts[0] if len(parts) >= 1 else ""
+        description = parts[1] if len(parts) >= 2 else ""
+
+    return Constant(name=name, value=value, unit=unit, description=description)

consync/parsers/csv_parser.py

@@ -0,0 +1,133 @@
+"""CSV parser — reads constants from comma/tab-separated files.
+
+Expected format:
+  Row 1: Header (Name, Value, Unit, Description)
+  Row 2+: Data
+
+Auto-detects delimiter (comma, tab, semicolon).
+
+Array values are supported using pipe (|) or semicolon separation within the
+value cell:
+    THRESHOLDS,"50|100|150|200|250",bar,Brake pressure thresholds
+    GAINS,"1.0|2.5|3.7",,PID gain table
+"""
+
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+
+from consync.models import Constant
+from consync.parsers import register
+from consync.precision import parse_number
+
+
+def _parse_value(raw: str) -> float | int | str | list[int] | list[float] | list[str]:
+    """Parse a value cell, detecting arrays (pipe or semicolon-separated).
+
+    Returns a list if the value contains | or ; delimiters with multiple items.
+    Otherwise returns a scalar.
+    """
+    # Detect array delimiter — pipes first, then semicolons (if not the CSV delimiter itself)
+    for delim in ("|", ";"):
+        if delim in raw:
+            parts = [p.strip() for p in raw.split(delim) if p.strip()]
+            if len(parts) >= 2:
+                return _parse_array_parts(parts)
+
+    # Scalar
+    try:
+        return parse_number(raw)
+    except (ValueError, IndexError):
+        return raw
+
+
+def _parse_array_parts(parts: list[str]) -> list[int] | list[float] | list[str]:
+    """Parse a list of string parts into a typed array."""
+    # Try all-int first
+    try:
+        return [int(p, 16) if p.lower().startswith("0x") else int(p) for p in parts]
+    except (ValueError, TypeError):
+        pass
+
+    # Try all-float
+    try:
+        return [float(p) for p in parts]
+    except (ValueError, TypeError):
+        pass
+
+    # Fallback: string array
+    return parts
+
+
+@register("csv")
+def parse_csv(filepath: str | Path, **kwargs) -> list[Constant]:
+    """Parse constants from a CSV file.
+
+    Args:
+        filepath: Path to .csv file.
+        delimiter: Override delimiter (default: auto-detect).
+
+    Returns:
+        List of Constant objects.
+    """
+    filepath = Path(filepath)
+    if not filepath.exists():
+        raise FileNotFoundError(f"CSV file not found: {filepath}")
+
+    text = filepath.read_text(encoding="utf-8")
+
+    # Auto-detect delimiter
+    delimiter = kwargs.get("delimiter")
+    if delimiter is None:
+        sniffer = csv.Sniffer()
+        try:
+            dialect = sniffer.sniff(text[:2048])
+            delimiter = dialect.delimiter
+        except csv.Error:
+            delimiter = ","
+
+    reader = csv.reader(text.splitlines(), delimiter=delimiter)
+    rows = list(reader)
+
+    if len(rows) < 2:
+        return []
+
+    # Header row — find columns
+    headers = [h.strip().lower() for h in rows[0]]
+
+    name_col = _find_col(headers, {"name", "constant", "parameter", "symbol"})
+    value_col = _find_col(headers, {"value", "val", "data", "number"})
+    unit_col = _find_col(headers, {"unit", "units", "uom"})
+    desc_col = _find_col(headers, {"description", "desc", "comment", "note"})
+
+    if name_col is None:
+        name_col = 0
+    if value_col is None:
+        value_col = 1
+
+    constants: list[Constant] = []
+    for row in rows[1:]:
+        if not row or not row[name_col].strip():
+            continue
+
+        name = row[name_col].strip()
+        raw_value = row[value_col].strip() if value_col < len(row) else ""
+        if not raw_value:
+            continue
+
+        value = _parse_value(raw_value)
+
+        unit = row[unit_col].strip() if unit_col is not None and unit_col < len(row) else ""
+        desc = row[desc_col].strip() if desc_col is not None and desc_col < len(row) else ""
+
+        constants.append(Constant(name=name, value=value, unit=unit, description=desc))
+
+    return constants
+
+
+def _find_col(headers: list[str], aliases: set[str]) -> int | None:
+    for i, h in enumerate(headers):
+        if h in aliases:
+            return i
+    return None

consync/parsers/json_parser.py

@@ -0,0 +1,138 @@
+"""JSON parser — reads constants from a JSON file.
+
+Supports two formats:
+
+Format A (flat object):
+    {
+        "R_SENSE": 1.9999999999910001,
+        "R_PULLUP": 4706
+    }
+
+Format B (array with metadata):
+    [
+        {"name": "R_SENSE", "value": 1.999, "unit": "Ohm", "description": "..."},
+        ...
+    ]
+
+Format C (nested object):
+    {
+        "R_SENSE": {"value": 1.999, "unit": "Ohm", "description": "..."},
+        ...
+    }
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from consync.models import Constant
+from consync.parsers import register
+from consync.precision import parse_number
+
+
+@register("json")
+def parse_json(filepath: str | Path, **kwargs) -> list[Constant]:
+    """Parse constants from a JSON file.
+
+    Auto-detects format (flat, array, or nested object).
+    """
+    filepath = Path(filepath)
+    if not filepath.exists():
+        raise FileNotFoundError(f"JSON file not found: {filepath}")
+
+    data = json.loads(filepath.read_text(encoding="utf-8"))
+
+    # Format B: array of objects
+    if isinstance(data, list):
+        return _parse_array(data)
+
+    # Format A or C: object
+    if isinstance(data, dict):
+        # Check first value to distinguish A vs C
+        first_val = next(iter(data.values()), None) if data else None
+        if isinstance(first_val, dict):
+            return _parse_nested(data)
+        return _parse_flat(data)
+
+    raise ValueError(f"Unexpected JSON structure: expected object or array, got {type(data).__name__}")
+
+
+def _parse_flat(data: dict) -> list[Constant]:
+    """Format A: {"NAME": value, ...} — value can be scalar or array."""
+    constants = []
+    for name, value in data.items():
+        if isinstance(value, list):
+            # Array constant — typed list of ints, floats, or strings
+            constants.append(Constant(name=name, value=_coerce_array(value)))
+        elif isinstance(value, (int, float)):
+            constants.append(Constant(name=name, value=value))
+        elif isinstance(value, str):
+            try:
+                constants.append(Constant(name=name, value=parse_number(value)))
+            except ValueError:
+                constants.append(Constant(name=name, value=value))
+    return constants
+
+
+def _parse_array(data: list) -> list[Constant]:
+    """Format B: [{"name": ..., "value": ..., ...}, ...]"""
+    constants = []
+    for item in data:
+        if not isinstance(item, dict):
+            continue
+        name = item.get("name", "")
+        value = item.get("value")
+        if not name or value is None:
+            continue
+        # Support array values in Format B
+        if isinstance(value, list):
+            value = _coerce_array(value)
+        constants.append(Constant(
+            name=name,
+            value=value,
+            unit=str(item.get("unit", "")),
+            description=str(item.get("description", item.get("desc", ""))),
+        ))
+    return constants
+
+
+def _parse_nested(data: dict) -> list[Constant]:
+    """Format C: {"NAME": {"value": ..., "unit": ..., ...}, ...}"""
+    constants = []
+    for name, props in data.items():
+        if not isinstance(props, dict):
+            continue
+        value = props.get("value")
+        if value is None:
+            continue
+        # Support array values in Format C
+        if isinstance(value, list):
+            value = _coerce_array(value)
+        constants.append(Constant(
+            name=name,
+            value=value,
+            unit=str(props.get("unit", "")),
+            description=str(props.get("description", props.get("desc", ""))),
+        ))
+    return constants
+
+
+def _coerce_array(arr: list) -> list[int] | list[float] | list[str]:
+    """Coerce a JSON array into a typed Python list.
+
+    Priority: int → float → str.
+    """
+    if not arr:
+        return []
+
+    # Check if all ints
+    if all(isinstance(x, int) for x in arr):
+        return arr
+
+    # Check if all numeric (mix of int/float → float)
+    if all(isinstance(x, (int, float)) for x in arr):
+        return [float(x) for x in arr]
+
+    # Fallback to strings
+    return [str(x) for x in arr]

consync/parsers/toml_parser.py

@@ -0,0 +1,74 @@
+"""TOML parser — reads constants from a TOML file.
+
+Supports two formats:
+
+Format A (flat):
+    [constants]
+    R_SENSE = 1.9999999999910001
+    R_PULLUP = 4706
+
+Format B (tables with metadata):
+    [constants.R_SENSE]
+    value = 1.999
+    unit = "Ohm"
+    description = "Current sense resistor"
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from consync.models import Constant
+from consync.parsers import register
+
+
+def _load_toml(filepath: Path) -> dict:
+    """Load TOML file using tomllib (3.11+) or tomli."""
+    text = filepath.read_text(encoding="utf-8")
+    if sys.version_info >= (3, 11):
+        import tomllib
+        return tomllib.loads(text)
+    else:
+        try:
+            import tomli
+            return tomli.loads(text)
+        except ImportError:
+            raise ImportError(
+                "TOML support requires Python 3.11+ or 'pip install tomli'. "
+                "Install with: pip install consync[toml]"
+            )
+
+
+@register("toml")
+def parse_toml(filepath: str | Path, **kwargs) -> list[Constant]:
+    """Parse constants from a TOML file."""
+    filepath = Path(filepath)
+    if not filepath.exists():
+        raise FileNotFoundError(f"TOML file not found: {filepath}")
+
+    data = _load_toml(filepath)
+
+    # Look for a [constants] section, fallback to root
+    section = data.get("constants", data)
+
+    constants: list[Constant] = []
+    for name, value in section.items():
+        if isinstance(value, dict):
+            # Format B: table with metadata
+            val = value.get("value")
+            if val is None:
+                continue
+            constants.append(Constant(
+                name=name,
+                value=val,
+                unit=str(value.get("unit", "")),
+                description=str(value.get("description", value.get("desc", ""))),
+            ))
+        elif isinstance(value, (int, float)):
+            # Format A: flat key=value
+            constants.append(Constant(name=name, value=value))
+        elif isinstance(value, str):
+            constants.append(Constant(name=name, value=value))
+
+    return constants

consync/parsers/xlsx.py

@@ -0,0 +1,116 @@
+"""Excel (.xlsx) parser — reads constants from a spreadsheet.
+
+Expected format:
+  Row 1: Header row (Name, Value, Unit, Description)
+  Row 2+: Data rows
+
+Column mapping is flexible — auto-detects by header names.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from consync.models import Constant
+from consync.parsers import register
+
+
+# Column header aliases (case-insensitive matching)
+NAME_ALIASES = {"name", "constant", "parameter", "variable", "symbol", "id"}
+VALUE_ALIASES = {"value", "val", "data", "number", "amount"}
+UNIT_ALIASES = {"unit", "units", "uom", "dimension"}
+DESC_ALIASES = {"description", "desc", "comment", "note", "notes", "info"}
+
+
+def _find_column(headers: list[str], aliases: set[str]) -> int | None:
+    """Find column index matching any alias (case-insensitive)."""
+    for i, h in enumerate(headers):
+        if h and h.strip().lower() in aliases:
+            return i
+    return None
+
+
+@register("xlsx")
+def parse_xlsx(filepath: str | Path, **kwargs) -> list[Constant]:
+    """Parse constants from an Excel file.
+
+    Args:
+        filepath: Path to .xlsx file.
+        sheet: Sheet name or index (default: active sheet).
+
+    Returns:
+        List of Constant objects.
+    """
+    import openpyxl
+
+    filepath = Path(filepath)
+    if not filepath.exists():
+        raise FileNotFoundError(f"Excel file not found: {filepath}")
+
+    wb = openpyxl.load_workbook(filepath, data_only=True)
+
+    sheet = kwargs.get("sheet")
+    if sheet is not None:
+        if isinstance(sheet, int):
+            ws = wb.worksheets[sheet]
+        else:
+            ws = wb[sheet]
+    else:
+        ws = wb.active
+
+    # Read header row
+    header_row = [str(cell.value or "").strip() for cell in ws[1]]
+
+    # Auto-detect columns
+    name_col = _find_column(header_row, NAME_ALIASES)
+    value_col = _find_column(header_row, VALUE_ALIASES)
+    unit_col = _find_column(header_row, UNIT_ALIASES)
+    desc_col = _find_column(header_row, DESC_ALIASES)
+
+    # Fallback to positional: A=Name, B=Value, C=Unit, D=Description
+    if name_col is None:
+        name_col = 0
+    if value_col is None:
+        value_col = 1
+    if unit_col is None:
+        unit_col = 2 if len(header_row) > 2 else None
+    if desc_col is None:
+        desc_col = 3 if len(header_row) > 3 else None
+
+    constants: list[Constant] = []
+    for row in ws.iter_rows(min_row=2, values_only=True):
+        if not row or row[name_col] is None:
+            continue
+
+        name = str(row[name_col]).strip()
+        if not name:
+            continue
+
+        raw_value = row[value_col] if value_col < len(row) else None
+        if raw_value is None:
+            continue
+
+        # Preserve numeric types
+        if isinstance(raw_value, (int, float)):
+            value = raw_value
+        else:
+            # Try to parse as number
+            try:
+                value = int(str(raw_value))
+            except ValueError:
+                try:
+                    value = float(str(raw_value))
+                except ValueError:
+                    value = str(raw_value)
+
+        unit = ""
+        if unit_col is not None and unit_col < len(row) and row[unit_col]:
+            unit = str(row[unit_col]).strip()
+
+        description = ""
+        if desc_col is not None and desc_col < len(row) and row[desc_col]:
+            description = str(row[desc_col]).strip()
+
+        constants.append(Constant(name=name, value=value, unit=unit, description=description))
+
+    return constants