{"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,"last_verified":"2026-05-12T08:14:07.643Z","next_check":"2026-06-17T00:00:00.000Z","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,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":1.2,"disk_size":"31.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":1.2,"disk_size":"32M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.4,"disk_size":"34.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.4,"disk_size":"35M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1,"disk_size":"26.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1,"disk_size":"27M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.3,"disk_size":"25.6M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.1,"disk_size":"26M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":1.2,"disk_size":"29.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":1.2,"disk_size":"30M"}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}