sdc-gdr2edifact 4.0.0__py3-none-any.whl

sdc_gdr2edifact/__init__.py

@@ -0,0 +1,28 @@
+"""sdc-gdr2edifact: Governed Data Records as UN/EDIFACT D.24A interchanges, through sdc-mapper.
+
+    from sdc_mapper import Engine, load_mapping
+    from sdc_gdr2edifact import EDIFACTMapper, mapping_path
+    mapper = EDIFACTMapper("/path/to/d24a.zip")       # the directory as downloaded from UNECE; or $SDC_EDIFACT_DIRECTORY
+    result = Engine().map_record(xml, mapper, load_mapping(mapping_path("cacl4njrwanj15g3p3so8t6h")))
+
+One mapping file per model, in `mappings/`. Registered with sdc-mapper as the target `edifact`.
+"""
+from pathlib import Path
+
+__version__ = "4.0.0"
+
+MAPPINGS = Path(__file__).with_name("mappings")
+
+
+def mapping_path(ct_id: str) -> Path:
+    """The mapping file this package publishes for a model, by the model's identifier."""
+    found = sorted(MAPPINGS.glob(f"*-{ct_id}.yaml"))
+    if not found:
+        raise FileNotFoundError(f"sdc-gdr2edifact has no mapping for model {ct_id}")
+    return found[-1]
+
+
+from .directory import Directory, DirectoryNotFound  # noqa: E402
+from .mapper import EDIFACTMapper  # noqa: E402
+
+__all__ = ["EDIFACTMapper", "Directory", "DirectoryNotFound", "mapping_path", "MAPPINGS", "__version__"]

sdc_gdr2edifact/check.py

