fancy-template 0.2.0__tar.gz → 0.4.0__tar.gz

{fancy_template-0.2.0 → fancy_template-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fancy-template
-Version: 0.2.0
+Version: 0.4.0
 Summary: Document templates for the Fancy document writers: a writer document with {{ tokens }} and JSON directives, plus a declaration of the data it needs. inspect() at save time, validate_data() before render, render() to plain writer JSON. No code execution, no includes, bounded everywhere. One spec, three runtimes, held to a shared conformance table.
 Project-URL: Homepage, https://github.com/Particle-Academy/fancy-template
 Project-URL: Issues, https://github.com/Particle-Academy/fancy-template/issues

{fancy_template-0.2.0 → fancy_template-0.4.0}/SPEC.md

@@ -331,7 +331,7 @@ index, `**` for zero or more. **Anything not listed refuses tokens**
 | encoding | result |
 |---|---|
 | `text` | the string, every token stringified |
-| `band` | as `text`, but a VALUE containing `{page}` or `{pages}` is `VALUE_PAGE_FIELD` |
+| `band` | as `text`, but a VALUE containing a writer's band field is `VALUE_PAGE_FIELD`: `{page}` `{pages}` `{section}` `{sectionpages}` `{author}` `{title}` `{filename}`, and `{date}` / `{time}`, each with an optional `:FORMAT` of one or more characters that are not a brace, a double quote or a backslash. Other braces are ordinary text |
 | `markup` | as `text`, each value escaped for the element's `format`: `markdown` backslash-escapes every ASCII punctuation character (CommonMark), `html` escapes `& < > " '` as entities, `plain` or absent leaves it |
 | `markdown` | as `markup` with format fixed to markdown |
 | `cell` | a whole token keeps a number, boolean or date as-is; every other result is written `{ "value": s }`, so user data can never become a formula. "Date" means: the token's path is DECLARED `date` and the result (after filters) is a valid `date` string (section 3) -- a date-shaped value of a `string` variable is wrapped, and `{{ d \| date:"yyyy" }}` is text. A valid date cannot begin with `=`. A literal (token-free) cell is the author's and is left as written |
@@ -339,10 +339,13 @@ index, `**` for zero or more. **Anything not listed refuses tokens**
 
 Wrong use of an image field is `TOKEN_IMAGE_FIELD`.
 
-**`{page}` is refused rather than escaped** because neither fine-print nor
-last-word has an escape for it: both replace the literal text in a band. A refusal
-is loud; any lookalike substitution would print a different character. When a
-writer gains an escape, the band encoding uses it.
+**A band field is refused rather than escaped** because neither fine-print nor
+last-word has an escape for it: both turn the literal text into a live value in a
+band, in a one-line slot and in a blocks band's run text alike, so a blocks band's
+run text is `band` too. The list is one for both writers, including the ones a
+writer writes literally today (fine-print's `{date}`), so a value that refuses in
+one refuses in the other. A refusal is loud; any lookalike substitution would print
+a different character. When a writer gains an escape, the band encoding uses it.
 
 **The markdown escape is CommonMark's, and the profile does not force `plain`.**
 dark-slide's PPTX writer (`MarkdownInline`, in all three of its languages) does
@@ -414,5 +417,340 @@ PHP `Template::validateData`, TypeScript `validateData`, Python `validate_data`)
 - `preview(template, options?) -> document` -- `render` with each variable's
   `example` (else `default`).
 - `tokenize(text, options?) -> parts` (section 5).
+- `inspectFile(bytes, options?)` and `renderFile(bytes, data, options?)` (section 12).
 
 Output key order is the template's, minus directive keys.
+
+## 12. Office files as templates
+
+Owner's rule: **any file can be a template.** A customer's own `.docx`, `.pptx`
+or `.xlsx` with `{{ tokens }}` typed into it is filled AS IT IS, in its own
+text, with every other byte of the package kept. Nothing is read into a writer
+model and written back, because a model drops what it does not carry (custom
+styles, embedded objects, fields, comments, layout).
+
+**Status.** PHP implements this section. TypeScript and Python expose the two
+functions and throw `FileTemplatesNotImplementedError` (`code`
+`FILE_NOT_IMPLEMENTED`, `operation` the function's name), never a silent
+no-op. Shared rows and fixtures: `fixtures/files/` (section 12.10).
+
+### 12.1 API
+
+| | PHP | TypeScript | Python |
+|---|---|---|---|
+| inspect | `Template::inspectFile(string $bytes, array $options = [])` | `inspectFile(bytes: Uint8Array, options?)` | `inspect_file(data: bytes, options=None)` |
+| render | `Template::renderFile(string $bytes, mixed $data, array $options = []) : string` | `renderFile(bytes, data, options?) : Uint8Array` | `render_file(data, values, options=None) -> bytes` |
+
+`inspectFile` returns
+`{ ok, format, kind, issues: [{code, path, variable?}], placeholders: [{path, token, variable?}], variables: [name] }`:
+
+- `format`: `docx`, `pptx` or `xlsx`; `kind`: `document` or `template` (from the
+  main part's content type, 12.3). Both `null` when the file is refused.
+- `placeholders`: every token, in order (12.5): `path` is its location, `token`
+  the token's source text from `{{` to `}}` as it reads in the joined text,
+  `variable` the dotted path (absent for a string-literal token).
+- `variables`: the HEAD of every token path, distinct, in first-use order: the
+  names the data must supply.
+- A refused file (any `FILE_` code) is reported as the single issue, as an
+  oversized template is (section 10), and `inspectFile` does not throw for it.
+
+`renderFile` returns the filled file's bytes, or throws `TemplateError`. Order:
+open and classify the package (`FILE_` codes), inspect (first issue), validate
+the data as `validateData` does (first error, path into the data), fill.
+
+Options: `variables` (12.2), `limits` (`tokens`, `tokenLength`, `outputBytes`,
+and `depth` for the data, apply; the rest have nothing to bound in a file) and
+`fileLimits` (12.8). An
+unknown `fileLimits` key, or a value that is not a positive integer, is refused
+as an unknown `limits` key is.
+
+### 12.2 Declarations: a sidecar, not document properties
+
+`options.variables` is a declaration map exactly as an envelope's `variables`
+(section 3), checked by the same rules with the same codes and paths
+(`DECL_INVALID` at `/variables/<name>/...`; a non-object is `TEMPLATE_SHAPE` at
+`/variables`). With it, the file is inspected as a template is: a token whose
+path is not declared is `TOKEN_UNDECLARED`, a token naming an `image` variable
+is `TOKEN_IMAGE_FIELD` (an image cannot be text), data is validated with
+`DATA_*` codes and defaults apply.
+
+**Why a sidecar.** Custom document properties would put the declarations inside
+the customer's file, where:
+
+- anyone who opens it in Word sees and can edit them (File > Properties), so the
+  customer can break the template without knowing it is one;
+- writing or updating them rewrites `docProps/custom.xml`, which is exactly the
+  kind of change to a customer's file this feature exists to avoid;
+- they are flat strings, so a declaration would be JSON inside a property, a
+  second format to parse in three languages;
+- some editors drop unknown custom properties on save.
+
+The host already stores a record for every file it accepts as a template; the
+declarations belong in that record, beside the file, where they can be versioned
+and reused across new uploads of the same file.
+
+**Without declarations** the names are INFERRED from the tokens, the way
+`inspect` reports them: no token is undeclared, nothing is typed, and
+`validateData` has no member to check (data must still be a plain JSON object:
+`DATA_TYPE`, `DATA_TOO_DEEP`). Every token must still resolve at render: absent
+is `TEMPLATE_MISSING`, a container is `TEMPLATE_NOT_SCALAR`, a wrong filter input
+is `FILTER_INPUT`. A file has no `$each`, so `$index`, `$first` and `$last` are
+`TOKEN_UNDECLARED` in both modes.
+
+### 12.3 Recognising the package
+
+In this order; the first failure is the answer.
+
+1. An OLE compound file (first 8 bytes `D0 CF 11 E0 A1 B1 1A E1`) is
+   `FILE_ENCRYPTED` when its bytes contain the UTF-16LE stream name
+   `EncryptedPackage` (a password-protected OOXML file), else `FILE_UNSUPPORTED`
+   (a legacy binary `.doc`/`.xls`/`.ppt`).
+2. The zip is indexed and checked (12.8).
+3. `[Content_Types].xml` must be a member (exact name), else `FILE_UNSUPPORTED`.
+   It is read like every part (12.7). Each member's content type is its
+   `Override` (by part name `/` + member name, ASCII case-insensitive), else the
+   `Default` for its extension (case-insensitive), else none. Content types
+   compare case-insensitively.
+4. A member whose type is a macro-enabled or binary main type is
+   `FILE_MACRO_ENABLED`: `application/vnd.ms-word.document.macroEnabled.main+xml`,
+   `...ms-word.template.macroEnabledTemplate.main+xml`,
+   `...ms-powerpoint.{presentation,slideshow,template,addin}.macroEnabled.main+xml`,
+   `...ms-excel.{sheet,template,addin}.macroEnabled.main+xml`,
+   `...ms-excel.sheet.binary.macroEnabled.main`.
+5. Exactly one member must have one of these main types, else `FILE_UNSUPPORTED`:
+
+   | content type (`application/vnd.openxmlformats-officedocument.` +) | format | kind |
+   |---|---|---|
+   | `wordprocessingml.document.main+xml` | docx | document |
+   | `wordprocessingml.template.main+xml` | docx | template |
+   | `presentationml.presentation.main+xml`, `presentationml.slideshow.main+xml` | pptx | document |
+   | `presentationml.template.main+xml` | pptx | template |
+   | `spreadsheetml.sheet.main+xml` | xlsx | document |
+   | `spreadsheetml.template.main+xml` | xlsx | template |
+
+6. A VBA project anywhere is `FILE_MACRO_ENABLED`: any declared type (`Default`
+   or `Override`) equal to `application/vnd.ms-office.vbaProject`, or any member
+   whose name ends with `vbaProject.bin` (case-insensitive). A `.docx` may not
+   smuggle what a `.docm` declares.
+
+**Macro-enabled files are refused, not passed through.** Passing one through
+would hand back, from this system and filled by an agent, a file carrying code
+nothing here inspected; macro documents are the most common malware carrier,
+and last-word's template intake already refuses them. A customer who needs the
+macros keeps them in their own copy. **Encrypted files are refused** because
+there is nothing to fill: the text is ciphertext without the password, and
+"passing it through" would return the input unchanged with every placeholder
+still in it.
+
+**The parts that are filled**, by content type (prefix as above):
+
+| format | parts |
+|---|---|
+| docx | the main document (`document.main` or `template.main`), `header`, `footer`, `footnotes`, `endnotes`, `comments` (`wordprocessingml.*+xml`) |
+| pptx | `slide`, `slideLayout`, `slideMaster`, `notesSlide`, `notesMaster` (`presentationml.*+xml`) |
+| xlsx | `sharedStrings`, `worksheet` (`spreadsheetml.*+xml`) |
+
+**Layouts and masters are filled.** A token on a master or layout (a footer's
+`{{ client }}`, a confidentiality line) is drawn on every slide that uses it,
+so leaving it unfilled would print `{{ client }}` on every slide; that is the
+common reason to put text there at all. A placeholder's prompt text on a layout
+("Click to add title") is never shown in a slide show, so filling a token in it
+is harmless. **Comments are filled** because they ride along with the file and
+an unfilled token in one leaks the template into the customer's review pane.
+
+**Every other `.xml` or `.rels` member is still read** (12.7, so a DOCTYPE in
+it is refused) and searched for `{{`: one found is `TOKEN_FORBIDDEN_FIELD` at
+`/<member name>`. A token in a place that is not filled is refused, not left
+in the output, exactly as a profile refuses a field it does not list (section
+9): document properties, charts, SmartArt, a glossary, custom XML.
+
+### 12.4 Where text is: containers, runs, text nodes, barriers
+
+Elements are matched by namespace URI and local name, never by prefix. Each
+format accepts its transitional and strict namespace:
+
+| format | namespace (transitional; strict) |
+|---|---|
+| docx | `http://schemas.openxmlformats.org/wordprocessingml/2006/main`; `http://purl.oclc.org/ooxml/wordprocessingml/main` |
+| pptx | `http://schemas.openxmlformats.org/drawingml/2006/main`; `http://purl.oclc.org/ooxml/drawingml/main` |
+| xlsx | `http://schemas.openxmlformats.org/spreadsheetml/2006/main`; `http://purl.oclc.org/ooxml/spreadsheetml/main` |
+
+| format | container | run | text node | transparent run children | barriers |
+|---|---|---|---|---|---|
+| docx | `p` | `r` | `t` child of a run | `rPr`, `delText`, `lastRenderedPageBreak` | every other run child (`tab`, `br`, `cr`, `drawing`, `pict`, `fldChar`, `instrText`, `sym`, `footnoteReference`, ...); `m:oMath`/`m:oMathPara` (OMML namespace) inside the container |
+| pptx | `p` | `r` | `t` child of a run | `rPr` | every other run child; `br` and `fld` inside the container (outside a run) |
+| xlsx | `si`, `is` | `r` | `t` child of a run, or `t` child of the container itself | `rPr` | every other run child |
+
+- A **container** is a paragraph (docx/pptx), a shared-string item `si` or an
+  inline string `is` (xlsx). A container inside another (a text box's paragraph
+  inside a run's drawing) is its own container; the run child holding it
+  (`drawing`) is a barrier in the outer one.
+- A **run** is a run element that is a descendant of the innermost open
+  container and not inside another run. Containers' other children (`proofErr`,
+  `bookmarkStart`, `ins`, `hyperlink`, `fldSimple`, `sdt`, `commentRangeStart`,
+  `rPh`, ...) are neither text nor barriers; runs inside them are runs.
+  `delText` is not text: deleted text is not shown and is not joined.
+- The text nodes of a container, in document order, split at barriers, form its
+  **spans**. A span's **joined text** is its nodes' decoded text (12.7)
+  concatenated. An empty text node (`<w:t/>`, `<w:t></w:t>`) is skipped.
+- A container's **location** is `/<member name>#<label>`, the label being the
+  container's local name and its 0-based index among the part's containers in
+  START-tag order (`#p0`, `#si3`), except an xlsx `is` inside a `c` whose `r`
+  attribute is a cell reference (`[A-Z0-9]+`): then the label is that reference
+  (`#B4`). A text box's paragraph is numbered after the paragraph holding it.
+- The **visible text** of a container, used by the shared rows, is its text
+  nodes' decoded text concatenated (barriers add nothing); in xlsx, a
+  `_xHHHH_` escape is then decoded to its character.
+
+### 12.5 Tokens, inspection, and the run-split rule
+
+Each span whose joined text contains `{{` is scanned with section 5's grammar
+and bounds. A scan failure (`TOKEN_UNCLOSED`, `TOKEN_TOO_LONG`, `TOKEN_EMPTY`,
+`TOKEN_SYNTAX`) is one issue at the container's location, and that span
+contributes no tokens. A token cannot cross a barrier or a container boundary,
+so a `{{` before a tab and its `}}` after it is `TOKEN_UNCLOSED`.
+
+Per token, in order: its path (`TOKEN_UNDECLARED` with `variable`, or
+`TOKEN_IMAGE_FIELD`, 12.2), then each filter (`FILTER_UNKNOWN`, `FILTER_ARG`),
+all at the container's location.
+
+Issue order: sidecar declarations (12.2), then members in CENTRAL-DIRECTORY
+order; within a filled part, containers in location order, spans in order,
+tokens in order. Placeholders are in the same order. When the file's tokens
+outnumber `limits.tokens`, the issues are exactly `[TEMPLATE_TOO_MANY_TOKENS at ""]`.
+
+**The run-split rule.** Word splits text into runs for spell-check marks,
+revision ids and formatting, so `{{ client }}` may be `{{ cli` in one run and
+`ent }}` in the next. A token is found in the span's joined text, then:
+
+1. The value is written into the text node where the token STARTS, at the
+   token's position, replacing the token's characters in that node. That node's
+   run keeps its properties, so **the value takes the formatting of the run
+   holding `{{`**: `{{ cli` bold + `ent }}` italic fills bold.
+2. The rest of the token is cut from each following node it covers. Text in
+   those nodes outside the token stays, in its own run with its own formatting.
+3. **No node and no run is ever removed**, even one left empty: an empty run is
+   invisible, and a run may be what a bookmark, a comment range or a revision
+   is anchored to.
+4. Text around a token in a touched node is copied as its ORIGINAL bytes (its
+   entities, character references, comments and CDATA as written); only the
+   token's own bytes change. A node no token touches is not changed at all.
+
+### 12.6 Values
+
+A token's value is computed as a `text` field's (sections 6 and 7): resolved
+against the (defaulted) data, filtered, stringified. Then:
+
+- It must hold only characters XML 1.0 can carry: a control character other
+  than TAB, LF and CR, or U+FFFE / U+FFFF, is `VALUE_XML_CHAR` at the location,
+  with `variable`. There is no escape for these in XML 1.0.
+- It is **XML-escaped**: `&` `<` `>` as `&amp;` `&lt;` `&gt;`. Nothing in a
+  value can become markup.
+- **xlsx**: a value is written as text in the shared string or inline string
+  that held the token, and the cell around it is never touched, so it stays a
+  text cell: a value starting with `=`, `+`, `-` or `@` is text, never a
+  formula. A `_xHHHH_` sequence in a value has its `_` written as `_x005F_`
+  (ECMA-376 ST_Xstring), so Excel shows the value as given instead of decoding it.
+- **A whole-token number in an xlsx cell stays a string.** The token sits in a
+  shared string, which may be used by several cells, so turning one cell into a
+  number means editing the worksheet's cells and possibly splitting the string;
+  the cell's number format was authored for text; and the value has already been
+  stringified by section 6's rules, which is what the customer typed the token
+  into. A future option may write declared `number` values as number cells;
+  until then the rule is: text in, text out.
+- **docx and xlsx white space**: when a touched text node's new text begins or
+  ends with white space and its start tag has no `xml:space` attribute,
+  ` xml:space="preserve"` is inserted before the tag's `>`, because Word and
+  Excel otherwise drop it. pptx text keeps its white space and needs none.
+- A value is never re-scanned: `{{` in a value reaches the file literally.
+- `limits.outputBytes` bounds the UTF-8 bytes of all values written
+  (`RENDER_TOO_LARGE` at `""`).
+
+### 12.7 Reading XML
+
+Every member that is read (`[Content_Types].xml`, the filled parts and the
+searched `.xml`/`.rels` members) is refused with `FILE_DOCTYPE` at
+`/<member name>` when it contains `<!DOCTYPE` (ASCII case-insensitive),
+before it is parsed. Nothing defines an entity, so nothing expands one, and
+there is no DTD to fetch.
+
+The filled parts and `[Content_Types].xml` are read by a forward-only lexer that
+reports each element with its byte offsets. `FILE_XML` at `/<member name>` for:
+a UTF-16 byte-order mark, an XML declaration naming an encoding other than
+UTF-8, any `<!` other than a comment or CDATA, an unterminated comment, CDATA or
+processing instruction, a mismatched or unclosed tag, more than one root, an
+attribute that is unquoted, repeated or holds `<`, an unbound prefix, an entity
+other than the five predefined ones, a character reference to a character XML
+cannot hold, or an element inside a text node. Text-node content decodes the
+five entities and character references, takes CDATA literally and skips
+comments and processing instructions.
+
+A filled part is re-read by the same lexer before it is written; failing that is
+a bug in the implementation, not a file problem.
+
+### 12.8 The archive
+
+The central directory is parsed and checked before any member is decompressed.
+Bounds, through `options.fileLimits` (the defaults are last-word's):
+
+| limit | default | measured as | code |
+|---|---|---|---|
+| `archiveBytes` | 67108864 | the file | `FILE_TOO_LARGE` |
+| `entries` | 16384 | members in the central directory | `FILE_TOO_MANY_ENTRIES` |
+| `partBytes` | 67108864 | any member's declared uncompressed size | `FILE_TOO_LARGE` |
+| `expandedBytes` | 268435456 | all declared uncompressed sizes together | `FILE_TOO_LARGE` |
+| `compressionRatio` | 1000 | a member's uncompressed / max(1, compressed) | `FILE_ZIP_BOMB` |
+
+All with path `""`. Also refused, path `""`:
+
+| code | when |
+|---|---|
+| `FILE_ARCHIVE` | no end-of-central-directory record that accounts for the whole file; multi-disk; zip64 (an entry count of 65535, a 0xFFFFFFFF size or offset, a zip64 extra field); a method other than stored (0) or deflate (8); a version needed above 2.0; a flag other than bits 1, 2, 3 and 11; a stored member whose sizes differ; a local header that disagrees with the central one (signature, flags, method, name, CRC and sizes unless bit 3 defers them to a matching data descriptor); members that overlap; bytes between the last central record and the end record; a non-ASCII name without the UTF-8 flag; a member whose decompressed length or CRC differs from the directory |
+| `FILE_ENCRYPTED` | the encryption flag (bit 0) or the strong-encryption flag (bit 6), method 99, or an AES extra field (0x9901) |
+| `FILE_PATH` | a name that is empty, starts with `/`, contains `\` or `:` or a control character, is not UTF-8, or has an empty, `.` or `..` segment; two names equal under ASCII case folding (two spellings of one OPC part let a scan read one and an office suite the other) |
+
+**Nothing is fetched.** Relationships are never resolved: an external target
+(`TargetMode="External"`, a remote image, a `file://` link) is bytes in a
+`.rels` member, copied with it.
+
+**Output.** The output has the input's members in the same local and central
+order with the same archive comment. Every member not filled is its ORIGINAL
+LOCAL RECORD, byte for byte (header, extra field, compressed data, data
+descriptor), and its central record is the original with only the local-header
+offset changed. A filled member is written deflated (or stored, if the
+compressor chooses) with its original timestamp, UTF-8 flag and attributes, no
+extra field, no comment and no data descriptor.
+
+### 12.9 Not covered
+
+- **Repeating sections** (a table row per line item). They would need: a
+  marker that delimits the repeated block in the file's own text (for example
+  a row whose first cell holds `{{ #each lines as line }}` and a closing marker),
+  the block located at the XML-element level (a `w:tr`, a run of `w:p`, an
+  `a:tr`, a worksheet `row`) rather than in text, copies of that element with
+  fresh ids where the format demands unique ones (`w14:paraId`, drawing
+  `docPr/@id`, bookmark ids, xlsx row numbers and every cell reference, shared
+  formula ranges, merged cells and defined names below it), the same
+  `iterations` bound, and a rule for what happens to a split marker. That is a
+  structural edit, not a text substitution, which is why it is a separate step.
+- Text that is not in a container's text nodes: attribute values (alt text,
+  hyperlink targets), field codes (`instrText`), chart and SmartArt text, xlsx
+  header/footer strings (`oddHeader`), cell comments, formulas. A token in a
+  member that is not filled is refused (12.3); one in a filled member outside
+  its text nodes is not seen.
+- A newline in a value is written as a newline character, which Word and
+  PowerPoint show as a space; turning it into a break element is not done.
+- ODF (`.odt`, `.odp`, `.ods`), legacy binary formats, `.xlsb`.
+
+### 12.10 Shared rows
+
+`fixtures/files/cases.json` holds the rows (hand-written from this section)
+and `fixtures/files/*` the files, built by `scripts/files/build-fixtures.php`:
+hand-authored minimal OOXML, plus a docx written by last-word and a pptx written
+by dark-slide (then given a layout, a master and a split run). The rows are in
+fancy-conformance's case-table shape, ready to become its `template/files`
+suite; until then every leg reads them from here. A port is done when it passes
+every row: `expect.text` by visible text (12.4), `expect.changed` as the exact
+set of members whose bytes differ (all others byte-identical records),
+`expect.contains` / `expect.absent` as raw substrings, `expect.error` as the
+thrown error and as `inspectFile`'s single issue.

fancy_template-0.4.0/profiles/fine-print.json

@@ -0,0 +1,50 @@
+{
+  "writer": "fine-print",
+  "schema": "fine-print 0.3",
+  "notes": "An ALLOWLIST: a string field not matched here refuses tokens. link, color, font, fonts, page geometry and every style field are deliberately absent. First match wins, so a band's own patterns come before the generic text ones. Every band slot and a blocks band's run text refuse a value holding a field token ({page}, {section}, {date}, ...): fine-print resolves them there and has no escape.",
+  "fields": [
+    { "path": "title", "encode": "text" },
+    { "path": "page.header.left", "encode": "band" },
+    { "path": "page.header.center", "encode": "band" },
+    { "path": "page.header.right", "encode": "band" },
+    { "path": "page.footer.left", "encode": "band" },
+    { "path": "page.footer.center", "encode": "band" },
+    { "path": "page.footer.right", "encode": "band" },
+    { "path": "page.firstHeader.left", "encode": "band" },
+    { "path": "page.firstHeader.center", "encode": "band" },
+    { "path": "page.firstHeader.right", "encode": "band" },
+    { "path": "page.firstFooter.left", "encode": "band" },
+    { "path": "page.firstFooter.center", "encode": "band" },
+    { "path": "page.firstFooter.right", "encode": "band" },
+    { "path": "page.evenHeader.left", "encode": "band" },
+    { "path": "page.evenHeader.center", "encode": "band" },
+    { "path": "page.evenHeader.right", "encode": "band" },
+    { "path": "page.evenFooter.left", "encode": "band" },
+    { "path": "page.evenFooter.center", "encode": "band" },
+    { "path": "page.evenFooter.right", "encode": "band" },
+    { "path": "blocks.*.page.header.left", "encode": "band" },
+    { "path": "blocks.*.page.header.center", "encode": "band" },
+    { "path": "blocks.*.page.header.right", "encode": "band" },
+    { "path": "blocks.*.page.footer.left", "encode": "band" },
+    { "path": "blocks.*.page.footer.center", "encode": "band" },
+    { "path": "blocks.*.page.footer.right", "encode": "band" },
+    { "path": "blocks.*.page.firstHeader.left", "encode": "band" },
+    { "path": "blocks.*.page.firstHeader.center", "encode": "band" },
+    { "path": "blocks.*.page.firstHeader.right", "encode": "band" },
+    { "path": "blocks.*.page.firstFooter.left", "encode": "band" },
+    { "path": "blocks.*.page.firstFooter.center", "encode": "band" },
+    { "path": "blocks.*.page.firstFooter.right", "encode": "band" },
+    { "path": "blocks.*.page.evenHeader.left", "encode": "band" },
+    { "path": "blocks.*.page.evenHeader.center", "encode": "band" },
+    { "path": "blocks.*.page.evenHeader.right", "encode": "band" },
+    { "path": "blocks.*.page.evenFooter.left", "encode": "band" },
+    { "path": "blocks.*.page.evenFooter.center", "encode": "band" },
+    { "path": "blocks.*.page.evenFooter.right", "encode": "band" },
+    { "path": "page.*.blocks.**.runs.*.text", "encode": "band" },
+    { "path": "blocks.*.page.*.blocks.**.runs.*.text", "encode": "band" },
+    { "path": "**.runs.*.text", "encode": "text" },
+    { "path": "**.blocks.*.text", "encode": "text" },
+    { "path": "**.blocks.*.alt", "encode": "text" },
+    { "path": "**.blocks.*.src", "encode": "image", "mime": ["image/png", "image/jpeg"] }
+  ]
+}

{fancy_template-0.2.0 → fancy_template-0.4.0}/profiles/last-word.json

@@ -1,9 +1,10 @@
 {
   "writer": "last-word",
   "schema": "last-word 0.x (Doc model shared with fine-print)",
-  "notes": "An ALLOWLIST: a string field not matched here refuses tokens. link, chart option, color, font, fonts, page geometry and every style field are deliberately absent. Band slots refuse a value containing {page}/{pages}: last-word writes them as PAGE and NUMPAGES fields with str_replace and has no escape.",
+  "notes": "An ALLOWLIST: a string field not matched here refuses tokens. link, chart option, color, font, fonts, page geometry and every style field are deliberately absent. First match wins, so a band's own patterns come before the generic text ones. Band slots and a blocks band's run text refuse a value holding a field token ({page}, {section}, {date}, ...): last-word writes them as live Word fields and has no escape.",
   "fields": [
     { "path": "title", "encode": "text" },
+    { "path": "page.*.blocks.**.runs.*.text", "encode": "band" },
     { "path": "**.runs.*.text", "encode": "text" },
     { "path": "**.blocks.*.text", "encode": "text" },
     { "path": "**.blocks.*.alt", "encode": "text" },

{fancy_template-0.2.0 → fancy_template-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fancy-template"
-version = "0.2.0"
+version = "0.4.0"
 description = "Document templates for the Fancy document writers: a writer document with {{ tokens }} and JSON directives, plus a declaration of the data it needs. inspect() at save time, validate_data() before render, render() to plain writer JSON. No code execution, no includes, bounded everywhere. One spec, three runtimes, held to a shared conformance table."
 readme = "README.md"
 # 3.11, matching every other Fancy Python package (3.10 reaches end of life on

{fancy_template-0.2.0 → fancy_template-0.4.0}/src/fancy_template/__init__.py

@@ -28,6 +28,7 @@ from typing import Any
 
 from ._declarations import apply_defaults, validate_members
 from ._errors import TemplateError
+from ._files import FileTemplatesNotImplementedError, inspect_file, render_file
 from ._inspector import Inspector, declared_variables
 from ._json import first_too_deep, plain
 from ._limits import DEFAULT_LIMITS, Limits, limits_from
@@ -37,15 +38,18 @@ from ._scanner import tokenize as _scan
 
 __all__ = [
     "DEFAULT_LIMITS",
+    "FileTemplatesNotImplementedError",
     "TemplateError",
     "inspect",
+    "inspect_file",
     "preview",
     "render",
+    "render_file",
     "tokenize",
     "validate_data",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 
 def inspect(template: Any, options: dict[str, Any] | None = None) -> dict[str, Any]:

fancy_template-0.4.0/src/fancy_template/_files.py

@@ -0,0 +1,40 @@
+"""Office files as templates (SPEC.md section 12): ``inspect_file`` and
+``render_file``. Implemented in the PHP leg only, so far.
+
+They exist in this leg so that a caller gets a LOUD, named refusal rather than
+a missing name or a silent no-op: a ``render_file`` that returned its input
+unchanged would hand back a document full of ``{{ placeholders }}`` and look
+like success. The behaviour to implement is SPEC.md section 12; the shared rows
+and fixtures are in ``fixtures/files/``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, NoReturn
+
+
+class FileTemplatesNotImplementedError(NotImplementedError):
+    """Raised by ``inspect_file`` and ``render_file`` in this language.
+
+    Office-file templates are implemented in PHP (``Template::inspectFile``),
+    not yet here. ``code`` is always ``FILE_NOT_IMPLEMENTED``; ``operation``
+    names the function.
+    """
+
+    code = "FILE_NOT_IMPLEMENTED"
+
+    def __init__(self, operation: Literal["inspect_file", "render_file"]) -> None:
+        super().__init__(
+            f"{operation} is not yet implemented in the Python leg of fancy-template (SPEC.md section 12; PHP has it)."
+        )
+        self.operation = operation
+
+
+def inspect_file(data: bytes, options: dict[str, Any] | None = None) -> NoReturn:
+    """The placeholders in a .docx / .pptx / .xlsx. Not yet implemented here: always raises."""
+    raise FileTemplatesNotImplementedError("inspect_file")
+
+
+def render_file(data: bytes, values: Any, options: dict[str, Any] | None = None) -> NoReturn:
+    """Fill a .docx / .pptx / .xlsx in place. Not yet implemented here: always raises."""
+    raise FileTemplatesNotImplementedError("render_file")

{fancy_template-0.2.0 → fancy_template-0.4.0}/src/fancy_template/_renderer.py

@@ -9,6 +9,7 @@ is refused before it is built rather than after.
 
 from __future__ import annotations
 
+import re
 from collections.abc import Callable, Iterator
 from typing import Any
 
@@ -23,6 +24,13 @@ from ._limits import Limits
 from ._profile import Profile
 from ._scanner import LOOP_HEADS, is_digits, path_only, tokenize
 
+# A writer's band field, the grammar last-word's Schema::FIELD_TOKEN and
+# fine-print's share. Run over a VALUE, never over template text; a value holding
+# one is refused (SPEC.md section 9).
+BAND_FIELD = re.compile(
+    r'\{(?:(?:page|pages|section|sectionpages|author|title|filename)|(?:date|time)(?::[^{}"\\]+)?)\}'
+)
+
 
 def escape_markdown(s: str) -> str:
     """CommonMark: a backslash before every ASCII punctuation character (SPEC.md section 9)."""
@@ -232,7 +240,7 @@ class Renderer:
             except TemplateError as e:
                 raise TemplateError(e.code, path, variable) from None
 
-            if field["encode"] == "band" and ("{page}" in piece or "{pages}" in piece):
+            if field["encode"] == "band" and BAND_FIELD.search(piece):
                 raise TemplateError("VALUE_PAGE_FIELD", path, variable)
             out += escape(piece)
 

fancy_template-0.4.0/tests/test_band_value.py

@@ -0,0 +1,92 @@
+"""User data must not become a live field: a value holding a band token is refused,
+never rewritten. The PHP and TypeScript legs hold the same rows."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from fancy_template import TemplateError, render
+
+BANDS = ["header", "footer", "firstHeader", "firstFooter", "evenHeader", "evenFooter"]
+
+
+def tpl(writer: str, document: dict[str, Any]) -> dict[str, Any]:
+    return {"fancyTemplate": 1, "writer": writer, "variables": {"v": {"type": "string"}}, "document": document}
+
+
+def code(template: dict[str, Any], value: str) -> str | None:
+    try:
+        render(template, {"v": value})
+    except TemplateError as e:
+        return e.code
+    return None
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "{page}",
+        "{pages}",
+        "{section}",
+        "{sectionpages}",
+        "{author}",
+        "{title}",
+        "{filename}",
+        "{date}",
+        "{time}",
+        "see {section} here",
+        "{date:d MMMM yyyy}",
+        "{time:HH:mm}",
+    ],
+)
+@pytest.mark.parametrize("writer", ["fine-print", "last-word"])
+def test_refuses_a_band_value_holding_any_field_token(writer: str, value: str) -> None:
+    assert code(tpl(writer, {"blocks": [], "page": {"footer": {"left": "{{ v }}"}}}), value) == "VALUE_PAGE_FIELD"
+
+
+@pytest.mark.parametrize("value", ["{Page}", "{pagex}", "x{ page }", "{date:}", "{date:a{b}", "no braces"])
+def test_keeps_a_value_that_is_only_brace_shaped(value: str) -> None:
+    out = render(tpl("fine-print", {"blocks": [], "page": {"footer": {"left": "{{ v }}"}}}), {"v": value})
+    assert out["page"]["footer"]["left"] == value
+
+
+@pytest.mark.parametrize("key", BANDS)
+@pytest.mark.parametrize("slot", ["left", "center", "right"])
+def test_every_fine_print_band_slot(key: str, slot: str) -> None:
+    template = tpl("fine-print", {"blocks": [], "page": {key: {slot: "{{ v }}"}}})
+    assert code(template, "Ada") is None
+    assert code(template, "{section}") == "VALUE_PAGE_FIELD"
+
+
+@pytest.mark.parametrize("key", BANDS)
+def test_a_band_on_a_fine_print_break(key: str) -> None:
+    template = tpl(
+        "fine-print",
+        {"blocks": [{"type": "pageBreak", "page": {"orientation": "landscape", key: {"left": "{{ v }}"}}}]},
+    )
+    assert code(template, "Ada") is None
+    assert code(template, "{pages}") == "VALUE_PAGE_FIELD"
+
+
+@pytest.mark.parametrize("writer", ["fine-print", "last-word"])
+def test_a_blocks_band_and_a_table_cell_in_it(writer: str) -> None:
+    para = {"type": "paragraph", "runs": [{"text": "{{ v }}"}]}
+    cell = {"type": "table", "rows": [{"cells": [{"blocks": [para]}]}]}
+    for block in (para, cell):
+        assert (
+            code(tpl(writer, {"blocks": [], "page": {"footer": {"blocks": [block]}}}), "see {page}")
+            == "VALUE_PAGE_FIELD"
+        )
+
+
+def test_a_body_run_keeps_a_token_shaped_value_literal() -> None:
+    assert code(tpl("fine-print", {"blocks": [{"type": "paragraph", "runs": [{"text": "{{ v }}"}]}]}), "{page}") is None
+
+
+def test_page_geometry_on_a_break_stays_closed_to_tokens() -> None:
+    assert (
+        code(tpl("fine-print", {"blocks": [{"type": "pageBreak", "page": {"orientation": "{{ v }}"}}]}), "landscape")
+        is not None
+    )

{fancy_template-0.2.0 → fancy_template-0.4.0}/tests/test_conformance.py

@@ -24,7 +24,7 @@ from template_runner import run_template_case
 # version (package.json's range + the committed lockfile; composer.json's exact
 # require-dev). Move all of them together, and only after re-running the tables in
 # every runtime; the tests below fail otherwise.
-PINNED_SUITE_VERSION = "0.36.0"
+PINNED_SUITE_VERSION = "0.44.0"
 
 SUITES = (
     "template/tokenize",

fancy_template-0.4.0/tests/test_files.py

@@ -0,0 +1,28 @@
+"""Office-file templates (SPEC.md section 12) are PHP-only so far. This leg must
+refuse LOUDLY and by name -- never return the input, never return nothing."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from fancy_template import FileTemplatesNotImplementedError, TemplateError, inspect_file, render_file
+
+DOCX = (Path(__file__).resolve().parents[2] / "fixtures" / "files" / "proposal.docx").read_bytes()
+
+
+def test_inspect_file_raises_the_named_error() -> None:
+    with pytest.raises(FileTemplatesNotImplementedError) as info:
+        inspect_file(DOCX)
+    assert info.value.code == "FILE_NOT_IMPLEMENTED"
+    assert info.value.operation == "inspect_file"
+    assert isinstance(info.value, NotImplementedError)
+
+
+def test_render_file_raises_the_named_error_not_a_template_refusal() -> None:
+    with pytest.raises(FileTemplatesNotImplementedError) as info:
+        render_file(DOCX, {"client": "Ada"})
+    assert info.value.operation == "render_file"
+    assert not isinstance(info.value, TemplateError)
+    assert "SPEC.md section 12" in str(info.value)

fancy_template-0.2.0/profiles/fine-print.json

@@ -1,18 +0,0 @@
-{
-  "writer": "fine-print",
-  "schema": "fine-print 0.3",
-  "notes": "An ALLOWLIST: a string field not matched here refuses tokens. link, color, font, fonts, page geometry and every style field are deliberately absent. Band slots refuse a value containing {page}/{pages}: fine-print replaces them with str_replace and has no escape.",
-  "fields": [
-    { "path": "title", "encode": "text" },
-    { "path": "**.runs.*.text", "encode": "text" },
-    { "path": "**.blocks.*.text", "encode": "text" },
-    { "path": "**.blocks.*.alt", "encode": "text" },
-    { "path": "**.blocks.*.src", "encode": "image", "mime": ["image/png", "image/jpeg"] },
-    { "path": "page.header.left", "encode": "band" },
-    { "path": "page.header.center", "encode": "band" },
-    { "path": "page.header.right", "encode": "band" },
-    { "path": "page.footer.left", "encode": "band" },
-    { "path": "page.footer.center", "encode": "band" },
-    { "path": "page.footer.right", "encode": "band" }
-  ]
-}