From 05434be32558bef47b65ed0b9c314b1442025c29 Mon Sep 17 00:00:00 2001 From: Samuel Johnson Date: Mon, 2 Feb 2026 15:04:29 -0500 Subject: [PATCH] readme --- README.md | 65 ++++++++++++++---- core.py | 8 ++- .../resources => resources}/datasets/TS.json | 0 .../resources => resources}/datasets/ae.xpt | Bin .../test_Issues/test_CoreIssue208.py | 2 +- .../test_Issues/test_CoreIssue324.py | 2 +- .../test_core/test_validate.py | 6 +- 7 files changed, 61 insertions(+), 22 deletions(-) rename {tests/resources => resources}/datasets/TS.json (100%) rename {tests/resources => resources}/datasets/ae.xpt (100%) diff --git a/README.md b/README.md index 4d0488b20..44e37700c 100644 --- a/README.md +++ b/README.md @@ -21,32 +21,64 @@ Open source offering of the CDISC Rules Engine, a tool designed for validating c 1. Download the latest executable for your operating system from [Releases](https://github.com/cdisc-org/cdisc-rules-engine/releases) 2. Unzip the downloaded file 3. Open a terminal in the unzipped directory -4. Run validation using the commands for your OS as suggested below: +4. **Verify the installation** (optional but recommended): + + **Windows (PowerShell):** -**Windows (PowerShell):** ```bash -.\core.exe validate -s sdtmig -v 3-4 -d C:\path\to\datasets + .\core.exe --help ``` -> **Note for Windows users:** The Windows commands provided in this README are written for PowerShell. While most commands are compatible with both PowerShell and Command Prompt, some adjustments may be necessary when using Command Prompt. If you encounter any issues running these commands in Command Prompt, try using PowerShell or consult the Command Prompt documentation for equivalent commands. +**Linux/Mac:** -**Linux:** ```bash -# First, make it executable (one-time setup) -chmod +x ./core + # First, make it executable (one-time setup) + chmod +x ./core -# Then run validation -./core validate -s sdtmig -v 3-4 -d /path/to/datasets + # Then verify + ./core --help ``` -**Mac:** +This displays all available commands and confirms the executable is working properly. + +**Mac users:** If you encounter security warnings, you may need to remove the quarantine attribute first: + ```bash -# First, remove quarantine and make executable (one-time setup) -xattr -rd com.apple.quarantine . -chmod +x ./core + xattr -rd com.apple.quarantine . +``` + +5. **Run a test validation** (optional): + + CORE includes built-in test commands to verify core functionality: -# Then run validation -./core validate -s sdtmig -v 3-4 -d /path/to/datasets +```bash + # Windows + .\core.exe test-validate json + + # Linux/Mac + ./core test-validate json +``` + +This confirms the executable is working correctly. Test results are automatically cleaned up after completion and cannot be accessed by the user. + +6. **Run your first validation:** + + **Windows (PowerShell):** + +```bash + .\core.exe validate -s sdtmig -v 3-4 -d C:\path\to\datasets +``` + +**Linux:** + +```bash + ./core validate -s sdtmig -v 3-4 -d /path/to/datasets +``` + +**Mac:** + +```bash + ./core validate -s sdtmig -v 3-4 -d /path/to/datasets ``` --- @@ -58,12 +90,14 @@ chmod +x ./core **Prerequisites:** Python 3.12 installed on your system. 1. Clone the repository: + ```bash git clone https://github.com/cdisc-org/cdisc-rules-engine.git cd cdisc-rules-engine ``` 2. Install dependencies: + ```bash pip install -r requirements.txt -r requirements-dev.txt ``` @@ -78,6 +112,7 @@ chmod +x ./core ## Command-line Interface All examples below use `python core.py` for source code users. **If you're using the executable**, replace `python core.py` with: + - **Windows:** `.\core.exe` - **Linux/Mac:** `./core` diff --git a/core.py b/core.py index 6048935c1..c45df0c48 100644 --- a/core.py +++ b/core.py @@ -809,9 +809,13 @@ def list_ct(cache_path: str, subsets: set[str]): @click.command() @click.argument("filetype", type=click.Choice(["json", "xpt"], case_sensitive=False)) def test_validate(filetype): - """**Release Test** validate command for executable.""" + """ + Verify CORE with a test validation. + Requires FILETYPE argument: 'json' or 'xpt'. + Report file is confirmed and automatically cleaned up. For actual validation, use 'validate' command. + """ try: - base_path = os.path.join("tests", "resources", "datasets") + base_path = os.path.join("resources", "datasets") if filetype.lower() == "json": test_file = os.path.join(base_path, "TS.json") output_name = "json_validation_output" diff --git a/tests/resources/datasets/TS.json b/resources/datasets/TS.json similarity index 100% rename from tests/resources/datasets/TS.json rename to resources/datasets/TS.json diff --git a/tests/resources/datasets/ae.xpt b/resources/datasets/ae.xpt similarity index 100% rename from tests/resources/datasets/ae.xpt rename to resources/datasets/ae.xpt diff --git a/tests/QARegressionTests/test_Issues/test_CoreIssue208.py b/tests/QARegressionTests/test_Issues/test_CoreIssue208.py index fcf9ebae0..acd8e243a 100644 --- a/tests/QARegressionTests/test_Issues/test_CoreIssue208.py +++ b/tests/QARegressionTests/test_Issues/test_CoreIssue208.py @@ -44,7 +44,7 @@ def setUpClass(cls): "-v", "3.4", "-dp", - os.path.join("tests", "resources", "datasets", "ae.xpt"), + os.path.join("resources", "datasets", "ae.xpt"), "-of", "JSON", ] diff --git a/tests/QARegressionTests/test_Issues/test_CoreIssue324.py b/tests/QARegressionTests/test_Issues/test_CoreIssue324.py index fb070830f..62e926b38 100644 --- a/tests/QARegressionTests/test_Issues/test_CoreIssue324.py +++ b/tests/QARegressionTests/test_Issues/test_CoreIssue324.py @@ -21,7 +21,7 @@ def setUpClass(cls): "-v", "3.4", "-dp", - os.path.join("tests", "resources", "datasets", "ae.xpt"), + os.path.join("resources", "datasets", "ae.xpt"), ] subprocess.run(command, check=True) diff --git a/tests/QARegressionTests/test_core/test_validate.py b/tests/QARegressionTests/test_core/test_validate.py index afcfbfc99..14748fd3e 100644 --- a/tests/QARegressionTests/test_core/test_validate.py +++ b/tests/QARegressionTests/test_core/test_validate.py @@ -182,7 +182,7 @@ def test_validate_local_rule(self): "-v", "3.4", "-dp", - os.path.join("tests", "resources", "datasets", "ae.xpt"), + os.path.join("resources", "datasets", "ae.xpt"), "-lr", os.path.join("tests", "resources", "rules"), "-r", @@ -203,7 +203,7 @@ def test_validate_local_exclude_rule(self): "-v", "3.4", "-dp", - os.path.join("tests", "resources", "datasets", "ae.xpt"), + os.path.join("resources", "datasets", "ae.xpt"), "-lr", os.path.join("tests", "resources", "rules"), "-er", @@ -226,7 +226,7 @@ def test_validate_include_exclude(self): "-v", "3.4", "-dp", - os.path.join("tests", "resources", "datasets", "ae.xpt"), + os.path.join("resources", "datasets", "ae.xpt"), "-lr", os.path.join("tests", "resources", "rules"), "-r",