docxcast 0.1.0__py3-none-any.whl

docxcast/__init__.py

@@ -0,0 +1,41 @@
+"""DocXCast: Turn Word content controls into a typed schema, then cast data back into documents."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from docxcast.derive import DeriveError, derive_schema
+from docxcast.render import RenderError, RenderResult, render
+from docxcast.schema import (
+    FORMAT_DATE,
+    FORMAT_DATE_MONTH,
+    FORMAT_DATE_TIME,
+    FORMAT_DATE_YEAR,
+    Field,
+    Issue,
+    Repeat,
+    Schema,
+    Section,
+    ValidationResult,
+)
+
+try:
+    __version__ = version('docxcast')
+except PackageNotFoundError:
+    __version__ = '0.1.0'
+
+__all__ = [
+    'derive_schema',
+    'DeriveError',
+    'render',
+    'RenderError',
+    'RenderResult',
+    'Schema',
+    'Section',
+    'Repeat',
+    'Field',
+    'Issue',
+    'ValidationResult',
+    'FORMAT_DATE',
+    'FORMAT_DATE_MONTH',
+    'FORMAT_DATE_YEAR',
+    'FORMAT_DATE_TIME',
+]

docxcast/_ooxml.py

@@ -0,0 +1,191 @@
+"""OOXML namespace constants and shared sdt helpers used by both derive and render."""
+
+from functools import lru_cache
+from typing import Optional
+
+NS = {
+    'w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
+    'w14': 'http://schemas.microsoft.com/office/word/2010/wordml',
+    'w15': 'http://schemas.microsoft.com/office/word/2012/wordml',
+}
+
+XML_SPACE = '{http://www.w3.org/XML/1998/namespace}space'
+
+
+@lru_cache(maxsize=None)
+def qn(tag: str) -> str:
+    prefix, local = tag.split(':')
+    return f'{{{NS[prefix]}}}{local}'
+
+
+# tags the sdt walker descends into (paragraphs and table cells)
+CONTAINER_TAGS = frozenset(qn(t) for t in ('w:p', 'w:tbl', 'w:tr', 'w:tc'))
+
+KIND_REPEAT = 'repeat'
+KIND_ITEM = 'item'
+KIND_SECTION = 'section'
+KIND_GROUP = 'group'
+KIND_PICTURE = 'picture'
+KIND_DROPDOWN = 'dropdown'
+KIND_DATE = 'date'
+KIND_CHECKBOX = 'checkbox'
+KIND_TEXT = 'text'
+
+_TAG_KINDS = {
+    qn('w15:repeatingSection'): KIND_REPEAT,
+    qn('w15:repeatingSectionItem'): KIND_ITEM,
+    qn('w:docPartList'): KIND_SECTION,
+    qn('w:group'): KIND_GROUP,
+    qn('w:picture'): KIND_PICTURE,
+    qn('w:dropDownList'): KIND_DROPDOWN,
+    qn('w:date'): KIND_DATE,
+    qn('w14:checkbox'): KIND_CHECKBOX,
+}
+
+
+def kind_of(pr) -> str:
+    for child in pr:
+        kind = _TAG_KINDS.get(child.tag)
+        if kind is not None:
+            return kind
+    return KIND_TEXT
+
+
+def repeating_item(content):
+    for child in content:
+        if child.tag != qn('w:sdt'):
+            continue
+        pr = child.find(qn('w:sdtPr'))
+        if pr is not None and pr.find(qn('w15:repeatingSectionItem')) is not None:
+            return child
+    return None
+
+
+def dropdown_items(pr) -> list:
+    """(display, value) pairs of a dropdown, skipping placeholder items without display text."""
+    dropdown = pr.find(qn('w:dropDownList'))
+    if dropdown is None:
+        return []
+    items = []
+    for item in dropdown.findall(qn('w:listItem')):
+        display = item.get(qn('w:displayText'))
+        if display is not None:
+            items.append((display, item.get(qn('w:value'))))
+    return items
+
+
+def text_attr(pr, tag: str) -> Optional[str]:
+    el = pr.find(qn(tag))
+    return el.get(qn('w:val')) if el is not None else None
+
+
+def date_mask_runs(mask: str) -> list:
+    """Tokenize a Word dateFormat mask into (letter, text) runs: quoted
+    spans and non-ASCII-letter text are literals (letter None), an
+    unquoted ASCII letter run is a token carrying its letter. Shared by
+    derive (granularity) and render (formatting) so both read one
+    grammar and can't drift apart."""
+    runs = []
+    i = 0
+    while i < len(mask):
+        c = mask[i]
+        if c == "'":  # a quoted literal
+            end = mask.find("'", i + 1)
+            if end == -1:
+                runs.append((None, mask[i + 1:]))
+                break
+            runs.append((None, mask[i + 1:end]))
+            i = end + 1
+            continue
+        j = i
+        while j < len(mask) and mask[j] == c:
+            j += 1
+        runs.append((c if c.isascii() and c.isalpha() else None, mask[i:j]))
+        i = j
+    return runs
+
+
+# guard names injected into every repeating-section item's scope; a real
+# field may not take them
+RESERVED = frozenset(('has_prev', 'has_next'))
+
+
+def split_conditional(alias: Optional[str]) -> tuple[Optional[str], bool]:
+    """A trailing '?' on an address (TS-style ``name?``) marks its block
+    conditionally displayed: a falsy value removes the block."""
+    if alias and alias.endswith('?'):
+        return alias[:-1], True
+    return alias, False
+
+
+def scope_guards(i: int, n: int) -> dict:
+    """Positional guard values for item ``i`` of ``n`` in a repeat."""
+    return {'has_prev': i > 0, 'has_next': i < n - 1}
+
+
+def is_block(content) -> bool:
+    """Group content is block-level when the outside-sdt walk meets a
+    paragraph — the same walk group_literals chunks, so block and
+    inline cannot be classified two ways."""
+    return any(el.tag == qn('w:p') for el in outside_sdts(content))
+
+
+def outside_sdts(container):
+    """Iterate elements of ``container`` without descending into nested
+    content controls — their content belongs to the control, not the
+    group around it."""
+    for child in container:
+        if child.tag == qn('w:sdt'):
+            continue
+        yield child
+        yield from outside_sdts(child)
+
+
+def group_members(content) -> list:
+    """(sdt, pr, alias, tag) of a group's control members, in document
+    order."""
+    members = []
+    for child in content:
+        if child.tag == qn('w:sdt'):
+            if (pr := child.find(qn('w:sdtPr'))) is not None:
+                members.append((child, pr, text_attr(pr, 'w:alias'), text_attr(pr, 'w:tag')))
+        elif child.tag in CONTAINER_TAGS:
+            members.extend(group_members(child))
+    return members
+
+
+def group_address(pr, members) -> tuple:
+    """A group's (alias, tag, member index, conditional): the group's own
+    address if it carries one, else the first member that does (-1 if
+    none). The alias comes back unmarked — split_conditional's trailing
+    '?' marks the group a conditional block. Shared by derive and
+    render so the two can't drift apart."""
+    if text_attr(pr, 'w:alias') or text_attr(pr, 'w:tag'):
+        name, conditional = split_conditional(text_attr(pr, 'w:alias'))
+        return name, text_attr(pr, 'w:tag'), -1, conditional
+    for i, (_, mpr, alias, tag) in enumerate(members):
+        if alias or tag:
+            name, conditional = split_conditional(alias)
+            return name, tag, i, conditional
+    return None, None, -1, False
+
+
+def outside_text(el) -> str:
+    return ''.join(t.text or '' for t in outside_sdts(el) if t.tag == qn('w:t')).strip()
+
+
+def group_chunks(content) -> list:
+    """A group's literal text as (holder, text) pairs: one per
+    paragraph outside nested controls, or the joined run text of an
+    inline group. Derive advertises the texts, render deletes from the
+    holders — one chunking rule for both."""
+    els = list(outside_sdts(content))
+    if paras := [p for p in els if p.tag == qn('w:p')]:
+        return [(p, outside_text(p)) for p in paras]
+    return [(content, outside_text(content))]
+
+
+def group_literals(content) -> list:
+    """A group's literal value alternatives: the text it shows when no
+    control applies."""
+    return [text for _, text in group_chunks(content) if text]

