python-library-ralf-model 0.1.0__tar.gz → 0.1.2__tar.gz

python_library_ralf_model-0.1.2/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.env.*
+!.env.example
+# packages 示例本地密钥（*.example 为模板，可提交）
+packages/**/examples/**/.env
+!packages/**/examples/**/.env.example
+packages/**/examples/**/mcp.json
+!packages/**/examples/**/mcp.json.example
+packages/**/examples/**/.sandbox/
+.pytest_cache/
+config.yaml
+logs/
+.cursor/
+uv.lock

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-library-ralf-model
-Version: 0.1.0
+Version: 0.1.2
 Requires-Python: >=3.10
 Requires-Dist: pydantic<3,>=2.0
 Description-Content-Type: text/markdown
@@ -41,6 +41,8 @@ doc = load_ralf_file(
 ## 能力范围
 
 - **block**：定义 ``block 名 { ... }``；简单映射 ``block 名 @地址;``；赋值与可选路径、地址 ``block 左名 = 右名``、``block 左名 = 右名 (hdl路径)``、``... @地址``，可与 ``{ ... }`` 组合。
+- **register**：``register 名 [ (hdl路径) ] [ @字节偏移 ] { ... }`` 或 ``register 名;`` 前向引用。
+- **field**：``field 名 [(hdl路径)] [ @位偏移 ] { ... }``（括号路径可紧贴字段名，如 ``field f(hdl.f)``）。
 - `field` 花括号内按**源顺序**保留各条语句（含 `enum { ... };` 等），便于往返。
 - `@` 后的偏移在写出时统一为 Verilog 风格十六进制字面量（如 `'h5`）；`bytes` 等为十进制。
 

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/README.md

@@ -34,6 +34,8 @@ doc = load_ralf_file(
 ## 能力范围
 
 - **block**：定义 ``block 名 { ... }``；简单映射 ``block 名 @地址;``；赋值与可选路径、地址 ``block 左名 = 右名``、``block 左名 = 右名 (hdl路径)``、``... @地址``，可与 ``{ ... }`` 组合。
+- **register**：``register 名 [ (hdl路径) ] [ @字节偏移 ] { ... }`` 或 ``register 名;`` 前向引用。
+- **field**：``field 名 [(hdl路径)] [ @位偏移 ] { ... }``（括号路径可紧贴字段名，如 ``field f(hdl.f)``）。
 - `field` 花括号内按**源顺序**保留各条语句（含 `enum { ... };` 等），便于往返。
 - `@` 后的偏移在写出时统一为 Verilog 风格十六进制字面量（如 `'h5`）；`bytes` 等为十进制。
 

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-library-ralf-model"
-version = "0.1.0"
+version = "0.1.2"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/ralf_model/emit.py

@@ -12,6 +12,8 @@ def _fmt_at_int(v: int) -> str:
 
 def _emit_field(f: FieldNode, indent: str) -> list[str]:
     head = f"{indent}field {f.name}"
+    if f.paren_path is not None:
+        head += f"({f.paren_path})"
     if f.offset_bits is not None:
         head += f" @{_fmt_at_int(f.offset_bits)}"
     head += " {"
@@ -26,6 +28,8 @@ def _emit_field(f: FieldNode, indent: str) -> list[str]:
 
 def _emit_register(r: RegisterNode, indent: str) -> list[str]:
     head = f"{indent}register {r.name}"
+    if r.paren_path is not None:
+        head += f" ({r.paren_path})"
     if r.offset_bytes is not None:
         head += f" @{_fmt_at_int(r.offset_bytes)}"
     if r.declaration_only:

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/ralf_model/errors.py

@@ -10,10 +10,22 @@ class RalfError(Exception):
 class RalfParseError(RalfError):
     """文本不符合预期语法或词法。"""
 
-    def __init__(self, message: str, *, line: int, col: int) -> None:
-        super().__init__(f"{message} (行 {line}, 列 {col})")
+    def __init__(
+        self,
+        message: str,
+        *,
+        line: int,
+        col: int,
+        path: Path | None = None,
+    ) -> None:
+        loc = f"行 {line}, 列 {col}"
+        if path is not None:
+            loc = f"{path}: {loc}"
+        super().__init__(f"{message} ({loc})")
+        self.message = message
         self.line = line
         self.col = col
+        self.path = path
 
 
 class RalfSourceError(RalfError):

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/ralf_model/io.py

@@ -20,9 +20,13 @@ def load_ralf_file(
     p = Path(path).resolve()
     text = p.read_text(encoding=encoding)
     inc = tuple(Path(x).resolve() for x in (include_paths or ()))
+    line_sources: list[Path] | None = None
     if expand_source:
-        text = expand_ralf_sources(text, current_file=p, include_paths=inc, encoding=encoding)
-    return parse_ralf(text)
+        text, line_sources = expand_ralf_sources(
+            text, current_file=p, include_paths=inc, encoding=encoding
+        )
+        return parse_ralf(text, line_sources=line_sources)
+    return parse_ralf(text, path=p)
 
 
 def loads_ralf(
@@ -38,13 +42,14 @@ def loads_ralf(
     virtual = bd / "__inline__.ralf"
     inc = tuple(Path(x).resolve() for x in (include_paths or ()))
     if expand_source:
-        text = expand_ralf_sources(
+        text, line_sources = expand_ralf_sources(
             text,
             current_file=virtual,
             include_paths=inc,
             encoding=encoding,
         )
-    return parse_ralf(text)
+        return parse_ralf(text, line_sources=line_sources)
+    return parse_ralf(text, path=virtual)
 
 
 def dump_ralf_file(doc: RalfDocument, path: str | Path, *, encoding: str = "utf-8") -> None:

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/ralf_model/nodes.py

@@ -9,6 +9,10 @@ class FieldNode(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     name: str
+    paren_path: str | None = Field(
+        default=None,
+        description="紧跟在 field 名后的圆括号路径内容（不含括号），如 ``field f(hdl.sig)``",
+    )
     offset_bits: int | None = Field(default=None, description="field 内 `@` 后的位偏移")
     inner_statements: list[str] = Field(
         default_factory=list,
@@ -22,6 +26,10 @@ class RegisterNode(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     name: str
+    paren_path: str | None = Field(
+        default=None,
+        description="紧跟在 register 名后的圆括号路径内容（不含括号），如 ``register r (dut.reg)``",
+    )
     offset_bytes: int | None = Field(default=None, description="register 后的 `@` 字节偏移")
     bytes_width: int | None = None
     fields: list[FieldNode] = Field(default_factory=list)

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/ralf_model/parse.py

@@ -1,18 +1,28 @@
 from __future__ import annotations
 
 import re
+from collections.abc import Sequence
+from pathlib import Path
 
 from ralf_model.errors import RalfParseError
 from ralf_model.nodes import BlockNode, FieldNode, RalfDocument, RegisterNode
 
 
 class _Parser:
-    def __init__(self, text: str) -> None:
+    def __init__(
+        self,
+        text: str,
+        *,
+        path: Path | None = None,
+        line_sources: Sequence[Path] | None = None,
+    ) -> None:
         self._s = text
         self._n = len(text)
         self._i = 0
         self.line = 1
         self.col = 1
+        self._path = path
+        self._line_sources = line_sources
 
     def _advance(self, n: int = 1) -> None:
         for _ in range(n):
@@ -30,7 +40,10 @@ class _Parser:
         return self._s[j] if j < self._n else None
 
     def _error(self, msg: str) -> None:
-        raise RalfParseError(msg, line=self.line, col=self.col)
+        path = self._path
+        if self._line_sources and 0 < self.line <= len(self._line_sources):
+            path = self._line_sources[self.line - 1]
+        raise RalfParseError(msg, line=self.line, col=self.col, path=path)
 
     def skip_ws_and_comments(self) -> None:
         while self._i < self._n:
@@ -336,6 +349,10 @@ class _Parser:
         self.expect_keyword("register")
         name = self.read_ident()
         self.skip_ws_and_comments()
+        paren_path: str | None = None
+        if self._peek() == "(":
+            paren_path = self.read_round_paren_inner()
+            self.skip_ws_and_comments()
         offset: int | None = None
         if self._peek() == "@":
             self._advance()
@@ -345,6 +362,7 @@ class _Parser:
             self._advance()
             return RegisterNode(
                 name=name,
+                paren_path=paren_path,
                 offset_bytes=offset,
                 declaration_only=True,
             )
@@ -354,6 +372,7 @@ class _Parser:
             self.expect_char("}")
             return RegisterNode(
                 name=name,
+                paren_path=paren_path,
                 offset_bytes=offset,
                 bytes_width=rbw,
                 fields=fields,
@@ -383,6 +402,10 @@ class _Parser:
         self.expect_keyword("field")
         name = self.read_ident()
         self.skip_ws_and_comments()
+        paren_path: str | None = None
+        if self._peek() == "(":
+            paren_path = self.read_round_paren_inner()
+            self.skip_ws_and_comments()
         off_bits: int | None = None
         if self._peek() == "@":
             self._advance()
@@ -390,7 +413,9 @@ class _Parser:
         self.expect_char("{")
         fn = self._parse_field_body()
         self.expect_char("}")
-        return fn.model_copy(update={"name": name, "offset_bits": off_bits})
+        return fn.model_copy(
+            update={"name": name, "paren_path": paren_path, "offset_bits": off_bits}
+        )
 
     def _parse_field_body(self) -> FieldNode:
         inner: list[str] = []
@@ -519,9 +544,14 @@ def _parse_verilog_sized(s: str, i: int) -> tuple[int, int]:
 _VER_WS = re.compile(r"\s+")
 
 
-def parse_ralf(text: str) -> RalfDocument:
+def parse_ralf(
+    text: str,
+    *,
+    path: Path | None = None,
+    line_sources: Sequence[Path] | None = None,
+) -> RalfDocument:
     """将 RALF 源文本解析为 `RalfDocument`。"""
-    p = _Parser(text)
+    p = _Parser(text, path=path, line_sources=line_sources)
     doc = p.parse_document()
     return doc
 

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/ralf_model/source_expand.py

@@ -109,11 +109,13 @@ def expand_ralf_sources(
     include_paths: Sequence[Path] = (),
     encoding: str = "utf-8",
     _chain: tuple[Path, ...] = (),
-) -> str:
+) -> tuple[str, list[Path]]:
     """将 Tcl 风格 ``source path`` 递归展开为单段 RALF 文本后再交给 ``parse_ralf``。
 
     ``current_file`` 用于确定相对路径的基准目录（通常为 ``path.parent``），并参与循环检测。
     从内存加载字符串时可使用 ``base_dir / \"__inline__.ralf\"`` 这类占位路径。
+
+    返回 ``(展开后文本, 行来源)``：``行来源[i]`` 对应展开结果第 ``i+1`` 行的源文件路径。
     """
     cf = current_file.resolve()
     if cf in _chain:
@@ -123,15 +125,17 @@ def expand_ralf_sources(
     inc = tuple(Path(p).resolve() for p in include_paths)
 
     out: list[str] = []
+    line_sources: list[Path] = []
     for line in text.splitlines(keepends=True):
         spec = _parse_source_argument(line)
         if spec is None:
             out.append(line)
+            line_sources.append(cf)
             continue
 
         inner_path = resolve_source_path(spec, base_dir=cf.parent, include_paths=inc)
         inner_text = inner_path.read_text(encoding=encoding)
-        expanded_inner = expand_ralf_sources(
+        expanded_inner, inner_sources = expand_ralf_sources(
             inner_text,
             current_file=inner_path,
             include_paths=inc,
@@ -139,7 +143,9 @@ def expand_ralf_sources(
             _chain=chain,
         )
         out.append(expanded_inner)
+        line_sources.extend(inner_sources)
         if expanded_inner and not expanded_inner.endswith("\n"):
             out.append("\n")
+            line_sources.append(inner_sources[-1] if inner_sources else inner_path)
 
-    return "".join(out)
+    return "".join(out), line_sources

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/tests/test_ralf_model.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import tempfile
 import unittest
+from pathlib import Path
 
-from ralf_model import dump_ralf, parse_ralf
+from ralf_model import RalfParseError, dump_ralf, load_ralf_file, parse_ralf
 from ralf_model.parse import normalize_ralf_whitespace
 
 
@@ -146,6 +148,69 @@ block top {
         out = dump_ralf(doc)
         self.assertIn("register R0;", out)
 
+    def test_register_paren_path_at_offset(self) -> None:
+        src = """
+block top {
+  bytes 4;
+  register CTRL (dut.ctrl_reg) @'h0 {
+    bytes 4;
+    field ena(dut.ctrl_reg.en) @1 {
+      bits 1;
+      access rw;
+    }
+  }
+}
+"""
+        doc = parse_ralf(src)
+        reg = doc.blocks[0].registers[0]
+        self.assertEqual(reg.name, "CTRL")
+        self.assertEqual(reg.paren_path, "dut.ctrl_reg")
+        self.assertEqual(reg.offset_bytes, 0)
+        fld = reg.fields[0]
+        self.assertEqual(fld.name, "ena")
+        self.assertEqual(fld.paren_path, "dut.ctrl_reg.en")
+        self.assertEqual(fld.offset_bits, 1)
+        out = dump_ralf(doc)
+        self.assertIn("register CTRL (dut.ctrl_reg) @'h0", out)
+        self.assertIn("field ena(dut.ctrl_reg.en) @'h1", out)
+        doc2 = parse_ralf(out)
+        self.assertEqual(doc.model_dump(), doc2.model_dump())
+
+    def test_register_paren_path_forward_decl(self) -> None:
+        src = """
+block top {
+  register R0 (hdl.r0) @'h10;
+}
+"""
+        doc = parse_ralf(src)
+        r = doc.blocks[0].registers[0]
+        self.assertTrue(r.declaration_only)
+        self.assertEqual(r.paren_path, "hdl.r0")
+        self.assertEqual(r.offset_bytes, 0x10)
+        out = dump_ralf(doc)
+        self.assertIn("register R0 (hdl.r0) @'h10;", out)
+        doc2 = parse_ralf(out)
+        self.assertEqual(doc.model_dump(), doc2.model_dump())
+
+    def test_field_paren_path_no_space(self) -> None:
+        src = """
+block top {
+  register r {
+    bytes 4;
+    field sig(hdl.sig) @0 {
+      bits 4;
+    }
+  }
+}
+"""
+        doc = parse_ralf(src)
+        fld = doc.blocks[0].registers[0].fields[0]
+        self.assertEqual(fld.paren_path, "hdl.sig")
+        out = dump_ralf(doc)
+        self.assertIn("field sig(hdl.sig)", out)
+        doc2 = parse_ralf(out)
+        self.assertEqual(doc.model_dump(), doc2.model_dump())
+
     def test_block_ref_rhs_with_parentheses(self) -> None:
         src = """
 block top {
@@ -176,5 +241,29 @@ block a {
         self.assertNotIn("//", n)
 
 
+class ParseErrorTests(unittest.TestCase):
+    def test_parse_error_includes_file_path(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            bad = Path(td) / "bad.ralf"
+            bad.write_text("block x {\n  ???\n}\n", encoding="utf-8")
+            with self.assertRaises(RalfParseError) as ctx:
+                load_ralf_file(bad, expand_source=False)
+            self.assertIn(str(bad.resolve()), str(ctx.exception))
+
+    def test_parse_error_in_included_file(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            inc = root / "inc"
+            inc.mkdir()
+            (inc / "broken.ralf").write_text("block y {\n  ???\n}\n", encoding="utf-8")
+            top = root / "top.ralf"
+            top.write_text('source "inc/broken.ralf"\n', encoding="utf-8")
+            broken = (inc / "broken.ralf").resolve()
+            with self.assertRaises(RalfParseError) as ctx:
+                load_ralf_file(top)
+            self.assertIn(str(broken), str(ctx.exception))
+            self.assertNotIn(str(top.resolve()), str(ctx.exception))
+
+
 if __name__ == "__main__":
     unittest.main()

{python_library_ralf_model-0.1.0 → python_library_ralf_model-0.1.2}/tests/test_source_include.py

@@ -51,7 +51,7 @@ class SourceIncludeTests(unittest.TestCase):
             top = root / "top.ralf"
             top.write_text('source "mid.ralf"\n', encoding="utf-8")
 
-            out = expand_ralf_sources(
+            out, _line_sources = expand_ralf_sources(
                 top.read_text(encoding="utf-8"),
                 current_file=top.resolve(),
                 include_paths=(),

python_library_ralf_model-0.1.0/.gitignore

@@ -1,12 +0,0 @@
-__pycache__/
-*.pyc
-*.pyo
-*.egg-info/
-dist/
-build/
-.venv/
-.env
-.pytest_cache/
-config.yaml
-logs/
-.cursor/