Metadata-Version: 2.4
Name: defineutils
Version: 0.2.0
Summary: CDISC Define-XML v2.1 utilities
Author-email: Sam Hume <swhume@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Sam Hume
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/swhume/defineutils
Keywords: define.xml,Define-XML,CDISC
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: elementpath>=5.0.4
Requires-Dist: lxml>=6.0.1
Requires-Dist: xmlschema>=4.1.0
Requires-Dist: tomli; python_version < "3.11"
Dynamic: license-file

# defineutils

## CDISC Define-XML v2.1 utilities

The defineutils package currently includes 2 modules:
1. `definehtml.py`: transforms a define.xml into a define.html using the stylesheet
2. `validate.py`: schema validates a define.xml file

The `definehtml.py` module includes the Define-XML v2.1 style sheet to simplify usage. It generates a define.html file,
or alternatively will generate an HTML string.

The `validate.py` module includes the Define-XML v2.1 schema to simplify usage. It schema validates a define.xml file
and returns a define.xml is valid message to indicate success, or a detailed message documenting the schema validation
issues.

## Using defineutils

Currently, defineutils contains 2 modules, one for generating an HTML rendition and one for schema validation.

Example code used to generate a define.html from a define.xml:
```python
from pathlib import Path
from defineutils.definehtml import DefineHtml, DefineHtmlGenerationError

out_file = Path(__file__).parent.joinpath("define.html")
dh = DefineHtml(Path(__file__).parent.joinpath("define.xml"))
dh.transform_to_html_file(out_file)
```

The above code applies the Define-XML v2.1 stylesheet to the define.xml to generation the define.html file. The 
stylesheet is embedded in the module. For error handling, use the custom DefineHtmlGenerationError exception.

Example code used to schema validate a define.xml:
```python
from pathlib import Path
from defineutils.validate import DefineSchemaValidator, DefineSchemaValidationError

validator = DefineSchemaValidator(Path(__file__).parent.joinpath("define.xml"))
try:
    result = validator.validate_define_file()
except DefineSchemaValidationError as e:
    print(e)
```

The above code schema validates the specified define.xml file. The Define-XML v2.1 schema is embedded into the module.
The schema validation errors are reported via the DefineSchemaValidationError exception.

## Running defineutils from the Command-line

When you run a module with the -m switch it will execute the defineutils modules from the command-line. For example,
to transform a define.xml file into HTML using the stylesheet, the following command-line example executes the module
to generate define.html. The -m parameter instructs Python to run the module as an application. The definehtml program
uses the -d parameter to specify the define.xml file path and the -o to specify the define.html file path.

```commandline
python3 -m defineutils.definehtml -d tests/define.xml -o tests/define.html
```

The validate command can be executed using the command-line the same way. For validate, only the -d parameter is 
required to indicate the file path of the define.xml to validate.

```commandline
python3 -m defineutils.validate -d tests/define.xml
```

If you are running defineutils from the source code using a virtual environment, you may need to activate that virtual
environment before running the code from the command-line.

```commandline
source .venv/bin/activate
python3 -m defineutils.validate -d tests/define.xml
```
