Merge pull request #146 from Origen-SDK/origen_metal

Reference File API

.github/workflows/publish_metal.yml

@@ -17,7 +17,7 @@ jobs:
         with: 
           maturin-version: v0.11.3-beta.6
           command: build
-          args: --release --no-sdist --manifest-path rust/pyapi_metal/Cargo.toml --interpreter python3.6 python3.7 python3.8 python3.9
+          args: --release --no-sdist --manifest-path rust/pyapi_metal/Cargo.toml --interpreter python3.7 python3.8 python3.9
           manylinux: 2010
           container: quay.io/pypa/manylinux2010_x86_64:2021-08-16-2fbce44
           rust-toolchain: 1.54.0
@@ -28,7 +28,7 @@ jobs:
         with: 
           maturin-version: v0.11.3-beta.6
           command: build
-          args: --release --no-sdist --manifest-path rust/pyapi_metal/Cargo.toml --interpreter C:\hostedtoolcache\windows\Python\3.6.8\x64\python.exe C:\hostedtoolcache\windows\Python\3.7.9\x64\python.exe C:\hostedtoolcache\windows\Python\3.8.10\x64\python.exe C:\hostedtoolcache\windows\Python\3.9.6\x64\python.exe
+          args: --release --no-sdist --manifest-path rust/pyapi_metal/Cargo.toml --interpreter C:\hostedtoolcache\windows\Python\3.7.9\x64\python.exe C:\hostedtoolcache\windows\Python\3.8.10\x64\python.exe C:\hostedtoolcache\windows\Python\3.9.6\x64\python.exe
           target: x86_64-pc-windows-msvc
           rust-toolchain: 1.54.0
 

.github/workflows/regression_test.yml

@@ -6,7 +6,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [3.7, 3.8, 3.9]
 
     runs-on: ${{ matrix.os }}
     env:

python/origen_metal/origen_metal/framework/__init__.py

@@ -0,0 +1,7 @@
+"""
+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
+application framework, but they are not quite as generic as the APIs found in the origen_metal.utils module.
+"""

python/origen_metal/origen_metal/framework/reference_files.py

@@ -0,0 +1,75 @@
+"""
+This module provides an API to implement Origen's reference file system, that is the system
+which records when output files are new or whether they have changed vs. a previously generated
+reference file, allowing the user to decide when and if to save the latest version as a new
+reference.
+
+Under the hood the API fully supports parallel recording of change/new file references, and is
+therefore fully compatible with references being recorded when batch processing on a system
+like LSF.
+"""
+
+
+def set_save_ref_dir(dir: str):
+    """
+    **This must be called before using any other function**.
+    
+    It defines where you want the temporary files (the so called save_refs) to be stored.
+
+    The given directory should not be under revision control.
+    """
+    ...
+
+
+def create_changed_ref(key: str, new_file: str, ref_file: str):
+    """
+    When a change has been detected between a newly created file and reference file, call this
+    to record the change.
+
+    The given key can be later used to apply it (copy the new file over to the reference
+    file location).
+    """
+    ...
+
+
+def create_new_ref(key: str, new_file: str, ref_file: str):
+    """
+    When a new file has been detected (one that doesn't have an existing reference file to compare to),
+    call this to record the new file.
+
+    The given key can be later used to apply it (copy the new file over to the reference
+    file location).
+    """
+    ...
+
+
+def apply_ref(key: str):
+    """
+    Apply's a particular change or new file reference by copying the changed/new file over to the
+    previously given reference file location.
+
+    The key given to this function should match a key previously given to either 
+    origen_metal.framework.create_changed_ref() or origen_metal.framework.create_new_ref()
+    """
+    ...
+
+
+def apply_all_changed_refs():
+    """
+    Apply's all changed references that have been previously registered via origen_metal.framework.create_changed_ref()
+    """
+    ...
+
+
+def apply_all_new_refs():
+    """
+    Apply's all new file references that have been previously registered via origen_metal.framework.create_new_ref()
+    """
+    ...
+
+
+def clear_save_refs():
+    """
+    Clears all previously registered changed or new file references
+    """
+    ...

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

@@ -0,0 +1,38 @@
+from typing import Optional, Tuple, List
+
+
+def has_diffs(
+    file_a: str,
+    file_b: str,
+    ignore_comments: Optional[List[str]] = None,
+    ignore_blocks: Optional[List[Tuple[str, str]]] = None,
+    ignore_blank_lines: bool = True,
+) -> bool:
+    """
+    This function compares the two ASCII files at the given paths and returns True if any
+    differences are found between them.
+
+    Blank lines will be ignored by default, so additional blank lines in one file will
+    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 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_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=[("/*", "*/"), ("{{", "}}")])
+    ```
+    """
+    ...