Aspose.Words for Python via .NET 22.3 Release Notes

Major Features

There are 355 improvements and fixes in this release. The most notable are:

• Added saving to PDF 2.0 and several other improvements in PDF output.
• Improved DML chart axis scaling algorithm.
• Improved table comparing algorithm.
• Provided comments syntax in LINQ Reporting.
• AZW3 format (KF8 is another name of the format) is now supported for loading.
• Added an ability to get custom field data which is associated with the field.
• Provided an ability to convert Shapes to SVG images upon export to HTML, MHTML or EPUB.
• Improved rendering of operators in MathML formulas.
• Introduced a new option to control conflicting styles behavior upon import.
• Provided dynamic text color setting using LINQ Reporting Engine.
• Introduced an ability to get OOXML of content control.
• Implemented loading previously saved font search cache to speed up the font cache initialization process upon rendering.
• Added recognition of non-standard footnotes in PDF documents during the import workflow.
• Implemented support for ‘Allow Latin text to wrap in the middle of a word’ feature.

Full List of Issues Covering all Changes in this Release (Reported by .NET Users)

Full List of Issues Covering all Changes in this Release (Reported by Java Users)

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 22.3. It includes not only new and obsoleted public methods, but also a description of any changes in the behavior behind the scenes in Aspose.Words which may affect existing code. Any behavior introduced that could be seen as regression and modifies the existing behavior is especially important and is documented here.

Added saving to PDF 2.0 and several other improvements in PDF output

Related issue: WORDSNET-23250

1. New value PDF20 added to PdfCompliance enum

2. Improvements in PDF digital signatures Changed PDF digital signature type from “adbe.pcks7.sha1” to “adbe.pcks7.detached” to fit all supported PDF versions. Added PdfDigitalSignatureHashAlgorithm.RIPE_MD160 value. PdfDigitalSignatureHashAlgorithm.SHA1 and PdfDigitalSignatureHashAlgorithm.MD5 values are marked as obsolete. Default value for PdfDigitalSignatureDetails.hash_algorithm changed from PdfDigitalSignatureHashAlgorithm.SHA512 to PdfDigitalSignatureHashAlgorithm.SHA256. SHA256 is most popular hashing algorithm, it is strong enough and it is used by default by Adobe Acrobat when signing the document.

3. Improvements in PDF encryption Removed PdfEncryptionAlgorithm enum and encryption_algorithm parameter from PdfEncryptionDetails constructor. This is a breaking change. Now PDF 1.7 output is encrypted with AES-128 encryption algorithm and PDF 2.0 output with AES-256 algorithm.

