pyx12 4.0.0__py3-none-any.whl

pyx12/__init__.py

@@ -0,0 +1,10 @@
+"""
+Validate and transform HIPAA X12 documents
+"""
+
+__author__ = "John Holland <john.holland@swmbh.org>"
+__status__ = "production"
+from .version import __version__ as __version__
+
+__date__ = "2021-05-28"
+__revision__ = ""

pyx12/codes.py

@@ -0,0 +1,120 @@
+######################################################################
+# Copyright
+#   John Holland <john@zoner.org>
+# All rights reserved.
+#
+# This software is licensed as described in the file LICENSE.txt, which
+# you should have received as part of this distribution.
+#
+######################################################################
+
+"""
+External Codes interface
+"""
+
+from __future__ import annotations
+
+import logging
+import os.path
+from importlib.resources import files as _res_files
+from typing import IO, Any, TypedDict
+
+import defusedxml.ElementTree as et
+
+from pyx12.errors import EngineError
+
+
+class CodesError(Exception):
+    """Class for code modules errors."""
+
+
+class _CodeSet(TypedDict):
+    name: str | None
+    dataele: str | None
+    codes: frozenset[str | None]
+
+
+class ExternalCodes:
+    """
+    Validates an ID against an external list of codes
+    """
+
+    codes: dict[str | None, _CodeSet]
+    exclude_list: list[str]
+
+    def __init__(self, base_path: str | None = None, exclude: str | None = None) -> None:
+        """
+        Initialize the external list of codes
+
+        :param base_path: Override directory containing codes.xml.
+            If None, uses package resource folder.
+        :param exclude: comma-separated string of external code names to ignore.
+
+        ``self.codes`` maps codeset_id to ``{'name', 'dataele', 'codes'}``.
+        """
+        logger = logging.getLogger("pyx12")
+        self.codes = {}
+        codes_file = "codes.xml"
+        # ElementTree.parse accepts either text- or binary-mode streams; the
+        # file source differs between override path and bundled package resource.
+        code_fd: IO[Any]
+        if base_path is not None:
+            logger.debug(f"Looking for codes file '{codes_file}' in map_path '{base_path}'")
+            code_fd = open(os.path.join(base_path, codes_file), encoding="utf-8")
+        else:
+            logger.debug(f"Looking for codes file '{codes_file}' in package resources")
+            code_fd = _res_files("pyx12").joinpath("map", codes_file).open("rb")
+
+        self.exclude_list = exclude.split(",") if exclude is not None else []
+        with code_fd:
+            parser = et.XMLParser(encoding="utf-8")
+            for cElem in et.parse(code_fd, parser=parser).iter("codeset"):
+                codeset_id = cElem.findtext("id")
+                self.codes[codeset_id] = {
+                    "name": cElem.findtext("name"),
+                    "dataele": cElem.findtext("data_ele"),
+                    "codes": frozenset(c.text for c in cElem.iterfind("version/code")),
+                }
+
+    def isValid(self, key: str | None, code: str | None, check_dte: str | None = None) -> bool:
+        """
+        Return True if code is in the codeset identified by key.
+        """
+        if not key:
+            raise EngineError(f"bad key {key!r}")
+        if key in self.exclude_list:
+            return True
+        if key not in self.codes:
+            raise EngineError(f'External Code "{key}" is not defined')
+        return code in self.codes[key]["codes"]
+
+    def debug_print(self, count: int = 10) -> None:
+        """Debug print first <count> codes for each codeset (alphabetical)."""
+        for key in self.codes:
+            print(sorted(self.codes[key]["codes"], key=lambda c: c or "")[:count])
+
+
+def list_external_codesets(base_path: str | None = None) -> list[tuple[str, str]]:
+    """Return ``(id, name)`` for every codeset in ``codes.xml``.
+
+    Used by CLI scripts to populate ``--help`` with the list of names
+    accepted by the ``--exclude-external-codes`` flag. Loads the metadata
+    only — does not parse code values — so the cost is small.
+
+    :param base_path: Override directory containing codes.xml.
+        If None, uses package resource folder.
+    """
+    code_fd: IO[Any]
+    if base_path is not None:
+        code_fd = open(os.path.join(base_path, "codes.xml"), encoding="utf-8")
+    else:
+        code_fd = _res_files("pyx12").joinpath("map", "codes.xml").open("rb")
+    pairs: list[tuple[str, str]] = []
+    with code_fd:
+        parser = et.XMLParser(encoding="utf-8")
+        for cs in et.parse(code_fd, parser=parser).iter("codeset"):
+            cid = (cs.findtext("id") or "").strip()
+            name = (cs.findtext("name") or "").strip()
+            if cid:
+                pairs.append((cid, name))
+    return pairs