docxcast/derive.py

@@ -0,0 +1,203 @@
+"""Derive a Schema from the content controls of a docx template."""
+
+from __future__ import annotations
+
+from docx import Document
+
+from docxcast._ooxml import (
+    CONTAINER_TAGS,
+    KIND_CHECKBOX,
+    KIND_DATE,
+    KIND_DROPDOWN,
+    KIND_GROUP,
+    KIND_ITEM,
+    KIND_REPEAT,
+    KIND_SECTION,
+    RESERVED,
+    date_mask_runs,
+    dropdown_items,
+    group_address,
+    group_literals,
+    group_members,
+    is_block,
+    kind_of,
+    qn,
+    repeating_item,
+    split_conditional,
+    text_attr,
+)
+
+from docxcast.schema import (
+    FORMAT_DATE,
+    FORMAT_DATE_MONTH,
+    FORMAT_DATE_TIME,
+    FORMAT_DATE_YEAR,
+    TYPE_BOOLEAN,
+    Field,
+    Repeat,
+    Schema,
+    Section,
+)
+
+
+def derive_schema(template) -> Schema:
+    """Read the content controls of a docx template and return its Schema.
+
+    template: a path-like or file-like object holding a .docx file.
+    """
+    return _derive(Document(template))
+
+
+class DeriveError(ValueError):
+    """Raised when a template addresses one field twice — e.g. two named
+    members inside a single group. A ValueError so host apps map it to
+    their bad-input response, not a crash."""
+
+
+def _derive(doc: Document) -> Schema:
+    children = []
+    _parse_children(doc.element.body, children)
+    return Schema(children=children)
+
+
+def _parse_children(container, out: list, repeat: bool = False) -> None:
+    for child in container:
+        if child.tag == qn('w:sdt'):
+            _parse_sdt(child, out, repeat)
+        elif child.tag in CONTAINER_TAGS:
+            _parse_children(child, out, repeat)
+
+
+def _parse_sdt(sdt, out: list, repeat: bool = False) -> None:
+    pr = sdt.find(qn('w:sdtPr'))
+    if pr is None:
+        return
+    name = text_attr(pr, 'w:alias')
+    remark = text_attr(pr, 'w:tag')
+    kind = kind_of(pr)
+    if kind in (KIND_REPEAT, KIND_SECTION) and name is None:
+        return  # unaddressable, skip entirely
+    if kind != KIND_GROUP:
+        if split_conditional(name)[1]:
+            raise DeriveError(f'{name!r}: a trailing "?" marks a conditional block — '
+                              'wrap the block in a group control')
+        if name in RESERVED:
+            raise DeriveError(f'{name!r} is reserved for the positional guards '
+                              f'({"/".join(sorted(RESERVED))}) inside repeats')
+    content = sdt.find(qn('w:sdtContent'))
+    if kind == KIND_REPEAT:
+        out.append(_parse_repeat(content, name, remark, _is_locked(pr)))
+    elif kind == KIND_ITEM:
+        _parse_children(content, out, repeat)
+    elif kind == KIND_SECTION:
+        out.append(_parse_section(content, name, remark, _is_locked(pr)))
+    elif kind == KIND_GROUP:
+        if (group := _parse_group(pr, content, repeat)) is not None:
+            out.append(group)
+    elif name is not None:
+        out.append(_parse_field(pr, name, remark, _is_locked(pr), kind))
+
+
+def _parse_repeat(content, name, remark, required) -> Repeat:
+    fields = []
+    if (item := repeating_item(content)) is not None:
+        _parse_children(item.find(qn('w:sdtContent')), fields, repeat=True)
+    return Repeat(name=name, remark=remark, fields=fields, required=required)
+
+
+def _parse_section(content, name, remark, required) -> Section:
+    # a section fills from its own dict at render, so a repeat item's
+    # positional-guard scope ends here
+    children = []
+    _parse_children(content, children)
+    return Section(name=name, remark=remark, children=children, required=required)
+
+
+def _parse_field(pr, name: str, remark, required: bool, kind: str) -> Field:
+    kwargs = {}
+    if kind == KIND_DROPDOWN:
+        pairs = dropdown_items(pr)
+        kwargs.update(enum=[v for _, v in pairs], enum_labels=[d for d, _ in pairs])
+    elif kind == KIND_DATE:
+        date = pr.find(qn('w:date'))
+        kwargs['format'] = (
+            FORMAT_DATE_TIME if text_attr(date, 'w:storeMappedDataAs') == 'dateTime'
+            else _granularity(text_attr(date, 'w:dateFormat'))
+        )
+    elif kind == KIND_CHECKBOX:
+        kwargs['type'] = TYPE_BOOLEAN
+    return Field(name=name, remark=remark, required=required, **kwargs)
+
+
+def _parse_group(pr, content, repeat: bool = False):
+    """One field assembled from a group's members: the group's own
+    address if it carries one, else the first member that does; every
+    other member must stay anonymous and no second control is allowed.
+    The control member gives type/format; the group's literal text
+    becomes the value alternatives. A trailing '?' on the address turns
+    the group into a conditional block instead: the literal text stays
+    decoration (never alternatives), render drops the whole block when
+    the value is falsy, and the guarded member may be a repeat or
+    section, not just a control."""
+    members = group_members(content)
+    name, remark, source, conditional = group_address(pr, members)
+    for i, (_, _, alias, tag) in enumerate(members):
+        if (alias or tag) and i != source:
+            raise DeriveError(
+                f'group {name!r}: member {alias or tag!r} also carries an address '
+                f'(w:alias/w:tag); a group is one field, address it once')
+    if len(members) > 1:
+        raise DeriveError(
+            f'group {name!r}: {len(members)} control members; a group is one '
+            f'field — one control, the rest literal text')
+    if name is None:
+        return None  # unaddressable, skipped like unaddressable repeats
+    if name in RESERVED:
+        if not conditional:
+            raise DeriveError(f'{name!r} is reserved for the positional guards '
+                              f'({"/".join(sorted(RESERVED))}) inside repeats')
+        if not repeat:
+            raise DeriveError(f'{name}? is a positional guard; it only exists '
+                              'inside a repeating section item')
+        return None  # a render directive, never a schema node
+    if not conditional and is_block(content):
+        raise DeriveError(
+            f'group {name!r}: a block-level group is a conditional block — mark '
+            f'the guarded control\'s Title with a trailing \'?\'')
+    required = _is_locked(pr) or (bool(members) and _is_locked(members[0][1]))
+    if conditional:
+        if not members:  # the group itself is the guard of static content
+            return Field(name=name, remark=remark, required=required)
+        msdt, mpr, _, _ = members[0]
+        mcontent = msdt.find(qn('w:sdtContent'))
+        if (mkind := kind_of(mpr)) == KIND_REPEAT:
+            return _parse_repeat(mcontent, name, remark, required)
+        if mkind == KIND_SECTION:
+            return _parse_section(mcontent, name, remark, required)
+        return _parse_field(mpr, name, remark, required, mkind)
+    if members:
+        field = _parse_field(members[0][1], name, remark, required, kind_of(members[0][1]))
+    else:
+        field = Field(name=name, remark=remark, required=required)
+    if literals := group_literals(content):
+        field.alternatives = literals
+    return field
+
+
+def _granularity(date_format) -> str:
+    """The picker's own display format names the finest unit the value
+    carries; quoted literals in the mask are decoration, not tokens."""
+    if not date_format:
+        return FORMAT_DATE  # a bare picker collects a full date
+    letters = {letter for letter, _ in date_mask_runs(date_format) if letter}
+    if 'd' in letters:
+        return FORMAT_DATE
+    return FORMAT_DATE_MONTH if 'M' in letters else FORMAT_DATE_YEAR
+
+
+def _is_locked(pr) -> bool:
+    lock = pr.find(qn('w:lock'))
+    if lock is None:
+        return False
+    vals = {lock.get(qn('w:val')), lock.get(qn('w:lockType'))}
+    return 'sdtLocked' in vals

