python-docx¶
python-docx is a Python library for creating and updating Microsoft Word (.docx) files.
What it can do¶
Here’s an example of what python-docx can do:
from docx import Document from docx.shared import Inches document = Document() document.add_heading('Document Title', 0) p = document.add_paragraph('A plain paragraph having some ') p.add_run('bold').bold = True p.add_run(' and some ') p.add_run('italic.').italic = True document.add_heading('Heading, level 1', level=1) document.add_paragraph('Intense quote', style='Intense Quote') document.add_paragraph( 'first item in unordered list', style='List Bullet' ) document.add_paragraph( 'first item in ordered list', style='List Number' ) document.add_picture('monty-truth.png', width=Inches(1.25)) records = ( (3, '101', 'Spam'), (7, '422', 'Eggs'), (4, '631', 'Spam, spam, eggs, and spam') ) table = document.add_table(rows=1, cols=3) hdr_cells = table.rows[0].cells hdr_cells[0].text = 'Qty' hdr_cells[1].text = 'Id' hdr_cells[2].text = 'Desc' for qty, id, desc in records: row_cells = table.add_row().cells row_cells[0].text = str(qty) row_cells[1].text = id row_cells[2].text = desc document.add_page_break() document.save('demo.docx')
User Guide¶
API Documentation¶
- Document objects
- Document constructor
- Document objects
- CoreProperties objects
- Styles objects
- BaseStyle objects
- _CharacterStyle objects
- _ParagraphStyle objects
- _TableStyle objects
- _NumberingStyle objects
- LatentStyles objects
- _LatentStyle objects
- Paragraph objects
- ParagraphFormat objects
- Run objects
- Font objects
- TabStop objects
- TabStops objects
- Table objects
- _Cell objects
- _Row objects
- _Column objects
- _Rows objects
- _Columns objects
- Sections objects
- Section objects
- _Header and _Footer objects
- InlineShapes objects
- InlineShape objects
- ColorFormat objects
- Length objects
- RGBColor objects
- MSO_COLOR_TYPE
- MSO_THEME_COLOR_INDEX
- WD_PARAGRAPH_ALIGNMENT
- WD_BUILTIN_STYLE
- WD_CELL_VERTICAL_ALIGNMENT
- WD_COLOR_INDEX
- WD_LINE_SPACING
- WD_ORIENTATION
- WD_TABLE_ALIGNMENT
- WD_ROW_HEIGHT_RULE
- WD_SECTION_START
- WD_STYLE_TYPE
- WD_TAB_ALIGNMENT
- WD_TAB_LEADER
- WD_TABLE_DIRECTION
- WD_UNDERLINE
Автоматизированная сборка документа «Текст программы» по ЕСПД с помощью python-docx
Статья не имеет цели доказать важность и необходимость существования документа «Текст программы» и, тем более, необходимость его разработки в виде документа, которым кто-то когда-либо воспользуется. Цель статьи показать основы автоматизации обработки документов формата *.doc (*.docx) с использованием скриптов, написанных на языке Python.
Документ «Текст программы» (далее – Документ) входит в состав комплекта программных документов, перечень которых определен ГОСТ 19.101-77. ГОСТ, бесспорно, достаточно старый, однако его требования до сих пор востребованы при разработке программной продукции, соответственно требуется и разработка рассматриваемого Документа.
Содержание Документа определено ГОСТ 19.401-78 и должно включать в себя либо символическую запись на исходном языке, либо символическую запись на промежуточных языках, либо символическое представление машинных кодов (и т.п.).
Учитывая объемы современных веб приложений, разрабатываемых с использованием нескольких фреймворков, подготовить данный документ без использования автоматизации достаточно сложно.
Возможно два варианта создания документа:
- разработчики собирают содержание всех файлов проекта в один текстовый файл и передают техническому писателю на обработку;
- разработчики передают техническому писателю архив с файлами проекта, которые технический писатель должен обработать сам.
Первый вариант зависим от загруженности разработчиков. Чтобы сформировать текстовый файл с кодом программы, кто-то из команды разработчиков должен отвлечься, выгрузить код проекта из репозитория, написать программу, которая обработает выгруженный код и выдаст текстовый файл. Файл может быть размером как в пару мегабайт, так и в пару сотен мегабайт, его нужно вставить в Документ и как-то оформить. Вставка такого объема информации в файл Microsoft Word может занять как 30 минут, так и несколько часов. При этом, когда вставка будет завершена, Документ будет не структурирован и не читаем.
Второй вариант зависим от технических навыков исполнителя, но предпочтителен с точки зрения отсутствия необходимости привлечения людей, не имеющих отношения к разработке документации, вследствие чего будем автоматизировать именно этот вариант.
Автоматизация рассматриваемого Документа заключается в том, чтобы перенести текст кода программы в документ с заданным форматированием и структурой, чтобы в дальнейшем им можно было воспользоваться (маловероятный, но имеющий право на жизнь вариант использования).
Файл формата Microsoft Word (*.doc, *.docx) представляет собой набор данных в разметке xml. Файл имеет такие атрибуты, как параграф, рисунок, таблица, стиль. Для доступа к файлу и его атрибутам Microsoft в свое время была разработана технология OLE (Object Linking and Embedding). OLE позволяет передавать часть работы от одной программы редактирования к другой и возвращать результаты назад.
Библиотеки, осуществляющие взаимодействие с файлами офисного пакета Microsoft Office с использованием технологии OLE, есть практически для всех языков программирования. Для Python это библиотека python-docx. Описание библиотеки доступно по ссылке. Установить библиотеку можно командой:
Общий алгоритм разработки Документа представляет собой последовательность шагов:
- Подготовка шаблона документа;
- Подготовка скрипта сборки на Python;
- Обновление содержания и числа страниц;
- Сохранение в PDF.
Шаг 1
Конечный Документ проще сформировать на основе заранее подготовленного шаблона (например файл с именем template.docx). Форматирование и атрибуты (наименование программы, разработчик, децимальный номер, аннотация, текст основной части) шаблона Документа должны соответствовать ГОСТ 19.104-78.
Кроме требований ГОСТ шаблон Документа должен удовлетворять следующим требованиям (последовательность шагов описана для Microsoft Word 2019):
- иметь поле автоматического подсчета числа страниц в строке «Листов …»:
- иметь предопределенные стили для заголовков уровня 1, 2, 3, а также для кода:
- иметь поле автоматической сборки содержания:
- заголовки уровня 1, 2, 3 должны переноситься в содержание (Ссылки→Оглавление→Настраиваемое оглавление→Параметры→Выбрать созданные стили и присвоить им уровень);
- шаблон документа должен содержать фразу, на место которой будет вставлен код программы, выполненную в необходимом стиле, например «».
Шаг 2
Папка с проектом содержит значительное число файлов, часть которых не являются кодом. К ним относятся графические файлы интерфейса программы, файлы фреймворков, а также файлы программ, используемых в процессе разработки и оставляющих после себя следы (GIT, SVN, Docker). Все эти файлы необходимо отфильтровать.
Функция, которая будет отфильтровывать только файлы, удовлетворяющие условию, выглядит следующим образом:
def check(string): result = False if string[-3:] == '.js': result = True if string[-4:] == '.vue': result = True if string[-5:] == '.json': result = True if string[-4:] == '.css': result = True return resultЧтобы получить список файлов, удовлетворяющих условиям фильтра, сначала необходимо получить список всех каталогов в директории проекта:
folder = [] for i in os.walk(folder_name): folder.append(i)Из полученного списка каталогов читаем имена всех файлов во всех директориях проекта, и те, которые удовлетворяют условиям фильтра, складываем в отдельный список:
paths = [] for address, dirs, files in folder: for file in files: if check(file): paths.append(address+'\\'+file)Перед обработкой полученного списка файлов необходимо подготовить функцию, которая будет считывать содержимое файла в одну строку с сохранением разметки переносов строк. Это необходимо для дальнейшего ускорения вставки кода в Word.
def read_file(filename): f = codecs.open(filename, "r", "utf_8_sig" ) file = [] for line in f: file.append(line) file = ''.join(file) f.close() return fileИспользуя функцию read_file, считываем содержимое отфильтрованных файлов, попутно вставляя строки-разделители каталогов и файлов. Это понадобится для автоматического формирования содержания.
for i, path in enumerate(paths): if i == 0: catalog = path[folder_name_len:].split('\')[1] total_code_file.append('Каталог '+catalog+'\n') if path[folder_name_len:].split('\')[1] != catalog: catalog = path[folder_name_len:].split('\')[1] total_code_file.append('Каталог '+catalog+'\n') total_code_file.append('Файл '+path[folder_name_len:]+'\n') total_code_file.append(read_file(path)) total_code_file += '\n'Для переноса полученного кода программы подключаемся к документу, ищем контрольную фразу, заменяем ее на пустую строку и начинаем вставлять полученный код. Если код содержит слово «Каталог», форматируем его в стиле заголовка 2 уровня, если содержит слово «Файл» – в стиле заголовка 3 уровня, остальной текст форматируем в стиле кода программы:
doc = Document(sample_file) for p in doc.paragraphs: if '' in p.text: p.text = '' for line in total_code_file: if line.rstrip() > '' and line.split()[0] == 'Каталог': p.insert_paragraph_before(line.rstrip(), 'ЗАГ_2') elif line.rstrip() > '' and line.split()[0] == 'Файл': p.insert_paragraph_before(line.rstrip(), 'ЗАГ_3') else: p.insert_paragraph_before(line.rstrip(), 'КОД')По завершении сохраняем документ. Программная обработка документа завершена.
Шаг 3
После вставки текста программы в Документ необходимо открыть его в Microsoft Word, выделить все (Ctrl+A) и обновить автозаполняемые поля (F9). Данную операцию необходимо выполнить дважды, так как поля обновляются последовательно, и после формирования содержания итоговое число страниц изменится.
Данная операция занимает время, так как Word выполняет расчет страниц, последовательно обрабатывая документ до конца.
Шаг 4
После завершения обновления автозаполняемых полей необходимо сохранить Документ в формате *.pdf средствами Word. Это необходимо, чтобы зафиксировать форматирование и исключить дальнейшую работу с файлом в Word, так как Word будет выполнять пересчет числа страниц при каждом открытии файла или его изменении. С *.pdf такой проблемы не будет.
*.pdf имеет больший размер, но легко открывается любой подходящей программой. Ссылки в содержании после сохранения работают.
Полный код проекта доступен по ссылке.
Описанный вариант автоматизации не обрабатывает ошибки, связанные с разными кодировками файлов, и имеет варианты развития:
- обработка ошибок, связанных с кодировкой файлов;
- автоматическая выгрузка архива проекта;
- программный запуск пересчета полей автозаполнения.
