Final API clean up and documentation

python/origen_metal/origen_metal/framework/__init__.py

@@ -1,5 +1,5 @@
 """
-This module provides APIs that are closely related to creating feature for an application framework
+This module provides APIs that are closely related to creating features for an application framework
 like Origen, e.g. a logging system.
 
 They are generic enough to allow you to use them to create a similar feature in your own

python/origen_metal/origen_metal/utils/__init__.py

@@ -0,0 +1,4 @@
+"""
+This module contains low-level APIs that are very generic and could be used in many
+different applications.
+"""

python/origen_metal/origen_metal/utils/differ.py

@@ -5,7 +5,7 @@ def has_diffs(
     file_a: str,
     file_b: str,
     ignore_comments: Optional[List[str]] = None,
-    ignore_block: Optional[List[Tuple[str, str]]] = None,
+    ignore_blocks: Optional[List[Tuple[str, str]]] = None,
     ignore_blank_lines: bool = True,
 ) -> bool:
     """
@@ -16,16 +16,23 @@ def has_diffs(
     not result in a diff being reported if they are otherwise the same.
 
     Differences in comments can be ignored by specifying the comment char(s) to be used,
-    and also start and end sequences for C-style block comments
-
+    and blocks of content can be ignored (e.g. C-style block comments) by specifying start
+    and end characters.
+    
     # Examples
 
     ```python
     # Ignore Python style comments
     has_diffs("file_a.py", "file_b.py", ignore_comments=["#"])
 
     # Ignore C++ style comments, including blocks
-    has_diffs("file_a.cpp", "file_b.cpp", ignore_comments=["//"], ignore_block=[("/*", "*/")])
+    has_diffs("file_a.cpp", "file_b.cpp", ignore_comments=["//"], ignore_blocks=[("/*", "*/")])
+    
+    # Multiple entries can be given to both the ignore_comments and ignore_blocks arguments
+    has_diffs("file_a.cpp",
+              "file_b.cpp",
+              ignore_comments=["//", "#"],
+              ignore_blocks=[("/*", "*/"), ("{{", "}}")])
     ```
     """
     ...

python/origen_metal/tests/test_differ.py

@@ -13,10 +13,10 @@ def test_basic_operation():
     os.close(fb)
 
     assert (has_diffs(file_a, file_b))
-    assert (not has_diffs(file_a, file_b, ignore_comments="//"))
+    assert (not has_diffs(file_a, file_b, ignore_comments=["//"]))
     assert (has_diffs(file_a,
                       file_b,
-                      ignore_comments="//",
+                      ignore_comments=["//"],
                       ignore_blank_lines=False))
 
 
@@ -40,7 +40,7 @@ def test_basic_suspend_works():
 
     assert (has_diffs(file_a, file_b))
     assert (not has_diffs(
-        file_a, file_b, suspend_on="<START>", resume_on="<STOP>"))
+        file_a, file_b, ignore_blocks=[("<START>", "<STOP>")]))
 
 
 def test_pre_suspend_works():
@@ -62,8 +62,7 @@ def test_pre_suspend_works():
     os.close(fb)
 
     assert (has_diffs(file_a, file_b))
-    assert (has_diffs(file_a, file_b, suspend_on="<START>",
-                      resume_on="<STOP>"))
+    assert (has_diffs(file_a, file_b, ignore_blocks=[("<START>", "<STOP>")]))
 
 
 def test_post_suspend_works():
@@ -85,8 +84,7 @@ def test_post_suspend_works():
     os.close(fb)
 
     assert (has_diffs(file_a, file_b))
-    assert (has_diffs(file_a, file_b, suspend_on="<START>",
-                      resume_on="<STOP>"))
+    assert (has_diffs(file_a, file_b, ignore_blocks=[("<START>", "<STOP>")]))
 
 
 def test_blank_lines_works():
@@ -124,4 +122,4 @@ def test_c_style_comments():
          This part is the same""")
 
     assert (has_diffs(file_a, file_b))
-    assert (not has_diffs(file_a, file_b, suspend_on="/*", resume_on="*/"))
+    assert (not has_diffs(file_a, file_b, ignore_blocks=[("/*", "*/")]))

rust/pyapi_metal/src/utils/differ.rs

@@ -5,14 +5,14 @@ use std::path::Path;
 
 #[pyfunction(
     ignore_comments = "None",
-    ignore_block = "None",
+    ignore_blocks = "None",
     ignore_blank_lines = "true"
 )]
 pub fn has_diffs(
     file_a: &str,
     file_b: &str,
     ignore_comments: Option<Vec<String>>,
-    ignore_block: Option<Vec<Vec<String>>>,
+    ignore_blocks: Option<Vec<Vec<String>>>,
     ignore_blank_lines: bool,
 ) -> PyResult<bool> {
     let mut differ = ASCIIDiffer::new(Path::new(file_a), Path::new(file_b));
@@ -22,9 +22,9 @@ pub fn has_diffs(
             differ.ignore_comments(&c)?;
         }
     }
-    if let Some(blocks) = ignore_block {
+    if let Some(blocks) = ignore_blocks {
         for b in blocks {
-            differ.suspend_on(&c)?;
+            differ.ignore_block(&b[0], &b[1])?;
         }
     }
     Ok(differ.has_diffs()?)