@@ -0,0 +1,167 @@
+"""An interchange checked against the directory, from its text, by code that shares nothing with the writer.
+
+    errors = check(text, Directory.load())        # [] when the interchange conforms
+
+The text is parsed afresh (the UNA service string, the release character, segments, data elements, components); the
+envelope is checked (UNB first and UNZ last, one UNH to UNT message, UNT's segment count and UNZ's message count,
+matching control references); the message's segment sequence is matched against the message specification's segment
+table by a recursive descent over its positions (a segment position takes up to its repeat count of segments, a group
+opens on its trigger segment and repeats up to its count, a mandatory position missing is an error, a segment nothing
+takes is an error); and every segment against its definition (known tag, no more data elements or components than
+defined, mandatory ones present, lengths and numeric representations within the directory's).
+"""
+from __future__ import annotations
+
+import re
+
+from .directory import Directory
+
+REPR = re.compile(r"^(an|a|n)(\.\.)?(\d+)$")
+
+
+def parse(text: str) -> list[tuple[str, list[list[str]]]]:
+    text = text.lstrip()
+    comp, elem, rel, term = ":", "+", "?", "'"
+    if text.startswith("UNA"):
+        comp, elem, rel, term = text[3], text[4], text[6], text[8]
+        text = text[9:]
+    segments, cur, comps, elements, tag = [], [], [], [], None
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if ch == rel and i + 1 < len(text):
+            cur.append(text[i + 1])
+            i += 2
+            continue
+        if ch in "\r\n" and not cur and tag is None:
+            i += 1
+            continue
+        if ch == elem or ch == term:
+            if tag is None:
+                tag = "".join(cur).strip()
+            else:
+                comps.append("".join(cur))
+                elements.append(comps)
+            cur, comps = [], []
+            if ch == term:
+                segments.append((tag, elements))
+                tag, elements = None, []
+        elif ch == comp and tag is not None:
+            comps.append("".join(cur))
+            cur = []
+        else:
+            cur.append(ch)
+        i += 1
+    if tag is not None or cur:
+        segments.append(("?", [["".join(cur)]]))
+    return segments
+
+
+def _value(elements, i, j=0) -> str:
+    return elements[i][j] if i < len(elements) and j < len(elements[i]) else ""
+
+
+def check(text: str, d: Directory) -> list[str]:
+    segs = parse(text)
+    errors: list[str] = []
+    tags = [t for t, _ in segs]
+    if not segs or tags[0] != "UNB" or tags[-1] != "UNZ":
+        return ["an interchange starts with UNB and ends with UNZ"]
+    if tags.count("UNH") != 1 or tags.count("UNT") != 1:
+        return [f"one message expected; {tags.count('UNH')} UNH and {tags.count('UNT')} UNT"]
+    h, t = tags.index("UNH"), tags.index("UNT")
+    msg = segs[h:t + 1]
+    unb, unh, unt, unz = segs[0][1], segs[h][1], segs[t][1], segs[-1][1]
+    if _value(unt, 0) != str(len(msg)):
+        errors.append(f"UNT counts {_value(unt, 0)} segments; the message has {len(msg)}")
+    if _value(unt, 1) != _value(unh, 0):
+        errors.append("UNT's message reference differs from UNH's")
+    if _value(unz, 0) != "1" or _value(unz, 1) != _value(unb, 4):
+        errors.append("UNZ's count or control reference does not match the interchange")
+    for k, (i, j) in enumerate(((0, 0), (0, 1), (1, 0), (2, 0), (3, 0), (3, 1), (4, 0))):
+        if not _value(unb, i, j):
+            errors.append(f"UNB is missing its mandatory data at element {i + 1}, component {j + 1}")
+    name = _value(unh, 1, 0)
+    spec = d.messages.get(name)
+    if spec is None:
+        return errors + [f"{name} is not a message of {d.version}"]
+    if (_value(unh, 1, 1), _value(unh, 1, 2), _value(unh, 1, 3)) != (spec["version"], spec["release"], spec["agency"]):
+        errors.append(f"UNH names {':'.join(unh[1][1:4])}, the directory {spec['version']}:{spec['release']}:{spec['agency']}")
+    errors += _table(spec["segment_table"], msg, name)
+    errors += _segments(msg, d)
+    return errors
+
+
+def _table(table, segs, name) -> list[str]:
+    errors: list[str] = []
+
+    def match(items, i, where):
+        for it in items:
+            if "items" in it:
+                trigger, n = it["items"][0]["tag"], 0
+                while i < len(segs) and segs[i][0] == trigger and n < it["repeat"]:
+                    i = match(it["items"], i, f"{where}/SG{it['group']}")
+                    n += 1
+                if n == 0 and it["status"] == "M":
+                    errors.append(f"{where}: mandatory segment group {it['group']} is missing")
+            else:
+                n = 0
+                while i < len(segs) and segs[i][0] == it["tag"] and n < it["repeat"]:
+                    i += 1
+                    n += 1
+                if n == 0 and it["status"] == "M":
+                    errors.append(f"{where}: mandatory segment {it['tag']} is missing")
+        return i
+
+    i = match(table, 0, name)
+    if i < len(segs):
+        errors.append(f"{name}: segment {i + 1} ({segs[i][0]}) is not where the segment table allows it")
+    return errors
+
+
+def _repr(value, repr_, where) -> list[str]:
+    m = REPR.match(repr_ or "")
+    if not m:
+        return []
+    kind, variable, size = m.group(1), m.group(2), int(m.group(3))
+    length = len(re.sub(r"[^0-9]", "", value)) if kind == "n" else len(value)
+    if length > size or (not variable and length != size):
+        return [f"{where}: {length} characters, representation {repr_}"]
+    if kind == "n" and not re.fullmatch(r"-?\d+(\.\d+)?", value):
+        return [f"{where}: '{value[:20]}' is not numeric ({repr_})"]
+    return []
+
+
+def _segments(segs, d: Directory) -> list[str]:
+    errors: list[str] = []
+    for k, (tag, elements) in enumerate(segs, 1):
+        if tag in ("UNH", "UNT", "UNS"):
+            continue
+        spec = d.segments.get(tag)
+        if spec is None:
+            errors.append(f"segment {k}: {tag} is not a segment of {d.version}")
+            continue
+        defs = spec["elements"]
+        if len(elements) > len(defs):
+            errors.append(f"segment {k} ({tag}): {len(elements)} data elements; {len(defs)} defined")
+        for j, e in enumerate(defs):
+            given = elements[j] if j < len(elements) else []
+            present = any(c != "" for c in given)
+            if e["status"] == "M" and not present:
+                errors.append(f"segment {k} ({tag}): mandatory {e['tag']} is missing")
+            if not present:
+                continue
+            if e["components"]:
+                if len(given) > len(e["components"]):
+                    errors.append(f"segment {k} ({tag}) {e['tag']}: {len(given)} components; {len(e['components'])} defined")
+                for c, cd in enumerate(e["components"]):
+                    v = given[c] if c < len(given) else ""
+                    if cd["status"] == "M" and v == "":
+                        errors.append(f"segment {k} ({tag}) {e['tag']}: mandatory {cd['tag']} is missing")
+                    elif v:
+                        errors += _repr(v, cd["repr"], f"segment {k} ({tag}) {e['tag']}/{cd['tag']}")
+            else:
+                if len(given) > 1:
+                    errors.append(f"segment {k} ({tag}) {e['tag']} is a simple data element; it has components")
+                errors += _repr(given[0], e["repr"], f"segment {k} ({tag}) {e['tag']}")
+    return errors

