{"id":135,"library":"hl7apy","title":"hl7apy – Python HL7 v2 Library","description":"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.","status":"maintenance","version":"1.3.5","language":"python","source_language":"en","source_url":"https://github.com/crs4/hl7apy","tags":["hl7","healthcare","hl7v2","parser","mllp","medical","interoperability","python"],"install":[{"cmd":"pip install hl7apy","lang":"bash","label":"Python"}],"dependencies":[],"imports":[{"note":"parse_message lives in hl7apy.parser, not the top-level package.","wrong":"from hl7apy import parse_message","symbol":"Message","correct":"from hl7apy.parser import parse_message"},{"note":"Message class is in hl7apy.core, not the top-level namespace.","wrong":"from hl7apy import Message","symbol":"Message (construction)","correct":"from hl7apy.core import Message"},{"note":"Segment is in hl7apy.core alongside Message, Group, Field, Component, etc.","symbol":"Segment","correct":"from hl7apy.core import Segment"}],"quickstart":{"code":"from hl7apy.core import Message\nfrom hl7apy.parser import parse_message\n\n# Create a new ADT^A01 message\nm = Message('ADT_A01')\nm.msh.msh_9.msh_9_1 = 'ADT'\nm.msh.msh_9.msh_9_2 = 'A01'\nm.msh.msh_10 = 'MSG00001'\nm.msh.msh_11.msh_11_1 = 'P'\nm.msh.msh_12 = '2.5'\nprint(m.to_er7())\n\n# Parse an existing HL7 message\nraw = 'MSH|^~\\\\&|SENDING|FACILITY|RECEIVING|FACILITY|20230101120000||ADT^A01|MSG00001|P|2.5\\rPID|||12345||Doe^John'\nparsed = parse_message(raw)\nprint(parsed.pid.pid_5.pid_5_1.value)","lang":"python","description":"Create and parse HL7 v2.5 messages using hl7apy."},"warnings":[{"fix":"Use \\r between segments: 'MSH|...|2.5\\rPID|...' and ensure raw strings or proper escaping.","message":"HL7 messages use \\r (carriage return) as the segment separator, not \\n. Using \\n will cause parse failures.","severity":"gotcha","affected_versions":"all"},{"fix":"Pass validation_level=VALIDATION_LEVEL.TOLERANT when constructing or parsing: Message('ADT_A01', validation_level=VALIDATION_LEVEL.TOLERANT)","message":"Validation is strict by default. Setting a field to a value that doesn't match the HL7 datatype raises an exception.","severity":"gotcha","affected_versions":"all"},{"fix":"Use parse_segment() from hl7apy.parser for individual segments, or always pass complete messages to parse_message().","message":"parse_message() expects the full message string including MSH segment. Passing a single segment string will raise InvalidEncodingChars or similar errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Refer to HL7 spec field numbers. Access sending application as m.msh.msh_3, not m.msh.msh_2.","message":"Field/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.","severity":"gotcha","affected_versions":"all"},{"fix":"Use Python 3.6+ and verify examples against current API. Check GitHub issues for compatibility notes.","message":"The library has infrequent releases. Last major update was 1.3.4. Python 2 support was dropped but some legacy patterns remain in documentation.","severity":"deprecated","affected_versions":"all"},{"fix":"Always join segments with \\r when building composite output manually.","message":"to_er7() returns the ER7-encoded string but does not add trailing segment separators. Concatenating multiple to_er7() outputs requires manual \\r insertion.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'2.1':19 '2.7':21 'api':31 'construct':34 'creat':10 'healthcar':48 'high':25 'high-level':24 'hl7':3,13,17,37,47 'hl7apy':1 'hl7v2':49 'interoper':53 'layer':43 'level':26,30 'librari':5,7 'low':29 'low-level':28 'lower':42 'manipul':12 'medic':52 'messag':15,33 'minim':41 'mllp':40,51 'pars':9 'parser':50 'protocol':44 'provid':22 'python':2,6,54 'schema':38 'support':16,46 'transport':45 'v2':4 'v2.x':14 'valid':35 'version':18","created_at":"2026-03-18T16:00:22.745953+00:00","updated_at":"2026-04-16T15:34:51.939385+00:00","problems":[{"fix":"Install the library using pip: `pip install hl7apy`","cause":"The `hl7apy` library is not installed in your Python environment or is not accessible via your Python path.","error":"ModuleNotFoundError: No module named 'hl7apy'"},{"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.","cause":"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.","error":"hl7apy.exceptions.ParserError: Invalid message"},{"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.","cause":"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.","error":"hl7apy.exceptions.ChildNotFound: No child named <ELEMENT_NAME>"},{"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.","cause":"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.","error":"ValueError: <VALUE> is not an HL7 valid date value"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"1.3.5","cli_name":"","cli_version":null,"type":"library","homepage":"http://crs4.github.io/hl7apy/","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/hl7apy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-27","last_verified":"2026-08-26","next_check":"2026-07-27","install_tag":"verified"}}