4. Several options (use_core_fonts, custom_properties_export in PdfSaveOptions cannot be used when saving PDF 2.0

5. Removed obsolete PdfCompliance.PDF15 enum value

Added FieldStart.field_data property

Related issue: WORDSNET-23198

The following public property is added to FieldStart class:

@property
def field_data(self) -> bytes:
    """Gets custom field data which is associated with the field."""
    ...

Use Case:

doc = aw.Document(filename)
field = doc.range.fields[0]
print(len(field.start.field_data))

Added HtmlSaveOptions.save_shapes_as_svg public property

Related issue: WORDSNET-23235

This option controls whether Shape nodes are converted to SVG images when saving to HTML, MHTML or EPUB. Default value is False.

If this option is set to True, Shape nodes are exported as <svg> elements. Otherwise, they are rendered to bitmaps and are exported as <img> elements.

Note that this options also affects text boxes, because they are represented by Shape nodes. As a result, if this option is set to True, it overrides the export_text_box_as_svg property value and causes text boxes to be converted to SVG.

Use Case:

doc = aw.Document(filename)
save_options = aw.saving.HtmlSaveOptions()
save_options.export_shapes_as_svg = True
doc.save(output_filename, save_options)

AZW3 format is now supported for loading

Related issue: WORDSNET-22411

Aspose.Words can now load AZW3 documents (KF8 is another name of the format). Usually, documents in the AZW3 format have the “.azw3” or “.mobi” extension. However, a “.mobi” document may be in the older MOBI format, and some “.mobi” documents contain two versions of content - MOBI and AZW3 - for backward compatibility.

The following table explains what reader Aspose.Words uses to load MOBI and AZW3 documents in different cases:

Currently, Aspose.Words always loads all topics from an AZW3 document in the order in which they appear in the table of contents.

The following publicly visible enum values were added:

• LoadFormat.AZW3

The FileFormatUtil class can now be used to determine if a file is an AZW3 document. For example, the following call

info = aw.FileFormatUtil.detect_file_format("book.azw3");

will return an info instance with the FileFormatInfo.load_format property set to LoadFormat.AZW3.

Currently, no load options have effect when loading AZW3 documents. LoadOptions.resource_loading_callback is not invoked when loading AZW3 documents, because Aspose.Words expects all referenced resource files to be stored locally in the AZW3 document. Like in the Kindle reader, references to external resource files are ignored.

As a result, the only use cases for loading AZW3 documents that is currently available is the one illustrated below:

doc = aw.Document("book.azw3")

Breaking change – explicit Table.auto_fit() call may be required to make table structure match the specified cell widths in a builder scenario

A major update that handles tables with incorrect or missing column width data in the source document is released.

Cell/column width data and the number of columns spanned by a cell are re-calculated from table and cell properties. Column width data stored in the document are replaced by re-calculated values.

The algorithm imitates MS Word logic that does not use cell widths. (In fact, cell width is not even stored in .DOCX format used by MS Word).

The new logic may change the output for some document builder scenarios. In the following example the number of columns spanned by the cell in row 2 is no longer calculated automatically from the specified cell widths:

doc = aw.Document()
builder = aw.DocumentBuilder(doc)

# First row
builder.start_table()

cell1 = builder.insert_cell()
cell1.cell_format.width = 100
builder.write("Text in cell 1.")

cell2 = builder.insert_cell()
cell2.cell_format.width = 100
builder.write("Text in cell 2.")

# End of first row
builder.end_row()

# Second row
cell3 = builder.insert_cell()
cell3.cell_format.width = 200
builder.write("Row 2 cell spans 2 columns.")

# End of second row
builder.end_row()
builder.end_table()

doc.update_page_layout()
doc.save("merged_cell.docx")

The behavior was changed because cell width data proved to be unreliable in a number of generated documents.

In order to preserve the specified cell widths in the above scenario and calculate the number of columns spanned by a cell from cell width, Aspose.Words should be explicitly instructed by calling Table.auto_fit() method:

...
table = builder.end_table()

# Re-calculate table structure from the specified cell widths.
table.auto_fit(aw.tables.AutoFitBehavior.FIXED_COLUMN_WIDTHS)
doc.update_page_layout()
doc.save("merged_cell.docx")

This will also set table layout to fixed, which is better suited for preserving cell widths regardless of contents.

Removed obsolete property FieldXE.has_page_range_bookmark_name

Removed obsolete property FieldXE.has_page_range_bookmark_name. Please, use the FieldXE.page_range_bookmark_name property instead.

Added new Chart.source_full_name property

Related issue: WORDSNET-22664

The following public property has been added to the Chart class. If a chart is linked to an external xls/xlsx document, the property returns its file name.

@property
def source_full_name(self) -> str:
    """Gets the path and name of an xls/xlsx file this chart is linked to."""
    ...

Use Case:

doc = aw.Document(filename)
shape = doc.get_child(aw.NodeType.SHAPE, 0, True).as_shape()
print(shape.chart.source_full_name)

Added new ImportFormatOptions.force_copy_styles property

Related issue: WORDSNET-19268.

ImportFormatOptions.force_copy_styles is a boolean value indicating either to copy conflicting styles in ImportFormatMode.KEEP_SOURCE_FORMATTING mode. The default value is False.

By default, if a matching style already exists in a destination document, the source style formatting is expanded into direct node attributes and the style of this node is reset to a default.

When this option is set to True, the source style will be forcibly copied into destination document with unique name and applied to the imported node.

Note, in this case it is not guaranteed that formatting of the imported node in destination document will be preserved.

Use Case: Explains how to force import styles in KEEP_SOURCE_FORMATTING mode.

# There are MyStyle1 and MyStyle2 in both source and destination document.
# Also there is style MyStyle3 that exists only in source document.
src_doc = aw.Document("Src.docx")
dst_doc = aw.Document("Dst.docx")

options = aw.ImportFormatOptions()
options.force_copy_styles = True
node_importer = aw.NodeImporter(src_doc, dst_doc, aw.ImportFormatMode.KEEP_SOURCE_FORMATTING, options)

print("Imported styles:")
paras = src_doc.first_section.body.paragraphs
for i in range(paras.count):
    imported_para = node_importer.import_node(paras[i], True).as_paragraph()
    print(imported_para.paragraph_format.style_name)

# The code produces the following output:
# Imported styles:
# MyStyle1_0
# MyStyle2_0
# MyStyle3

Added saving to PDFUA-1

Related issue: WORDSNET-6614

New value PDF_UA1 added to PdfCompliance enum.

The primary purpose of PDF/UA is to define how to represent electronic documents in the PDF format in a manner that allows the file to be accessible.

Removed obsolete property LayoutOptions.show_comments

Removes obsolete property LayoutOptions.show_comments.

Use LayoutOptions.comment_display_mode property instead:

doc = aw.Document("in.docx")
doc.layout_options.comment_display_mode = aw.layout.CommentDisplayMode.SHOW_IN_BALLOONS
doc.save("out.pdf")

Added new feature to save and load font search cache

Related issue: WORDSNET-22278

Loading previously saved font search cache will speed up the font cache initialization process. It is especially useful when access to font sources is complicated (e.g. when fonts are loaded via network).

To provide this feature following methods and properties has been added:

class FontSettings:

    def save_search_cache(self, output_stream: io.BytesIO):
        """Saves the font search cache to the stream.

        :param output_stream: Output stream."""
        ...

    def set_fonts_sources(self, sources: List[aw.fonts.FontSourceBase], cache_input_stream: io.BytesIO):
        """Sets the sources where Aspose.Words looks for TrueType fonts and additionally loads previously saved
        font search cache.

        Loading previously saved font search cache will speed up the font cache initialization process. It is
        especially useful when access to font sources is complicated (e.g. when fonts are loaded via network).

        When saving and loading font search cache, fonts in the provided sources are identified via cache key.
        For the fonts in the SystemFontSource and FolderFontSource cache key is the path
        to the font file. For MemoryFontSource and StreamFontSource cache key is defined
        in the MemoryFontSource.cache_key and StreamFontSource.cache_key properties
        respectively. For the FileFontSource cache key is either FileFontSource.cache_key
        property or a file path if the FileFontSource.cache_key is None.

        It is highly recommended to provide the same font sources when loading cache as at the time the cache was saved.
        Any changes in the font sources (e.g. adding new fonts, moving font files or changing the cache key) may lead to the
        inaccurate font resolving by Aspose.Words.

        :param sources: An array of sources that contain TrueType fonts.
        :param cache_input_stream: Input stream with saved font search cache.
        """
        ...




class FileFontSource:

    def __init__(self, file_path: str, priority: int, cache_key: str):
        """Initializer.

        :param file_path: Path to font file.
        :param priority: Font source priority. See the FontSourceBase.priority property description for more information.
        :param cache_key: The key of this source in the cache. See cache_key property description for more information.
        """
        ...

    @property
    def cache_key(self) -> str:
        """The key of this source in the cache.

        This key is used to identify cache item when saving/loading font search cache with
        FontSettings.save_search_cache() and FontSettings.set_fonts_sources() methods.

        If key is not specified then file_path will be used as a key instead.
        """
        ...




class MemoryFontSource:

    def __init__(self, font_data: bytes, priority: int, cacheKey: str):
        """Initializer.

        :param font_data: Binary font data.
        :param priority: Font source priority. See the FontSourceBase.priority property description for more information.
        :param cache_key: The key of this source in the cache. See cache_key property description for more information.
        """
        ...

    @property
    def cache_key(self) -> str:
        """The key of this source in the cache."""

        This key is used to identify cache item when saving/loading font search cache with
        FontSettings.save_search_cache() and FontSettings.set_fonts_sources() methods.
        ...

Use Case:

# Prepare font sources and generate font search cache beforehand.
file_source = aw.fonts.FileFontSource(file_path, file_source_priority, file_source_key)
memory_source = aw.fonts.MemoryFontSource(font_data, memory_source_priority, memory_source_key)
settings = aw.fonts.FontSettings()
settings.set_fonts_sources([file_source, memory_source])
settings.save_search_cache(cache_output_stream)

# Set font sources and load search cache before processing documents. Note that sources should be the same as when saving font search cache.
file_source = aw.fonts.FileFontSource(file_path, file_source_priority, file_source_key)
memory_source = aw.fonts.MemoryFontSource(font_data, memory_source_priority, memory_source_key)
settings = aw.fonts.FontSettings()
settings.set_fonts_sources([file_source, memory_source], cache_input_stream)

Added new public method Fill.set_image

Related issue: WORDSNET-22811

Use Case: Explains how to work with Fill.set_image.

builder = aw.DocumentBuilder()

# Add new rectangle shape.
shape = builder.insert_shape(aw.drawing.ShapeType.RECTANGLE, 80, 80)
# Apply one single image to the shape.
shape.fill.set_image("ShapeBackground.jpg")

builder.document.save("SingleImageDocument.docx")

Added word_open_xml property for content control nodes

Related issue: WORDSNET-22409

The following member has been added to the StructuredDocumentTag and StructuredDocumentTagRangeStart nodes:

@property
def word_open_xml(self) -> str:
    """Gets a string that represents the XML contained within the node in the SaveFormat.FLAT_OPC format."""
    ...

Use Case:

doc = aw.Document("Test.docx")
sdt = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
fopc_content = sdt.word_open_xml