Merge pull request #4 from StructuralPython/releases/v0.2.0

Releases/v0.2.0

Author: connorferster

.gitignore

@@ -152,3 +152,4 @@ cython_debug/
 #.idea/
 tests/test_data/stored_results.xlsx
 /tests/test_data/design
+tests/test_data/~$example_wb.xlsx

README.md

@@ -1,2 +1,94 @@
 # xl-engine
  Use your existing Excel workbooks like they were Python programs: A utility built on XLWings to automate the input, execution, and data retrieval of your existing Excel Workbooks. 
+
+
+## Installation
+
+`pip install xl-engine`
+
+## Basic Usage
+
+### `execute_workbook`
+
+Use `execute_workbook` when you want to execute a workbook once with known, provided parameters.
+
+```python
+import xl_engine as xl
+
+results = xl.execute_workbook(
+    TEST_DATA_DIR / "example_wb.xlsx",
+    cells_to_change = {"B1": 33, "B2": 66},
+    cells_to_retrieve=['B4', 'B5'], # This can either be a list or a dict; see next example
+    sheet_idx=1,
+    new_filepath=TEST_DATA_DIR / "stored_results.xlsx"
+)
+
+# results
+# {'B4': 22.0, 'B5': 11.0}
+```
+
+You can also use a dictionary in `cells_to_retrieve` to meaningfully label the results:
+
+```python
+results2 = xl.execute_workbook(
+    TEST_DATA_DIR / "example_wb.xlsx",
+    cells_to_change = {"B1": 33, "B2": 66},
+    cells_to_retrieve={'B4': "label1", 'B5': "label2"}, # Now a dict
+    sheet_idx=1,
+    new_filepath=TEST_DATA_DIR / "stored_results.xlsx"
+)
+
+# results2
+# {'label1': 44.0, 'label2': 39.599999999999994}
+```
+
+### `excel_runner`
+
+Use `excel_runner` when you want to execute a workbook multiple times (static inputs) with multiple options (dynamic inputs).
+
+```python
+import xl_engine as xl
+
+# Creates a callable with the following function signature: callable(x: float | int) -> bool:
+# When a value is a passed to dcr2, i.e. dcr2(some_value), it will return True if
+# the value is greater-than-or-equal-to 2
+dcr2 = xl.create_condition_check(2, "ge")
+
+# static_inputs will be used to populate each workbook.
+# Within each set of static inputs, a second sub-iteration will occur
+# where the dynamic inputs will be input allowing you to test the
+# results for different "options" of dynamic inputs.
+# If the save conditions pass (return True for all keys), then a copy of the
+# workbook will be saved to disk with the successful inputs recorded.
+# A dictionary of all calculated results will be returned.
+results = xl.excel_runner(
+        TEST_DATA_DIR / "example_wb.xlsx",
+        static_inputs={"B1": [10, 20], "Labels": ["C01", "C02"]},
+        dynamic_inputs={
+            "OptA": {"B2": 22},
+            "OptB": {"B2": 33},
+            "OptC": {"B2": 55},
+        },
+        success_conditions={"B6": dcr2},
+        static_identifier_keys=["Labels"],
+        result_labels={"B6": "meaningful_value"},
+        save_dir=TEST_DATA_DIR / "design"
+)
+```
+
+Return value (for the "example_wb.xlsx" file included in the tests directory):
+
+```python
+{
+    'C01': {
+        'successful_key': None, # None of the options were successful for this case
+        'OptA': {'meaningful_value': 1.2121212121212122}, 
+        'OptB': {'meaningful_value': 0.8080808080808081}, 
+        'OptC': {'meaningful_value': 0.48484848484848486}
+    }, 
+    'C02': {
+        'successful_key': 'OptA', 
+        'meaningful_value': 2.4242424242424243
+    }
+}
+```

src/xl_engine/__init__.py

@@ -3,6 +3,6 @@
 execute, and save Excel workbooks.
 """
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 from xl_engine.excel_engine import create_condition_check, execute_workbook, excel_runner

src/xl_engine/excel_engine.py

@@ -15,7 +15,7 @@ def excel_runner(
     xlsx_filepath,
     static_inputs: dict[str, list],
     dynamic_inputs: dict[str, dict[str, float]],
-    save_conditions: dict[str, callable],
+    success_conditions: dict[str, callable],
     static_identifier_keys: Optional[list[str]] = None,
     result_labels: Optional[dict[str, str]] = None,
     save_dir: Optional[str] = None,
@@ -40,9 +40,9 @@ def excel_runner(
         label to describe the iteration, e.g. the name of the design element.
         The values are dictionaries keyed by cell references with single values which will
         populate the workbook for every static iteration.
-    'save_conditions': a dictionary keyed by cell references whose values are unary callables
+    'success_conditions': a dictionary keyed by cell references whose values are unary callables
         which return a bool when passed the value retrieved from the workbook at the cell 
-        reference during each iteration. If all callables in the 'save_conditions' dict
+        reference during each iteration. If all callables in the 'success_conditions' dict
         return True, then that iteration of the workbook will be saved to disk. Use the
         create_condition_check() function in this module to quickly create such callables.
     'static_identifier_keys': The keys in 'static_inputs', which are not cell references,
@@ -105,7 +105,7 @@ def excel_runner(
                 calculated_results = execute_workbook(
                     xlsx_filepath, 
                     cells_to_change=cells_to_change,
-                    cells_to_retrieve=list(save_conditions.keys()),
+                    cells_to_retrieve=list(success_conditions.keys()),
                     sheet_idx=sheet_idx
                 )
                 if isinstance(result_labels, dict):
@@ -116,7 +116,7 @@ def excel_runner(
                 failed_results.update({design_tag: labeled_results})
 
                 save_condition_acc = []
-                for result_cell_id, save_condition in save_conditions.items():
+                for result_cell_id, save_condition in success_conditions.items():
                     calculated_result = calculated_results[result_cell_id]
                     save_condition_acc.append(save_condition(calculated_result))
                 variations_progress.update(variations_task, advance=1)
@@ -133,7 +133,7 @@ def excel_runner(
                     _ = execute_workbook(
                         xlsx_filepath, 
                         cells_to_change=cells_to_change,
-                        cells_to_retrieve=list(save_conditions.keys()),
+                        cells_to_retrieve=list(success_conditions.keys()),
                         new_filepath=f"{str(save_dir)}/{new_filename}",
                         sheet_idx=sheet_idx,
                     )

tests/test_excel_engine.py

@@ -28,12 +28,12 @@ def test_execute_workbook():
     results2 = xl.execute_workbook(
         TEST_DATA_DIR / "example_wb.xlsx",
         cells_to_change = {"B1": 33, "B2": 66},
-        cells_to_retrieve=['B4', 'B5'],
+        cells_to_retrieve={'B4': "label1", 'B5': "label2"},
         sheet_idx=1,
         new_filepath=TEST_DATA_DIR / "stored_results.xlsx"
     )
-    assert results2['B4'] == 44
-    assert math.isclose(results2['B5'], 39.6)
+    assert results2['label1'] == 44
+    assert math.isclose(results2['label2'], 39.6)
 
     import xlwings as xw
     with xw.Book(TEST_DATA_DIR / "stored_results.xlsx") as wb:
@@ -51,7 +51,7 @@ def test_excel_runner():
             "OptB": {"B2": 33},
             "OptC": {"B2": 55},
         },
-        save_conditions={"B6": dcr2},
+        success_conditions={"B6": dcr2},
         static_identifier_keys=["Labels"],
         result_labels={"B6": "meaningful_value"},
         save_dir=TEST_DATA_DIR / "design"