Делаем конвертер из Markdown в Word с сохранением форматирования

В прошлый раз мы написали конвертер на Python, который берёт текст из файла с расширением .txt и сохраняет в файл Word c расширением .docx. Сегодня сделаем кое-что посложнее: напишем конвертер для файлов разметки Markdown.

Что делаем

Наш предыдущий конвертер брал текстовый файл, считывал содержимое и сохранял в документ Word. В этот раз сделаем такое:

Для конвертации текста в Word мы использовали библиотеку python-docx. Сейчас она не подойдёт, потому что не понимает разметку Markdown.

В этот раз мы используем Pandoc — универсальный конвертер файлов, с которым можно работать из командной строки. Чтобы он был доступен в скрипте, мы подключим специальную библиотеку pypandoc. Такие библиотеки называют обёртками — в них как бы заворачивают другую программу, чтобы она была доступна для работы через код.

Пишем файл разметки

Для Markdown-файла мы используем несколько возможностей:

Так код будет выглядеть в файле input.md:

![Эта картинка лежит в той же папке, что и файл Markdown](image.png)

# Заголовок первого уровня

## Заголовок второго уровня

### Заголовок третьего уровня

Этот текст содержит **жирный текст**, _курсив_ и [ссылку](https://dev.thecode.media/txt-to-doc-script/).

Чек-лист:

- [x] Выполненный пункт
- [ ] Невыполненный пункт
- [ ] Невыполненный пункт

А так код будет отображаться в программе, которая понимает разметку Markdown:

Вам может быть интересно:

Как сделать игру на Python бесплатноДелаем тетрис на PythonСоздаём на Python скрипт, который делает из простого текстового файла .txt вордовский файл .docxПишем на Python тесты для проверки знанийПрокачиваем учебные тесты на Python: добавляем чтение из документаДобавляем графический интерфейс программе для учебных тестов

Устанавливаем библиотеки

Для работы нам понадобятся два инструмента: библиотека pypandoc и сам Pandoc. Библиотека будет отправлять наш файл на сервер Pandoc и принимать готовый документ с расширением .docx.

Для этого нужно выполнить две команды:

pip install pandoc
pip install pypandoc

Это можно сделать как в командной строке…

…так и в терминале, если вы работаете в IDE, например PyCharm или Visual Studio Code:

Пишем функцию-конвертер

Импортируем в наш скрипт модуль convert_file из библиотеки pypandoc для конвертации файлов:

from pypandoc import convert_file

После этого весь процесс будет происходить в одной строке:

convert_file(‘input.md’, ‘docx’, outputfile=’output.docx’)

Файл input.md должен лежать в той же папке, что и наш скрипт. Для итогового вордовского файла можно брать любое название.

Теперь оформим красиво. Положим код в функцию, чтобы давать ей файлы для конвертации в отдельных переменных, а после выведем сообщение о проделанной работе:

# объявляем функцию
def markdown_to_docx(md_file, docx_file):
  # запускаем процесс конвертации
  convert_file(md_file, 'docx', outputfile=docx_file)
  # пишем, что всё прошло хорошо
  print("Конвертация успешно завершена.")

Теперь можно вызвать эту функцию в любом месте и задать путь до нужных файлов. У нас они лежат рядом со скриптом, поэтому пишем только их название:

markdown_to_docx(‘input.md’, ‘output.docx’)

Теперь сделаем так, чтобы программа могла сама справляться с некоторыми ошибками при запуске.

Добавляем проверку файла

В разработке нужно предусматривать обработку ввода — например, если пользователь вводит кириллические буквы вместо латинских или номер телефона, в котором меньше 10 цифр. Мы добавим две проверки: убедимся, что у файла правильный формат и что он вообще есть.

Чтобы итоговый скрипт мог проверять существование файла, нужен встроенный в Python модуль для работы с операционной системой os. Устанавливать его не надо, достаточно просто подключить:

import os

Для проверки формата нужно поработать со строками, потому что путь и название файла мы задаём строкой:

markdown_file = ‘input.md’

Теперь используем готовые методы для работы со строками:

Если какая-то из проверок нашла ошибку, останавливаем код. Самый простой способ прервать выполнение функции — использовать команду return.

# объявляем новую функцию
def markdown_to_docx(md_file, docx_file):
  
       # проверяем расширение файла: такая конструкция вернёт True или False
       if not md_file.lower().endswith('.md'):
           # останавливаем выполнение функции, если получили True
           return

       # проверяем, существует ли файл Markdown: такая конструкция вернёт True или False
       if not os.path.exists(md_file):
           # останавливаем выполнение функции, если получили True
           return

Этого достаточно для обработки ошибок, но мы сделаем ещё лучше: добавим обработку исключений.

Вызываем исключения через операторы Try и Except

В Python можно объявить, что мы пробуем выполнить какой-то код, а если что-то пойдёт не так — сказать коду, что делать дальше. Для этого используют конструкцию try-except.

После слова try мы выполняем код, который теоретически может вызвать ошибку, а в блоке except объясняем компьютеру, какие могут быть ошибки и что делать в этом случае. 

У нас будет три варианта исключений:

Для наших исключений мы подготовим сообщения и будем выводить для каждого своё:

# объявляем новую функцию
def markdown_to_docx(md_file, docx_file):
   # пробуем обработать файл
   try:
       # проверяем расширение файла: такая конструкция вернёт True или False
       if not md_file.lower().endswith('.md'):
           # вызываем исключение, если на предыдущей строке получили True
           raise ValueError("Указанный файл не является файлом Markdown.")

       # проверяем, существует ли файл Markdown: такая конструкция вернёт True или False
       if not os.path.exists(md_file):
           # вызываем исключение, если на предыдущей строке получили True
           raise FileNotFoundError("Указанный файл не найден.")

       # конвертируем файл Markdown в файл Word (docx)
       convert_file(md_file, 'docx', outputfile=docx_file)
       # выводим на экран отчёт, что всё прошло хорошо
       print("Конвертация успешно завершена.")

   # объявляем исключения для проверки файлов и передаём сообщения, которые прописали в блоках if
   except (ValueError, FileNotFoundError) as e:
       print(f"Ошибка: {e}")
   # если конвертация почему-то не удалась, 
   # объявляем исключение для всех остальных случаев и выводим на экран стандартный текст ошибки
   except Exception as e:
       print(f"Ошибка при конвертации: {e}")

Теперь остановимся подробнее на том, как именно происходит работа с ошибками.

Обработка исключений

Если сработала проверка в блоке if, мы не прерываем программу командой return, а обрабатываем нужный тип исключения. Само исключение вызывается командой raise, после которой в скобках нужно написать понятное для пользователя сообщение об ошибке. 

Главная обработка исключений происходит в блоках except. В каждом из них мы пишем тип исключения и соответствующее поведение: у нас это просто текст, который мы выводим на экран. Выглядит это так:

print(f”Ошибка: {e}”)

Строчная буква f перед кавычками означает, что внутри кавычек может быть переменная в фигурных скобках.

Конструкция as e сохраняет в переменную e сообщение из блока raise. Поэтому теперь, если произошло исключение ValueError, мы получим такое сообщение:

Ошибка: Указанный файл не является файлом Markdown.

Кладём скрипт в отдельный класс

Наш конвертер уже работает хорошо, но мы сделаем ещё лучше: сделаем так, чтобы можно было подключать его в другие скрипты командой import. Для этого используем классы, поэтому сразу создадим новый класс:

class Mark2doc:

Класс работает с помощью методов. В коде они выглядят точно так же, как функции, кроме того, что в скобках на первом месте обязательно должно стоять слово self. Чтобы превратить нашу функцию-конвертер в метод класса, нужно добавить к аргументам слово self.

Было:

def markdown_to_docx(md_file, docx_file):

Стало:

def markdown_to_docx(self, md_file, docx_file):

Теперь создаём новый объект на основе нашего класса, чтобы можно было использовать его как конвертер:

converter = Mark2doc()

Наконец, запускаем обработку с помощью этого объекта и переменных с именами файлов:

# записываем в переменную путь и название файла с разметкой Markdown
markdown_file = "input.md"
# записываем путь и названия для выходного документа Word
word_file = "output.docx"
# запускаем метод класса
converter.markdown_to_docx(markdown_file, word_file)

Осталось сделать так, чтобы всё это можно было импортировать в другой скрипт. Для этого:

Теперь можно создавать объект конвертера и конвертировать файлы. Вот как это выглядит целиком:

# импортируем конвертер из другого скрипта
from markdown2docx import Mark2doc

# создаём объект класса
converter = Mark2doc()
# записываем в переменную путь и название файла с разметкой Markdown
markdown_file = "input.md"
# записываем путь и названия для выходного документа Word
word_file = "output.docx"
# запускаем импортированный метод класса
converter.markdown_to_docx(markdown_file, word_file)

Что дальше

Наш конвертер не совершенен, потому что у всех библиотек для автоматической конвертации есть свои проблемы: в одной не сохраняется форматирование списков, в других — картинки, третьи просто зависают.

Можно сделать идеальный конвертер, который будет сохранять всю возможную разметку Markdown. Для этого нужно:

Наш скрипт тоже можно улучшить — например, вызывать его без необходимости создания объекта класса. Займёмся этим в следующий раз.

# импортируем стороннюю библиотеку для конвертации
from pypandoc import convert_file
# импортируем встроенный модуль для работы с операционной системой
import os


# объявляем новый класс
class Mark2doc:

   # пишем метод класса
   def markdown_to_docx(self, md_file, docx_file):
       # пробуем обработать файл
       try:
           # проверяем расширение файла: такая конструкция вернёт True или False
           if not md_file.lower().endswith('.md'):
               # вызываем исключение, если на предыдущей строке получили True
               raise ValueError("Указанный файл не является файлом Markdown.")

           # проверяем, существует ли файл Markdown: такая конструкция вернёт True или False
           if not os.path.exists(md_file):
               # вызываем исключение, если на предыдущей строке получили True
               raise FileNotFoundError("Указанный файл не найден.")

           # конвертируем файл Markdown в файл Word (docx)
           convert_file(md_file, 'docx', outputfile=docx_file)
           # выводим на экран отчёт, что всё прошло хорошо
           print("Конвертация успешно завершена.")

       # объявляем исключения для проверки файлов и передаём сообщения, которые прописали в блоках if
       except (ValueError, FileNotFoundError) as e:
           print(f"Ошибка: {e}")
       # если конвертация почему-то не удалась,
       # объявляем исключение для всех остальных случаев и выводим на экран системный текст ошибки
       except Exception as e:
           print(f"Ошибка при конвертации: {e}")

Любишь Python? Зарабатывай на нём!

Изучите самый модный язык программирования и станьте крутым бэкенд-разработчиком. Старт — бесплатно.

Попробовать бесплатно