hl7types 0.1.0__tar.gz

hl7types-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keiron O'Shea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hl7types-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: hl7types
+Version: 0.1.0
+Summary: Typed, Pydantic-powered HL7 v2 models with built-in ER7 and XML serialisation
+Author-email: Keiron O'Shea <keiron@keiron.xyz>
+License: MIT
+Project-URL: Homepage, https://github.com/KeironO/hl7types
+Project-URL: Repository, https://github.com/KeironO/hl7types
+Project-URL: Issues, https://github.com/KeironO/hl7types/issues
+Keywords: hl7,hl7v2,healthcare,interoperability,pydantic,er7,xml,fhir,clinical,messaging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.13.4
+Dynamic: license-file
+
+# hl7types
+
+HL7 v2 (Health Level Seven Version 2) is the most widely deployed healthcare messaging standard in the world, used to exchange clinical and administrative data between hospital systems, laboratories, pharmacies, and other healthcare applications. It defines a pipe-delimited wire format (ER7) for encoding messages such as patient admissions, lab results, and order requests, and is the backbone of interoperability in the majority of existing healthcare infrastructure globally.
+
+`hl7types` provides typed, Pydantic-powered Python models for HL7 v2 messages, segments, and datatypes, with built-in ER7 and XML serialisation. Models are generated directly from the HL7 specification, giving you full type safety, IDE autocompletion, and validation out of the box.
+
+With thanks to the [fhir.resources](https://github.com/nazrulworld/fhir.resources) project for demonstrating what modern, Pydantic-powered healthcare data tooling can look like.
+
+All HL7 v2 model classes are generated using [hl7-parser](https://github.com/KeironO/hl7-parser).
+
+HL7® is a registered trademark owned by [Health Level Seven International](https://www.hl7.org/legal/trademarks.cfm).
+
+
+## Version info
+
+Each HL7 version is available as a sub-package under `hl7types.hl7.<version>`, where the version string uses underscores in place of dots , so v2.5.1 is at `hl7types.hl7.v2_5_1` and v2.1 is at `hl7types.hl7.v2_1`.
+
+**Available versions:**
+
+- v2.1 (`hl7types.hl7.v2_1`)
+- v2.2 (`hl7types.hl7.v2_2`)
+- v2.3 (`hl7types.hl7.v2_3`)
+- v2.3.1 (`hl7types.hl7.v2_3_1`)
+- v2.4 (`hl7types.hl7.v2_4`)
+- v2.5 (`hl7types.hl7.v2_5`)
+- v2.5.1 (`hl7types.hl7.v2_5_1`)
+- v2.6 (`hl7types.hl7.v2_6`)
+- v2.7 (`hl7types.hl7.v2_7`)
+- v2.7.1 (`hl7types.hl7.v2_7_1`)
+- v2.8 (`hl7types.hl7.v2_8`)
+- v2.8.1 (`hl7types.hl7.v2_8_1`)
+- v2.8.2 (`hl7types.hl7.v2_8_2`)
+
+## Installation
+
+```bash
+pip install hl7types
+```
+
+## Usage
+
+**Example 1:** Construct an ADT^A01 message from typed models and access fields directly:
+
+```python
+>>> from hl7types.hl7.v2_5_1.datatypes import CE, CX, FN, HD, MSG, PT, SAD, TS, VID, XAD, XPN, XTN
+>>> from hl7types.hl7.v2_5_1.messages import ADT_A01
+>>> from hl7types.hl7.v2_5_1.segments import EVN, MSH, PID, PV1
+>>> msh = MSH(
+...     msh_3=HD(hd_1="HL7TYPES"),
+...     msh_4=HD(hd_1="YSBYTY PONTYPANDY"),
+...     msh_5=HD(hd_1="WPAS"),
+...     msh_6=HD(hd_1="YSBYTY CWM YSWYTH"),
+...     msh_7=TS(ts_1="20240101090000"),
+...     msh_9=MSG(msg_1="ADT", msg_2="A01"),
+...     msh_10="MSG000001",
+...     msh_11=PT(pt_1="P"),
+...     msh_12=VID(vid_1="2.5.1"),
+...     msh_17="CYM",
+... )
+>>> evn = EVN(evn_2=TS(ts_1="20260101000000"), evn_3=TS(ts_1="20240101090000"))
+>>> pid = PID(
+...     pid_3=[CX(cx_1="M12345", cx_4=HD(hd_1="WPAS"), cx_5="PI")],
+...     pid_5=[XPN(xpn_1=FN(fn_1="Jones"), xpn_2="Brynn", xpn_5="Mr")],
+...     pid_7=TS(ts_1="19930707"),
+...     pid_8="M",
+...     pid_11=[XAD(xad_1=SAD(sad_1="18 Stryd Mill"), xad_3="Pontypandy", xad_5="CF41 7ZQ", xad_6="CYM", xad_7="H")],
+...     pid_13=[XTN(xtn_1="0118 999 881 999 119 725 3", xtn_2="PRN", xtn_3="PH")],
+...     pid_15=CE(ce_1="cy", ce_2="Cymraeg"),
+... )
+>>> msg = ADT_A01(MSH=msh, EVN=evn, PID=pid, PV1=PV1(pv1_2="I"))
+>>> isinstance(msg.PID.pid_5[0], XPN)
+True
+>>> msg.PID.pid_5[0].xpn_1.fn_1
+'Jones'
+>>> msg.PID.pid_8
+'M'
+```
+
+---
+
+**Example 2:** Encode to ER7 (pipe-delimited):
+
+```python
+>>> er7 = msg.model_dump_er7()
+>>> for segment in er7.split("\r"):
+...     print(segment)
+MSH|^~\&|HL7TYPES|YSBYTY PONTYPANDY|WPAS|YSBYTY CWM YSWYTH|20240101090000||ADT^A01|MSG000001|P|2.5.1|||||CYM
+EVN||20260101000000|20240101090000
+PID|||M12345^^^WPAS^PI||Jones^Brynn^^^Mr||19930707|M|||18 Stryd Mill^^Pontypandy^Rhondda Cynon Taf^CF41 7ZQ^CYM^H||0118 999 881 999 119 725 3^PRN^PH||cy^Cymraeg
+PV1||I
+```
+
+---
+
+**Example 3:** Decode an ER7 string back into typed models:
+
+```python
+>>> decoded = ADT_A01.model_validate_er7(er7)
+>>> isinstance(decoded.PID.pid_5[0], XPN)
+True
+>>> decoded.PID.pid_5[0].xpn_1.fn_1
+'Jones'
+>>> decoded.PID.pid_8
+'M'
+```
+
+---
+
+**Example 4:** Standard Pydantic serialisation is available on all models:
+
+```python
+>>> import json
+>>> data = json.loads(msg.PID.model_dump_json())
+>>> data["PID.8"]
+'M'
+```
+
+---
+
+**Example 5:** Type validation is enforced , passing the wrong type raises a `ValidationError`:
+
+```python
+>>> from pydantic import ValidationError
+>>> try:
+...     PID(pid_3="not-a-list")
+... except ValidationError as e:
+...     print(e)
+2 validation errors for PID
+pid_3
+  Input should be a valid list [type=list_type, input_value='not-a-list', input_type=str]
+    For further information visit https://errors.pydantic.dev/2.13/v/list_type
+pid_5
+  Field required [type=missing, input_value={'pid_3': 'not-a-list'}, input_type=dict]
+    For further information visit https://errors.pydantic.dev/2.13/v/missing
+```
+
+---
+
+**Example 6:** Fields accept human-readable aliases as well as the positional names , all three forms are equivalent:
+
+```python
+>>> from hl7types.hl7.v2_5_1.segments import MSH
+>>> from hl7types.hl7.v2_5_1.datatypes import HD
+>>> # these are all the same field
+>>> MSH(msh_3=HD(hd_1="HL7TYPES")).msh_3.hd_1
+'HL7TYPES'
+>>> MSH(sending_application=HD(hd_1="HL7TYPES")).msh_3.hd_1
+'HL7TYPES'
+>>> MSH(**{"MSH.3": HD(hd_1="HL7TYPES")}).msh_3.hd_1
+'HL7TYPES'
+```
+
+---
+
+**Example 7:** Encode to XML:
+
+```python
+>>> print(msg.model_dump_xml())
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?><ADT_A01 xmlns="urn:hl7-org:v2xml">
+    <MSH>
+        <MSH.1>|</MSH.1>
+        <MSH.2>^~\&amp;</MSH.2>
+        <MSH.3>
+            ...
+```
+
+## License
+
+Proudly licensed under the MIT License. See [LICENSE](LICENSE) for details.

hl7types-0.1.0/README.md

@@ -0,0 +1,172 @@
+# hl7types
+
+HL7 v2 (Health Level Seven Version 2) is the most widely deployed healthcare messaging standard in the world, used to exchange clinical and administrative data between hospital systems, laboratories, pharmacies, and other healthcare applications. It defines a pipe-delimited wire format (ER7) for encoding messages such as patient admissions, lab results, and order requests, and is the backbone of interoperability in the majority of existing healthcare infrastructure globally.
+
+`hl7types` provides typed, Pydantic-powered Python models for HL7 v2 messages, segments, and datatypes, with built-in ER7 and XML serialisation. Models are generated directly from the HL7 specification, giving you full type safety, IDE autocompletion, and validation out of the box.
+
+With thanks to the [fhir.resources](https://github.com/nazrulworld/fhir.resources) project for demonstrating what modern, Pydantic-powered healthcare data tooling can look like.
+
+All HL7 v2 model classes are generated using [hl7-parser](https://github.com/KeironO/hl7-parser).
+
+HL7® is a registered trademark owned by [Health Level Seven International](https://www.hl7.org/legal/trademarks.cfm).
+
+
+## Version info
+
+Each HL7 version is available as a sub-package under `hl7types.hl7.<version>`, where the version string uses underscores in place of dots , so v2.5.1 is at `hl7types.hl7.v2_5_1` and v2.1 is at `hl7types.hl7.v2_1`.
+
+**Available versions:**
+
+- v2.1 (`hl7types.hl7.v2_1`)
+- v2.2 (`hl7types.hl7.v2_2`)
+- v2.3 (`hl7types.hl7.v2_3`)
+- v2.3.1 (`hl7types.hl7.v2_3_1`)
+- v2.4 (`hl7types.hl7.v2_4`)
+- v2.5 (`hl7types.hl7.v2_5`)
+- v2.5.1 (`hl7types.hl7.v2_5_1`)
+- v2.6 (`hl7types.hl7.v2_6`)
+- v2.7 (`hl7types.hl7.v2_7`)
+- v2.7.1 (`hl7types.hl7.v2_7_1`)
+- v2.8 (`hl7types.hl7.v2_8`)
+- v2.8.1 (`hl7types.hl7.v2_8_1`)
+- v2.8.2 (`hl7types.hl7.v2_8_2`)
+
+## Installation
+
+```bash
+pip install hl7types
+```
+
+## Usage
+
+**Example 1:** Construct an ADT^A01 message from typed models and access fields directly:
+
+```python
+>>> from hl7types.hl7.v2_5_1.datatypes import CE, CX, FN, HD, MSG, PT, SAD, TS, VID, XAD, XPN, XTN
+>>> from hl7types.hl7.v2_5_1.messages import ADT_A01
+>>> from hl7types.hl7.v2_5_1.segments import EVN, MSH, PID, PV1
+>>> msh = MSH(
+...     msh_3=HD(hd_1="HL7TYPES"),
+...     msh_4=HD(hd_1="YSBYTY PONTYPANDY"),
+...     msh_5=HD(hd_1="WPAS"),
+...     msh_6=HD(hd_1="YSBYTY CWM YSWYTH"),
+...     msh_7=TS(ts_1="20240101090000"),
+...     msh_9=MSG(msg_1="ADT", msg_2="A01"),
+...     msh_10="MSG000001",
+...     msh_11=PT(pt_1="P"),
+...     msh_12=VID(vid_1="2.5.1"),
+...     msh_17="CYM",
+... )
+>>> evn = EVN(evn_2=TS(ts_1="20260101000000"), evn_3=TS(ts_1="20240101090000"))
+>>> pid = PID(
+...     pid_3=[CX(cx_1="M12345", cx_4=HD(hd_1="WPAS"), cx_5="PI")],
+...     pid_5=[XPN(xpn_1=FN(fn_1="Jones"), xpn_2="Brynn", xpn_5="Mr")],
+...     pid_7=TS(ts_1="19930707"),
+...     pid_8="M",
+...     pid_11=[XAD(xad_1=SAD(sad_1="18 Stryd Mill"), xad_3="Pontypandy", xad_5="CF41 7ZQ", xad_6="CYM", xad_7="H")],
+...     pid_13=[XTN(xtn_1="0118 999 881 999 119 725 3", xtn_2="PRN", xtn_3="PH")],
+...     pid_15=CE(ce_1="cy", ce_2="Cymraeg"),
+... )
+>>> msg = ADT_A01(MSH=msh, EVN=evn, PID=pid, PV1=PV1(pv1_2="I"))
+>>> isinstance(msg.PID.pid_5[0], XPN)
+True
+>>> msg.PID.pid_5[0].xpn_1.fn_1
+'Jones'
+>>> msg.PID.pid_8
+'M'
+```
+
+---
+
+**Example 2:** Encode to ER7 (pipe-delimited):
+
+```python
+>>> er7 = msg.model_dump_er7()
+>>> for segment in er7.split("\r"):
+...     print(segment)
+MSH|^~\&|HL7TYPES|YSBYTY PONTYPANDY|WPAS|YSBYTY CWM YSWYTH|20240101090000||ADT^A01|MSG000001|P|2.5.1|||||CYM
+EVN||20260101000000|20240101090000
+PID|||M12345^^^WPAS^PI||Jones^Brynn^^^Mr||19930707|M|||18 Stryd Mill^^Pontypandy^Rhondda Cynon Taf^CF41 7ZQ^CYM^H||0118 999 881 999 119 725 3^PRN^PH||cy^Cymraeg
+PV1||I
+```
+
+---
+
+**Example 3:** Decode an ER7 string back into typed models:
+
+```python
+>>> decoded = ADT_A01.model_validate_er7(er7)
+>>> isinstance(decoded.PID.pid_5[0], XPN)
+True
+>>> decoded.PID.pid_5[0].xpn_1.fn_1
+'Jones'
+>>> decoded.PID.pid_8
+'M'
+```
+
+---
+
+**Example 4:** Standard Pydantic serialisation is available on all models:
+
+```python
+>>> import json
+>>> data = json.loads(msg.PID.model_dump_json())
+>>> data["PID.8"]
+'M'
+```
+
+---
+
+**Example 5:** Type validation is enforced , passing the wrong type raises a `ValidationError`:
+
+```python
+>>> from pydantic import ValidationError
+>>> try:
+...     PID(pid_3="not-a-list")
+... except ValidationError as e:
+...     print(e)
+2 validation errors for PID
+pid_3
+  Input should be a valid list [type=list_type, input_value='not-a-list', input_type=str]
+    For further information visit https://errors.pydantic.dev/2.13/v/list_type
+pid_5
+  Field required [type=missing, input_value={'pid_3': 'not-a-list'}, input_type=dict]
+    For further information visit https://errors.pydantic.dev/2.13/v/missing
+```
+
+---
+
+**Example 6:** Fields accept human-readable aliases as well as the positional names , all three forms are equivalent:
+
+```python
+>>> from hl7types.hl7.v2_5_1.segments import MSH
+>>> from hl7types.hl7.v2_5_1.datatypes import HD
+>>> # these are all the same field
+>>> MSH(msh_3=HD(hd_1="HL7TYPES")).msh_3.hd_1
+'HL7TYPES'
+>>> MSH(sending_application=HD(hd_1="HL7TYPES")).msh_3.hd_1
+'HL7TYPES'
+>>> MSH(**{"MSH.3": HD(hd_1="HL7TYPES")}).msh_3.hd_1
+'HL7TYPES'
+```
+
+---
+
+**Example 7:** Encode to XML:
+
+```python
+>>> print(msg.model_dump_xml())
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?><ADT_A01 xmlns="urn:hl7-org:v2xml">
+    <MSH>
+        <MSH.1>|</MSH.1>
+        <MSH.2>^~\&amp;</MSH.2>
+        <MSH.3>
+            ...
+```
+
+## License
+
+Proudly licensed under the MIT License. See [LICENSE](LICENSE) for details.

hl7types-0.1.0/hl7types/__init__.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+# Patches BaseModel.__init_subclass__ so every class defined under hl7types.hl7.*
+# gets model_dump_er7() and model_validate_er7() injected at class-definition time.
+# Scoped to hl7types.hl7.* to avoid polluting unrelated BaseModel subclasses.
+# hl7types must be imported before any hl7types.hl7.* imports for the hook to fire.
+from typing import Any
+
+from pydantic import BaseModel
+
+from hl7types.codecs.er7.decoder import _is_segment_cls, decode_er7, decode_er7_segment
+from hl7types.codecs.er7.encoder import (
+    DEFAULT_ENCODING,
+    EncodingChars,
+    _is_segment,
+    encode_er7,
+    encode_er7_segment,
+)
+from hl7types.codecs.xml.encoder import encode_xml
+
+
+def _dump_er7(
+    self: BaseModel,
+    segment_separator: str = "\r",
+    enc: EncodingChars | None = None,
+) -> str:
+    effective_enc = enc if enc is not None else DEFAULT_ENCODING
+    if _is_segment(self):
+        return encode_er7_segment(self, effective_enc)
+    return encode_er7(self, segment_separator=segment_separator)
+
+
+def _validate_er7(
+    cls: type[BaseModel],
+    wire: str,
+    segment_separator: str = "\r",
+    enc: EncodingChars | None = None,
+) -> BaseModel:
+    effective_enc = enc if enc is not None else DEFAULT_ENCODING
+    if _is_segment_cls(cls):
+        return decode_er7_segment(wire, cls, effective_enc)
+    return decode_er7(wire, msg_cls=cls, segment_separator=segment_separator)
+
+
+def _dump_xml(
+    self: BaseModel,
+    *,
+    pretty: bool = True,
+) -> str:
+    return encode_xml(self, pretty=pretty)
+
+
+def _inject(cls: type) -> None:
+    cls.model_dump_er7 = _dump_er7
+    cls.model_validate_er7 = classmethod(_validate_er7)
+    cls.model_dump_xml = _dump_xml
+
+
+_original_init_subclass = BaseModel.__init_subclass__
+
+
+@classmethod  # type: ignore[misc]
+def _patched_init_subclass(cls, **kwargs: Any) -> None:
+    _original_init_subclass(**kwargs)
+    if cls.__module__.startswith("hl7types.hl7."):
+        _inject(cls)
+
+
+BaseModel.__init_subclass__ = _patched_init_subclass  # type: ignore[method-assign]
+
+
+__all__ = [
+    "EncodingChars",
+    "DEFAULT_ENCODING",
+    "encode_er7",
+    "encode_er7_segment",
+    "decode_er7",
+    "decode_er7_segment",
+    "encode_xml",
+]

hl7types-0.1.0/hl7types/codecs/er7/__init__.py

@@ -0,0 +1,16 @@
+from hl7types.codecs.er7.decoder import decode_er7, decode_er7_segment
+from hl7types.codecs.er7.encoder import (
+    DEFAULT_ENCODING,
+    EncodingChars,
+    encode_er7,
+    encode_er7_segment,
+)
+
+__all__ = [
+    "EncodingChars",
+    "DEFAULT_ENCODING",
+    "encode_er7",
+    "encode_er7_segment",
+    "decode_er7",
+    "decode_er7_segment",
+]