【Python×Word】Apply and Define Style in python-docx

Japanese is here>>

This article describes the “python-docx” library, which manipulates MS-Office Word with Python.

So far, we have covered how to use python-docx to “Create Text” “Insert Image and Table” and “Manage page by section”.

Links to related articles can be found here.

In this third article in the series, we will explain how to “Apply style to document” and “Register user-defined style“.

The advantages of using the style include

• Able to create a consistent look and feel throughout the document
• Multiple sentences with the same style applied can be reflected at once.
• Confusing format setting can be registered once as the Style and reused in subsequent document (Less code and simpler)

… and others.

In the Word UI Menu, the following items allow you to set the “Style”.

The “python-docx” library provides functions related to these operations.

In the previous sections, we have used the arg:style and sytle property (attribute) to set the default style (built-in style) for each object (Paragraph, Ran, Table) that manages text and table.

The python-docx libraries provide the Style object that manages styles. In addition to applying the predefined styles in Word, users can also customize their own formatting and register it as ”style”.

This article will explain in more depth how to make use of this Style.

To summarize the main points, this article discusses the following

In the next section, we will explain in detail how to handle the Style object.

１. Overview of Style (Style Object)

Operations such as “Apply” or “Define” the Style are managed by the Style object.

In this section, we will first discuss the Style object type and its hierarchical structure, and then review how to apply Style.

1.1 Type of Style Object and Structure

All style format defined in the document are located in the Styles Object (suffixed with s) under the Document Object.

The Styles Object is iterable object (collection) whose elements are Style objects. (see Fig2)

The layers and elements of Word document, such as paragraph, word(character) and table, have their own styles and are clearly distinguished from each other.

The paragraph layer is the _ParagraphStyle object, the word (character) layer is the _CharacterStyle object and the table element is the _TableStyle object, each of which is separate objects.

All of these objects inherit from the BaseStyle object, but there is little need to be aware of this. (Fig3)

These are the style classifications by function.

In addition, Style objects can be broadly classified into two types: those that are pre-installed in Word and can be used immediately and those that are defined (custom) by the user.

The official website distinguishes between “Built-in styles” and “Custom styles” respectively, so this article is written accordingly.

Users can define their own styles (Custom styles) for paragraph, word(character), table. (Fig5)

「Built-in styles」 will be explained in detail in Section 2, and 「Custom styles」 will be explained in detail in Section 3.

1.2 Apply Style(Style Object)

Now that you understand the advantages and overview of styles, we will explain the procedure for actually applying styles. There are two ways to apply Style (Style Object).

【1. Specify “Argument:style” of the method】

The add_paragraph() and add_table() methods, which add objects such as paragraph, character and tables have an optional argument:style.

By specifying a style name (string) in the argument style, such as “‘Meiryo UI‘”, the style will be applied when the object is added.

In both cases, the argument style is optional, and if omitted, the Default style is applied.

【2. Set by style property of target Object】

You can also set it using the style property provided by the target object for paragraph, character and table. You can also get the name of the style currently being applied.

The format for setting the attribute is as follows, specifying either style name (string) such as “‘Meiryo UI'” or the Style object such as Styles collection[‘Meiryo UI’].

【SAMPLE (1)】

Let’s see an example of applying the style with sample code.

While adding paragraph and character (Run), you can see examples of applying style by specifying method argument or property. <List1>

※Note that notations such as [A1][A2]…[B3] in the code comments correspond to the results of the subsequent execution.

from docx import Document

doc = Document() # Get the Document Object


# （A）--------------------------------------------------------------------------------
# Apply style by argument style


# Paragraph: specified by style name(Title)・・・[A1]
pg1 = doc.add_paragraph('Set StyleName by method arg:style', style='Title') 
print(pg1.style.name) # >>Title

# Character: specified by style name (Subtitle Char)・・・[A2]
run1 = pg1.add_run('Set StyleName by add_run() argu:style', style='Subtitle Char')
print(run1.style.name) # >>Subtitle Char

#-----------------------------