docxcast/render.py

@@ -0,0 +1,306 @@
+"""Render data back into a docx template: fill controls, clone repeats, unwrap."""
+
+from __future__ import annotations
+
+import re
+from calendar import month_abbr, month_name
+from copy import deepcopy
+from dataclasses import dataclass
+from io import BytesIO
+from pathlib import Path
+from typing import Optional
+
+from docx import Document
+from lxml import etree
+
+from docxcast._ooxml import (
+    CONTAINER_TAGS,
+    KIND_CHECKBOX,
+    KIND_DATE,
+    KIND_DROPDOWN,
+    KIND_GROUP,
+    KIND_ITEM,
+    KIND_PICTURE,
+    KIND_REPEAT,
+    KIND_SECTION,
+    XML_SPACE,
+    dropdown_items,
+    date_mask_runs,
+    group_address,
+    group_chunks,
+    group_literals,
+    group_members,
+    kind_of,
+    qn,
+    repeating_item,
+    scope_guards,
+    split_conditional,
+    text_attr,
+)
+from docxcast.derive import _derive
+from docxcast.schema import Issue, ValidationResult
+
+
+class RenderError(Exception):
+    """Raised by render(strict=True) on the first error-level validation issue."""
+
+    def __init__(self, issue: Issue):
+        self.issue = issue
+        super().__init__(f'{issue.path}: {issue.message}')
+
+
+@dataclass
+class RenderResult:
+    document: bytes
+    report: ValidationResult
+
+    def save(self, path) -> None:
+        Path(path).write_bytes(self.document)
+
+
+def render(template, data, *, strict: bool = False, keep_controls: bool = False) -> RenderResult:
+    """Fill data into the template's content controls and return the rendered docx.
+
+    Controls are unwrapped by default so the output is a clean document; pass
+    keep_controls=True to keep the control structure for round-trip editing.
+    The template is re-parsed on every call and data is validated against it.
+    """
+    doc = Document(template)
+    report = _derive(doc).validate(data)
+    if strict and report.errors:
+        raise RenderError(report.errors[0])
+    _fill_children(doc.element.body, _as_dict(data), keep_controls)
+    buf = BytesIO()
+    doc.save(buf)
+    return RenderResult(document=buf.getvalue(), report=report)
+
+
+def _fill_children(container, data: dict, keep_controls: bool) -> None:
+    for child in list(container):
+        if child.tag == qn('w:sdt'):
+            _handle_sdt(child, data, keep_controls)
+        elif child.tag in CONTAINER_TAGS:
+            _fill_children(child, data, keep_controls)
+
+
+def _handle_sdt(sdt, data: dict, keep_controls: bool) -> None:
+    pr = sdt.find(qn('w:sdtPr'))
+    content = sdt.find(qn('w:sdtContent'))
+    if pr is None or content is None:
+        return
+    # derive rejects '?' outside conditional groups, so by fill time a
+    # marked address is always a conditional group's member
+    alias, _ = split_conditional(text_attr(pr, 'w:alias'))
+    kind = kind_of(pr)
+    value = data.get(alias) if alias else None
+
+    if kind == KIND_REPEAT:
+        if value is None:
+            _unwrap(sdt, [], keep_controls)
+            return
+        item = repeating_item(content)
+        if item is None:
+            return
+        blocks = []
+        for i, entry in enumerate(value):
+            clone = deepcopy(item)
+            clone_content = clone.find(qn('w:sdtContent'))
+            _fill_children(clone_content, _scoped(entry, i, len(value)), keep_controls)
+            if keep_controls:
+                blocks.append(clone)
+            else:
+                blocks.extend(clone_content)
+        if keep_controls:
+            content[:] = blocks
+        else:
+            _splice(sdt, blocks)
+        return
+
+    if kind in (KIND_SECTION, KIND_ITEM):
+        if kind == KIND_SECTION and value is None:
+            _unwrap(sdt, [], keep_controls)
+            return
+        _fill_children(content, _as_dict(value) if kind == KIND_SECTION else data, keep_controls)
+        _unwrap(sdt, content, keep_controls)
+        return
+
+    if kind == KIND_PICTURE:
+        _unwrap(sdt, [], False)  # picture controls are always removed
+        return
+
+    if kind == KIND_GROUP:
+        _fill_group(sdt, pr, content, data, keep_controls)
+        return
+
+    if value is not None:
+        _fill_leaf(content, kind, value, pr)
+    _unwrap(sdt, content, keep_controls)
+
+
+def _fill_group(sdt, pr, content, data: dict, keep_controls: bool) -> None:
+    """A group renders exactly one of its branches: the value either
+    fills the control (literal text dropped) or is one of the literals
+    (control dropped). keep_controls=True keeps both sides editable
+    instead of erasing the unchosen branch. A conditional group (its
+    address ends in '?') instead gates its whole block on the value:
+    falsy drops the block — label and all — truthy fills transparently
+    with the literal text kept as decoration."""
+    members = group_members(content)
+    name, _, _, conditional = group_address(pr, members)
+    value = data.get(name) if name else None
+    if conditional:
+        if not value:
+            _unwrap(sdt, [], keep_controls)
+            return
+        _fill_children(content, data, keep_controls)
+        _unwrap(sdt, content, keep_controls)
+        return
+    literals = group_literals(content)
+    if value in literals:
+        for msdt, *_ in members:
+            _unwrap(msdt, [], keep_controls)
+    elif value is not None and members:
+        if not keep_controls:
+            _drop_literal_runs(content, set(literals))  # before the fill unwraps the leaf
+        msdt, mpr, _, _ = members[0]
+        mcontent = msdt.find(qn('w:sdtContent'))
+        if mcontent is not None:
+            _fill_leaf(mcontent, kind_of(mpr), value, mpr)
+            _unwrap(msdt, mcontent, keep_controls)
+    _unwrap(sdt, content, keep_controls)
+
+
+def _drop_literal_runs(content, texts: set) -> None:
+    for holder, text in group_chunks(content):
+        if text in texts:
+            for r in [c for c in holder if c.tag == qn('w:r')]:
+                holder.remove(r)
+
+
+def _fill_leaf(content, kind: str, value, pr) -> None:
+    if kind == KIND_CHECKBOX:
+        _set_checkbox(content, pr, bool(value))
+    elif kind == KIND_DROPDOWN:
+        _set_text(content, _display_text(pr, value) or str(value))
+    elif kind == KIND_DATE:
+        _set_text(content, _date_text(pr, value))
+    else:
+        _set_text(content, str(value))
+
+
+def _set_checkbox(content, pr, checked: bool) -> None:
+    checkbox = pr.find(qn('w14:checkbox'))
+    state = None
+    if checkbox is not None:
+        checked_el = checkbox.find(qn('w14:checked'))
+        if checked_el is None:
+            checked_el = etree.SubElement(checkbox, qn('w14:checked'))
+        checked_el.set(qn('w14:val'), '1' if checked else '0')
+        state = checkbox.find(qn('w14:checkedState') if checked else qn('w14:uncheckedState'))
+    glyph = '☒' if checked else '☐'
+    if state is not None and (val := state.get(qn('w14:val'))):
+        glyph = chr(int(val, 16))
+    _set_text(content, glyph)
+
+
+def _display_text(pr, value) -> Optional[str]:
+    target = str(value)
+    for display, item_value in dropdown_items(pr):
+        if item_value == target:
+            return display
+    return None
+
+
+def _date_text(pr, value) -> str:
+    """A date control fills with its own display mask — the same text Word
+    would write had the user picked the date in the picker. Values that
+    don't parse fall back to the raw string. The w:date element is
+    guaranteed: _fill_leaf only routes KIND_DATE controls here."""
+    s = str(value)
+    mask = text_attr(pr.find(qn('w:date')), 'w:dateFormat')
+    if not mask or (parts := _date_parts(s)) is None:
+        return s
+    return _apply_mask(mask, *parts)
+
+
+# the shapes schema's four format regexes accept, capture-grouped: month
+# only opens day, day only opens the clock — a time without a date never
+# parses
+_ISO_RE = re.compile(r'^(\d{4})(?:-(\d{2})(?:-(\d{2})'
+                     r'(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?)?)?')
+
+
+def _date_parts(value: str) -> Optional[tuple]:
+    m = _ISO_RE.match(value)
+    if m is None:
+        return None
+    return tuple(int(p) if p else None for p in m.groups())
+
+
+def _apply_mask(mask: str, year: int, month: Optional[int], day: Optional[int],
+                hour: Optional[int], minute: Optional[int],
+                second: Optional[int]) -> str:
+    """Render a date-time through a Word dateFormat mask, run by run. A
+    run's letter dispatches the field-code units (y/M/d, H/h 24-12-hour,
+    m minute, s second — the units a mask's own granularity guarantees
+    are present); unrecognized letters and literals pass through. Month
+    names are the locale-independent English tables."""
+    out = []
+    for letter, text in date_mask_runs(mask):
+        width = len(text)
+        if letter == 'y':
+            out.append(f'{year:04d}' if width > 2 else f'{year % 100:02d}')
+        elif letter == 'M' and month is not None:
+            out.append(str(month) if width == 1 else month_abbr[month] if width == 3
+                       else month_name[month] if width == 4 else f'{month:02d}')
+        elif letter == 'd' and day is not None:
+            out.append(str(day) if width == 1 else f'{day:02d}')
+        elif letter in ('h', 'H') and hour is not None:
+            h = hour if letter == 'H' else (hour % 12 or 12)
+            out.append(str(h) if width == 1 else f'{h:02d}')
+        elif letter == 'm' and minute is not None:
+            out.append(str(minute) if width == 1 else f'{minute:02d}')
+        elif letter == 's' and second is not None:
+            out.append(str(second) if width == 1 else f'{second:02d}')
+        else:
+            out.append(text)
+    return ''.join(out)
+
+
+def _set_text(content, text: str) -> None:
+    runs = content.findall(qn('w:r'))
+    r = runs[0] if runs else etree.SubElement(content, qn('w:r'))
+    r_pr = r.find(qn('w:rPr'))
+    for extra in runs[1:]:
+        content.remove(extra)
+    r.clear()
+    if r_pr is not None:
+        r.append(r_pr)
+    t = etree.SubElement(r, qn('w:t'))
+    t.set(XML_SPACE, 'preserve')
+    t.text = text
+
+
+def _unwrap(sdt, nodes, keep_controls: bool) -> None:
+    if not keep_controls:
+        _splice(sdt, list(nodes))
+
+
+def _splice(old, nodes) -> None:
+    parent = old.getparent()
+    if parent is None:
+        return
+    for node in nodes:
+        old.addprevious(node)
+    parent.remove(old)
+    if parent.tag == qn('w:tc') and not parent.findall(qn('w:p')):
+        etree.SubElement(parent, qn('w:p'))  # a cell must keep a paragraph
+
+
+def _as_dict(value) -> dict:
+    return value if isinstance(value, dict) else {}
+
+
+def _scoped(entry, i: int, n: int) -> dict:
+    """Item-local guard scope: positional booleans for conditional blocks."""
+    return {**_as_dict(entry), **scope_guards(i, n)}

