Metadata-Version: 2.4
Name: defineutils
Version: 0.2.1
Summary: CDISC Define-XML v2.1 utilities
Author-email: Sam Hume <swhume@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/swhume/defineutils
Keywords: define.xml,Define-XML,CDISC
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
```