# Paragraph: Specify by Style object・・・[A3]
pg2 = doc.add_paragraph('add_paragraph() Set the Object to arg:style.', style=doc.styles['Intense Quote'])
print(pg2.style.name) # >>Intense Quote


# （B）--------------------------------------------------------------------------------
# Set and get style by property

# Paragraph: Check default style・・・[B1]
pg3 = doc.add_paragraph('Paragraph: Setting Style by Property')
print(pg3.style.name) # >>Normal

# Paragraph: Set and get by style name(Caption)
pg3.style = 'Caption'
print(pg3.style.name) # >>Caption

#-----------------------------

# Character: Check default style・・・[B2]
run3 = pg3.add_run('Character: Setting Style by Property')
print(run3.style.name) # >>Default Paragraph Font

# Character: Set and get by style name(string)
run3.style = 'Intense Emphasis'
print(run3.style.name) # >>Intense Emphasis

#-----------------------------

# Paragraph: Set by Style object・・・[B3]
pg4 = doc.add_paragraph('Paragraph: setting style by property (object)')
pg4.style = doc.styles['Body Text']
print(pg4.style.name) # >>Body Text


doc.save('Apply_Style_List1.docx')

Now, let me explain some key points.

The style name is checked in the name attribute at each step, and it can be confirmed that the style name is reflected as set. ※The main methods and properties under the Style object are explained in detail in Section3.

The result of the <List1> run is as follows (Fig.6)

The style format is applied as specified.

Notations such as [A1][A2]…[B3] correspond to comments in the code.

This has been an overview of styles and how to apply them. Several examples of “built-in styles” have appeared so far, and the next section presents all of the built-in styles in Word.

2. Design Recipes for “Built-in Style”

This section introduces all of the Built-in Styles designs.

Please use it as a design recipe!

Word comes with about 200 pre-built styles that can be used as templates.

As in the previous section, you can apply a style by simply specifying a “style name” to method or property, because this predefined style is built into Word.

All style names are defined in the “WordprocessingML file” in a globally standardized notation in English. The python-docx library also conforms to this.

Therefore, it cannot be specified with a Japanese style name that appears in a WordUI that supports Japanese.

You can check the correspondence between the global unified notation and Japanese style names by downloading and executing the macro from the following site.

Reference：DocTools Word Macros&Tips

https://www.thedoctools.com/word-macros-tips/word-macros/create-style-name-list/

2.1 Paragraph Style (_ParagraphStyle Object)

Shows an example of applying all 36 types of built-in paragraph styles (_ParagraphStyle object ). If the style specification is omitted, the default ‘Normal‘ is applied. In addition, there are several systems of paragraph styles, such as “Heading-based,” “BodyText-based,” and “List-based.

Paragraph styles in default template

https://python-docx.readthedocs.io/en/latest/user/styles-understanding.html#paragraph-styles-in-default-template

2.2 Character Style(_CharacterStyle Object)

The built-in style of character(_CharacterStyle object) shows an example of applying all 27 types. If the style specification is omitted, the default ‘DefaultParagraphFont‘ is applied.

In addition, there are several systems of character styles, such as “Heading”, “BodyText” and “Emphasis”.

Character styles in default template

https://python-docx.readthedocs.io/en/latest/user/styles-understanding.html#character-styles-in-default-template

2.3 Table Style(_TableStyle Object)

There are many built-in Table style (_TableStyle object) 100 types in all. In the following, those of the same type with different color designations are omitted.

If the style specification is omitted, the default ‘Normal Table‘ is applied.

Table styles in default template

https://python-docx.readthedocs.io/en/latest/user/styles-understanding.html#table-Paragraph styles in default template

This is an introduction to Built-in Styles. Styles can be defined by the user as well as using the default templates. The next section describes these user-defined style (Custom-Style).

3. About User-Defined Style(Custom style)

In addition to choosing from the default Built-in Style, users can define and customize their own style. This section describes user-defined style( Custom style ).

This section also describes how to use the methods and properties necessary for defining and using Style objects.

3.1 Add and Define User-Defined Style

