# HL7Conv2
A high-performance HL7 to JSON converter written in Rust with Python bindings, featuring comprehensive validation and escape sequence support.
## About
This is a Python library written in Rust that provides bidirectional conversion between HL7 (Health Level 7) medical format and JSON, with built-in validation capabilities and support for HL7 escape sequences. The JSON payload after conversion is compatible with Google's HL7 storage parser.
### Features
- **Bidirectional Conversion**: Convert HL7 to JSON and JSON to HL7
- **Built-in Validation**: Comprehensive HL7 message validation with strict/lenient modes
- **Escape Sequence Support**: Full support for HL7 escape sequences and special characters
- **Flexible Control**: Enable/disable validation and escaping independently
- **High Performance**: Written in Rust for optimal speed and memory efficiency
- **Error Handling**: Detailed error messages with context-specific information
## How to install
```
pip install hl7conv2
```
## Examples
### HL7 to JSON Conversion
#### Basic Usage (Validation Disabled by Default)
```python
from hl7conv2 import Hl7Json
# Load HL7 message from file (validation disabled by default)
hl7_obj = Hl7Json.from_file("examples/hl7_example.txt")
json_data = hl7_obj.hl7_json
print(json_data)
# Load from file with custom settings
hl7_obj = Hl7Json.from_file(
"examples/hl7_example.txt",
validation_enabled=True,
strict_validation=False,
escaping_enabled=True
)
# Check validation settings
print(f"Validation enabled: {hl7_obj.validation_enabled}")
print(f"Strict validation: {hl7_obj.strict_validation}")
print(f"Escaping enabled: {hl7_obj.escaping_enabled}")
```
#### Load HL7 from string and convert to JSON
```python
from hl7conv2 import Hl7Json
hl7_string = """MSH|^~\\&|ADT1|HOSPITAL|LAB|HOSPITAL|20240101120000|SECURITY|ADT^A01^ADT_A01|MSG00001|T|2.5.1
PID|1||PATID1234||DOE^JOHN||19800101|M"""
# Basic usage (default settings)
hl7_obj = Hl7Json(hl7_string)
json_data = hl7_obj.hl7_json
print(json_data)
# Create with custom settings
hl7_obj = Hl7Json(
hl7_string,
validation_enabled=True,
strict_validation=False,
escaping_enabled=True
)
```
#### Custom Validation and Escaping Settings
```python
from hl7conv2 import Hl7Json
# Create with default settings and configure at runtime
hl7_obj = Hl7Json("MSH|^~\\&|ADT1|HOSPITAL|...")
# Configure validation and escaping
hl7_obj.validation_enabled = True
hl7_obj.strict_validation = False # Use lenient validation
hl7_obj.escaping_enabled = True # Enable escape sequence processing
# Validate with custom settings
hl7_obj.validate(strict_mode=False, validate_required_fields=True)
```
#### Process Invalid Messages
```python
from hl7conv2 import Hl7Json
# Process invalid HL7 messages without validation
hl7_obj = Hl7Json("INVALID|SEGMENT")
hl7_obj.validation_enabled = False
json_data = hl7_obj.hl7_json # Processes without validation
```
#### Escape Sequence Handling
```python
from hl7conv2 import Hl7Json
hl7_obj = Hl7Json("MSH|^~\\&|ADT1|HOSPITAL")
# Check current settings
print(f"Escaping enabled: {hl7_obj.escaping_enabled}")
print(f"Validation enabled: {hl7_obj.validation_enabled}")
```
### JSON to HL7 Conversion
#### Load JSON from file and convert to HL7
```python
from hl7conv2 import JsonHl7
# Load JSON data from file
json_hl7 = JsonHl7.from_file("examples/json_example.json")
hl7_string = json_hl7.hl7_string
print(hl7_string)
```
#### Create JSON data programmatically and convert to HL7
```python
from hl7conv2 import JsonHl7
# Create JSON data representing HL7 segments
json_data = [
{
"segment_name": "MSH",
"1": "^~\\&",
"2": "ADT1",
"3": "HOSPITAL",
"4": "LAB",
"5": "HOSPITAL",
"6": "20240101120000",
"7": "SECURITY",
"8.1": "ADT",
"8.2": "A01",
"8.3": "ADT_A01",
"9": "MSG00001",
"10": "T",
"11": "2.5.1"
},
{
"segment_name": "PID",
"1": "1",
"3.1": "PATID1234",
"3.2": "5",
"3.3": "M11",
"5.1": "DOE",
"5.2": "JOHN",
"7": "19800101",
"8": "M"
}
]
json_hl7 = JsonHl7(json_data)
hl7_string = json_hl7.hl7_string
print(hl7_string)
```
#### Access JSON data
```python
from hl7conv2 import JsonHl7
json_hl7 = JsonHl7.from_file("examples/json_example.json")
print(json_hl7.json_data)
```
### JSON Format Structure
The JSON format uses the following structure:
- **List of dictionaries**: Each dictionary represents an HL7 segment
- **`segment_name`**: Contains the segment type (MSH, PID, EVN, etc.)
- **Numeric keys**: Field positions (1, 2, 3, etc.)
- **Dot notation**: Field components (3.1, 3.2, 3.3 for field 3 components)
- **Empty strings**: Represent empty fields
#### Example JSON Structure:
```json
[
{
"segment_name": "MSH",
"1": "^~\\&",
"2": "ADT1",
"3": "HOSPITAL",
"8.1": "ADT",
"8.2": "A01",
"8.3": "ADT_A01"
},
{
"segment_name": "PID",
"1": "1",
"3.1": "PATID1234",
"3.2": "5",
"3.3": "M11"
}
]
```
This converts to:
```
MSH|^~\\&|ADT1|HOSPITAL|||||ADT^A01^ADT_A01
PID|1||PATID1234^5^M11
```
## Validation Features
### Built-in Validation
The `Hl7Json` class includes comprehensive validation capabilities:
#### Validation Modes
- **Strict Mode**: Full validation including HL7 version compatibility, message type format, and required segments
- **Lenient Mode**: Basic structure validation with optional required field validation
#### Properties and Settings
```python
# Check current settings
print(f"Validation enabled: {hl7_obj.validation_enabled}")
print(f"Strict validation: {hl7_obj.strict_validation}")
print(f"Escaping enabled: {hl7_obj.escaping_enabled}")
```
#### Validation Methods
```python
# Validate manually
try:
hl7_obj.validate()
print("Message is valid")
except ValueError as e:
print(f"Validation error: {e}")
# Custom validation settings
hl7_obj.validate(
strict_mode=True,
validate_required_fields=True
)
# Enable/disable validation and escaping
hl7_obj.validation_enabled = True
hl7_obj.strict_validation = True
hl7_obj.escaping_enabled = True
```
### Error Handling
The library provides detailed error messages for various scenarios:
- **Validation Errors**: Specific validation failures with context
- **Parsing Errors**: Line-specific parsing issues
- **Field Errors**: Field-specific problems with segment and field information
- **Component Errors**: Component-specific issues with detailed location
## Bidirectional Conversion Example
```python
from hl7conv2 import Hl7Json, JsonHl7
# Original HL7 message
original_hl7 = "MSH|^~\\&|ADT1|HOSPITAL|LAB|HOSPITAL|20240101120000|SECURITY|ADT^A01^ADT_A01|MSG00001|T|2.5.1"
# HL7 → JSON → HL7
hl7_obj = Hl7Json(original_hl7)
json_data = hl7_obj.hl7_json
json_hl7 = JsonHl7(json_data)
converted_hl7 = json_hl7.hl7_string
print(f"Original: {original_hl7}")
print(f"Converted: {converted_hl7}")
print(f"Match: {original_hl7 == converted_hl7}")
```
## API Reference
### Hl7Json Class
#### Constructors
- `Hl7Json(hl7_string, validation_enabled=None, strict_validation=None, escaping_enabled=None)` - Create with optional settings
- `Hl7Json.from_file(path, validation_enabled=None, strict_validation=None, escaping_enabled=None)` - Load from file with optional settings
#### Properties
- `hl7_string` - Original HL7 message string
- `validation_enabled` - Whether validation is enabled
- `strict_validation` - Whether strict validation mode is used
- `escaping_enabled` - Whether escaping is enabled during parsing
- `hl7_json` - Converted JSON data (triggers validation if enabled)
#### Methods
- `validate(strict_mode=None, validate_required_fields=None)` - Validate the message manually with optional custom settings
**Note:** Validation is lazy - it only occurs when explicitly called via `validate()` or when accessing the `hl7_json` property (if `validation_enabled=True`). Constructors do not perform automatic validation.
### JsonHl7 Class
#### Constructors
- `JsonHl7(json_data)` - Create from JSON data
- `JsonHl7.from_file(path)` - Load JSON from file
#### Properties
- `json_data` - Original JSON data
- `hl7_string` - Converted HL7 message string
## Development
This library is built with:
- **Rust** - Core conversion logic with high performance
- **PyO3** - Python bindings for seamless integration
- **Maturin** - Build system for Python extensions
- **Serde** - Fast serialization/deserialization
- **ThisError** - Comprehensive error handling
### Key Features
- **Performance Optimizations**: Serde integration and memory-efficient parsing
- **Escape Sequence Support**: Full HL7 escape sequence handling
- **Comprehensive Validation**: Built-in validation with configurable strictness
- **Error Handling**: Detailed, context-specific error messages
- **Type Safety**: Full Python type hints and stubs
Raw data
{
"_id": null,
"home_page": "https://github.com/IlyaKalosha/hl7conv2",
"name": "hl7conv2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "hl7, healthcare, json, converter, medical, health-level-7",
"author": null,
"author_email": "Ilya Kalosha <kalosha.ilya@yandex.com>",
"download_url": null,
"platform": null,
"description": "# HL7Conv2\n\nA high-performance HL7 to JSON converter written in Rust with Python bindings, featuring comprehensive validation and escape sequence support.\n\n## About\nThis is a Python library written in Rust that provides bidirectional conversion between HL7 (Health Level 7) medical format and JSON, with built-in validation capabilities and support for HL7 escape sequences. The JSON payload after conversion is compatible with Google's HL7 storage parser.\n\n### Features\n\n- **Bidirectional Conversion**: Convert HL7 to JSON and JSON to HL7\n- **Built-in Validation**: Comprehensive HL7 message validation with strict/lenient modes\n- **Escape Sequence Support**: Full support for HL7 escape sequences and special characters\n- **Flexible Control**: Enable/disable validation and escaping independently\n- **High Performance**: Written in Rust for optimal speed and memory efficiency\n- **Error Handling**: Detailed error messages with context-specific information\n\n## How to install\n```\npip install hl7conv2\n```\n\n## Examples\n\n### HL7 to JSON Conversion\n\n#### Basic Usage (Validation Disabled by Default)\n```python\nfrom hl7conv2 import Hl7Json\n\n# Load HL7 message from file (validation disabled by default)\nhl7_obj = Hl7Json.from_file(\"examples/hl7_example.txt\")\njson_data = hl7_obj.hl7_json\nprint(json_data)\n\n# Load from file with custom settings\nhl7_obj = Hl7Json.from_file(\n \"examples/hl7_example.txt\",\n validation_enabled=True,\n strict_validation=False,\n escaping_enabled=True\n)\n\n# Check validation settings\nprint(f\"Validation enabled: {hl7_obj.validation_enabled}\")\nprint(f\"Strict validation: {hl7_obj.strict_validation}\")\nprint(f\"Escaping enabled: {hl7_obj.escaping_enabled}\")\n```\n\n#### Load HL7 from string and convert to JSON\n```python\nfrom hl7conv2 import Hl7Json\n\nhl7_string = \"\"\"MSH|^~\\\\&|ADT1|HOSPITAL|LAB|HOSPITAL|20240101120000|SECURITY|ADT^A01^ADT_A01|MSG00001|T|2.5.1\nPID|1||PATID1234||DOE^JOHN||19800101|M\"\"\"\n\n# Basic usage (default settings)\nhl7_obj = Hl7Json(hl7_string)\njson_data = hl7_obj.hl7_json\nprint(json_data)\n\n# Create with custom settings\nhl7_obj = Hl7Json(\n hl7_string,\n validation_enabled=True,\n strict_validation=False,\n escaping_enabled=True\n)\n```\n\n#### Custom Validation and Escaping Settings\n```python\nfrom hl7conv2 import Hl7Json\n\n# Create with default settings and configure at runtime\nhl7_obj = Hl7Json(\"MSH|^~\\\\&|ADT1|HOSPITAL|...\")\n\n# Configure validation and escaping\nhl7_obj.validation_enabled = True\nhl7_obj.strict_validation = False # Use lenient validation\nhl7_obj.escaping_enabled = True # Enable escape sequence processing\n\n# Validate with custom settings\nhl7_obj.validate(strict_mode=False, validate_required_fields=True)\n```\n\n#### Process Invalid Messages\n```python\nfrom hl7conv2 import Hl7Json\n\n# Process invalid HL7 messages without validation\nhl7_obj = Hl7Json(\"INVALID|SEGMENT\")\nhl7_obj.validation_enabled = False\njson_data = hl7_obj.hl7_json # Processes without validation\n```\n\n#### Escape Sequence Handling\n```python\nfrom hl7conv2 import Hl7Json\n\nhl7_obj = Hl7Json(\"MSH|^~\\\\&|ADT1|HOSPITAL\")\n\n\n# Check current settings\nprint(f\"Escaping enabled: {hl7_obj.escaping_enabled}\")\nprint(f\"Validation enabled: {hl7_obj.validation_enabled}\")\n```\n\n### JSON to HL7 Conversion\n\n#### Load JSON from file and convert to HL7\n```python\nfrom hl7conv2 import JsonHl7\n\n# Load JSON data from file\njson_hl7 = JsonHl7.from_file(\"examples/json_example.json\")\nhl7_string = json_hl7.hl7_string\nprint(hl7_string)\n```\n\n#### Create JSON data programmatically and convert to HL7\n```python\nfrom hl7conv2 import JsonHl7\n\n# Create JSON data representing HL7 segments\njson_data = [\n {\n \"segment_name\": \"MSH\",\n \"1\": \"^~\\\\&\",\n \"2\": \"ADT1\",\n \"3\": \"HOSPITAL\",\n \"4\": \"LAB\",\n \"5\": \"HOSPITAL\",\n \"6\": \"20240101120000\",\n \"7\": \"SECURITY\",\n \"8.1\": \"ADT\",\n \"8.2\": \"A01\",\n \"8.3\": \"ADT_A01\",\n \"9\": \"MSG00001\",\n \"10\": \"T\",\n \"11\": \"2.5.1\"\n },\n {\n \"segment_name\": \"PID\",\n \"1\": \"1\",\n \"3.1\": \"PATID1234\",\n \"3.2\": \"5\",\n \"3.3\": \"M11\",\n \"5.1\": \"DOE\",\n \"5.2\": \"JOHN\",\n \"7\": \"19800101\",\n \"8\": \"M\"\n }\n]\n\njson_hl7 = JsonHl7(json_data)\nhl7_string = json_hl7.hl7_string\nprint(hl7_string)\n```\n\n#### Access JSON data\n```python\nfrom hl7conv2 import JsonHl7\n\njson_hl7 = JsonHl7.from_file(\"examples/json_example.json\")\nprint(json_hl7.json_data)\n```\n\n### JSON Format Structure\n\nThe JSON format uses the following structure:\n\n- **List of dictionaries**: Each dictionary represents an HL7 segment\n- **`segment_name`**: Contains the segment type (MSH, PID, EVN, etc.)\n- **Numeric keys**: Field positions (1, 2, 3, etc.)\n- **Dot notation**: Field components (3.1, 3.2, 3.3 for field 3 components)\n- **Empty strings**: Represent empty fields\n\n#### Example JSON Structure:\n```json\n[\n {\n \"segment_name\": \"MSH\",\n \"1\": \"^~\\\\&\",\n \"2\": \"ADT1\",\n \"3\": \"HOSPITAL\",\n \"8.1\": \"ADT\",\n \"8.2\": \"A01\",\n \"8.3\": \"ADT_A01\"\n },\n {\n \"segment_name\": \"PID\",\n \"1\": \"1\",\n \"3.1\": \"PATID1234\",\n \"3.2\": \"5\",\n \"3.3\": \"M11\"\n }\n]\n```\n\nThis converts to:\n```\nMSH|^~\\\\&|ADT1|HOSPITAL|||||ADT^A01^ADT_A01\nPID|1||PATID1234^5^M11\n```\n\n## Validation Features\n\n### Built-in Validation\n\nThe `Hl7Json` class includes comprehensive validation capabilities:\n\n#### Validation Modes\n- **Strict Mode**: Full validation including HL7 version compatibility, message type format, and required segments\n- **Lenient Mode**: Basic structure validation with optional required field validation\n\n#### Properties and Settings\n```python\n# Check current settings\nprint(f\"Validation enabled: {hl7_obj.validation_enabled}\")\nprint(f\"Strict validation: {hl7_obj.strict_validation}\")\nprint(f\"Escaping enabled: {hl7_obj.escaping_enabled}\")\n```\n\n#### Validation Methods\n```python\n# Validate manually\ntry:\n hl7_obj.validate()\n print(\"Message is valid\")\nexcept ValueError as e:\n print(f\"Validation error: {e}\")\n\n# Custom validation settings\nhl7_obj.validate(\n strict_mode=True,\n validate_required_fields=True\n)\n\n# Enable/disable validation and escaping\nhl7_obj.validation_enabled = True\nhl7_obj.strict_validation = True\nhl7_obj.escaping_enabled = True\n```\n\n### Error Handling\n\nThe library provides detailed error messages for various scenarios:\n- **Validation Errors**: Specific validation failures with context\n- **Parsing Errors**: Line-specific parsing issues\n- **Field Errors**: Field-specific problems with segment and field information\n- **Component Errors**: Component-specific issues with detailed location\n\n## Bidirectional Conversion Example\n\n```python\nfrom hl7conv2 import Hl7Json, JsonHl7\n\n# Original HL7 message\noriginal_hl7 = \"MSH|^~\\\\&|ADT1|HOSPITAL|LAB|HOSPITAL|20240101120000|SECURITY|ADT^A01^ADT_A01|MSG00001|T|2.5.1\"\n\n# HL7 \u2192 JSON \u2192 HL7\nhl7_obj = Hl7Json(original_hl7)\njson_data = hl7_obj.hl7_json\njson_hl7 = JsonHl7(json_data)\nconverted_hl7 = json_hl7.hl7_string\n\nprint(f\"Original: {original_hl7}\")\nprint(f\"Converted: {converted_hl7}\")\nprint(f\"Match: {original_hl7 == converted_hl7}\")\n```\n\n## API Reference\n\n### Hl7Json Class\n\n#### Constructors\n- `Hl7Json(hl7_string, validation_enabled=None, strict_validation=None, escaping_enabled=None)` - Create with optional settings\n- `Hl7Json.from_file(path, validation_enabled=None, strict_validation=None, escaping_enabled=None)` - Load from file with optional settings\n\n#### Properties\n- `hl7_string` - Original HL7 message string\n- `validation_enabled` - Whether validation is enabled\n- `strict_validation` - Whether strict validation mode is used\n- `escaping_enabled` - Whether escaping is enabled during parsing\n- `hl7_json` - Converted JSON data (triggers validation if enabled)\n\n#### Methods\n- `validate(strict_mode=None, validate_required_fields=None)` - Validate the message manually with optional custom settings\n\n**Note:** Validation is lazy - it only occurs when explicitly called via `validate()` or when accessing the `hl7_json` property (if `validation_enabled=True`). Constructors do not perform automatic validation.\n\n### JsonHl7 Class\n\n#### Constructors\n- `JsonHl7(json_data)` - Create from JSON data\n- `JsonHl7.from_file(path)` - Load JSON from file\n\n#### Properties\n- `json_data` - Original JSON data\n- `hl7_string` - Converted HL7 message string\n\n## Development\n\nThis library is built with:\n- **Rust** - Core conversion logic with high performance\n- **PyO3** - Python bindings for seamless integration\n- **Maturin** - Build system for Python extensions\n- **Serde** - Fast serialization/deserialization\n- **ThisError** - Comprehensive error handling\n\n### Key Features\n- **Performance Optimizations**: Serde integration and memory-efficient parsing\n- **Escape Sequence Support**: Full HL7 escape sequence handling\n- **Comprehensive Validation**: Built-in validation with configurable strictness\n- **Error Handling**: Detailed, context-specific error messages\n- **Type Safety**: Full Python type hints and stubs\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A high-performance HL7 to JSON converter written in Rust with Python bindings",
"version": "0.2.0",
"project_urls": {
"Change Log": "https://github.com/IlyaKalosha/hl7conv2/releases",
"Homepage": "https://github.com/IlyaKalosha/hl7conv2",
"Issues": "https://github.com/IlyaKalosha/hl7conv2/issues"
},
"split_keywords": [
"hl7",
" healthcare",
" json",
" converter",
" medical",
" health-level-7"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4f99dfb81b4c08e0df94bb3a7a1c2e9756eefc78ce74374ccd7846f297c64d28",
"md5": "29fca0500f7700f87de517bfc03e2385",
"sha256": "84bb012738f2ff9f5b6fd5de373aa8fd3784f625c90826f2d5b82c60ecc9d521"
},
"downloads": -1,
"filename": "hl7conv2-0.2.0-cp313-cp313-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "29fca0500f7700f87de517bfc03e2385",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.8",
"size": 332475,
"upload_time": "2025-10-10T09:32:30",
"upload_time_iso_8601": "2025-10-10T09:32:30.398767Z",
"url": "https://files.pythonhosted.org/packages/4f/99/dfb81b4c08e0df94bb3a7a1c2e9756eefc78ce74374ccd7846f297c64d28/hl7conv2-0.2.0-cp313-cp313-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 09:32:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IlyaKalosha",
"github_project": "hl7conv2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hl7conv2"
}
JSON