docxcast/schema.py

@@ -0,0 +1,272 @@
+"""Schema model: the contract derived from a docx template and validated against data."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Optional, Union
+
+class _Missing:
+    """Sentinel that survives deepcopy so asdict-based filtering works."""
+
+    def __deepcopy__(self, memo):
+        return self
+
+
+MISSING = _Missing()
+
+MISSING_REQUIRED = 'missing_required'
+TYPE_MISMATCH = 'type_mismatch'
+ENUM_INVALID = 'enum_invalid'
+FORMAT_INVALID = 'format_invalid'
+UNKNOWN_KEY = 'unknown_key'
+
+FORMAT_DATE = 'date'
+FORMAT_DATE_MONTH = 'date-month'
+FORMAT_DATE_YEAR = 'date-year'
+FORMAT_DATE_TIME = 'date-time'
+TYPE_BOOLEAN = 'boolean'
+
+_MESSAGES = {
+    MISSING_REQUIRED: 'Required value is missing.',
+    TYPE_MISMATCH: 'Value has the wrong type.',
+    ENUM_INVALID: 'Value is not among the allowed options.',
+    FORMAT_INVALID: 'Value does not match the expected format.',
+    UNKNOWN_KEY: 'Key is not defined in the schema.',
+}
+
+# everything except the warning-level code is an error
+ERROR_CODES = frozenset(_MESSAGES) - {UNKNOWN_KEY}
+
+_DATE_RE = re.compile(r'^\d{4}-\d{2}-\d{2}$')
+_DATE_MONTH_RE = re.compile(r'^\d{4}-\d{2}$')
+_DATE_YEAR_RE = re.compile(r'^\d{4}$')
+_DATETIME_RE = re.compile(
+    r'^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:?\d{2})?$'
+)
+
+_FORMATS = (
+    (FORMAT_DATE, _DATE_RE, 'ISO 8601 date (YYYY-MM-DD)'),
+    (FORMAT_DATE_MONTH, _DATE_MONTH_RE, 'ISO 8601 month (YYYY-MM)'),
+    (FORMAT_DATE_YEAR, _DATE_YEAR_RE, 'year (YYYY)'),
+    (FORMAT_DATE_TIME, _DATETIME_RE, 'ISO 8601 date-time'),
+)
+
+# the regex source of truth, emitted as JSON Schema `pattern` so the
+# format branch is enforced by any validator, not just this one
+_PATTERNS = {fmt: rx.pattern for fmt, rx, _ in _FORMATS}
+
+
+@dataclass
+class Issue:
+    """A single validation issue. `message` is English and self-contained."""
+
+    path: str
+    code: str
+    message: str
+    expected: object = MISSING
+    got: object = MISSING
+
+    def to_dict(self) -> dict:
+        return {k: v for k, v in asdict(self).items() if v is not MISSING}
+
+
+@dataclass
+class Field:
+    name: str
+    remark: Optional[str] = None
+    type: str = 'string'  # 'string' | 'boolean'
+    format: Optional[str] = None  # 'date' | 'date-month' | 'date-year' | 'date-time'
+    enum: Optional[list] = None
+    alternatives: Optional[list] = None  # literal values a group shows instead of the format
+    enum_labels: Optional[list] = None  # display labels parallel to enum
+    required: bool = False
+
+    def to_json_schema(self) -> dict:
+        node = self._value_branch()
+        if self.alternatives:
+            # a union carries no type of its own — each branch does
+            node = {'anyOf': [node, {'enum': self.alternatives}]}
+        if self.enum is not None and not self.required:
+            # an optional field may stay unfilled — '' rides the emitted
+            # contract so strict validators (jsonschema etc.) agree with
+            # _validate_field, not just this one
+            node = {'anyOf': [node, {'enum': ['']}]}
+        if (desc := self._description()) is not None:
+            node['description'] = desc
+        return node
+
+    def _value_branch(self) -> dict:
+        """The field's value node — a union wraps it in anyOf."""
+        branch = {'type': self.type}
+        for key, val in (
+            ('format', self.format),
+            ('enum', self.enum),
+            ('pattern', _PATTERNS.get(self.format)),
+        ):
+            if val is not None:
+                branch[key] = val
+        return branch
+
+    def _description(self) -> Optional[str]:
+        if self.enum_labels and self.enum:
+            mapping = '; '.join(f'{d}={v}' for d, v in zip(self.enum_labels, self.enum))
+            return f'{self.remark} ({mapping})' if self.remark else mapping
+        return self.remark
+
+
+@dataclass
+class Repeat:
+    name: str
+    remark: Optional[str] = None
+    fields: list = field(default_factory=list)
+    required: bool = False
+
+    def to_json_schema(self) -> dict:
+        node = {'type': 'array', 'items': _object_schema(self.fields)}
+        if self.remark is not None:
+            node['description'] = self.remark
+        return node
+
+
+@dataclass
+class Section:
+    name: str
+    remark: Optional[str] = None
+    children: list = field(default_factory=list)
+    required: bool = False
+
+    def to_json_schema(self) -> dict:
+        return _object_schema(self.children, self.remark)
+
+
+Node = Union[Field, Repeat, Section]
+
+
+@dataclass
+class Schema:
+    children: list = field(default_factory=list)
+
+    def to_json_schema(self) -> dict:
+        return _object_schema(self.children)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    def validate(self, data: object) -> ValidationResult:
+        issues: list = []
+        if data is not None:
+            _validate_object(self.children, data, '', issues)
+        return ValidationResult(issues=issues)
+
+
+@dataclass
+class ValidationResult:
+    issues: list = field(default_factory=list)
+
+    @property
+    def errors(self) -> list:
+        return [i for i in self.issues if i.code in ERROR_CODES]
+
+    @property
+    def warnings(self) -> list:
+        return [i for i in self.issues if i.code not in ERROR_CODES]
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def to_dict(self) -> dict:
+        return {'ok': self.ok, 'issues': [i.to_dict() for i in self.issues]}
+
+
+def _nullable(schema: dict) -> dict:
+    """An optional object may also be null — the shape the model reads:
+    an omitted structure field is absent, not filled with an empty
+    object. Arrays keep a single type: empty already reads falsy to
+    the renderer, and the dashscope schema validator rejects type
+    unions on arrays."""
+    if schema.get('type') == 'object':
+        schema['type'] = ['object', 'null']
+    return schema
+
+
+def _object_schema(children: list, remark: Optional[str] = None) -> dict:
+    node = {'type': 'object'}
+    if children:
+        node['properties'] = {
+            c.name: c.to_json_schema() if c.required
+            else _nullable(c.to_json_schema()) for c in children}
+    required = [c.name for c in children if c.required]
+    if required:
+        node['required'] = required
+    if remark is not None:
+        node['description'] = remark
+    return node
+
+
+def _validate_children(nodes: list, data: dict, prefix: str, issues: list) -> None:
+    known = set()
+    for node in nodes:
+        known.add(node.name)
+        value = data.get(node.name, MISSING)
+        if value is MISSING:
+            if node.required:
+                issues.append(_issue(_path(prefix, node.name), MISSING_REQUIRED))
+            continue
+        _validate_node(node, value, _path(prefix, node.name), issues)
+    for key in data:
+        if key not in known:
+            issues.append(_issue(_path(prefix, key), UNKNOWN_KEY))
+
+
+def _validate_node(node: Node, value: object, path: str, issues: list) -> None:
+    if value is None:
+        if node.required:
+            issues.append(_issue(path, MISSING_REQUIRED))
+        return  # null is an absent value, allowed on every optional node
+    if isinstance(node, Section):
+        _validate_object(node.children, value, path, issues)
+    elif isinstance(node, Repeat):
+        if not isinstance(value, list):
+            issues.append(_issue(path, TYPE_MISMATCH, expected='array', got=value))
+            return
+        for i, item in enumerate(value):
+            _validate_object(node.fields, item, f'{path}[{i}]', issues)
+    else:
+        _validate_field(node, value, path, issues)
+
+
+def _validate_object(nodes: list, value: object, path: str, issues: list) -> None:
+    if not isinstance(value, dict):
+        issues.append(_issue(path, TYPE_MISMATCH, expected='object', got=value))
+        return
+    _validate_children(nodes, value, path, issues)
+
+
+def _validate_field(field: Field, value: object, path: str, issues: list) -> None:
+    if field.alternatives and value in field.alternatives:
+        return  # a literal alternative satisfies the union on its own
+    if field.type == TYPE_BOOLEAN:
+        if not isinstance(value, bool):
+            issues.append(_issue(path, TYPE_MISMATCH, expected=TYPE_BOOLEAN, got=value))
+        return
+    if not isinstance(value, str):
+        issues.append(_issue(path, TYPE_MISMATCH, expected=field.type, got=value))
+        return
+    if value == '' and not field.required:
+        return  # an optional field may stay unfilled: emptiness is governed
+                # by required (the control's lock), never by enum membership
+    if field.enum is not None and value not in field.enum:
+        issues.append(_issue(path, ENUM_INVALID, expected=field.enum, got=value))
+    for fmt, rx, label in _FORMATS:
+        if field.format == fmt and not rx.match(value):
+            issues.append(_issue(path, FORMAT_INVALID, expected=label, got=value))
+
+
+def _issue(path: str, code: str, expected: object = MISSING, got: object = MISSING) -> Issue:
+    return Issue(path=path, code=code, message=_MESSAGES[code], expected=expected, got=got)
+
+
+def _path(prefix: str, name: str) -> str:
+    return f'{prefix}.{name}' if prefix else name