To define additional style, first get the Styles object, which is collection of Style objects, and then execute the add_styles() method under it as follows.

As explained in <Sec1.1>, the Style object are managed for each individual element of document (Paragraph, Character, Table).

Therefore, when adding the Style object with the add_style() method, it is necessary to clearly indicate in the arg:style_type which individual element the style corresponds to. Specify the Enum definition for the WD_STYLE_TYPE class. (Fig15)

Now, you have added the Style object, but at this stage it inherits the “Default” style. To customize it, the user should use the method and property (attribute) provided under the Style object.

First, here are the main methods/properties common to paragraph, character, and table Style object.

The base_style attribute can be used to specify template style. For example, specifying ‘Body Text 2’ will inherit the style formatting of ‘Body Text 2’ and override any settings the user wishes to change. If you do not specify otherwise, the Default style will be used as the template.

The font property can also be used to set typeface, bold, italic, underline, etc., in the same way as setting the font for paragraph and character.

Please refer to <Font Object>.

In addition to the above, the style formatting for paragraph (including paragraph in table cells) has the paragraph_format property. As with normal paragraph formatting, you can also set the formatting (alignment, indentation, spacing, etc.) via the ParagraphFormat object.

Please refer to <ParagraphFormat Object>.

In addition, the paragraph style has a useful attribute (next_paragraph_style property) that allows you to predefine the style to be applied to the next paragraph to be added after the current paragraph.

It is useful if you have a fixed rule, such as putting in a heading (‘Heading 1‘), followed by the body text (‘Body Text‘), and so on.

【SAMPLE (2)】

Here, let’s check the user-defined style with sample code.

A paragraph is added, and customized fonts and paragraph formatting are applied.

from docx import Document
from docx.enum.style import WD_STYLE_TYPE
from docx.shared import Pt, Inches, RGBColor    
from docx.enum.text import WD_ALIGN_PARAGRAPH


doc = Document()

styles = doc.styles # Get the Styles object (container)

# Add new Style object with the add_style()
style = styles.add_style('Original-Style', WD_STYLE_TYPE.PARAGRAPH)


# Check the existing style inherited by base_style property
# None" is displayed when newly added (i.e. Default style is applied)
print(style.base_style) # >>None

# Inherit existing styles with base_style property
style.base_style = styles['Title']
print(style.base_style) # >>_ParagraphStyle('Title') id: 2408904452360


#---------------------------------------------------------------------------------
# Font Definition

# Get Font object for font formatting
font = style.font

# Get and set font typeface with name property
print(font.name) # >>None
font.name = 'Meiryo UI'
print(font.name) # >>Meiryo UI

# Get and set character size with size property
print(font.size) # >>None
font.size = Pt(20)
print(font.size.pt) # >>10.0

# Get and set font color with the color property
print(font.color.rgb) # >>None
font.color.rgb = RGBColor(255,0,0)
print(font.color.rgb) # >>FF0000

#---------------------------------------------------------------------------------
# Define the format of paragraph

# Get the Paragraph_Formatting object to set paragraph formatting
paragraph_format = style.paragraph_format

# Get and set paragraph alignment with alignment property
print(paragraph_format.alignment) # >>None
paragraph_format.alignment = WD_ALIGN_PARAGRAPH.LEFT
print(paragraph_format.alignment) # >>LEFT(1)

# Get and set the left indent of paragraph
print(paragraph_format.left_indent) # >>None
paragraph_format.left_indent = Inches(0.50)
print(paragraph_format.left_indent.inches) # >>0.5

#---------------------------------------------------------------------------------

# Apply the newly added style to paragraph
doc.add_paragraph('Define and apply Custom-Style', style = style)

#print(len(styles)) # >>165
#style.delete()
#print(len(styles)) # >>164

#doc.add_paragraph('Define and apply Custom-Style', style = style)


doc.save('CustomStyle_List2.docx')


print(len(styles)) # >>165
# Delete additional style
style.delete()
print(len(styles)) # >>164

