import docx doc = docx.Document(docx=None)
docx=None - может быть либо путем к файлу .docx (строка), либо к файловым объектом.Document.Класс docx.Document() представляет собой загруженный документ, переданный docx, где аргумент docx может быть либо путем к файлу .docx (строка), либо к файловым объектом.
Если docx=None или отсутствует, то загружается встроенный "шаблон" документа по умолчанию.
Document.Document.add_heading() добавляет абзац заголовка,Document.add_page_break() добавляет разрыв страницы,Document.add_paragraph() добавляет абзац,Document.add_picture() добавляет изображения в отдельный абзац,Document.add_section() добавляет новую секцию,Document.add_table() добавляет новую таблицу,Document.core_properties основные свойства документа,Document.inline_shapes список объектов изображений InlineShape,Document.paragraphs список объектов абзацев Paragraph,Document.save() сохраняет этот документ,Document.sections список объектов раздела Section,Document.settings объект Settings,Document.styles объект Styles,Document.tables список объектов таблиц Table,Document.add_heading(text='', level=1):Метод Document.add_heading() добавляет абзац с текстом text и отформатированный как заголовок. Абзац добавляется в конец документа. Метод возвращает ссылку на объект этого абзаца.
Стиль заголовка будет определяться уровнем level. Если уровень равен 0, то устанавливается стиль 'Title'. Если уровень 1 (или опущен), то используется заголовок 'Heading 1'. Эти стили определены в интерфейсе MS Word, и если стоит локализованная версия Word, то эти названия стилей будут переведены на родной язык, например "Заголовок 1".
Вызывает ошибку ValueError, если уровень выходит за пределы диапазона 0 - 9.
from docx import Document from docx.enum.text import WD_ALIGN_PARAGRAPH # создание пустого документа doc = Document() # без указания аргумента `level` # добавляется заголовок "Heading 1" head = doc.add_heading('Работа с файлами Microsoft Word на Python.') # выравнивание посередине head.alignment = WD_ALIGN_PARAGRAPH.CENTER doc.add_heading('Добавление заголовка второго уровня', level=2) doc.save('test.docx')
Можно не пользоваться этим методом, а добавлять заголовки вручную, используя метод Document.add_paragraph() с последующим форматированием.
from docx import Document from docx.shared import Pt doc = Document() # добавляем текст прогоном run = doc.add_paragraph().add_run('Заголовок, размером 24 pt.') # размер шрифта run.font.size = Pt(24) run.bold = True doc.save('test.docx')
Document.add_page_break():Метод Document.add_page_break() добавляет разрыв страницы и возвращает ссылку на объект Paragraph, содержащий только этот добавленный разрыв страницы.
По своей сути, метод Document.add_page_break() эквивалентен функции page_break(), которая определена в коде ниже:
from docx import Document def page_break(): """Метод Document.add_page_break()""" from docx.enum.text import WD_BREAK p = doc.add_paragraph() p.add_run().add_break(WD_BREAK.PAGE) doc.add_paragraph() return p doc = Document() page_break() doc.save('test.docx')
Document.add_paragraph(text='', style=None):Метод Document.add_paragraph() добавляет абзац в конец документа, заполненный текстом text и имеющий стиль абзаца style. Возвращает ссылку на объект добавленного абзаца Paragraph.
Аргумент text может содержать символы табуляции \t, которые преобразуются в соответствующую XML-форму. Текст также может содержать символы новой строки \n или возврата каретки \r, каждый из которых преобразуется в разрыв строки.
Аргумент style может принимать строку с Именем Стиля или объект стиля Style.
Важно!!! Значением аргумента style может быть Имя Стиля, которое встроено в интерфейс MS Word. Встроенные стили хранятся в файле WordprocessingML под своим английским именем, например 'Heading 1', и не зависят от локализации MS Word. Так как модуль python-docx работает с файлом WordprocessingML, то и поиск стиля должен использовать английское имя. Если файл WordprocessingML не найден (MS Word не установлен, например в OS Linux) то модуль python-docx работает со своей версией этого файла. Что бы создать сопоставление между именами стилей на местном языке и именами в английском стиле посетите эту ссылку.
Пользовательские стили, которые ВЫ сами настроили, не локализованы и доступны по имени, как они отображается в пользовательском интерфейсе MS Word.
Пример добавления абзаца с текстом и стилем:
from docx import Document from docx.shared import Pt doc = Document() # добавляем абзацы doc.add_paragraph('Абзацы в Word имеют основополагающее значение.') doc.add_paragraph('Стиль абзаца как цитата', style='Intense Quote') doc.add_paragraph('Обычный список.', style='List Bullet') doc.add_paragraph('Обычный список.', style='List Bullet') # можно применить стиль и так doc.add_paragraph('Нумерованный список.').style='List Number' # а можно применить стиль позже, к объекту абзаца `p` p = doc.add_paragraph('Нумерованный список.') p.style='List Number' doc.save('test.docx')
Document.add_picture(image_path_or_stream, width=None, height=None):Метод Document.add_picture() добавляет изображения в отдельный абзац в конце документа при этом возвращает ссылку на объект добавленного изображения Document.inline_shapes. Абзац будет содержать изображение в image_path_or_stream, масштабированное по ширине width и высоте height.
Если ни ширина, ни высота не указаны, то изображение отображается в исходном размере. Если указан только один размер, то он используется для вычисления коэффициента масштабирования, который затем применяется к неопределенному размеру, сохраняя соотношение сторон изображения.
Собственный размер изображения рассчитывается с использованием значения точек на дюйм dpi, указанного в файле изображения. Если dpi в изображении отсутствует, как это часто бывает, то по умолчанию будет использоваться 72 dpi.
По своей сути, метод Document.add_picture() эквивалентен функции add_img(), которая определена в коде ниже:
from docx import Document from docx.shared import Mm def add_img(image_path, width=None, height=None): """Метод Document.add_picture()""" img = doc.add_paragraph().add_run().add_picture(image_path, width, height) return img doc = Document() add_img('/path/to/image.jpg', width=Mm(25)) doc.save('test.docx')
Примеры добавления картинок в документ MS Word, а так же их извлечение, смотрите в материале "Добавление/извлечение изображений в документ .docx".
Document.add_section(start_type=2):Метод Document.add_section() добавляет новую секцию/раздел в конец документа. Необязательный аргумент start_type должен быть членом перечисления WD_SECTION_START и по умолчанию равен WD_SECTION.NEW_PAGE, если не указан.
Метод возвращает ссылку на объект добавленного раздела Section, который позволяет настраивать/изменять макет документа, включая колонтитулы.
Примеры использования метода Document.add_section() смотрите в материале "Изменение макета документа".
Document.add_table(rows, cols, style=None):Метод Document.add_table() добавляет таблицу, содержащую количество строк rows и столбцов col в строках и столбцах соответственно и стиль таблицы style. Возвращает объект Table.
Аргумент style может быть именем стиля абзаца. Если style=None, то таблица наследует стиль таблицы, определенный в документе по умолчанию.
Примеры использования метода Document.add_table() смотрите в материале "Добавление/изменение таблиц в документе .docx".
Document.core_properties:Свойство Document.core_properties представляет собой объект CoreProperties, обеспечивающий доступ для чтения и записи к так называемым основным свойствам документа (автор, категория, комментарии, когда и кем создан, ключевые слова, язык, тема, заголовок и версия).
Например:
from docx import Document doc = Document() prop = doc.core_properties prop.title = 'Пример' prop.author = 'docs-python.ru' prop.comments = 'Сгенерирован модулем python-docx' doc.save('test.docx')
Каждое свойство может быть одного из трех типов: str, datetime.datetime или int. Строковые свойства ограничены длиной до 255 символов и возвращают пустую строку '', если не заданы. Свойства даты назначаются и возвращаются как объекты datetime.datetime без часового пояса, то есть в формате UTC. За преобразование часового пояса отвечает клиент. Свойства даты возвращают значение None, если не задано.
Модуль python-docx не устанавливает автоматически какие-либо основные свойства документа. Если python-docx добавляет часть основных свойств, то они содержат значения по умолчанию для title, last_modified_by, revision. Клиентский код должен обновлять такие свойства, как revision и last_modified_by, если такое поведение желательно.
core_properties.author - тип str, автор документа;core_properties.category - тип str, классификация содержимого. Примеры значений могут включать: Резюме, Письмо, Финансовый прогноз, Предложение или Техническая презентация;core_properties.comments - тип str, комментарии к документу;core_properties.content_status - тип str, статус завершения документа, например 'черновик';core_properties.created - тип datetime.datetime, время первоначального создания документа;core_properties.identifier - тип str, однозначная ссылка на ресурс в заданном контексте, например ISBN;core_properties.keywords - тип str, описательные слова или короткие фразы, которые могут быть использованы в качестве поисковых запросов для этого документа;core_properties.language - тип str, язык на котором составлен документа;core_properties.last_modified_by - тип str, имя или другой идентификатор (например, адрес электронной почты) лица, последним изменившего документ;core_properties.last_printed - тип datetime.datetime, время последней печати документа;core_properties.modified - тип datetime.datetime, время последней модификации документа;core_properties.revision - тип int, номер редакции, увеличиваемый на 1 при каждом сохранении документа. Обратите внимание, что модуль python-docx автоматически не увеличивает номер редакции при сохранении документа;core_properties.subject - тип str, тема документа;core_properties.title - тип str, название документа;core_properties.version - тип str версии документа в произвольной форме;Document.inline_shapes:Свойство Document.inline_shapes представляет собой последовательность объектов InlineShape.
Объект InlineShape - это объект встроенной фигуры, содержащееся в текстовом слое документа и ведущий себя как глиф символа, переходящий как другой текст в абзаце. Другими словами, объекты InlineShape обрабатываются как символы и размещаются как символы в строке текста.
У встроенных фигур InlineShape нет имен. Встроенной фигурой может быть только изображение, объект OLE или элемент управления ActiveX.
Свойство Document.inline_shapes поддерживает функцию len(), итерацию и доступ к объектам по индексу.
.docx:inline_shape.height - для чтения/записи, высота изображения (поддерживает еще .cm и .mm, например: height.mm);inline_shape.width - для чтения/записи, высота изображения (поддерживает еще .cm и .mm, например: width.cm);inline_shape.type - только для чтения, тип связанной фигуры доступен как перечисление WD_INLINE_SHAPE.Тип связанной фигуры может быть:
WD_INLINE_SHAPE.LINKED_PICTURE;WD_INLINE_SHAPE.PICTURE;WD_INLINE_SHAPE.CHART;WD_INLINE_SHAPE.SMART_ART;WD_INLINE_SHAPE.NOT_IMPLEMENTED.Получить сведения о всех встроенных фигур в документе можно в цикле:
from docx import Document # открываем существующий документ doc = Document('/path/to/example.docx') for i, fig in enumerate(doc.inline_shapes, start=1): print(f'\nИзображение №{i}:') print(f'\t- Ширина и высота в мм: {fig.width.mm}, {fig.height.mm};') print(f'\t- Тип изображения: {fig.type}.')
Document.paragraphs:Атрибут Document.paragraphs представляет собой список объектов абзацев Paragraph, соответствующих абзацам в документе, в порядке их следования. Поддерживает функцию len(), итерацию и доступ к элементам по индексу.
В основном используется при чтении/изменении стиля абзацев существующего документа или извлечении текста.
Обратите внимание, что абзацы с пометками редакции, такими как <w:ins> или <w:del>, не отображаются в этом списке.
Пример:
>>> from docx import Document # открываем существующий документ >>> doc = Document('/path/to/example.docx') # количество абзацев в документе >>> len(doc.paragraphs) # текст первого абзаца в документе >>> doc.paragraphs[0].text # текст второго абзаца в документе >>> doc.paragraphs[1].text # текст первого прогона второго абзаца >>> doc.paragraphs[1].runs[0].text
Для того, чтобы узнать, какие еще свойства и методы есть у абзаца/параграфа необходимо обратиться к справочной информации по объекту Paragraph.
Document.save(path_or_stream):Метод Document.save() сохраняет этот документ в path_or_stream, который может быть либо путем файловой системы (строка), либо файловым объектом.
Document.sections:Свойство Document.sections представляет собой последовательность объектов раздела Section, соответствующих разделам в документе, в порядке их следования. Поддерживает функцию len(), итерацию и доступ к элементам по индексу. Используется при настройке макета вновь создаваемого и чтении/изменении существующего документа.
В несложных документах обычно присутствует только одна секция/раздел. В документах, где присутствуют разные ориентации страниц или применяются разные макеты страниц, для этих целей используются разные секции/разделы документа.
Пример:
>>> from docx import Document # открываем существующий документ >>> doc = Document('/path/to/example.docx') # количество разделов документа >>> len(doc.sections) # сведения первого раздела >>> doc.sections[0].orientation >>> doc.sections[0].page_width.cm >>> doc.sections[0].page_height.cm
Для того, чтобы узнать, какие еще параметры секции/раздела можно посмотреть/изменить/настроить необходимо обратиться к справочной информации по объекту Section.
Document.settings:Свойство Document.settings представляет собой объект Settings, предоставляющий доступ к настройкам этого документа на уровне XML.
Document.styles:Свойство Document.styles представляет собой объект Styles, обеспечивающий доступ к встроенным в пользовательский интерфейс MS Word стилям, которые в свою очередь можно перенастроить под себя. В модуле python-docx эти стили дублируются и постоянно обновляются.
Свойство поддерживает len(), итерацию и доступ в стиле словаря - по имени стиля, например Document.styles['Normal'].
Styles.Styles.add_style(name, style_type, builtin=False):Метод Styles.add_style возвращает недавно добавленный объект стиля для типа style_type который будет идентифицироваться по имени name. Тип стиля style_type задается перечислением WD_STYLE_TYPE.
Стиль, который будет встроен в пользовательский интерфейс MS Word, должен быть определен путем передачи True для необязательного аргумента builtin.
Как добавлять и использовать собственные объекты стилей, смотрите в материале "Работа с объектом Style модуля python-docx".
Styles.default(style_type):Метод Styles.add_style() возвращает стиль по умолчанию для style_type или None, если для этого типа не определено значение по умолчанию.
Styles.element:Свойство Styles.element представляет собой элемент lxml, проксируемый этим объектом.
Посмотреть все стили, встроенные в MS Word можно так:
>>> from docx import Document >>> doc = Document() # количество встроенных стилей >>> len(doc.styles) # 164 >>> for name in doc.styles: ... print(name) # _ParagraphStyle('Normal') id: 139972403301584 # _ParagraphStyle('Header') id: 139972421518768 ...
Изменить настройку стиля текста документа по умолчанию можно как-то так:
from docx import Document from docx.shared import Pt doc = Document() # получаем доступ к стилю 'Normal' # (это стиль текста по умолчанию) style = doc.styles['Normal'] # меняем название шрифта style.font.name = 'Arial' # меняем размер шрифта style.font.size = Pt(12) ...
Document.tables:Свойство Document.tables представляет собой список объектов таблиц Table, соответствующих таблицам в документе, в порядке следования их в документе. В основном используется при чтении/изменении стиля таблиц существующего документа или извлечении данных таблиц.
Обратите внимание, что в этом списке отображаются только таблицы, расположенные на верхнем уровне документа. Таблица, вложенная в ячейку таблицы, не отображается. Таблица с пометками ревизии, такими как <w:ins> или <w:del>, также не будет отображаться в списке.
Примеры добавления/изменения таблиц в документе DOCX смотрите в материале "Работа с таблицей при помощи модуля python-docx".