pyx12/dataele.py

@@ -0,0 +1,103 @@
+######################################################################
+# Copyright (c) 2001-2019
+#   John Holland <john@zoner.org>
+# All rights reserved.
+#
+# This software is licensed as described in the file LICENSE.txt, which
+# you should have received as part of this distribution.
+#
+######################################################################
+
+"""
+Interface to normalized Data Elements
+"""
+
+from __future__ import annotations
+
+import logging
+import os.path
+from importlib.resources import files as _res_files
+from typing import IO, Any, TypedDict
+
+import defusedxml.ElementTree as et
+
+# Intrapackage imports
+from pyx12.errors import EngineError
+
+
+class DataElementsError(Exception):
+    """Class for data elements module errors."""
+
+
+class _DataEle(TypedDict):
+    data_type: str | None
+    min_len: int
+    max_len: int
+    name: str | None
+
+
+class DataElements:
+    """
+    Interface to normalized Data Elements
+    """
+
+    dataele: dict[str | None, _DataEle]
+
+    def __init__(self, base_path: str | None = None) -> None:
+        """
+        Initialize the list of data elements
+
+        :param base_path: Override directory containing dataele.xml.  If None,
+            uses package resource folder
+        :type base_path: string
+
+        Note: ``self.dataele`` maps to the data element
+        ``{ele_num: {data_type, min_len, max_len, name}}``
+        """
+        logger = logging.getLogger("pyx12")
+        self.dataele = {}
+        dataele_file = "dataele.xml"
+        # ElementTree.parse accepts either text- or binary-mode streams; the
+        # file source differs between override path and bundled package resource.
+        fd: IO[Any]
+        if base_path is not None:
+            logger.debug(
+                f"Looking for data element definition file '{dataele_file}' in map_path '{base_path}'"
+            )
+            fd = open(os.path.join(base_path, dataele_file), encoding="utf-8")
+        else:
+            logger.debug(
+                f"Looking for data element definition file '{dataele_file}' in package resources"
+            )
+            fd = _res_files("pyx12").joinpath("map", dataele_file).open("rb")
+        with fd:
+            parser = et.XMLParser(encoding="utf-8")
+            for eElem in et.parse(fd, parser=parser).iter("data_ele"):
+                ele_num = eElem.get("ele_num")
+                self.dataele[ele_num] = {
+                    "data_type": eElem.get("data_type"),
+                    "min_len": int(eElem.get("min_len")),
+                    "max_len": int(eElem.get("max_len")),
+                    "name": eElem.get("name"),
+                }
+
+    def get_by_elem_num(self, ele_num: str | None) -> _DataEle:
+        """
+        Get the element characteristics for the indexed element code
+        :param ele_num: the data element code
+        :type ele_num: string
+        :return: {data_type, min_len, max_len, name}
+        :rtype: dict
+        """
+        if not ele_num:
+            raise EngineError(f"Bad data element {ele_num!r}")
+        if ele_num not in self.dataele:
+            raise EngineError(f'Data Element "{ele_num}" is not defined')
+        return self.dataele[ele_num]
+
+    def debug_print(self) -> None:
+        """
+        Debug print data elements
+        """
+        for ele_num in self.dataele:
+            print(self.dataele[ele_num])