# AttributeError' occurs because I tried to apply a style that has been deleted 
#doc.add_paragraph('Define and apply Custom-Style', style = style) # 'NoneType' object has no attribute 'type'

Now, let me explain the key points.

Finally, after checking all existing style counts (165), delete the added style with the “delete()” method. We confirm that the number of styles has been decreased by one to (164).

Note that deleting an applied style will return it to the “Default” style.

The results of the run are as follows (Fig16)

Font and paragraph formatting can be customized based on the template (‘Title’).

The above explains how to add and create user-defined Style(Custom Style). The next section describes how to display styles in the Word UI Menu and register them in the Recommended List and Gallery.

3.2 Display in Word’s Menu

User-defined styles can be displayed in Word’s menu list and gallery. This makes customized styles available not only from the code, but also directly from Word’s UI (user interface).

You can view the style gallery and the list of recommended styles (Fig17).

There are five properties related to display settings.

For example, to display the “Style List” and “Recommended List”, the hidden property must be set to “Flase” and the quick_style property must be set to “True“.

Also, if the locked property is set to “True“, it cannot be applied, let alone displayed.

The other attribute combinations are shown in Fig18.

【SAMPLE (3)】

Let’s check it out here with sample code that displays user-defined style in list or recommended list.

from docx import Document
from docx.enum.style import WD_STYLE_TYPE

doc=Document()
# Get the Styles object
styles = doc.styles

# Add style ('Original-A')
style_A = styles.add_style('Original-A', WD_STYLE_TYPE.PARAGRAPH)

# Add style ('Original-B')
style_B = styles.add_style('Original-B', WD_STYLE_TYPE.PARAGRAPH)

#------------------------------------------------------------
# Check the default attribute values

print(style_A.hidden)      # >>False
print(style_A.locked)      # >>False
print(style_A.quick_style) # >>False
print(style_A.priority)    # >>None

#------------------------------------------------------------
# Set the style ('Original-A') attribute
# Displayed in Word UI "Style List" and "Recommended List"
# Highest display priority

style_A.hidden = False
style_A.quick_style = True
style_A.priority = 0

#------------------------------------------------------------
# Set the style ('Original-B') attribute
# Show only in "Word UI Recommended List"
# Display priority is third.

style_B.hidden = False
style_B.quick_style = False
style_B.priority = 2

doc.save('WordUI_CustumStyle_List3.docx')

Now, let me explain the key points.

In lines 9 and 12, add two new paragraphs style (“original-A”, “original-B”).

The execution result of is as follows. (Fig19)

In the style list on the right, only the style (“original-A”) is shown, and the two styles could be shown together in the recommended list on the left. The priority is also as specified.

The above is an explanation of how to reflect user-defined style in the Word UI. Finally, let us summarize the contents of this article.

4. Summary

How was it ?

In this article, we have explained the procedure for applying “Style” with the “python-docx” library and “User-defined Style(Custom Style)”.

The appearance of the document is important. Any good content may not reach readers if it is uneven. Let’s make good use of styles to create a unified look. We hope this article will be of some help to you.

Finally, let me summarize some key points.

This is the last article in this series, but we hope to introduce more applications using python-doc when we have a chance. Please look forward to it.

In addition to Word, libraries for operating “Excel” and “PowerPoint” are also explained in the series of articles. Let’s combine the three major Office software with Python to improve your work efficiency!

〇 Learn more about the Excel series here.

【Python×Excel】Basic Usage of "openpy-xl" (Install ~ Book, Sheet, Cells)

This is an illustrated explanation of openpyxl, a library for manipulating Excel in Python. From how to install the library to "creating a new Workbook/Worksheet" and "manipulating rows, columns, and cells" are condensed in this one article.

www.shibutan-bloomers.com

2022.03.05

〇 Learn more about the PowerPoint series here.

【Python×PowerPoint】Create Presentation File and Slides with python-pptx

This is an explanation of "python-ppptx" to manipulate PowerPoint with Python. In this article, basic operations (creating and saving files and using templates) will be explained.

www.shibutan-bloomers.com

2022.05.23

Thank you for reading to the end.

Japanese is here>>