sdc_gdr2edifact/directory.py

@@ -0,0 +1,299 @@
+"""The UN/EDIFACT directory: read from the archive UNECE publishes, never shipped with this package.
+
+UNECE licenses each directory (UNTDID: the data elements EDED, composites EDCD, segments EDSD, code lists UNCL and
+message specifications EDMD) for use within the organization that downloads it, and lets the original file be passed
+on with its license; a modified directory may not be distributed. So this package carries no part of a directory:
+
+    d = Directory.load()                              # $SDC_EDIFACT_DIRECTORY, or a path given to load()
+    d = Directory.load("/data/edifact/d24a.zip")      # the zip downloaded from unece.org, unchanged
+
+The archive is read as downloaded (its parts are zips inside the zip), extracted in memory, and the extraction kept as
+a working copy in the user's cache directory, keyed by the archive's SHA-256, for use on that machine.
+"""
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import os
+import re
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import ClassVar
+
+ENV = "SDC_EDIFACT_DIRECTORY"
+EXTRACTION = 2          # the extraction's own version: a change to how the text files are read is a new cache entry
+DASH = re.compile(r"^-{20,}\s*$")
+
+
+class DirectoryNotFound(Exception):
+    pass
+
+
+def _cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache")
+    return Path(base) / "sdc-gdr2edifact"
+
+
+# ---------------------------------------------------------------- reading the text files
+def _text(raw: bytes) -> str:
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        text = raw.decode("latin-1", errors="replace")
+    return text.replace("’", "'").replace("‘", "'").replace("“", '"').replace("”", '"')
+
+
+def _blocks(text: str):
+    cur: list[str] = []
+    for line in text.splitlines():
+        if DASH.match(line):
+            if cur:
+                yield cur
+            cur = []
+        else:
+            cur.append(line)
+    if cur:
+        yield cur
+
+
+def _joined(lines: list[str]) -> str:
+    return re.sub(r"\s+", " ", " ".join(x.strip() for x in lines)).strip()
+
+
+def _field(lines: list[str], name: str) -> str:
+    out, on = [], False
+    for x in lines:
+        m = re.match(rf"^\s*{name}:\s*(.*)$", x)
+        if m:
+            out.append(m.group(1))
+            on = True
+            continue
+        if on:
+            if x.strip() == "" or re.match(r"^\s*(Desc|Repr|Note|Function|Notes?):", x) or re.match(r"^\d{3}\s", x):
+                on = False
+            else:
+                out.append(x)
+    return _joined(out)
+
+
+ELEMENT_HEAD = re.compile(r"^[+*#|X\-]?\s{1,6}(\d{4})\s{2}(.+?)\s{2,}\[([BIC])\]\s*$")
+COMPOSITE_HEAD = re.compile(r"^[+*#|X\-]?\s{1,8}(C\d{3})\s+(.+?)\s*$")
+# A name can run into the status column with a single space ("...FUNCTION CODE QUALIFIER M    1 an..3"), so the
+# status is found as a lone M or C before the repeat count or representation, not after two spaces.
+COMPONENT = re.compile(r"^(\d{3})\s+(\d{4})\s+(.+?)\s+([MC])\s+(\S+)\s*$")
+SEGMENT_HEAD = re.compile(r"^[+*#|X\-]?\s{1,8}([A-Z]{3})\s{2}(.+?)\s*$")
+SEG_ELEMENT = re.compile(r"^(\d{3})\s+(C\d{3}|\d{4})\s+(.+?)\s+([MC])\s+(\d+)(?:\s+(\S+))?\s*$")
+SEG_SUB = re.compile(r"^\s{4,}(\d{4})\s+(.+?)\s+([MC])\s+(\S+)\s*$")
+CODE_LINE = re.compile(r"^[+*#|X\-]?\s{1,6}(\S{1,3})\s{2,}(.+?)\s*$")
+GROUP = re.compile(r"^(\d{5})\s+-+\s+Segment group\s+(\d+)\s+-+\s+([MC])\s+(\d+)\s*-*\+\|*\s*$")
+SEGLINE = re.compile(r"^(\d{5})\s+([A-Z]{3})\s+(.+?)\s{2,}([MC])\s+(\d+)\s*(-*)(\++)?\s*\|*\s*$")
+
+
+def _elements(text: str) -> dict:
+    out = {}
+    for b in _blocks(text):
+        head = next((x for x in b if ELEMENT_HEAD.match(x)), None)
+        if head:
+            m = ELEMENT_HEAD.match(head)
+            out[m.group(1)] = {"tag": m.group(1), "name": m.group(2).strip(), "repr": _field(b, "Repr")}
+    return out
+
+
+def _composites(text: str) -> dict:
+    out = {}
+    for b in _blocks(text):
+        head = next((x for x in b if COMPOSITE_HEAD.match(x) and not x.strip().startswith("Desc")), None)
+        if not head:
+            continue
+        m = COMPOSITE_HEAD.match(head)
+        comps, pending = [], None
+        for x in b:
+            cm = COMPONENT.match(x)
+            if cm:
+                comps.append({"tag": cm.group(2), "name": cm.group(3).strip(), "status": cm.group(4), "repr": cm.group(5)})
+                pending = None
+            elif re.match(r"^(\d{3})\s+(\d{4})\s+(.+)$", x):
+                pending = re.match(r"^(\d{3})\s+(\d{4})\s+(.+)$", x)
+            elif pending and x.strip():
+                tail = re.match(r"^\s*(.+?)\s{2,}([MC])\s+(\S+)\s*$", x)
+                if tail:
+                    comps.append({"tag": pending.group(2), "name": f"{pending.group(3).strip()} {tail.group(1).strip()}",
+                                  "status": tail.group(2), "repr": tail.group(3)})
+                    pending = None
+        out[m.group(1)] = {"tag": m.group(1), "name": m.group(2).strip(), "components": comps}
+    return out
+
+
+def _segments(text: str) -> dict:
+    out = {}
+    for b in _blocks(text):
+        head = next((x for x in b if SEGMENT_HEAD.match(x) and x.strip()[:3].isalpha() and x.strip()[:3].isupper()
+                     and not x.strip().startswith(("Function", "Desc", "Note"))), None)
+        if not head or "Function:" not in "\n".join(b):
+            continue
+        m = SEGMENT_HEAD.match(head)
+        items, pending = [], None
+        for x in b:
+            em = SEG_ELEMENT.match(x)
+            if em:
+                items.append({"tag": em.group(2), "name": em.group(3).strip(), "status": em.group(4),
+                              "repeat": int(em.group(5)), "repr": em.group(6) or "", "components": []})
+                pending = None
+                continue
+            sm = SEG_SUB.match(x)
+            if sm and items and items[-1]["tag"].startswith("C"):
+                items[-1]["components"].append({"tag": sm.group(1), "name": sm.group(2).strip(), "status": sm.group(3),
+                                                "repr": sm.group(4)})
+                pending = None
+                continue
+            wm = re.match(r"^(\d{3})\s+(C\d{3}|\d{4})\s+(.+)$", x)
+            if wm:
+                pending = ("item", wm)
+                continue
+            wsm = re.match(r"^\s{4,}(\d{4})\s{2}(.+)$", x)
+            if wsm and items and items[-1]["tag"].startswith("C"):
+                pending = ("sub", wsm)
+                continue
+            if pending and x.strip():
+                tail = re.match(r"^\s*(.+?)\s{2,}([MC])\s+(\d+)?\s*(\S+)?\s*$", x)
+                if tail:
+                    kind, pm = pending
+                    if kind == "item":
+                        items.append({"tag": pm.group(2), "name": f"{pm.group(3).strip()} {tail.group(1).strip()}",
+                                      "status": tail.group(2), "repeat": int(tail.group(3) or 1), "repr": tail.group(4) or "",
+                                      "components": []})
+                    else:
+                        items[-1]["components"].append({"tag": pm.group(1), "name": f"{pm.group(2).strip()} {tail.group(1).strip()}",
+                                                        "status": tail.group(2), "repr": tail.group(4) or tail.group(3) or ""})
+                pending = None
+        out[m.group(1)] = {"tag": m.group(1), "name": m.group(2).strip(), "elements": items}
+    return out
+
+
+def _codelists(text: str) -> dict:
+    out = {}
+    for b in _blocks(text):
+        head = next((x for x in b if ELEMENT_HEAD.match(x)), None)
+        if not head:
+            continue
+        tag = ELEMENT_HEAD.match(head).group(1)
+        codes, started = [], False
+        for x in b:
+            if x is head:
+                started = True
+                continue
+            if not started or re.match(r"^\s*(Desc|Repr|Note):", x):
+                continue
+            cm = CODE_LINE.match(x)
+            if cm and (len(x) - len(x.lstrip(" +*#|X-")) <= 6) and not x.startswith("              "):
+                codes.append({"value": cm.group(1), "name": cm.group(2).strip()})
+        out[tag] = {"tag": tag, "codes": codes}
+    return out
+
+
+def _message(text: str, name: str) -> dict:
+    lines = text.splitlines()
+    head = {}
+    for key, pat in (("type", r"Message Type\s*:\s*(\S+)"), ("version", r"Version\s*:\s*(\S+)"),
+                     ("release", r"Release\s*:\s*(\S+)"), ("agency", r"Contr\. Agency\s*:\s*(\S+)")):
+        m = re.search(pat, text)
+        head[key] = m.group(1) if m else ""
+    n = max((i for i, x in enumerate(lines) if re.match(r"^\s*Pos\s+Tag\s+Name", x)), default=None)
+    root = {"group": 0, "status": "M", "repeat": 1, "items": []}
+    if n is not None:
+        stack = [root]
+        for x in lines[n + 1:]:
+            gm = GROUP.match(x)
+            if gm:
+                g = {"group": int(gm.group(2)), "status": gm.group(3), "repeat": int(gm.group(4)), "items": []}
+                stack[-1]["items"].append(g)
+                stack.append(g)
+                continue
+            sm = SEGLINE.match(x)
+            if sm:
+                stack[-1]["items"].append({"tag": sm.group(2), "name": sm.group(3).strip(), "status": sm.group(4),
+                                           "repeat": int(sm.group(5))})
+                for _ in range(len(sm.group(7) or "")):
+                    if len(stack) > 1:
+                        stack.pop()
+    return {"type": head["type"] or name.split("_")[0], "version": head["version"], "release": head["release"],
+            "agency": head["agency"], "segment_table": root["items"]}
+
+
+def extract(archive: bytes) -> dict:
+    """A directory archive (the zip as downloaded from UNECE) to its definitions."""
+    outer = zipfile.ZipFile(io.BytesIO(archive))
+    parts = {}
+    for name in outer.namelist():
+        if name.lower().endswith(".zip"):
+            parts[name.lower().split("/")[-1][:-4]] = zipfile.ZipFile(io.BytesIO(outer.read(name)))
+
+    def one(part: str, prefix: str) -> tuple[str, str]:
+        z = parts[part]
+        name = next(n for n in z.namelist() if n.upper().split("/")[-1].startswith(prefix + ".")
+                    and not n.upper().split("/")[-1].startswith(prefix + "I"))
+        return name, _text(z.read(name))
+
+    eded_name, eded = one("eded", "EDED")
+    suffix = eded_name.split(".")[-1].upper()                      # 24A
+    version = f"D.{suffix}"
+    messages = {}
+    for name in parts["edmd"].namelist():
+        if name.endswith("/"):
+            continue
+        m = _message(_text(parts["edmd"].read(name)), name.split("/")[-1])
+        messages[m["type"]] = m
+    return {"version": version, "elements": _elements(eded), "composites": _composites(one("edcd", "EDCD")[1]),
+            "segments": _segments(one("edsd", "EDSD")[1]), "codelists": _codelists(one("uncl", "UNCL")[1]),
+            "messages": messages}
+
+
+@dataclass
+class Directory:
+    version: str
+    elements: dict
+    composites: dict
+    segments: dict
+    codelists: dict
+    messages: dict
+    sha256: str = ""
+    _cache: dict = field(default_factory=dict, repr=False)
+
+    _loaded: ClassVar[dict] = {}
+
+    @classmethod
+    def load(cls, path: str | os.PathLike | None = None) -> "Directory":
+        path = path or os.environ.get(ENV)
+        if not path:
+            raise DirectoryNotFound(
+                f"the UN/EDIFACT directory is needed: download the D.24A archive from UNECE "
+                f"(https://unece.org/trade/uncefact/unedifact/download) and set {ENV} to the zip's path")
+        p = Path(path)
+        if not p.exists():
+            raise DirectoryNotFound(f"no UN/EDIFACT directory archive at {p}")
+        raw = p.read_bytes()
+        sha = hashlib.sha256(raw).hexdigest()
+        if sha in cls._loaded:
+            return cls._loaded[sha]
+        cache = _cache_dir() / f"{sha}-{EXTRACTION}.json"
+        if cache.exists():
+            data = json.loads(cache.read_text(encoding="utf-8"))
+        else:
+            data = extract(raw)
+            cache.parent.mkdir(parents=True, exist_ok=True)
+            cache.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+        obj = cls(data["version"], data["elements"], data["composites"], data["segments"], data["codelists"],
+                  data["messages"], sha256=sha)
+        cls._loaded[sha] = obj
+        return obj
+
+    def message(self, name: str) -> dict:
+        if name not in self.messages:
+            raise KeyError(f"{name} is not a message of {self.version}")
+        return self.messages[name]
+
+    def code(self, element: str, value: str) -> dict | None:
+        cl = self.codelists.get(element)
+        return next((c for c in cl["codes"] if c["value"] == value), None) if cl else None

