Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions HISTORY.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,13 @@
Release History
---------------

Unreleased
++++++++++

- Fix #212, #284, #363 Open and save macro-enabled documents (.docm), templates (.dotx) and
macro-enabled templates (.dotm); package kind and VBA project are preserved on save.


1.2.0 (2025-06-16)
++++++++++++++++++

Expand Down
196 changes: 196 additions & 0 deletions docs/dev/analysis/features/document-kinds.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,196 @@

Macro-enabled documents and templates
=====================================

Besides the regular document (``.docx``), Word saves three other kinds of
WordprocessingML package: the macro-enabled document (``.docm``), the template
(``.dotx``) and the macro-enabled template (``.dotm``).

Up to v1.2.0, |docx| refuses to open them, raising ``ValueError: file '...' is not
a Word file, content type is '...'`` (issues #212, #284, #363). This page
describes how the four kinds differ, how macros are stored, the experiments
showing that macros survive a load/save cycle unchanged, and the limits of the
approach.


Candidate protocol
------------------

.. highlight:: python

::

>>> document = Document('macros.docm')
>>> document.part.content_type
'application/vnd.ms-word.document.macroEnabled.main+xml'
>>> document.add_paragraph('Added by python-docx')
>>> document.save('macros-edited.docm') # -- still a .docm, macros preserved --

>>> document = Document('letterhead.dotx')
>>> document.part.content_type
'application/vnd.openxmlformats-officedocument.wordprocessingml.template.main+xml'

No new API is added. ``docx.Document()`` accepts the three additional kinds and
the package keeps its kind when saved.


How the four kinds differ
-------------------------

All four share the same package structure and the same main document part XML
(``word/document.xml`` with a ``<w:document>`` root element, same schema). The
only thing that tells Word which kind of file it is opening is the content-type
of the main document part, declared in ``[Content_Types].xml``:

========= ======================================================================================
Extension Main document part content-type
========= ======================================================================================
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml
.docm application/vnd.ms-word.document.macroEnabled.main+xml
.dotx application/vnd.openxmlformats-officedocument.wordprocessingml.template.main+xml
.dotm application/vnd.ms-word.template.macroEnabledTemplate.main+xml
========= ======================================================================================

These are available as ``docx.opc.constants.CONTENT_TYPE`` members
``WML_DOCUMENT_MAIN``, ``WML_DOCUMENT_MACRO_MAIN``, ``WML_TEMPLATE_MAIN`` and
``WML_TEMPLATE_MACRO_MAIN``.

The file extension must agree with that content-type; Word refuses to open a
file whose extension does not match ("the file format or file extension is not
valid").


How macros are stored
---------------------

A macro-enabled package (``.docm`` or ``.dotm``) adds these parts to the regular
document structure:

``word/vbaProject.bin``
The VBA project: an OLE compound file (MS-OVBA) holding the compressed source
and compiled p-code of every module, the project references and, when
password-protected, the protection data. Content-type
``application/vnd.ms-office.vbaProject``, related from the main document part
with relationship type
``http://schemas.microsoft.com/office/2006/relationships/vbaProject``.

``word/vbaData.xml``
Word-specific macro metadata (``<wne:vbaSuppData>``: one ``<wne:mcd>`` per
macro, with its name and encryption flag). Content-type
``application/vnd.ms-word.vbaData+xml``, related from ``vbaProject.bin``
(``word/_rels/vbaProject.bin.rels``) with relationship type
``http://schemas.microsoft.com/office/2006/relationships/wordVbaData``.

Optionally, depending on what the author did in Word:

* ``word/vbaProjectSignature.bin`` (and agile/V3 variants) – digital signature of
the VBA project, related from ``vbaProject.bin``.
* ``word/customizations.xml`` – keyboard shortcuts assigned to macros
(``keyMapCustomizations`` relationship from the main document part).
* ``word/activeX/*`` – ActiveX controls and their binary persistence parts.

|docx| has no part class for any of these. On load, the OPC layer instantiates
them as generic |Part| objects (via ``PartFactory.default_part_type``), keeping
the original blob and relationships; on save they are written back with the
same partname, content-type and relationships, byte for byte. This is the same
mechanism that already preserves any part |docx| does not understand in a
``.docx`` file (footnotes, glossary document, custom XML, etc.).


Implementation
--------------

The change is limited to recognising the three additional main-document
content-types:

* ``docx.opc.constants.CONTENT_TYPE``: add the three content-types.
* ``docx/__init__.py``: map each of them to |DocumentPart| in
``PartFactory.part_type_for``, so the main document part gets the same proxy
as in a ``.docx`` file.
* ``docx.api.Document()``: accept any of the four main-document content-types
instead of only ``WML_DOCUMENT_MAIN``.

The content-type of the main document part is stored on the part when loaded
and written back unchanged on save, which is what keeps the package kind.


Experiments
-----------

The following was used to establish that macros are preserved. The scripts
mentioned are not part of the library.

1. **Source files made by Word.** A document exercising most |docx| features
(headings, styles, runs and fonts, paragraph formatting, tables including
merged and nested cells, pictures in five formats, comments, four sections
with headers/footers) was saved by Word (Office 16, Windows) as
``.docm``, ``.dotx`` and ``.dotm``, after adding a VBA module to the
``.docm``/``.dotm``. The module contains a ``PythonDocxCheck`` macro that
reports document statistics and whether the last paragraph is the one added
by |docx|, plus a marker constant ``PYDOCX-MACRO-PROBE v1``.

2. **Without the change (python-docx 1.2.0 from PyPI).** The ``.docx`` opens;
the ``.docm``, ``.dotx`` and ``.dotm`` all raise ``ValueError: ... is not a
Word file``.

3. **Load, edit, save with the change.** Each file was opened with
``docx.Document()``, a paragraph was appended, and it was saved under a new
name with the same extension. Comparing the source and result packages:

* main document part content-type unchanged (``.docm`` stays ``.docm``, etc.),
* same set of parts: none lost, none added,
* every binary part byte-identical: ``word/vbaProject.bin`` and all five
images,
* ``vbaProject.bin`` still related from the main document part, and
``vbaData.xml`` from ``vbaProject.bin``,
* VBA source extracted from the saved ``vbaProject.bin`` (``oletools``)
still contains both macros and the marker.

4. **Heavier edits.** The same files were edited further (paragraph inserted
at the top, table cell text replaced, comment added, core properties
changed) and saved. Same results as in 3.

5. **Back in Word.** The saved ``.docm``/``.dotm`` files open in Word without a
repair prompt, the edits are shown, and after enabling content
``PythonDocxCheck`` runs and detects the paragraph added by |docx|.

The acceptance tests ``features/api-open-document.feature`` reproduce 2–3 in an
automated way with small fixtures: ``doc-default.docm``/``.dotx``/``.dotm`` are
``doc-default.docx`` with the main document content-type changed and, for the
macro-enabled ones, the VBA parts of the Word-made file above (a real VBA
project containing ``PythonDocxCheck``) added. The scenarios check the package
kind and that ``vbaProject.bin`` is preserved byte for byte.


Limits and unintended consequences
----------------------------------

* **Macros are opaque.** They cannot be read, added, changed or removed through
the |docx| API; they are carried along unchanged.

* **No conversion between kinds.** A template stays a template, a ``.docm``
stays a ``.docm``. Saving under another extension (e.g. a ``.dotx`` package
as ``foo.docx``) produces a file Word refuses to open; |docx| does not check
the extension against the content-type, as before. Converting would need a
new API (out of scope; see #363 for the workaround of setting the private
``DocumentPart._content_type``).

* **Digital signatures.** A signed VBA project stays signed and valid, because
``vbaProject.bin`` and the signature parts are not modified. Document-level
(XAdES package) signatures are invalidated by any save, as for ``.docx``.

* **Parts must be reachable by relationship.** As for ``.docx``, |docx| only
loads parts reachable from the package relationships. Word always relates the
VBA parts as described above; a hand-made package with an unrelated
``vbaProject.bin`` would lose it on save. This is unchanged behaviour.

* **Default template.** ``docx.Document()`` with no argument still creates a
``.docx``. Creating a macro-enabled file or template from scratch is out of
scope.

* **Templates opened as documents.** |docx| edits the template itself, as Word
does with *File > Open*. It does not create a new document based on the
template, which is what Word does when a template is double-clicked.

* **Other OOXML packages.** Opening a ``.xlsx``/``.pptx`` (or any package whose
main part is not one of the four content-types) still raises ``ValueError``.
1 change: 1 addition & 0 deletions docs/dev/analysis/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Feature Analysis
:titlesonly:

features/comments
features/document-kinds
features/header
features/settings
features/text/index
Expand Down
23 changes: 23 additions & 0 deletions docs/user/documents.rst
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,29 @@ Things to note:
what you intend.


Macro-enabled documents and templates
-------------------------------------

Besides a regular ``.docx`` document, |docx| can open a macro-enabled document
(``.docm``), a template (``.dotx``) and a macro-enabled template (``.dotm``)::

document = Document('letterhead.dotx')
document.add_paragraph('Dear Sir or Madam,')
document.save('letterhead-filled.dotx')

The file keeps its kind when saved. A template is saved as a template and a
macro-enabled file stays macro-enabled, so you should save it using the same
extension it was opened with, otherwise Word will refuse to open it. Any macros
(VBA project) the file contains are kept just as they are; |docx| can't read,
add or change macros.

Things to note:

* Saving a template under a ``.docx`` name does not turn it into a regular
document, the file is still a template inside and Word will complain about
it.


Opening a 'file-like' document
------------------------------

Expand Down
25 changes: 25 additions & 0 deletions features/api-open-document.feature
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,28 @@ Feature: Open a document
Given I have python-docx installed
When I call docx.Document() with no arguments
Then document is a Document object


Scenario Outline: Open a macro-enabled document or a template
Given I have python-docx installed
When I call docx.Document() with the path of a <ext> file
Then document is a Document object

Examples: Word file kinds
| ext |
| .docm |
| .dotx |
| .dotm |


Scenario Outline: Save a macro-enabled document or a template
Given a document opened from a <ext> file
When I save and reload the document
Then the document part content type is the <ext> content type
And the VBA project part is preserved: <has-vba>

Examples: Word file kinds
| ext | has-vba |
| .docm | True |
| .dotx | False |
| .dotm | True |
50 changes: 49 additions & 1 deletion features/steps/api.py
Original file line number Diff line number Diff line change
@@ -1,15 +1,30 @@
"""Step implementations for basic API features."""

import os

from behave import given, then, when

import docx
from docx import Document
from docx.opc.constants import CONTENT_TYPE as CT

from helpers import bool_vals, saved_docx_path, test_docx, test_file

from helpers import test_docx
main_content_types = {
".docm": CT.WML_DOCUMENT_MACRO_MAIN,
".dotx": CT.WML_TEMPLATE_MAIN,
".dotm": CT.WML_TEMPLATE_MACRO_MAIN,
}

# given ====================================================


@given("a document opened from a {ext} file")
def given_a_document_opened_from_an_ext_file(context, ext):
context.ext = ext
context.document = Document(test_file("doc-default%s" % ext))


@given("I have python-docx installed")
def given_I_have_python_docx_installed(context):
pass
Expand All @@ -28,9 +43,42 @@ def when_I_call_docx_Document_with_the_path_of_a_docx_file(context):
context.document = Document(test_docx("doc-default"))


@when("I call docx.Document() with the path of a {ext} file")
def when_I_call_docx_Document_with_the_path_of_an_ext_file(context, ext):
context.document = Document(test_file("doc-default%s" % ext))


@when("I save and reload the document")
def when_I_save_and_reload_the_document(context):
path = os.path.splitext(saved_docx_path)[0] + context.ext
context.document.save(path)
context.document = Document(path)


# then =====================================================


@then("the document part content type is the {ext} content type")
def then_the_document_part_content_type_is_the_ext_content_type(context, ext):
actual = context.document.part.content_type
expected = main_content_types[ext]
assert actual == expected, "expected '%s', got '%s'" % (expected, actual)


@then("the VBA project part is preserved: {has_vba}")
def then_the_VBA_project_part_is_preserved(context, has_vba):
original = Document(test_file("doc-default%s" % context.ext)).part.package
reloaded = context.document.part.package

def vba_blob(package):
parts = [p for p in package.iter_parts() if p.partname == "/word/vbaProject.bin"]
return parts[0].blob if parts else None

expected = vba_blob(original)
assert (expected is not None) is bool_vals[has_vba]
assert vba_blob(reloaded) == expected


@then("document is a Document object")
def then_document_is_a_Document_object(context):
document = context.document
Expand Down
Binary file added features/steps/test_files/doc-default.docm
Binary file not shown.
Binary file added features/steps/test_files/doc-default.dotm
Binary file not shown.
Binary file added features/steps/test_files/doc-default.dotx
Binary file not shown.
3 changes: 3 additions & 0 deletions src/docx/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,15 @@ def part_class_selector(content_type: str, reltype: str) -> Type[Part] | None:
PartFactory.part_class_selector = part_class_selector
PartFactory.part_type_for[CT.OPC_CORE_PROPERTIES] = CorePropertiesPart
PartFactory.part_type_for[CT.WML_COMMENTS] = CommentsPart
PartFactory.part_type_for[CT.WML_DOCUMENT_MACRO_MAIN] = DocumentPart
PartFactory.part_type_for[CT.WML_DOCUMENT_MAIN] = DocumentPart
PartFactory.part_type_for[CT.WML_FOOTER] = FooterPart
PartFactory.part_type_for[CT.WML_HEADER] = HeaderPart
PartFactory.part_type_for[CT.WML_NUMBERING] = NumberingPart
PartFactory.part_type_for[CT.WML_SETTINGS] = SettingsPart
PartFactory.part_type_for[CT.WML_STYLES] = StylesPart
PartFactory.part_type_for[CT.WML_TEMPLATE_MACRO_MAIN] = DocumentPart
PartFactory.part_type_for[CT.WML_TEMPLATE_MAIN] = DocumentPart

del (
CT,
Expand Down
Loading