Mammoth .docx to HTML converter
===============================
Mammoth is designed to convert .docx documents, such as those created by
Microsoft Word, Google Docs and LibreOffice, and convert them to HTML.
Mammoth aims to produce simple and clean HTML by using semantic
information in the document, and ignoring other details. For instance,
Mammoth converts any paragraph with the style ``Heading 1`` to ``h1``
elements, rather than attempting to exactly copy the styling (font, text
size, colour, etc.) of the heading.
There’s a large mismatch between the structure used by .docx and the
structure of HTML, meaning that the conversion is unlikely to be perfect
for more complicated documents. Mammoth works best if you only use
styles to semantically mark up your document.
The following features are currently supported:
- Headings.
- Lists.
- Customisable mapping from your own docx styles to HTML. For instance,
you could convert ``WarningHeading`` to ``h1.warning`` by providing
an appropriate style mapping.
- Tables. The formatting of the table itself, such as borders, is
currently ignored, but the formatting of the text is treated the same
as in the rest of the document.
- Footnotes and endnotes.
- Images.
- Bold, italics, underlines, strikethrough, superscript and subscript.
- Links.
- Line breaks.
- Text boxes. The contents of the text box are treated as a separate
paragraph that appears after the paragraph containing the text box.
- Comments.
Installation
------------
::
pip install mammoth
Other supported platforms
-------------------------
- `JavaScript <https://github.com/mwilliamson/mammoth.js>`__, both the
browser and node.js. Available `on
npm <https://www.npmjs.com/package/mammoth>`__.
- `WordPress <https://wordpress.org/plugins/mammoth-docx-converter/>`__.
- `Java/JVM <https://github.com/mwilliamson/java-mammoth>`__. Available
`on Maven
Central <http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.zwobble.mammoth%22%20AND%20a%3A%22mammoth%22>`__.
- `.NET <https://github.com/mwilliamson/dotnet-mammoth>`__. Available
`on NuGet <https://www.nuget.org/packages/Mammoth/>`__.
Usage
-----
CLI
~~~
You can convert docx files by passing the path to the docx file and the
output file. For instance:
::
mammoth document.docx output.html
If no output file is specified, output is written to stdout instead.
The output is an HTML fragment, rather than a full HTML document,
encoded with UTF-8. Since the encoding is not explicitly set in the
fragment, opening the output file in a web browser may cause Unicode
characters to be rendered incorrectly if the browser doesn’t default to
UTF-8.
Images
^^^^^^
By default, images are included inline in the output HTML. If an output
directory is specified by ``--output-dir``, the images are written to
separate files instead. For instance:
::
mammoth document.docx --output-dir=output-dir
Existing files will be overwritten if present.
Styles
^^^^^^
A custom style map can be read from a file using ``--style-map``. For
instance:
::
mammoth document.docx output.html --style-map=custom-style-map
Where ``custom-style-map`` looks something like:
::
p[style-name='Aside Heading'] => div.aside > h2:fresh
p[style-name='Aside Text'] => div.aside > p:fresh
A description of the syntax for style maps can be found in the section
`“Writing style maps” <#writing-style-maps>`__.
Markdown
^^^^^^^^
Markdown support is deprecated. Generating HTML and using a separate
library to convert the HTML to Markdown is recommended, and is likely to
produce better results.
Using ``--output-format=markdown`` will cause Markdown to be generated.
For instance:
::
mammoth document.docx --output-format=markdown
Library
~~~~~~~
Basic conversion
^^^^^^^^^^^^^^^^
To convert an existing .docx file to HTML, pass a file-like object to
``mammoth.convert_to_html``. The file should be opened in binary mode.
For instance:
.. code:: python
import mammoth
with open("document.docx", "rb") as docx_file:
result = mammoth.convert_to_html(docx_file)
html = result.value # The generated HTML
messages = result.messages # Any messages, such as warnings during conversion
You can also extract the raw text of the document by using
``mammoth.extract_raw_text``. This will ignore all formatting in the
document. Each paragraph is followed by two newlines.
.. code:: python
with open("document.docx", "rb") as docx_file:
result = mammoth.extract_raw_text(docx_file)
text = result.value # The raw text
messages = result.messages # Any messages
Custom style map
^^^^^^^^^^^^^^^^
By default, Mammoth maps some common .docx styles to HTML elements. For
instance, a paragraph with the style name ``Heading 1`` is converted to
a ``h1`` element. You can pass in a custom map for styles by passing an
options object with a ``style_map`` property as a second argument to
``convert_to_html``. A description of the syntax for style maps can be
found in the section `“Writing style maps” <#writing-style-maps>`__. For
instance, if paragraphs with the style name ``Section Title`` should be
converted to ``h1`` elements, and paragraphs with the style name
``Subsection Title`` should be converted to ``h2`` elements:
.. code:: python
import mammoth
style_map = """
p[style-name='Section Title'] => h1:fresh
p[style-name='Subsection Title'] => h2:fresh
"""
with open("document.docx", "rb") as docx_file:
result = mammoth.convert_to_html(docx_file, style_map=style_map)
User-defined style mappings are used in preference to the default style
mappings. To stop using the default style mappings altogether, pass
``include_default_style_map=False``:
.. code:: python
result = mammoth.convert_to_html(docx_file, style_map=style_map, include_default_style_map=False)
Custom image handlers
^^^^^^^^^^^^^^^^^^^^^
By default, images are converted to ``<img>`` elements with the source
included inline in the ``src`` attribute. This behaviour can be changed
by setting the ``convert_image`` argument to an `image
converter <#image-converters>`__ .
For instance, the following would replicate the default behaviour:
.. code:: python
def convert_image(image):
with image.open() as image_bytes:
encoded_src = base64.b64encode(image_bytes.read()).decode("ascii")
return {
"src": "data:{0};base64,{1}".format(image.content_type, encoded_src)
}
mammoth.convert_to_html(docx_file, convert_image=mammoth.images.img_element(convert_image))
Bold
^^^^
By default, bold text is wrapped in ``<strong>`` tags. This behaviour
can be changed by adding a style mapping for ``b``. For instance, to
wrap bold text in ``<em>`` tags:
.. code:: python
style_map = "b => em"
with open("document.docx", "rb") as docx_file:
result = mammoth.convert_to_html(docx_file, style_map=style_map)
Italic
^^^^^^
By default, italic text is wrapped in ``<em>`` tags. This behaviour can
be changed by adding a style mapping for ``i``. For instance, to wrap
italic text in ``<strong>`` tags:
.. code:: python
style_map = "i => strong"
with open("document.docx", "rb") as docx_file:
result = mammoth.convert_to_html(docx_file, style_map=style_map)
Underline
^^^^^^^^^
By default, the underlining of any text is ignored since underlining can
be confused with links in HTML documents. This behaviour can be changed
by adding a style mapping for ``u``. For instance, suppose that a source
document uses underlining for emphasis. The following will wrap any
explicitly underlined source text in ``<em>`` tags:
.. code:: python
import mammoth
style_map = "u => em"
with open("document.docx", "rb") as docx_file:
result = mammoth.convert_to_html(docx_file, style_map=style_map)
Strikethrough
^^^^^^^^^^^^^
By default, strikethrough text is wrapped in ``<s>`` tags. This
behaviour can be changed by adding a style mapping for ``strike``. For
instance, to wrap strikethrough text in ``<del>`` tags:
.. code:: python
style_map = "strike => del"
with open("document.docx", "rb") as docx_file:
result = mammoth.convert_to_html(docx_file, style_map=style_map)
Comments
^^^^^^^^
By default, comments are ignored. To include comments in the generated
HTML, add a style mapping for ``comment-reference``. For instance:
.. code:: python
style_map = "comment-reference => sup"
with open("document.docx", "rb") as docx_file:
result = mammoth.convert_to_html(docx_file, style_map=style_map)
Comments will be appended to the end of the document, with links to the
comments wrapped using the specified style mapping.
API
~~~
``mammoth.convert_to_html(fileobj, **kwargs)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Converts the source document to HTML.
- ``fileobj``: a file-like object containing the source document. Files
should be opened in binary mode.
- ``style_map``: a string to specify the mapping of Word styles to
HTML. See the section `“Writing style maps” <#writing-style-maps>`__
for a description of the syntax.
- ``include_embedded_style_map``: by default, if the document contains
an embedded style map, then it is combined with the default style
map. To ignore any embedded style maps, pass
``include_embedded_style_map=False``.
- ``include_default_style_map``: by default, the style map passed in
``style_map`` is combined with the default style map. To stop using
the default style map altogether, pass
``include_default_style_map=False``.
- ``convert_image``: by default, images are converted to ``<img>``
elements with the source included inline in the ``src`` attribute.
Set this argument to an `image converter <#image-converters>`__ to
override the default behaviour.
- ``ignore_empty_paragraphs``: by default, empty paragraphs are
ignored. Set this option to ``False`` to preserve empty paragraphs in
the output.
- ``id_prefix``: a string to prepend to any generated IDs, such as
those used by bookmarks, footnotes and endnotes. Defaults to an empty
string.
- ``transform_document``: if set, this function is applied to the
document read from the docx file before the conversion to HTML. The
API for document transforms should be considered unstable. See
`document transforms <#document-transforms>`__.
- Returns a result with the following properties:
- ``value``: the generated HTML
- ``messages``: any messages, such as errors and warnings, generated
during the conversion
``mammoth.convert_to_markdown(fileobj, **kwargs)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Markdown support is deprecated. Generating HTML and using a separate
library to convert the HTML to Markdown is recommended, and is likely to
produce better results.
Converts the source document to Markdown. This behaves the same as
``convert_to_html``, except that the ``value`` property of the result
contains Markdown rather than HTML.
``mammoth.extract_raw_text(fileobj)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Extract the raw text of the document. This will ignore all formatting in
the document. Each paragraph is followed by two newlines.
- ``fileobj``: a file-like object containing the source document. Files
should be opened in binary mode.
- Returns a result with the following properties:
- ``value``: the raw text
- ``messages``: any messages, such as errors and warnings
``mammoth.embed_style_map(fileobj, style_map)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Embeds the style map ``style_map`` into ``fileobj``. When Mammoth reads
a file object, it will use the embedded style map.
- ``fileobj``: a file-like object containing the source document. Files
should be opened for reading and writing in binary mode.
- ``style_map``: the style map to embed.
- Returns ``None``.
Messages
^^^^^^^^
Each message has the following properties:
- ``type``: a string representing the type of the message, such as
``"warning"``
- ``message``: a string containing the actual message
Image converters
^^^^^^^^^^^^^^^^
An image converter can be created by calling
``mammoth.images.img_element(func)``. This creates an ``<img>`` element
for each image in the original docx. ``func`` should be a function that
has one argument ``image``. This argument is the image element being
converted, and has the following properties:
- ``open()``: open the image file. Returns a file-like object.
- ``content_type``: the content type of the image, such as
``image/png``.
``func`` should return a ``dict`` of attributes for the ``<img>``
element. At a minimum, this should include the ``src`` attribute. If any
alt text is found for the image, this will be automatically added to the
element’s attributes.
For instance, the following replicates the default image conversion:
.. code:: python
def convert_image(image):
with image.open() as image_bytes:
encoded_src = base64.b64encode(image_bytes.read()).decode("ascii")
return {
"src": "data:{0};base64,{1}".format(image.content_type, encoded_src)
}
mammoth.images.img_element(convert_image)
``mammoth.images.data_uri`` is the default image converter.
WMF images are not handled by default by Mammoth. The recipes directory
contains `an example of how they can be converted using
LibreOffice <https://github.com/mwilliamson/python-mammoth/blob/master/recipes/wmf_images.py>`__,
although the fidelity of the conversion depends entirely on LibreOffice.
Document transforms
~~~~~~~~~~~~~~~~~~~
**The API for document transforms should be considered unstable, and may
change between any versions. If you rely on this behaviour, you should
pin to a specific version of Mammoth, and test carefully before
updating.**
Mammoth allows a document to be transformed before it is converted. For
instance, suppose that document has not been semantically marked up, but
you know that any centre-aligned paragraph should be a heading. You can
use the ``transform_document`` argument to modify the document
appropriately:
.. code:: python
import mammoth.transforms
def transform_paragraph(element):
if element.alignment == "center" and not element.style_id:
return element.copy(style_id="Heading2")
else:
return element
transform_document = mammoth.transforms.paragraph(transform_paragraph)
mammoth.convert_to_html(fileobj, transform_document=transform_document)
Or if you want paragraphs that have been explicitly set to use monospace
fonts to represent code:
.. code:: python
import mammoth.documents
import mammoth.transforms
_monospace_fonts = set(["consolas", "courier", "courier new"])
def transform_paragraph(paragraph):
runs = mammoth.transforms.get_descendants_of_type(paragraph, mammoth.documents.Run)
if runs and all(run.font and run.font.lower() in _monospace_fonts for run in runs):
return paragraph.copy(style_id="code", style_name="Code")
else:
return paragraph
convert_to_html(
fileobj,
transform_document=mammoth.transforms.paragraph(transform_paragraph),
style_map="p[style-name='Code'] => pre:separator('\n')",
)
``mammoth.transforms.paragraph(transform_paragraph)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Returns a function that can be used as the ``transform_document``
argument. This will apply the function ``transform_paragraph`` to each
paragraph element. ``transform_paragraph`` should return the new
paragraph.
``mammoth.transforms.run(transform_run)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Returns a function that can be used as the ``transform_document``
argument. This will apply the function ``transform_run`` to each run
element. ``transform_run`` should return the new run.
``mammoth.transforms.get_descendants(element)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Gets all descendants of an element.
``mammoth.transforms.get_descendants_of_type(element, type)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Gets all descendants of a particular type of an element. For instance,
to get all runs within an element ``paragraph``:
.. code:: python
import mammoth.documents
import mammoth.transforms
runs = mammoth.transforms.get_descendants_of_type(paragraph, documents.Run);
Writing style maps
------------------
A style map is made up of a number of style mappings separated by new
lines. Blank lines and lines starting with ``#`` are ignored.
A style mapping has two parts:
- On the left, before the arrow, is the document element matcher.
- On the right, after the arrow, is the HTML path.
When converting each paragraph, Mammoth finds the first style mapping
where the document element matcher matches the current paragraph.
Mammoth then ensures the HTML path is satisfied.
Freshness
~~~~~~~~~
When writing style mappings, it’s helpful to understand Mammoth’s notion
of freshness. When generating, Mammoth will only close an HTML element
when necessary. Otherwise, elements are reused.
For instance, suppose one of the specified style mappings is
``p[style-name='Heading 1'] => h1``. If Mammoth encounters a .docx
paragraph with the style name ``Heading 1``, the .docx paragraph is
converted to a ``h1`` element with the same text. If the next .docx
paragraph also has the style name ``Heading 1``, then the text of that
paragraph will be appended to the *existing* ``h1`` element, rather than
creating a new ``h1`` element.
In most cases, you’ll probably want to generate a new ``h1`` element
instead. You can specify this by using the ``:fresh`` modifier:
``p[style-name='Heading 1'] => h1:fresh``
The two consecutive ``Heading 1`` .docx paragraphs will then be
converted to two separate ``h1`` elements.
Reusing elements is useful in generating more complicated HTML
structures. For instance, suppose your .docx contains asides. Each aside
might have a heading and some body text, which should be contained
within a single ``div.aside`` element. In this case, style mappings
similar to ``p[style-name='Aside Heading'] => div.aside > h2:fresh`` and
``p[style-name='Aside Text'] => div.aside > p:fresh`` might be helpful.
Document element matchers
~~~~~~~~~~~~~~~~~~~~~~~~~
Paragraphs, runs and tables
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Match any paragraph:
::
p
Match any run:
::
r
Match any table:
::
table
To match a paragraph, run or table with a specific style, you can
reference the style by name. This is the style name that is displayed in
Microsoft Word or LibreOffice. For instance, to match a paragraph with
the style name ``Heading 1``:
::
p[style-name='Heading 1']
You can also match a style name by prefix. For instance, to match a
paragraph where the style name starts with ``Heading``:
::
p[style-name^='Heading']
Styles can also be referenced by style ID. This is the ID used
internally in the .docx file. To match a paragraph or run with a
specific style ID, append a dot followed by the style ID. For instance,
to match a paragraph with the style ID ``Heading1``:
::
p.Heading1
.. _bold-1:
Bold
^^^^
Match explicitly bold text:
::
b
Note that this matches text that has had bold explicitly applied to it.
It will not match any text that is bold because of its paragraph or run
style.
.. _italic-1:
Italic
^^^^^^
Match explicitly italic text:
::
i
Note that this matches text that has had italic explicitly applied to
it. It will not match any text that is italic because of its paragraph
or run style.
.. _underline-1:
Underline
^^^^^^^^^
Match explicitly underlined text:
::
u
Note that this matches text that has had underline explicitly applied to
it. It will not match any text that is underlined because of its
paragraph or run style.
Strikethough
^^^^^^^^^^^^
Match explicitly struckthrough text:
::
strike
Note that this matches text that has had strikethrough explicitly
applied to it. It will not match any text that is struckthrough because
of its paragraph or run style.
All caps
^^^^^^^^
Match explicitly all caps text:
::
all-caps
Note that this matches text that has had all caps explicitly applied to
it. It will not match any text that is all caps because of its paragraph
or run style.
Small caps
^^^^^^^^^^
Match explicitly small caps text:
::
small-caps
Note that this matches text that has had small caps explicitly applied
to it. It will not match any text that is small caps because of its
paragraph or run style.
Highlight
^^^^^^^^^
Match explicitly highlighted text:
::
highlight
Note that this matches text that has had a highlight explicitly applied
to it. It will not match any text that is highlighted because of its
paragraph or run style.
It’s also possible to match specific colours. For instance, to match
yellow highlights:
::
highlight[color='yellow']
The set of colours typically used are:
- ``black``
- ``blue``
- ``cyan``
- ``green``
- ``magenta``
- ``red``
- ``yellow``
- ``white``
- ``darkBlue``
- ``darkCyan``
- ``darkGreen``
- ``darkMagenta``
- ``darkRed``
- ``darkYellow``
- ``darkGray``
- ``lightGray``
Ignoring document elements
^^^^^^^^^^^^^^^^^^^^^^^^^^
Use ``!`` to ignore a document element. For instance, to ignore any
paragraph with the style ``Comment``:
::
p[style-name='Comment'] => !
HTML paths
~~~~~~~~~~
Single elements
^^^^^^^^^^^^^^^
The simplest HTML path is to specify a single element. For instance, to
specify an ``h1`` element:
::
h1
To give an element a CSS class, append a dot followed by the name of the
class:
::
h1.section-title
To add an attribute, use square brackets similarly to a CSS attribute
selector:
::
p[lang='fr']
To require that an element is fresh, use ``:fresh``:
::
h1:fresh
Modifiers must be used in the correct order:
::
h1.section-title:fresh
Separators
^^^^^^^^^^
To specify a separator to place between the contents of paragraphs that
are collapsed together, use ``:separator('SEPARATOR STRING')``.
For instance, suppose a document contains a block of code where each
line of code is a paragraph with the style ``Code Block``. We can write
a style mapping to map such paragraphs to ``<pre>`` elements:
::
p[style-name='Code Block'] => pre
Since ``pre`` isn’t marked as ``:fresh``, consecutive ``pre`` elements
will be collapsed together. However, this results in the code all being
on one line. We can use ``:separator`` to insert a newline between each
line of code:
::
p[style-name='Code Block'] => pre:separator('\n')
Nested elements
^^^^^^^^^^^^^^^
Use ``>`` to specify nested elements. For instance, to specify ``h2``
within ``div.aside``:
::
div.aside > h2
You can nest elements to any depth.
Donations
---------
If you’d like to say thanks, feel free to `make a donation through
Ko-fi <https://ko-fi.com/S6S01MG20>`__.
If you use Mammoth as part of your business, please consider supporting
the ongoing maintenance of Mammoth by `making a weekly donation through
Liberapay <https://liberapay.com/mwilliamson/donate>`__.
Raw data
{
"_id": null,
"home_page": "https://github.com/mwilliamson/python-mammoth",
"name": "mammoth",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "docx word office clean html markdown md",
"author": "Michael Williamson",
"author_email": "mike@zwobble.org",
"download_url": "https://files.pythonhosted.org/packages/0b/03/54ad55930465d571b4d74cfca4446c8353bf3410d2c5dc5c52a18dc6d039/mammoth-1.8.0.tar.gz",
"platform": null,
"description": "Mammoth .docx to HTML converter\n===============================\n\nMammoth is designed to convert .docx documents, such as those created by\nMicrosoft Word, Google Docs and LibreOffice, and convert them to HTML.\nMammoth aims to produce simple and clean HTML by using semantic\ninformation in the document, and ignoring other details. For instance,\nMammoth converts any paragraph with the style ``Heading 1`` to ``h1``\nelements, rather than attempting to exactly copy the styling (font, text\nsize, colour, etc.) of the heading.\n\nThere\u2019s a large mismatch between the structure used by .docx and the\nstructure of HTML, meaning that the conversion is unlikely to be perfect\nfor more complicated documents. Mammoth works best if you only use\nstyles to semantically mark up your document.\n\nThe following features are currently supported:\n\n- Headings.\n\n- Lists.\n\n- Customisable mapping from your own docx styles to HTML. For instance,\n you could convert ``WarningHeading`` to ``h1.warning`` by providing\n an appropriate style mapping.\n\n- Tables. The formatting of the table itself, such as borders, is\n currently ignored, but the formatting of the text is treated the same\n as in the rest of the document.\n\n- Footnotes and endnotes.\n\n- Images.\n\n- Bold, italics, underlines, strikethrough, superscript and subscript.\n\n- Links.\n\n- Line breaks.\n\n- Text boxes. The contents of the text box are treated as a separate\n paragraph that appears after the paragraph containing the text box.\n\n- Comments.\n\nInstallation\n------------\n\n::\n\n pip install mammoth\n\nOther supported platforms\n-------------------------\n\n- `JavaScript <https://github.com/mwilliamson/mammoth.js>`__, both the\n browser and node.js. Available `on\n npm <https://www.npmjs.com/package/mammoth>`__.\n\n- `WordPress <https://wordpress.org/plugins/mammoth-docx-converter/>`__.\n\n- `Java/JVM <https://github.com/mwilliamson/java-mammoth>`__. Available\n `on Maven\n Central <http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.zwobble.mammoth%22%20AND%20a%3A%22mammoth%22>`__.\n\n- `.NET <https://github.com/mwilliamson/dotnet-mammoth>`__. Available\n `on NuGet <https://www.nuget.org/packages/Mammoth/>`__.\n\nUsage\n-----\n\nCLI\n~~~\n\nYou can convert docx files by passing the path to the docx file and the\noutput file. For instance:\n\n::\n\n mammoth document.docx output.html\n\nIf no output file is specified, output is written to stdout instead.\n\nThe output is an HTML fragment, rather than a full HTML document,\nencoded with UTF-8. Since the encoding is not explicitly set in the\nfragment, opening the output file in a web browser may cause Unicode\ncharacters to be rendered incorrectly if the browser doesn\u2019t default to\nUTF-8.\n\nImages\n^^^^^^\n\nBy default, images are included inline in the output HTML. If an output\ndirectory is specified by ``--output-dir``, the images are written to\nseparate files instead. For instance:\n\n::\n\n mammoth document.docx --output-dir=output-dir\n\nExisting files will be overwritten if present.\n\nStyles\n^^^^^^\n\nA custom style map can be read from a file using ``--style-map``. For\ninstance:\n\n::\n\n mammoth document.docx output.html --style-map=custom-style-map\n\nWhere ``custom-style-map`` looks something like:\n\n::\n\n p[style-name='Aside Heading'] => div.aside > h2:fresh\n p[style-name='Aside Text'] => div.aside > p:fresh\n\nA description of the syntax for style maps can be found in the section\n`\u201cWriting style maps\u201d <#writing-style-maps>`__.\n\nMarkdown\n^^^^^^^^\n\nMarkdown support is deprecated. Generating HTML and using a separate\nlibrary to convert the HTML to Markdown is recommended, and is likely to\nproduce better results.\n\nUsing ``--output-format=markdown`` will cause Markdown to be generated.\nFor instance:\n\n::\n\n mammoth document.docx --output-format=markdown\n\nLibrary\n~~~~~~~\n\nBasic conversion\n^^^^^^^^^^^^^^^^\n\nTo convert an existing .docx file to HTML, pass a file-like object to\n``mammoth.convert_to_html``. The file should be opened in binary mode.\nFor instance:\n\n.. code:: python\n\n import mammoth\n\n with open(\"document.docx\", \"rb\") as docx_file:\n result = mammoth.convert_to_html(docx_file)\n html = result.value # The generated HTML\n messages = result.messages # Any messages, such as warnings during conversion\n\nYou can also extract the raw text of the document by using\n``mammoth.extract_raw_text``. This will ignore all formatting in the\ndocument. Each paragraph is followed by two newlines.\n\n.. code:: python\n\n with open(\"document.docx\", \"rb\") as docx_file:\n result = mammoth.extract_raw_text(docx_file)\n text = result.value # The raw text\n messages = result.messages # Any messages\n\nCustom style map\n^^^^^^^^^^^^^^^^\n\nBy default, Mammoth maps some common .docx styles to HTML elements. For\ninstance, a paragraph with the style name ``Heading 1`` is converted to\na ``h1`` element. You can pass in a custom map for styles by passing an\noptions object with a ``style_map`` property as a second argument to\n``convert_to_html``. A description of the syntax for style maps can be\nfound in the section `\u201cWriting style maps\u201d <#writing-style-maps>`__. For\ninstance, if paragraphs with the style name ``Section Title`` should be\nconverted to ``h1`` elements, and paragraphs with the style name\n``Subsection Title`` should be converted to ``h2`` elements:\n\n.. code:: python\n\n import mammoth\n\n style_map = \"\"\"\n p[style-name='Section Title'] => h1:fresh\n p[style-name='Subsection Title'] => h2:fresh\n \"\"\"\n\n with open(\"document.docx\", \"rb\") as docx_file:\n result = mammoth.convert_to_html(docx_file, style_map=style_map)\n\nUser-defined style mappings are used in preference to the default style\nmappings. To stop using the default style mappings altogether, pass\n``include_default_style_map=False``:\n\n.. code:: python\n\n result = mammoth.convert_to_html(docx_file, style_map=style_map, include_default_style_map=False)\n\nCustom image handlers\n^^^^^^^^^^^^^^^^^^^^^\n\nBy default, images are converted to ``<img>`` elements with the source\nincluded inline in the ``src`` attribute. This behaviour can be changed\nby setting the ``convert_image`` argument to an `image\nconverter <#image-converters>`__ .\n\nFor instance, the following would replicate the default behaviour:\n\n.. code:: python\n\n def convert_image(image):\n with image.open() as image_bytes:\n encoded_src = base64.b64encode(image_bytes.read()).decode(\"ascii\")\n\n return {\n \"src\": \"data:{0};base64,{1}\".format(image.content_type, encoded_src)\n }\n\n mammoth.convert_to_html(docx_file, convert_image=mammoth.images.img_element(convert_image))\n\nBold\n^^^^\n\nBy default, bold text is wrapped in ``<strong>`` tags. This behaviour\ncan be changed by adding a style mapping for ``b``. For instance, to\nwrap bold text in ``<em>`` tags:\n\n.. code:: python\n\n style_map = \"b => em\"\n\n with open(\"document.docx\", \"rb\") as docx_file:\n result = mammoth.convert_to_html(docx_file, style_map=style_map)\n\nItalic\n^^^^^^\n\nBy default, italic text is wrapped in ``<em>`` tags. This behaviour can\nbe changed by adding a style mapping for ``i``. For instance, to wrap\nitalic text in ``<strong>`` tags:\n\n.. code:: python\n\n style_map = \"i => strong\"\n\n with open(\"document.docx\", \"rb\") as docx_file:\n result = mammoth.convert_to_html(docx_file, style_map=style_map)\n\nUnderline\n^^^^^^^^^\n\nBy default, the underlining of any text is ignored since underlining can\nbe confused with links in HTML documents. This behaviour can be changed\nby adding a style mapping for ``u``. For instance, suppose that a source\ndocument uses underlining for emphasis. The following will wrap any\nexplicitly underlined source text in ``<em>`` tags:\n\n.. code:: python\n\n import mammoth\n\n style_map = \"u => em\"\n\n with open(\"document.docx\", \"rb\") as docx_file:\n result = mammoth.convert_to_html(docx_file, style_map=style_map)\n\nStrikethrough\n^^^^^^^^^^^^^\n\nBy default, strikethrough text is wrapped in ``<s>`` tags. This\nbehaviour can be changed by adding a style mapping for ``strike``. For\ninstance, to wrap strikethrough text in ``<del>`` tags:\n\n.. code:: python\n\n style_map = \"strike => del\"\n\n with open(\"document.docx\", \"rb\") as docx_file:\n result = mammoth.convert_to_html(docx_file, style_map=style_map)\n\nComments\n^^^^^^^^\n\nBy default, comments are ignored. To include comments in the generated\nHTML, add a style mapping for ``comment-reference``. For instance:\n\n.. code:: python\n\n style_map = \"comment-reference => sup\"\n\n with open(\"document.docx\", \"rb\") as docx_file:\n result = mammoth.convert_to_html(docx_file, style_map=style_map)\n\nComments will be appended to the end of the document, with links to the\ncomments wrapped using the specified style mapping.\n\nAPI\n~~~\n\n``mammoth.convert_to_html(fileobj, **kwargs)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nConverts the source document to HTML.\n\n- ``fileobj``: a file-like object containing the source document. Files\n should be opened in binary mode.\n\n- ``style_map``: a string to specify the mapping of Word styles to\n HTML. See the section `\u201cWriting style maps\u201d <#writing-style-maps>`__\n for a description of the syntax.\n\n- ``include_embedded_style_map``: by default, if the document contains\n an embedded style map, then it is combined with the default style\n map. To ignore any embedded style maps, pass\n ``include_embedded_style_map=False``.\n\n- ``include_default_style_map``: by default, the style map passed in\n ``style_map`` is combined with the default style map. To stop using\n the default style map altogether, pass\n ``include_default_style_map=False``.\n\n- ``convert_image``: by default, images are converted to ``<img>``\n elements with the source included inline in the ``src`` attribute.\n Set this argument to an `image converter <#image-converters>`__ to\n override the default behaviour.\n\n- ``ignore_empty_paragraphs``: by default, empty paragraphs are\n ignored. Set this option to ``False`` to preserve empty paragraphs in\n the output.\n\n- ``id_prefix``: a string to prepend to any generated IDs, such as\n those used by bookmarks, footnotes and endnotes. Defaults to an empty\n string.\n\n- ``transform_document``: if set, this function is applied to the\n document read from the docx file before the conversion to HTML. The\n API for document transforms should be considered unstable. See\n `document transforms <#document-transforms>`__.\n\n- Returns a result with the following properties:\n\n - ``value``: the generated HTML\n\n - ``messages``: any messages, such as errors and warnings, generated\n during the conversion\n\n``mammoth.convert_to_markdown(fileobj, **kwargs)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nMarkdown support is deprecated. Generating HTML and using a separate\nlibrary to convert the HTML to Markdown is recommended, and is likely to\nproduce better results.\n\nConverts the source document to Markdown. This behaves the same as\n``convert_to_html``, except that the ``value`` property of the result\ncontains Markdown rather than HTML.\n\n``mammoth.extract_raw_text(fileobj)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nExtract the raw text of the document. This will ignore all formatting in\nthe document. Each paragraph is followed by two newlines.\n\n- ``fileobj``: a file-like object containing the source document. Files\n should be opened in binary mode.\n\n- Returns a result with the following properties:\n\n - ``value``: the raw text\n\n - ``messages``: any messages, such as errors and warnings\n\n``mammoth.embed_style_map(fileobj, style_map)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nEmbeds the style map ``style_map`` into ``fileobj``. When Mammoth reads\na file object, it will use the embedded style map.\n\n- ``fileobj``: a file-like object containing the source document. Files\n should be opened for reading and writing in binary mode.\n\n- ``style_map``: the style map to embed.\n\n- Returns ``None``.\n\nMessages\n^^^^^^^^\n\nEach message has the following properties:\n\n- ``type``: a string representing the type of the message, such as\n ``\"warning\"``\n\n- ``message``: a string containing the actual message\n\nImage converters\n^^^^^^^^^^^^^^^^\n\nAn image converter can be created by calling\n``mammoth.images.img_element(func)``. This creates an ``<img>`` element\nfor each image in the original docx. ``func`` should be a function that\nhas one argument ``image``. This argument is the image element being\nconverted, and has the following properties:\n\n- ``open()``: open the image file. Returns a file-like object.\n\n- ``content_type``: the content type of the image, such as\n ``image/png``.\n\n``func`` should return a ``dict`` of attributes for the ``<img>``\nelement. At a minimum, this should include the ``src`` attribute. If any\nalt text is found for the image, this will be automatically added to the\nelement\u2019s attributes.\n\nFor instance, the following replicates the default image conversion:\n\n.. code:: python\n\n def convert_image(image):\n with image.open() as image_bytes:\n encoded_src = base64.b64encode(image_bytes.read()).decode(\"ascii\")\n\n return {\n \"src\": \"data:{0};base64,{1}\".format(image.content_type, encoded_src)\n }\n\n mammoth.images.img_element(convert_image)\n\n``mammoth.images.data_uri`` is the default image converter.\n\nWMF images are not handled by default by Mammoth. The recipes directory\ncontains `an example of how they can be converted using\nLibreOffice <https://github.com/mwilliamson/python-mammoth/blob/master/recipes/wmf_images.py>`__,\nalthough the fidelity of the conversion depends entirely on LibreOffice.\n\nDocument transforms\n~~~~~~~~~~~~~~~~~~~\n\n**The API for document transforms should be considered unstable, and may\nchange between any versions. If you rely on this behaviour, you should\npin to a specific version of Mammoth, and test carefully before\nupdating.**\n\nMammoth allows a document to be transformed before it is converted. For\ninstance, suppose that document has not been semantically marked up, but\nyou know that any centre-aligned paragraph should be a heading. You can\nuse the ``transform_document`` argument to modify the document\nappropriately:\n\n.. code:: python\n\n import mammoth.transforms\n\n def transform_paragraph(element):\n if element.alignment == \"center\" and not element.style_id:\n return element.copy(style_id=\"Heading2\")\n else:\n return element\n\n transform_document = mammoth.transforms.paragraph(transform_paragraph)\n\n mammoth.convert_to_html(fileobj, transform_document=transform_document)\n\nOr if you want paragraphs that have been explicitly set to use monospace\nfonts to represent code:\n\n.. code:: python\n\n import mammoth.documents\n import mammoth.transforms\n\n _monospace_fonts = set([\"consolas\", \"courier\", \"courier new\"])\n\n def transform_paragraph(paragraph):\n runs = mammoth.transforms.get_descendants_of_type(paragraph, mammoth.documents.Run)\n if runs and all(run.font and run.font.lower() in _monospace_fonts for run in runs):\n return paragraph.copy(style_id=\"code\", style_name=\"Code\")\n else:\n return paragraph\n\n convert_to_html(\n fileobj,\n transform_document=mammoth.transforms.paragraph(transform_paragraph),\n style_map=\"p[style-name='Code'] => pre:separator('\\n')\",\n )\n\n``mammoth.transforms.paragraph(transform_paragraph)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nReturns a function that can be used as the ``transform_document``\nargument. This will apply the function ``transform_paragraph`` to each\nparagraph element. ``transform_paragraph`` should return the new\nparagraph.\n\n``mammoth.transforms.run(transform_run)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nReturns a function that can be used as the ``transform_document``\nargument. This will apply the function ``transform_run`` to each run\nelement. ``transform_run`` should return the new run.\n\n``mammoth.transforms.get_descendants(element)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nGets all descendants of an element.\n\n``mammoth.transforms.get_descendants_of_type(element, type)``\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nGets all descendants of a particular type of an element. For instance,\nto get all runs within an element ``paragraph``:\n\n.. code:: python\n\n import mammoth.documents\n import mammoth.transforms\n\n runs = mammoth.transforms.get_descendants_of_type(paragraph, documents.Run);\n\nWriting style maps\n------------------\n\nA style map is made up of a number of style mappings separated by new\nlines. Blank lines and lines starting with ``#`` are ignored.\n\nA style mapping has two parts:\n\n- On the left, before the arrow, is the document element matcher.\n- On the right, after the arrow, is the HTML path.\n\nWhen converting each paragraph, Mammoth finds the first style mapping\nwhere the document element matcher matches the current paragraph.\nMammoth then ensures the HTML path is satisfied.\n\nFreshness\n~~~~~~~~~\n\nWhen writing style mappings, it\u2019s helpful to understand Mammoth\u2019s notion\nof freshness. When generating, Mammoth will only close an HTML element\nwhen necessary. Otherwise, elements are reused.\n\nFor instance, suppose one of the specified style mappings is\n``p[style-name='Heading 1'] => h1``. If Mammoth encounters a .docx\nparagraph with the style name ``Heading 1``, the .docx paragraph is\nconverted to a ``h1`` element with the same text. If the next .docx\nparagraph also has the style name ``Heading 1``, then the text of that\nparagraph will be appended to the *existing* ``h1`` element, rather than\ncreating a new ``h1`` element.\n\nIn most cases, you\u2019ll probably want to generate a new ``h1`` element\ninstead. You can specify this by using the ``:fresh`` modifier:\n\n``p[style-name='Heading 1'] => h1:fresh``\n\nThe two consecutive ``Heading 1`` .docx paragraphs will then be\nconverted to two separate ``h1`` elements.\n\nReusing elements is useful in generating more complicated HTML\nstructures. For instance, suppose your .docx contains asides. Each aside\nmight have a heading and some body text, which should be contained\nwithin a single ``div.aside`` element. In this case, style mappings\nsimilar to ``p[style-name='Aside Heading'] => div.aside > h2:fresh`` and\n``p[style-name='Aside Text'] => div.aside > p:fresh`` might be helpful.\n\nDocument element matchers\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nParagraphs, runs and tables\n^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nMatch any paragraph:\n\n::\n\n p\n\nMatch any run:\n\n::\n\n r\n\nMatch any table:\n\n::\n\n table\n\nTo match a paragraph, run or table with a specific style, you can\nreference the style by name. This is the style name that is displayed in\nMicrosoft Word or LibreOffice. For instance, to match a paragraph with\nthe style name ``Heading 1``:\n\n::\n\n p[style-name='Heading 1']\n\nYou can also match a style name by prefix. For instance, to match a\nparagraph where the style name starts with ``Heading``:\n\n::\n\n p[style-name^='Heading']\n\nStyles can also be referenced by style ID. This is the ID used\ninternally in the .docx file. To match a paragraph or run with a\nspecific style ID, append a dot followed by the style ID. For instance,\nto match a paragraph with the style ID ``Heading1``:\n\n::\n\n p.Heading1\n\n.. _bold-1:\n\nBold\n^^^^\n\nMatch explicitly bold text:\n\n::\n\n b\n\nNote that this matches text that has had bold explicitly applied to it.\nIt will not match any text that is bold because of its paragraph or run\nstyle.\n\n.. _italic-1:\n\nItalic\n^^^^^^\n\nMatch explicitly italic text:\n\n::\n\n i\n\nNote that this matches text that has had italic explicitly applied to\nit. It will not match any text that is italic because of its paragraph\nor run style.\n\n.. _underline-1:\n\nUnderline\n^^^^^^^^^\n\nMatch explicitly underlined text:\n\n::\n\n u\n\nNote that this matches text that has had underline explicitly applied to\nit. It will not match any text that is underlined because of its\nparagraph or run style.\n\nStrikethough\n^^^^^^^^^^^^\n\nMatch explicitly struckthrough text:\n\n::\n\n strike\n\nNote that this matches text that has had strikethrough explicitly\napplied to it. It will not match any text that is struckthrough because\nof its paragraph or run style.\n\nAll caps\n^^^^^^^^\n\nMatch explicitly all caps text:\n\n::\n\n all-caps\n\nNote that this matches text that has had all caps explicitly applied to\nit. It will not match any text that is all caps because of its paragraph\nor run style.\n\nSmall caps\n^^^^^^^^^^\n\nMatch explicitly small caps text:\n\n::\n\n small-caps\n\nNote that this matches text that has had small caps explicitly applied\nto it. It will not match any text that is small caps because of its\nparagraph or run style.\n\nHighlight\n^^^^^^^^^\n\nMatch explicitly highlighted text:\n\n::\n\n highlight\n\nNote that this matches text that has had a highlight explicitly applied\nto it. It will not match any text that is highlighted because of its\nparagraph or run style.\n\nIt\u2019s also possible to match specific colours. For instance, to match\nyellow highlights:\n\n::\n\n highlight[color='yellow']\n\nThe set of colours typically used are:\n\n- ``black``\n- ``blue``\n- ``cyan``\n- ``green``\n- ``magenta``\n- ``red``\n- ``yellow``\n- ``white``\n- ``darkBlue``\n- ``darkCyan``\n- ``darkGreen``\n- ``darkMagenta``\n- ``darkRed``\n- ``darkYellow``\n- ``darkGray``\n- ``lightGray``\n\nIgnoring document elements\n^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nUse ``!`` to ignore a document element. For instance, to ignore any\nparagraph with the style ``Comment``:\n\n::\n\n p[style-name='Comment'] => !\n\nHTML paths\n~~~~~~~~~~\n\nSingle elements\n^^^^^^^^^^^^^^^\n\nThe simplest HTML path is to specify a single element. For instance, to\nspecify an ``h1`` element:\n\n::\n\n h1\n\nTo give an element a CSS class, append a dot followed by the name of the\nclass:\n\n::\n\n h1.section-title\n\nTo add an attribute, use square brackets similarly to a CSS attribute\nselector:\n\n::\n\n p[lang='fr']\n\nTo require that an element is fresh, use ``:fresh``:\n\n::\n\n h1:fresh\n\nModifiers must be used in the correct order:\n\n::\n\n h1.section-title:fresh\n\nSeparators\n^^^^^^^^^^\n\nTo specify a separator to place between the contents of paragraphs that\nare collapsed together, use ``:separator('SEPARATOR STRING')``.\n\nFor instance, suppose a document contains a block of code where each\nline of code is a paragraph with the style ``Code Block``. We can write\na style mapping to map such paragraphs to ``<pre>`` elements:\n\n::\n\n p[style-name='Code Block'] => pre\n\nSince ``pre`` isn\u2019t marked as ``:fresh``, consecutive ``pre`` elements\nwill be collapsed together. However, this results in the code all being\non one line. We can use ``:separator`` to insert a newline between each\nline of code:\n\n::\n\n p[style-name='Code Block'] => pre:separator('\\n')\n\nNested elements\n^^^^^^^^^^^^^^^\n\nUse ``>`` to specify nested elements. For instance, to specify ``h2``\nwithin ``div.aside``:\n\n::\n\n div.aside > h2\n\nYou can nest elements to any depth.\n\nDonations\n---------\n\nIf you\u2019d like to say thanks, feel free to `make a donation through\nKo-fi <https://ko-fi.com/S6S01MG20>`__.\n\nIf you use Mammoth as part of your business, please consider supporting\nthe ongoing maintenance of Mammoth by `making a weekly donation through\nLiberapay <https://liberapay.com/mwilliamson/donate>`__.\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "Convert Word documents from docx to simple and clean HTML and Markdown",
"version": "1.8.0",
"project_urls": {
"Homepage": "https://github.com/mwilliamson/python-mammoth"
},
"split_keywords": [
"docx",
"word",
"office",
"clean",
"html",
"markdown",
"md"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b91979f55df27d0ac645588bb556aedcabc2ffa946a562d3a772b17dbeea8254",
"md5": "652a0b5b3a0c4b68290be275ddc68e91",
"sha256": "b2abf2340809b13a903c8b65a27846466290b869f0dd56e4a1e3072c4be1ea86"
},
"downloads": -1,
"filename": "mammoth-1.8.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "652a0b5b3a0c4b68290be275ddc68e91",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 52313,
"upload_time": "2024-06-16T17:06:52",
"upload_time_iso_8601": "2024-06-16T17:06:52.766306Z",
"url": "https://files.pythonhosted.org/packages/b9/19/79f55df27d0ac645588bb556aedcabc2ffa946a562d3a772b17dbeea8254/mammoth-1.8.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0b0354ad55930465d571b4d74cfca4446c8353bf3410d2c5dc5c52a18dc6d039",
"md5": "2478fe550456ac310c5a79aa1c31b542",
"sha256": "7e8aa7db53f4aa7e9620b22bf8b716f1a16c84e969de1a0b1f920c756184e3d8"
},
"downloads": -1,
"filename": "mammoth-1.8.0.tar.gz",
"has_sig": false,
"md5_digest": "2478fe550456ac310c5a79aa1c31b542",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 50336,
"upload_time": "2024-06-16T17:06:55",
"upload_time_iso_8601": "2024-06-16T17:06:55.657084Z",
"url": "https://files.pythonhosted.org/packages/0b/03/54ad55930465d571b4d74cfca4446c8353bf3410d2c5dc5c52a18dc6d039/mammoth-1.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-16 17:06:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mwilliamson",
"github_project": "python-mammoth",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "mammoth"
}
JSON