sdc_gdr2edifact/mapper.py

@@ -0,0 +1,130 @@
+"""The UN/EDIFACT mapper: a Governed Data Record as a D.24A interchange, by a mapping file.
+
+The business documents library links its components to UBL, not to UN/EDIFACT, so where a value goes in a message
+(a segment, a qualifier, a data element) is declared in a mapping file, one per model. Where the model does bind a
+value to a code list the directory uses, the mapping's `binding` transform takes the code from the model and the value
+is a lookup: UBL 2.3's PaymentMeansCode list is UNCL 4461, code for code, and the packaging types are UN/ECE
+Recommendation 21 codes.
+
+UN/EDIFACT has no null flavors. A free text segment could hold the words, but no qualifier the directory defines says
+"this value was asked for and refused" in a way a receiving system would act on, so an Exceptional Value is lost, and
+where the directory requires the value, the segment, the group or the message cannot be written, and the report says
+which and why.
+"""
+from __future__ import annotations
+
+import os
+
+from sdc_mapper import (DECLARED, JOIN, LOOKUP, LOST, NOT_REPRESENTABLE, EVRule, IncompleteMapping, MapResult,
+                        MappingError, ValueOutcome, place)
+from sdcreader.record import EXCEPTIONAL_VALUES
+
+from . import __version__
+from .check import check
+from .directory import ENV, Directory
+from .writer import Builder
+
+CANNOT_HOLD = [
+    "Exceptional Values: UN/EDIFACT has no null flavors",
+    "validity windows and the time a value was recorded (act, vtb, vte, tr)",
+    "the definitions the model binds each component to",
+    "the record's provenance and audit clusters",
+]
+
+
+class EDIFACTMapper:
+    name = "edifact"
+    target = "UN/EDIFACT"
+    target_version = "D.24A"
+    package = "sdc-gdr2edifact"
+    version = __version__
+    ev_table = {code: EVRule(LOST) for code in EXCEPTIONAL_VALUES}
+
+    def __init__(self, directory: str | os.PathLike | Directory | None = None):
+        self._directory = directory
+
+    @property
+    def directory(self) -> Directory:
+        if not isinstance(self._directory, Directory):
+            self._directory = Directory.load(self._directory or os.environ.get(ENV))
+        return self._directory
+
+    def map(self, record, mapping) -> MapResult:
+        if mapping is None:
+            raise MappingError("UN/EDIFACT needs a mapping file: the model does not say where its values go in a message")
+        if mapping.carry_rejected:
+            raise MappingError("UN/EDIFACT has no agreed place to carry a rejected value; carry_rejected is not available")
+        for code, override in mapping.exceptional_values.items():
+            if override["class"] != LOST:
+                raise MappingError(f"UN/EDIFACT cannot say {code}: it has no null flavors, so an Exceptional Value is lost")
+        placements, clusters = place(record, mapping)
+        message = next((p.steps[0][0] for p in placements if p.steps), None)
+        if message is None:
+            raise MappingError("nothing to write: no value of the record reached the message")
+        b = Builder(self.directory, message, mapping.cluster_order)
+        notes: dict[int, str] = {}
+        later = []
+        for p in placements:
+            v = p.value
+            if v.exceptional or p.omitted or p.rule is None or not p.steps:
+                continue
+            if p.text is None:
+                notes[v.position] = p.note or "no value to write"
+                continue
+            writes = [(p.steps, p.attribute, p.text, v.position, p)]
+            writes += [(e.steps, e.attribute, e.text, None, None) for e in p.extras if e.text is not None]
+            for w in writes:
+                if any(key == JOIN for _, key in w[0]):
+                    later.append(w)
+                else:
+                    self._write(b, *w)
+        # a join waits for the elements it may join: the shallower the deepest join of a write, the earlier it goes
+        later.sort(key=lambda w: max(i for i, (_, key) in enumerate(w[0]) if key == JOIN))
+        for w in later:
+            self._write(b, *w)
+        # A cluster's constant data (a NAD's party qualifier, a CPS's packaging level) go on its segment; the segment is
+        # written when the cluster's group holds anything of the record's, though no value lands in the segment itself.
+        for c in clusters:
+            if not c.attributes:
+                continue
+            node = b.find(c.steps, loose=True)
+            parent = b.find(c.steps[:-1], loose=True) if len(c.steps) > 2 else None
+            if node is None and parent is not None and parent.children:
+                node = b.ensure_under(parent, c.steps[-1])
+            if node is not None:
+                for k, val in c.attributes.items():
+                    node.attrs.setdefault(k, val)
+        text = b.interchange()
+        errors = check(text, self.directory)
+        if errors:
+            raise MappingError(f"the {message} does not conform to {self.directory.version}: {errors[0]}")
+        outcomes, missing = [], []
+        for p in placements:
+            v = p.value
+            if v.exceptional:
+                outcomes.append(ValueOutcome(v.position, LOST, note="UN/EDIFACT has no null flavors"))
+            elif p.omitted:
+                outcomes.append(ValueOutcome(v.position, NOT_REPRESENTABLE, note=p.omitted_by.reason or ""))
+            elif p.rule is None:
+                missing.append(f"{' / '.join(v.path_labels + [v.label])} ({v.ct_id})")
+            elif v.position in notes:
+                outcomes.append(ValueOutcome(v.position, NOT_REPRESENTABLE, note=notes[v.position]))
+            elif v.position in b.pruned:
+                outcomes.append(ValueOutcome(v.position, NOT_REPRESENTABLE, note=b.pruned[v.position]))
+            else:
+                cls = LOOKUP if p.rule.transform == "binding" else DECLARED
+                where = "/".join(n for n, _ in p.steps) + (f"/@{p.attribute}" if p.attribute else "")
+                outcomes.append(ValueOutcome(v.position, cls, location=where))
+        if missing:
+            raise IncompleteMapping(f"mapping {mapping.id} has no rule for {len(missing)} value(s): " + "; ".join(missing[:5]))
+        return MapResult(files={f"{message}.edi": text.encode("latin-1")}, outcomes=outcomes,
+                         cannot_hold=list(CANNOT_HOLD))
+
+    @staticmethod
+    def _write(b: Builder, steps, attribute, text, position, p):
+        node = b.put(steps, attribute, text, position)
+        if p is not None:
+            for k, val in p.attributes.items():
+                node.attrs.setdefault(k, val)
+            if p.units_attribute and p.units_text is not None:
+                node.attrs[p.units_attribute] = p.units_text