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

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

Что делаем

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

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

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

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

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

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

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

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

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

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

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

Чек-лист:

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

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

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

Для работы нам понадобятся два инструмента: библиотека 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? Зарабатывай на нём!

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

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