docxcast-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: docxcast
+Version: 0.1.0
+Summary: DocXCast: Turn Word content controls into a typed schema, then cast your data back into documents
+Project-URL: Homepage, https://github.com/flowjzh/docxcast
+Project-URL: Repository, https://github.com/flowjzh/docxcast.git
+Project-URL: Issues, https://github.com/flowjzh/docxcast/issues
+Author-email: Flow Jiang <flowjzh@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: content-controls,docx,llm,schema,structured-data,template,word
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: python-docx>=1.2.0
+Description-Content-Type: text/markdown
+
+# DocXCast
+
+<img width="600" alt="DocXCast" src="https://github.com/user-attachments/assets/dc3287be-341a-4d88-a18d-71acc48c0169" />
+
+> **"Your template is the mold. Data is poured in, documents take shape."**
+
+### 🪄 About
+
+**DocXCast** turns a Word document's **content controls** into a typed schema, and casts your data back into a formatted document.
+
+**The Idea:**
+
+A `.docx` template is a natural schema editor. In Word's Developer tab, anyone can insert content controls and describe them:
+
+| Word control property | Role in DocXCast |
+|---|---|
+| **Title** | field name (e.g. `name`) |
+| **Tag** | extraction requirement for the LLM (e.g. `the candidate's full name`) |
+| **Repeating section** | array of records |
+| **Building block gallery** | `Section` with its own extraction rule |
+| **Group control** with a `name?` Title | conditional block (see below) |
+| Locked control (`sdtLocked`) | required field |
+
+The full control inventory — every construct's Word-visible pseudo-structure and the OOXML it is made of — lives in **[SYNTAX.md](SYNTAX.md)**.
+
+**Two independent capabilities:**
+
+1. `derive_schema(template)` — read the controls and produce a `Schema`, serializable to JSON Schema for LLM structured extraction.
+2. `render(template, data)` — pour data back into the template: clone repeating sections, fill values, unwrap controls, keeping every run's formatting.
+
+### ⚡ Key Features
+
+* **Your template IS the schema** — field names, extraction requirements and repeats all live in the docx, editable by non-programmers.
+* **Typed control mapping** — text → `string`, dropdown → `enum`, date / date-time → `format`, checkbox → `boolean`, picture → derived and removed.
+* **LLM-friendly contract validation** — `schema.validate(data)` returns structured, machine-readable issues (`path` / `code` / `message` / `expected` / `got`) that can be fed back into an LLM correction loop.
+* **Lenient by default, strict on demand** — missing fields keep their template values; `strict=True` raises on the first error.
+* **Clean output** — controls are unwrapped by default; `keep_controls=True` keeps them for round-trip editing.
+* **Zero magic** — a single runtime dependency (`python-docx`).
+
+### 🚀 Quick Start
+
+```python
+from docxcast import derive_schema, render
+
+schema = derive_schema('resume-template.docx')
+
+# hand this to your LLM as the extraction contract
+json_schema = schema.to_json_schema()
+
+# validate what the LLM extracted
+report = schema.validate(data)
+if not report.ok:
+    # feed report.issues back into the LLM for correction
+    ...
+
+# cast data into the template; controls are unwrapped
+result = render('resume-template.docx', data)
+result.save('resume-output.docx')
+```
+
+### 📏 Validation
+
+`Schema.validate()` never raises; it returns a `ValidationResult`:
+
+```python
+result.ok      # False if any error-level issue exists
+result.errors  # missing_required / type_mismatch / enum_invalid / format_invalid
+result.warnings  # unknown_key
+```
+
+`render(..., strict=True)` raises `RenderError` on the first error-level issue.
+
+### 🔀 Conditional Blocks
+
+Wrap a block in a **group control** and mark the guarded control's Title with a trailing `?` (TS-style): a falsy value removes the whole group — label text included — while a truthy value fills normally.
+
+```
+Nationality: [nationality?]   truthy → "Nationality: Chinese"   falsy → the line is gone
+
+Work Experiences              both the heading and the repeat
+[repeat: work_experiences?]   disappear when the array is empty
+```
+
+The `?` is a render directive only — the derived schema (and the LLM contract) see a plain `nationality` field. Marker placement, inline vs block-level drops, positional `has_prev?` / `has_next?` separators and every misuse error live in **[SYNTAX.md](SYNTAX.md)**.
+
+### ⚠️ Limitations
+
+* `picture` controls are recognized in the schema but removed on render (no image insertion yet).
+* Date values are written verbatim; the template's display mask is not enforced.
+* Unnamed controls are skipped in the schema — every field needs a Title to be addressable.
+* No whitespace control: text outside a dropped inline conditional span survives — put separators inside the span.