pyx12/decorators.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import collections.abc
+import functools
+from collections.abc import Callable
+from typing import Any
+
+# See https://wiki.python.org/moin/PythonDecoratorLibrary
+
+
+def dump_args(func: Callable[..., Any]) -> Callable[..., Any]:
+    "This decorator dumps out the arguments passed to a function before calling it"
+    argnames = func.__code__.co_varnames[: func.__code__.co_argcount]
+    fname = func.__name__
+
+    def echo_func(*args: Any, **kwargs: Any) -> Any:
+        print(
+            (
+                fname,
+                ":",
+                ", ".join(
+                    "%s=%r" % entry for entry in list(zip(argnames, args)) + list(kwargs.items())
+                ),
+            )
+        )
+        return func(*args, **kwargs)
+
+    return echo_func
+
+
+def memoize(obj: Callable[..., Any]) -> Callable[..., Any]:
+    cache: dict[Any, Any] = {}
+    obj.cache = cache  # type: ignore[attr-defined]
+
+    @functools.wraps(obj)
+    def memoizer(*args: Any, **kwargs: Any) -> Any:
+        if kwargs:  # frozenset is used to ensure hashability
+            key: Any = (args, frozenset(kwargs.items()))
+        else:
+            key = args
+        if key not in cache:
+            cache[key] = obj(*args, **kwargs)
+        return cache[key]
+
+    return memoizer
+
+
+class memoized:
+    """Decorator. Caches a function's return value each time it is called.
+    If called later with the same arguments, the cached value is returned
+    (not reevaluated).
+    """
+
+    func: Callable[..., Any]
+    cache: dict[Any, Any]
+
+    def __init__(self, func: Callable[..., Any]) -> None:
+        self.func = func
+        self.cache = {}
+
+    def __call__(self, *args: Any) -> Any:
+        if not isinstance(args, collections.abc.Hashable):
+            # uncacheable. a list, for instance.
+            # better to not cache than blow up.
+            return self.func(*args)
+        if args in self.cache:
+            return self.cache[args]
+        else:
+            value = self.func(*args)
+            self.cache[args] = value
+            return value
+
+    def __repr__(self) -> str:
+        """Return the function's docstring."""
+        return self.func.__doc__ or ""
+
+    def __get__(self, obj: Any, objtype: Any) -> Callable[..., Any]:
+        """Support instance methods."""
+        return functools.partial(self.__call__, obj)

pyx12/errh_json.py

