mdhtml2docx 0.1.2__tar.gz → 0.1.4__tar.gz

mdhtml2docx-0.1.4/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: mdhtml2docx
+Version: 0.1.4
+Summary: Convert MDHTML to Word docx files
+Author-email: Jeremy Howard <j@fast.ai>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/AnswerDotAI/mdhtml2docx
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mdhtml>=0.1.39
+Requires-Dist: fast5ever>=0.1.5
+Requires-Dist: oxml>=0.1.1
+Provides-Extra: validation
+Requires-Dist: lxml; extra == "validation"
+Provides-Extra: dev
+Requires-Dist: mdhtml2docx[validation]; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: fastship; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# mdhtml2docx
+
+Convert [MDHTML](https://github.com/AnswerDotAI/mdhtml) to Word docx files.
+
+`mdhtml` renders Markdown to an HTML5 document format shared by format-specific exporters. `mdhtml2docx` converts its portable core to docx from scratch. It uses [fast5ever](https://github.com/AnswerDotAI/fast5ever)'s mutable WHATWG DOM for input and `oxml` for WordprocessingML construction, reference editing, DOCX packaging, and atomic saving. XML construction uses namespace-bound factories such as `e.tcW(type='dxa', w=2400)`, backed by fastcore's XML builder. Conversion requires neither lxml nor a .NET or Office runtime.
+
+MDHTML accepts the full HTML vocabulary. This exporter supports the elements and annotations listed below. It preserves the text of unknown inline elements and recurses through block containers. It returns a warning when an unsupported block must become a plain paragraph. HTML parsing and repair belong to `mdhtml`.
+
+## Usage
+
+```python
+from mdhtml import md2mdhtml
+from mdhtml2docx import mdhtml2docx
+
+html = md2mdhtml(markdown_text)
+warnings = mdhtml2docx(html, 'out.docx')
+```
+
+`mdhtml2docx` takes an MDHTML string, writes a docx, and returns a list of warning strings. It parses strings with `mdhtml.mdhtml2dom`. Normal HTML5 repair applies; the input need not be well-formed XML.
+
+You can also pass an existing mutable fast5ever DOM:
+
+```python
+from mdhtml import mdhtml2dom
+
+document = mdhtml2dom(html)
+document.children[0].attrs['custom-style'] = 'Contract Title'
+warnings = mdhtml2docx(document, 'out.docx')
+```
+
+Body-position text and phrasing content become implicit Word paragraphs. Whitespace between blocks does not produce content. HTML templates are not rendered.
+
+## Supported content
+
+The exporter supports these elements:
+
+- Headings, paragraphs, block quotes, fenced and indented code blocks, and horizontal rules.
+- Bold, italic, strikethrough, underline (`u`), highlight, superscript, subscript, inline code, and abbreviations.
+- External links and internal links through bookmarks.
+- Images from local files, embedded with their dimensions. Remote image URLs become links.
+- Bullet and numbered lists, including nesting, `start`, and task-list checkboxes.
+- Pipe and grid tables, including row and column spans and header rows.
+- Definition lists and footnotes.
+
+A `details` div becomes its label as a bold line above the body. It does not become a numbered heading or retain its collapsible behavior.
+
+Math spans and blocks become native Word math zones (`m:oMath`). These contain the source text unchanged, whether TeX, UnicodeMath, or AsciiMath. Math build-up and rendering are left to downstream tools. Pandoc reads the zones back as math.
+
+When [fastpylight](https://github.com/AnswerDotAI/fastpylight) is installed, code blocks with a language use syntax coloring. Tokens receive `Hl*` character styles such as `Hl Keyword`. Their colors come from the reference theme described below. You can restyle them in Word.
+
+## Styling
+
+The generated document uses named styles instead of inline formatting. Change the styles to change its appearance.
+
+Markdown headings map to Word styles as follows:
+
+- h1 uses Title and displays no number. It carries the numbering's invisible level 0, which restarts the count below each title. A file containing several documents can therefore number each from 1.
+- h2 through h6 use Heading 1 through Heading 5.
+
+Prose uses Body Text. The first paragraph after a heading or similar block uses First Paragraph, following Pandoc's convention. Other styles include Quote, Source Code, Verbatim Char, Hyperlink, List Paragraph, Compact for table cells, Definition Term, Definition, caption, and footnote styles. Tables default to Table Grid. The built-in template also provides Borderless Table for signature blocks and other layout tables.
+
+### Reference documents and themes
+
+Pass `reference='mydoc.docx'` to use your own document's styles, as with Pandoc's `--reference-doc`.
+
+Reference parts are located through their relationships, not assumed filenames. Existing reference media and unrelated parts are preserved; new images receive non-colliding part names, and relationship IDs are allocated in each source part's scope.
+
+`reference` also accepts a list. The first entry supplies the document, including page setup, fonts, and base styles. Later entries contribute styles and replace earlier styles with the same name. Each can be another `.docx` or a fastpylight theme name such as `'dracula'`.
+
+The default is the built-in template plus `'github_light'`. Pass a reference document without a theme for plain, uncolored code. To write a theme's styles to a standalone docx for inspection or editing, use `mdhtml2docx.styles.theme_ref('dracula', 'dracula.docx')`.
+
+The built-in template is generated by `tools/createref.py` from a stock Word document. It defines the styles the converter emits and next-paragraph chains for continued editing in Word.
+
+### Style annotations and table widths
+
+A `custom-style="Name"` attribute, written as `{custom-style="Name"}` in Markdown, applies that style from your reference document. If the style is missing, the converter inserts a stub and returns a warning.
+
+A plain class such as `{.note}` applies a style only when the reference document defines one named `note`. Otherwise it is ignored. Both annotations also work on tables. A named table style replaces Table Grid.
+
+Tables can mix fixed and proportional column widths. Add an attribute list after the table: `{: colwidths="10em 2fr 1fr"}`. Lengths fix a column's width. The `fr` values divide the remaining width proportionally, as in CSS grid.
+
+## Raw docx
+
+The converter accepts MDHTML raw data with `data-format="docx"`:
+
+```html
+<script type="application/vnd.mdhtml.raw" data-format="docx">…</script>
+```
+
+A ```` ```{=docx} ```` fenced block in Markdown, or inline code followed by `{=docx}`, produces this element. The payload is parsed as WordprocessingML and inserted verbatim. Block payloads contain elements such as `w:p` or `w:tbl`. Inline payloads contain elements such as `w:r`. The prefixes `w`, `r`, `wp`, `a`, `pic`, and `m` are predeclared.
+
+Payload encoding follows these rules:
+
+- No `data-encoding`: use the literal payload.
+- `data-encoding="html"`: perform one character-reference decoding pass.
+- `data-encoding="base64"`: decode a base64-encoded UTF-8 payload.
+
+Malformed payloads and unknown encodings are dropped with a warning. Raw data for other formats is skipped silently.
+
+For example, insert a page break with:
+
+    ```{=docx}
+    <w:p><w:r><w:br w:type="page"/></w:r></w:p>
+    ```
+
+## Cross-references
+
+Markdown references such as `[@sec-payment]` become live Word REF fields. MDHTML represents them as `a` elements with `data-ref`.
+
+The default field is `REF <bookmark> \w \h`. It displays the full-context paragraph number, such as "3.(c)(iii)", as a hyperlink. The converter sets `updateFields` in `settings.xml` so Word refreshes fields on open.
+
+The `leaf`, `rel`, `text`, and `page` tokens select other fields. The independent `bare` token suppresses the prefix word. Unknown or conflicting tokens are conversion errors.
+
+### Prefixes and groups
+
+The reference type is the part of the target id before its first `-`. It determines the word before the number. The built-in `sec` type uses Section or Sections. Add types with `reftypes=dict(exh=('Exhibit', 'Exhibits'))`.
+
+Use `[Clause @sec-x]` to override the word for one reference, or `[-@sec-x]` to suppress it.
+
+Grouped references use a `span` with `data-refs`. They render as "Sections 3.1 and 4.2", with one field per number. Groups never collapse into static ranges such as "3.1-3.3", whose meaning could change when a clause is inserted.
+
+A missing target id raises a conversion error. A reference type with no defined prefix also raises when a prefix is required. A lawyer's document must not open showing "Error! Reference source not found."
+
+### Heading numbering
+
+Number fields require numbered headings. If your reference docx already numbers its heading styles, the converter leaves that numbering unchanged.
+
+Otherwise, select a scheme with `number_headings`:
+
+- `'legal'` uses 1. / (a) / (i) numbering.
+- `'decimal'` uses 1. / 1.1. / 1.1.1. numbering.
+- A `{lvlText: numFmt}` dictionary supplies a custom scheme, with one entry per heading level from h1 down. Level 0 is the h1 title with an empty `lvlText`. `%2` is the h2 counter.
+
+The named schemes come from mdhtml's `SCHEMES`. The custom dictionary uses the same format as mdhtml.
+
+A reference-list entry ending in `.xml` can also supply styles and numbering. It contains raw `w:style`, `w:abstractNum`, and `w:num` elements. Each contributor's ids and references are remapped before merging, so separate contributors can reuse the same original numbering ids; later styles still win.
+
+### Figures and tables
+
+Figures and captioned tables use live SEQ fields. A figure's caption appears below its image as "Figure 1: caption", using the caption style. A table's caption appears above it as "Table 1: caption".
+
+When the element has an id, the converter bookmarks its label and number. `[@fig-plot]` inserts "Figure 1" from that bookmark without adding another prefix. A second, number-only bookmark supplies the bare number for references such as `[-@tbl-stages]`.
+
+`fig` and `tbl` are built-in reference types alongside `sec`. Their labels come from the same `reftypes` table. Same-type groups pluralize once. Mixed-type groups use each item's singular prefix, as in "Figure 1 and Table 2".
+
+Reference targets must be headings, paragraphs, figures, or tables with ids. A reference to anything else raises a conversion error.
+
+## Validation
+
+Independent schema validation is optional. Install `mdhtml2docx[validation]` to use `mdhtml2docx.validate.fast_checks(path)`; this extra requires lxml. Normal conversion does not import it.
+
+The test suite checks docx containers, CRCs, and XML, validates against the ECMA-376 schemas with lxml, and performs semantic round trips through Pandoc's independent docx reader. Periodic acceptance runs open documents in Microsoft Word through AppleScript.

mdhtml2docx-0.1.4/README.md

@@ -0,0 +1,152 @@
+# mdhtml2docx
+
+Convert [MDHTML](https://github.com/AnswerDotAI/mdhtml) to Word docx files.
+
+`mdhtml` renders Markdown to an HTML5 document format shared by format-specific exporters. `mdhtml2docx` converts its portable core to docx from scratch. It uses [fast5ever](https://github.com/AnswerDotAI/fast5ever)'s mutable WHATWG DOM for input and `oxml` for WordprocessingML construction, reference editing, DOCX packaging, and atomic saving. XML construction uses namespace-bound factories such as `e.tcW(type='dxa', w=2400)`, backed by fastcore's XML builder. Conversion requires neither lxml nor a .NET or Office runtime.
+
+MDHTML accepts the full HTML vocabulary. This exporter supports the elements and annotations listed below. It preserves the text of unknown inline elements and recurses through block containers. It returns a warning when an unsupported block must become a plain paragraph. HTML parsing and repair belong to `mdhtml`.
+
+## Usage
+
+```python
+from mdhtml import md2mdhtml
+from mdhtml2docx import mdhtml2docx
+
+html = md2mdhtml(markdown_text)
+warnings = mdhtml2docx(html, 'out.docx')
+```
+
+`mdhtml2docx` takes an MDHTML string, writes a docx, and returns a list of warning strings. It parses strings with `mdhtml.mdhtml2dom`. Normal HTML5 repair applies; the input need not be well-formed XML.
+
+You can also pass an existing mutable fast5ever DOM:
+
+```python
+from mdhtml import mdhtml2dom
+
+document = mdhtml2dom(html)
+document.children[0].attrs['custom-style'] = 'Contract Title'
+warnings = mdhtml2docx(document, 'out.docx')
+```
+
+Body-position text and phrasing content become implicit Word paragraphs. Whitespace between blocks does not produce content. HTML templates are not rendered.
+
+## Supported content
+
+The exporter supports these elements:
+
+- Headings, paragraphs, block quotes, fenced and indented code blocks, and horizontal rules.
+- Bold, italic, strikethrough, underline (`u`), highlight, superscript, subscript, inline code, and abbreviations.
+- External links and internal links through bookmarks.
+- Images from local files, embedded with their dimensions. Remote image URLs become links.
+- Bullet and numbered lists, including nesting, `start`, and task-list checkboxes.
+- Pipe and grid tables, including row and column spans and header rows.
+- Definition lists and footnotes.
+
+A `details` div becomes its label as a bold line above the body. It does not become a numbered heading or retain its collapsible behavior.
+
+Math spans and blocks become native Word math zones (`m:oMath`). These contain the source text unchanged, whether TeX, UnicodeMath, or AsciiMath. Math build-up and rendering are left to downstream tools. Pandoc reads the zones back as math.
+
+When [fastpylight](https://github.com/AnswerDotAI/fastpylight) is installed, code blocks with a language use syntax coloring. Tokens receive `Hl*` character styles such as `Hl Keyword`. Their colors come from the reference theme described below. You can restyle them in Word.
+
+## Styling
+
+The generated document uses named styles instead of inline formatting. Change the styles to change its appearance.
+
+Markdown headings map to Word styles as follows:
+
+- h1 uses Title and displays no number. It carries the numbering's invisible level 0, which restarts the count below each title. A file containing several documents can therefore number each from 1.
+- h2 through h6 use Heading 1 through Heading 5.
+
+Prose uses Body Text. The first paragraph after a heading or similar block uses First Paragraph, following Pandoc's convention. Other styles include Quote, Source Code, Verbatim Char, Hyperlink, List Paragraph, Compact for table cells, Definition Term, Definition, caption, and footnote styles. Tables default to Table Grid. The built-in template also provides Borderless Table for signature blocks and other layout tables.
+
+### Reference documents and themes
+
+Pass `reference='mydoc.docx'` to use your own document's styles, as with Pandoc's `--reference-doc`.
+
+Reference parts are located through their relationships, not assumed filenames. Existing reference media and unrelated parts are preserved; new images receive non-colliding part names, and relationship IDs are allocated in each source part's scope.
+
+`reference` also accepts a list. The first entry supplies the document, including page setup, fonts, and base styles. Later entries contribute styles and replace earlier styles with the same name. Each can be another `.docx` or a fastpylight theme name such as `'dracula'`.
+
+The default is the built-in template plus `'github_light'`. Pass a reference document without a theme for plain, uncolored code. To write a theme's styles to a standalone docx for inspection or editing, use `mdhtml2docx.styles.theme_ref('dracula', 'dracula.docx')`.
+
+The built-in template is generated by `tools/createref.py` from a stock Word document. It defines the styles the converter emits and next-paragraph chains for continued editing in Word.
+
+### Style annotations and table widths
+
+A `custom-style="Name"` attribute, written as `{custom-style="Name"}` in Markdown, applies that style from your reference document. If the style is missing, the converter inserts a stub and returns a warning.
+
+A plain class such as `{.note}` applies a style only when the reference document defines one named `note`. Otherwise it is ignored. Both annotations also work on tables. A named table style replaces Table Grid.
+
+Tables can mix fixed and proportional column widths. Add an attribute list after the table: `{: colwidths="10em 2fr 1fr"}`. Lengths fix a column's width. The `fr` values divide the remaining width proportionally, as in CSS grid.
+
+## Raw docx
+
+The converter accepts MDHTML raw data with `data-format="docx"`:
+
+```html
+<script type="application/vnd.mdhtml.raw" data-format="docx">…</script>
+```
+
+A ```` ```{=docx} ```` fenced block in Markdown, or inline code followed by `{=docx}`, produces this element. The payload is parsed as WordprocessingML and inserted verbatim. Block payloads contain elements such as `w:p` or `w:tbl`. Inline payloads contain elements such as `w:r`. The prefixes `w`, `r`, `wp`, `a`, `pic`, and `m` are predeclared.
+
+Payload encoding follows these rules:
+
+- No `data-encoding`: use the literal payload.
+- `data-encoding="html"`: perform one character-reference decoding pass.
+- `data-encoding="base64"`: decode a base64-encoded UTF-8 payload.
+
+Malformed payloads and unknown encodings are dropped with a warning. Raw data for other formats is skipped silently.
+
+For example, insert a page break with:
+
+    ```{=docx}
+    <w:p><w:r><w:br w:type="page"/></w:r></w:p>
+    ```
+
+## Cross-references
+
+Markdown references such as `[@sec-payment]` become live Word REF fields. MDHTML represents them as `a` elements with `data-ref`.
+
+The default field is `REF <bookmark> \w \h`. It displays the full-context paragraph number, such as "3.(c)(iii)", as a hyperlink. The converter sets `updateFields` in `settings.xml` so Word refreshes fields on open.
+
+The `leaf`, `rel`, `text`, and `page` tokens select other fields. The independent `bare` token suppresses the prefix word. Unknown or conflicting tokens are conversion errors.
+
+### Prefixes and groups
+
+The reference type is the part of the target id before its first `-`. It determines the word before the number. The built-in `sec` type uses Section or Sections. Add types with `reftypes=dict(exh=('Exhibit', 'Exhibits'))`.
+
+Use `[Clause @sec-x]` to override the word for one reference, or `[-@sec-x]` to suppress it.
+
+Grouped references use a `span` with `data-refs`. They render as "Sections 3.1 and 4.2", with one field per number. Groups never collapse into static ranges such as "3.1-3.3", whose meaning could change when a clause is inserted.
+
+A missing target id raises a conversion error. A reference type with no defined prefix also raises when a prefix is required. A lawyer's document must not open showing "Error! Reference source not found."
+
+### Heading numbering
+
+Number fields require numbered headings. If your reference docx already numbers its heading styles, the converter leaves that numbering unchanged.
+
+Otherwise, select a scheme with `number_headings`:
+
+- `'legal'` uses 1. / (a) / (i) numbering.
+- `'decimal'` uses 1. / 1.1. / 1.1.1. numbering.
+- A `{lvlText: numFmt}` dictionary supplies a custom scheme, with one entry per heading level from h1 down. Level 0 is the h1 title with an empty `lvlText`. `%2` is the h2 counter.
+
+The named schemes come from mdhtml's `SCHEMES`. The custom dictionary uses the same format as mdhtml.
+
+A reference-list entry ending in `.xml` can also supply styles and numbering. It contains raw `w:style`, `w:abstractNum`, and `w:num` elements. Each contributor's ids and references are remapped before merging, so separate contributors can reuse the same original numbering ids; later styles still win.
+
+### Figures and tables
+
+Figures and captioned tables use live SEQ fields. A figure's caption appears below its image as "Figure 1: caption", using the caption style. A table's caption appears above it as "Table 1: caption".
+
+When the element has an id, the converter bookmarks its label and number. `[@fig-plot]` inserts "Figure 1" from that bookmark without adding another prefix. A second, number-only bookmark supplies the bare number for references such as `[-@tbl-stages]`.
+
+`fig` and `tbl` are built-in reference types alongside `sec`. Their labels come from the same `reftypes` table. Same-type groups pluralize once. Mixed-type groups use each item's singular prefix, as in "Figure 1 and Table 2".
+
+Reference targets must be headings, paragraphs, figures, or tables with ids. A reference to anything else raises a conversion error.
+
+## Validation
+
+Independent schema validation is optional. Install `mdhtml2docx[validation]` to use `mdhtml2docx.validate.fast_checks(path)`; this extra requires lxml. Normal conversion does not import it.
+
+The test suite checks docx containers, CRCs, and XML, validates against the ECMA-376 schemas with lxml, and performs semantic round trips through Pandoc's independent docx reader. Periodic acceptance runs open documents in Microsoft Word through AppleScript.

mdhtml2docx-0.1.4/mdhtml2docx/__init__.py

@@ -0,0 +1,7 @@
+__version__ = "0.1.4"
+
+
+
+
+
+from .mdhtml2docx import mdhtml2docx

{mdhtml2docx-0.1.2 → mdhtml2docx-0.1.4}/mdhtml2docx/asvocab.py

@@ -3,7 +3,7 @@ import re
 from functools import cache
 from importlib.resources import files
 from aem import AEEnum
-from lxml import etree
+from xml.etree import ElementTree as etree
 
 __all__ = ['vocab', 'props', 'sd', 'sdfind']
 
@@ -80,9 +80,12 @@ def sdfind(pat, path=SDEF, maxlen=80):
     "Search sdef names and descriptions for regex `pat`, as (kind, name, description) rows; child nodes show as parent.name"
     r = re.compile(pat, re.I)
     res = []
-    for e in _sdef(path).iter(*_fmts, *_children):
+    root = _sdef(path)
+    parents = {c: p for p in root.iter() for c in p}
+    for e in root.iter():
+        if e.tag not in _fmts and e.tag not in _children: continue
         n, d = e.get('name') or '', e.get('description') or ''
         if not (r.search(n) or r.search(d)): continue
-        if e.tag in _children: n = f'{e.getparent().get("name")}.{n}'
+        if e.tag in _children: n = f'{parents[e].get("name")}.{n}'
         res.append((e.tag, n, d if len(d)<=maxlen else d[:maxlen]+'...'))
     return res

{mdhtml2docx-0.1.2 → mdhtml2docx-0.1.4}/mdhtml2docx/hilite.py

@@ -1,6 +1,6 @@
 """Optional syntax scopes for code blocks, via fastpylight (Jeremy's tree-sitter highlighter).
 When fastpylight is absent or the language unknown, callers fall back to plain runs, so the
-package keeps its lxml-only hard dependency. Colors live in the reference doc's Hl* character
+package does not require fastpylight. Colors live in the reference doc's Hl* character
 styles (see styles.theme_styles); this module only tokenizes."""
 
 # theme_colors is probed too: a pre-theme_colors fastpylight is treated as absent, not half-working