docxcast-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+docxcast/__init__.py,sha256=I7d8XVZXj08TU6HBgX122rk6mKWKjt6SD0lv5FwQ-R0,869
+docxcast/_ooxml.py,sha256=MGHIJJEoGswiGdz5V1XnO53dG9eoQf9F0q0dtXVmvPc,6419
+docxcast/derive.py,sha256=ksZYA-gzlf0PpD_lEKnjCmah-77q7XvJkm7AiSMpB5Y,7660
+docxcast/render.py,sha256=-4a60DsgSLzP_oh-LvTbUrDz_acTDiXnSBuJW3DM8VE,10584
+docxcast/schema.py,sha256=HN0LHMC04oVxAWuTC3hrS2NeeVHL7MVyvvcxTOQCZpw,9203
+docxcast-0.1.0.dist-info/METADATA,sha256=-a_7UTrbVI_Aq3Mpxgzb4VI0ZaQKgzxp8xYmssGjBjQ,5449
+docxcast-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+docxcast-0.1.0.dist-info/licenses/LICENSE,sha256=h8-551rXql0Z6aYn_7eita2vDlYtGqP12OGxrmlaQ74,1067
+docxcast-0.1.0.dist-info/RECORD,,

docxcast-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

docxcast-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flow Jiang
+
+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.