@@ -0,0 +1,161 @@
+######################################################################
+# Copyright
+#   John Holland <john@zoner.org>
+# All rights reserved.
+#
+# This software is licensed as described in the file LICENSE.txt, which
+# you should have received as part of this distribution.
+#
+######################################################################
+
+"""
+Generates a JSON document of validation errors.
+Visitor - Visits an error_handler composite (issue #50).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, TextIO
+
+import pyx12.error_visitor
+
+
+class errh_json_visitor(pyx12.error_visitor.error_visitor):
+    """
+    Visit an error_handler composite. Accumulate a nested dict mirroring
+    the ISA / GS / ST / segment / element hierarchy and dump it once as
+    JSON in visit_root_post.
+
+    Streaming JSON during the walk would require closing arrays mid-walk;
+    the err_handler tree always fits in memory for any X12 document, so
+    accumulate-then-dump is the right shape.
+    """
+
+    fd: TextIO
+    indent: int | None
+    doc: dict[str, Any]
+    _stack: list[dict[str, Any]]
+    _cur_seg: dict[str, Any] | None
+
+    def __init__(self, fd: TextIO, indent: int | None = 2) -> None:
+        """
+        :param fd: target file
+        :type fd: file descriptor
+        :param indent: json.dump indent argument; pass None for compact output
+        :type indent: int | None
+        """
+        self.fd = fd
+        self.indent = indent
+        self.doc = {"interchanges": []}
+        self._stack = []
+        self._cur_seg = None
+
+    def visit_root_post(self, errh: Any) -> None:
+        """
+        :param errh: Error handler
+        :type errh: L{error_handler.err_handler}
+        """
+        json.dump(self.doc, self.fd, indent=self.indent, default=str)
+
+    def visit_isa_pre(self, err_isa: Any) -> None:
+        """
+        :param err_isa: ISA error node
+        :type err_isa: L{error_handler.err_isa}
+        """
+        isa_dict: dict[str, Any] = {
+            "isa_trn_set_id": err_isa.isa_trn_set_id,
+            "ta1_req": err_isa.ta1_req,
+            "orig_date": err_isa.orig_date,
+            "orig_time": err_isa.orig_time,
+            "cur_line": err_isa.get_cur_line(),
+            "errors": [],
+            "groups": [],
+        }
+        self.doc["interchanges"].append(isa_dict)
+        self._stack.append(isa_dict)
+
+    def visit_isa_post(self, err_isa: Any) -> None:
+        isa_dict = self._stack[-1]
+        isa_dict["errors"] = [
+            {"err_cde": cde, "err_str": err_str} for (cde, err_str) in err_isa.errors
+        ]
+        self._stack.pop()
+
+    def visit_gs_pre(self, err_gs: Any) -> None:
+        gs_dict: dict[str, Any] = {
+            "gs_control_num": err_gs.gs_control_num,
+            "fic": err_gs.fic,
+            "vriic": err_gs.vriic,
+            "ack_code": err_gs.ack_code,
+            "st_count_orig": err_gs.st_count_orig,
+            "st_count_recv": err_gs.st_count_recv,
+            "cur_line": err_gs.get_cur_line(),
+            "errors": [],
+            "transactions": [],
+        }
+        self._stack[-1]["groups"].append(gs_dict)
+        self._stack.append(gs_dict)
+
+    def visit_gs_post(self, err_gs: Any) -> None:
+        gs_dict = self._stack[-1]
+        gs_dict["errors"] = [
+            {"err_cde": cde, "err_str": err_str} for (cde, err_str) in err_gs.errors
+        ]
+        self._stack.pop()
+
+    def visit_st_pre(self, err_st: Any) -> None:
+        st_dict: dict[str, Any] = {
+            "trn_set_id": err_st.trn_set_id,
+            "trn_set_control_num": err_st.trn_set_control_num,
+            "vriic": err_st.vriic,
+            "ack_code": err_st.ack_code,
+            "cur_line": err_st.get_cur_line(),
+            "errors": [],
+            "segments": [],
+        }
+        self._stack[-1]["transactions"].append(st_dict)
+        self._stack.append(st_dict)
+
+    def visit_st_post(self, err_st: Any) -> None:
+        st_dict = self._stack[-1]
+        st_dict["errors"] = [
+            {"err_cde": cde, "err_str": err_str} for (cde, err_str) in err_st.errors
+        ]
+        self._stack.pop()
+
+    def visit_seg(self, err_seg: Any) -> None:
+        seg_dict: dict[str, Any] = {
+            "seg_id": err_seg.seg_id,
+            "seg_count": err_seg.seg_count,
+            "pos": err_seg.pos,
+            "name": err_seg.name,
+            "ls_id": err_seg.ls_id,
+            "cur_line": err_seg.get_cur_line(),
+            "errors": [
+                {"err_cde": cde, "err_str": err_str, "err_val": err_val}
+                for (cde, err_str, err_val) in err_seg.errors
+            ],
+            "elements": [],
+        }
+        self._stack[-1]["segments"].append(seg_dict)
+        self._cur_seg = seg_dict
+
+    def visit_ele(self, err_ele: Any) -> None:
+        # err_ele.accept is only invoked from err_seg.accept (ISA / GS / ST
+        # accept methods do not walk their .elements list), so a non-None
+        # _cur_seg is guaranteed at this point.
+        if self._cur_seg is None:
+            return
+        ele_dict: dict[str, Any] = {
+            "ele_pos": err_ele.ele_pos,
+            "subele_pos": err_ele.subele_pos,
+            "repeat_pos": err_ele.repeat_pos,
+            "ele_ref_num": err_ele.ele_ref_num,
+            "name": err_ele.name,
+            "errors": [
+                {"err_cde": cde, "err_str": err_str, "err_val": err_val}
+                for (cde, err_str, err_val) in err_ele.errors
+            ],
+        }
+        self._cur_seg["elements"].append(ele_dict)