hl7apy

library1.3.5pypypi✓ verified 25d ago

Python library for parsing, creating, and manipulating HL7 v2.x messages. Supports HL7 versions 2.1 through 2.7, provides both high-level and low-level APIs for message construction, validation against HL7 schemas, and MLLP (Minimal Lower Layer Protocol) transport support.

serialization

pip install hl7apy

package ↗homepage ↗

INSTALL

IMPORT

SIG · HL7APY

hl7apy

serializationpythonv1.3.5

Install

3.1s avg

Import

18ms

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.018s · 31.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.1s · import 0.018s · 32MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Message

✓ from hl7apy.parser import parse_message

✗ from hl7apy import parse_message

parse_message lives in hl7apy.parser, not the top-level package.

Message (construction)

✓ from hl7apy.core import Message

✗ from hl7apy import Message

Message class is in hl7apy.core, not the top-level namespace.

Segment

✓ from hl7apy.core import Segment

Segment is in hl7apy.core alongside Message, Group, Field, Component, etc.

Create and parse HL7 v2.5 messages using hl7apy.

from hl7apy.core import Message from hl7apy.parser import parse_message # Create a new ADT^A01 message m = Message('ADT_A01') m.msh.msh_9.msh_9_1 = 'ADT' m.msh.msh_9.msh_9_2 = 'A01' m.msh.msh_10 = 'MSG00001' m.msh.msh_11.msh_11_1 = 'P' m.msh.msh_12 = '2.5' print(m.to_er7()) # Parse an existing HL7 message raw = 'MSH|^~\\&|SENDING|FACILITY|RECEIVING|FACILITY|20230101120000||ADT^A01|MSG00001|P|2.5\rPID|||12345||Doe^John' parsed = parse_message(raw) print(parsed.pid.pid_5.pid_5_1.value)

Debug

Known issues

gotchaHL7 messages use \r (carriage return) as the segment separator, not \n. Using \n will cause parse failures.

fix

Use \r between segments: 'MSH|...|2.5\rPID|...' and ensure raw strings or proper escaping.

affects: all

gotchaValidation is strict by default. Setting a field to a value that doesn't match the HL7 datatype raises an exception.

fix

Pass validation_level=VALIDATION_LEVEL.TOLERANT when constructing or parsing: Message('ADT_A01', validation_level=VALIDATION_LEVEL.TOLERANT)

affects: all

gotchaparse_message() expects the full message string including MSH segment. Passing a single segment string will raise InvalidEncodingChars or similar errors.

fix

Use parse_segment() from hl7apy.parser for individual segments, or always pass complete messages to parse_message().

affects: all

gotchaField/component access uses 1-based HL7 numbering (e.g., msh_9_1), but the MSH segment's field numbering starts at MSH-1 which is the field separator itself. MSH-3 is the sending application.

fix

Refer to HL7 spec field numbers. Access sending application as m.msh.msh_3, not m.msh.msh_2.

affects: all

deprecatedThe library has infrequent releases. Last major update was 1.3.4. Python 2 support was dropped but some legacy patterns remain in documentation.

fix

Use Python 3.6+ and verify examples against current API. Check GitHub issues for compatibility notes.

affects: all

gotchato_er7() returns the ER7-encoded string but does not add trailing segment separators. Concatenating multiple to_er7() outputs requires manual \r insertion.

fix

Always join segments with \r when building composite output manually.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hl7apy'

The `hl7apy` library is not installed in your Python environment or is not accessible via your Python path.

fix

Install the library using pip: `pip install hl7apy`

hl7apy.exceptions.ParserError: Invalid message

The input string provided to `hl7apy.parser.parse_message` does not conform to the expected HL7 v2 message format or contains invalid delimiters/characters, preventing proper parsing.

fix

Ensure the input string is a valid HL7 v2 message with correct segment delimiters (often `\r` or `\n` needs to be replaced with `\r`), field separators, and an MSH segment. You might need to preprocess the message string, e.g., `message.replace('\n', '\r')` or explicitly set `find_groups=False` if dealing with non-standard messages.

hl7apy.exceptions.ChildNotFound: No child named <ELEMENT_NAME>

You are attempting to access or add an HL7 element (segment, field, component) by a name that is not defined in the HL7 standard structure for the message type and version being used. This often happens in strict validation mode.

fix

Verify the HL7 message structure and element names against the official HL7 specification for your message type and version. If you intend to add a non-standard or 'Z' element, consider using `validation_level=VALIDATION_LEVEL.TOLERANT` during message creation or element assignment.

ValueError: <VALUE> is not an HL7 valid date value

An invalid date, time, or datetime string was assigned to a field or component that expects an HL7-compliant date/time format, and the validation level is set to strict.

fix

Ensure that date/time values adhere to HL7's specified formats (e.g., YYYYMMDD, YYYYMMDDHHMMSS, YYYYMMDDHHMMSS.sss[+/-ZZZZ]). If the format is intentionally non-standard, set the validation level to `VALIDATION_LEVEL.TOLERANT` for the message or element.

Upgrade

Version history

1.3.5latest on PyPI · released Mar 13, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/hl7apy/ ↗

homepagehttp://crs4.github.io/hl7apy/ ↗