#!/usr/bin/env python3
"""docx_tool — create .docx from markdown-ish text, or edit an existing one. Stdlib only.
create — markdown-lite → a real Word document:
python3 docx_tool.py create out.docx --text-file doc.md
echo "# Title\nBody **bold** text\n- bullet" | python3 docx_tool.py create out.docx --stdin
Supports: # / ## / ### headings, - bullets, 1. numbered, **bold**, *italic*, plain paragraphs.
fill — replace {{placeholders}} through an existing .docx (body, headers, footers):
python3 docx_tool.py fill template.docx out.docx --values '{"client":"Acme","date":"2026-07-03"}'
Handles Word's habit of splitting placeholders across runs by merging run text per paragraph
when a placeholder spans runs (formatting of the merged paragraph collapses to the first run).
extract — pull plain text out (for verification or diffing):
python3 docx_tool.py extract file.docx
Limits (honest): create supports the markdown subset above, default styling only;
fill collapses per-run formatting ONLY in paragraphs where a placeholder spans runs.
"""
import argparse, json, re, sys, zipfile
from xml.sax.saxutils import escape
W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
def runs_from_inline(text):
out = []
for tok in re.split(r"(\*\*.+?\*\*|\*.+?\*)", text):
if not tok: continue
if tok.startswith("**") and tok.endswith("**"):
out.append(f'{escape(tok[2:-2])}')
elif tok.startswith("*") and tok.endswith("*"):
out.append(f'{escape(tok[1:-1])}')
else:
out.append(f'{escape(tok)}')
return "".join(out) or ''
def para(text, style=None, numbered=False, bullet=False):
ppr = ""
if style: ppr = f''
if bullet: ppr = ''
if numbered: ppr = ''
return f'{ppr}{runs_from_inline(text)}'
STYLES = f'''
'''
NUMBERING = f'''
'''
def create(out, text):
body = []
for line in text.splitlines():
s = line.rstrip()
if not s.strip(): continue
if s.startswith("### "): body.append(para(s[4:], style="Heading3"))
elif s.startswith("## "): body.append(para(s[3:], style="Heading2"))
elif s.startswith("# "): body.append(para(s[2:], style="Heading1"))
elif re.match(r"^[-*] ", s): body.append(para(s[2:], bullet=True))
elif re.match(r"^\d+[.)] ", s): body.append(para(re.sub(r"^\d+[.)] ", "", s), numbered=True))
else: body.append(para(s))
document = (f''
f'{"".join(body)}')
with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z:
z.writestr("[Content_Types].xml",
''
''
''
''
''
''
''
'')
z.writestr("_rels/.rels",
''
''
''
'')
z.writestr("word/_rels/document.xml.rels",
''
''
''
''
'')
z.writestr("word/styles.xml", STYLES)
z.writestr("word/numbering.xml", NUMBERING)
z.writestr("word/document.xml", document)
print(f"wrote {out}")
def merge_split_placeholders(xml):
# Word splits text across runs arbitrarily; if a {{token}} spans runs,
# merge that paragraph's runs into one (first run's formatting wins).
def para_fix(m):
p = m.group(0)
texts = re.findall(r"]*>(.*?)", p, re.S)
joined = "".join(texts)
if "{{" in joined and not any("{{" in t and "}}" in t for t in texts):
first_rpr = re.search(r".*?", p, re.S)
rpr = first_rpr.group(0) if first_rpr else ""
new_run = f'{rpr}{joined}'
return re.sub(r"", new_run, p, flags=re.S)
return p
return re.sub(r"", para_fix, xml, flags=re.S)
def fill(template, out, values):
replaced = 0
with zipfile.ZipFile(template) as zin, zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as zout:
for item in zin.namelist():
data = zin.read(item)
if re.match(r"word/(document|header\d*|footer\d*)\.xml$", item):
text = merge_split_placeholders(data.decode("utf-8"))
for k, v in values.items():
token = "{{" + k + "}}"
replaced += text.count(token)
text = text.replace(token, escape(str(v)))
data = text.encode("utf-8")
zout.writestr(item, data)
print(f"wrote {out}: {replaced} placeholder(s) filled")
if replaced == 0:
print("warning: no {{placeholders}} found", file=sys.stderr)
def extract(path):
with zipfile.ZipFile(path) as z:
xml = z.read("word/document.xml").decode("utf-8")
for p in re.findall(r"", xml, re.S):
line = "".join(re.findall(r"]*>(.*?)", p, re.S))
if line.strip(): print(line)
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
sub = ap.add_subparsers(dest="cmd", required=True)
c = sub.add_parser("create"); c.add_argument("out"); c.add_argument("--text"); c.add_argument("--text-file"); c.add_argument("--stdin", action="store_true")
f = sub.add_parser("fill"); f.add_argument("template"); f.add_argument("out"); f.add_argument("--values", required=True)
e = sub.add_parser("extract"); e.add_argument("path")
a = ap.parse_args()
if a.cmd == "create":
text = a.text or (open(a.text_file).read() if a.text_file else sys.stdin.read())
create(a.out, text)
elif a.cmd == "fill":
fill(a.template, a.out, json.loads(a.values))
else:
extract(a.path)
if __name__ == "__main__":
main()