Набор скриптов на языке python для работы с многоуровневыми древовидными коллекциями электронных книг на базе известной сетевой библиотеки F и аналогов.
Поддерживаемые действия:
- Генерация дамп-файла коллекции книг из файловой системы.
- Воссоздание коллекции из дамп-файла и предварительно загруженного архива библиотеки.
- Создание из дамп-файла html-странички с раскрывающимися списками и прямыми ссылками на книги.
- Обновление описания книг из базы данных
- Допустим, есть коллекция электронных книг, разложенных по директориям произвольной вложенности.
- При этом все книги были скачаны с сетевой библиотеки (F, L, либо аналоги - но только одной: смешанные коллекции не поддерживаются) в формате fb2.zip и не переименовывались (либо переименовывались сохраняя соответствие шаблону; см. ниже).
- Для такой коллекции можно создать небольшой дамп-файл с полной необходимой информацией и восстановить коллекцию на другом компьютере из предварительно загруженного архива библиотеки.
- Сохранять дамп-файл как бэкап коллекции и восстанавливать в случае утери или сбоя.
- Делиться с другими.
- Тем, кто любит наводить порядок в своей локальной библиотеке.
- Тем, кто хочет пользоваться трудами предыдущей категории.
Преимущества:
- интуитивная понятность
- отсутствие необходимости в дополнительных файлах и программах
- лёгкость изменения коллекции в любом файловом менеджере
- лёгкость копирования на любое устройство или внешний носитель с сохранением структуры
- возможность использования в любых устройствах и программах с полноценным файловым менеджером.
- возможность использования дополнительных каталогизаторов поверх коллекции
Недостатки:
- необходимость универсальной и однозначной классификации; отсутствие возможности отнести одну книгу к нескольким категориям (без создания дубликата файла)
- не все устройства для чтения электронных книг имеют файловый менеджер
- не все программы и устройства поддерживают формат fb2.zip (решается конвертацией)
Все книги коллекции должны быть загружены с сетевой библиотеки в формате fb2.zip. Книги в других форматах не поддерживаются.
Работа скриптов основана на том, что названия файлов, скачанных с поддерживаемых сетевых библиотек соответствуют шаблону, содержащему уникальный номер этой книги: Avtor_nazvanie.12345.fb2.zip (плюс, возможно, хэш от описания). По этому номеру можно найти страницу книги на сайте (например, http://example.com/b/12345) и файл книги в архиве.
К скриптам прилагается тестовый дамп-файл с небольшим числом книг (library.dump). Рекомендуется перед полноценным использованием проверить работу скриптов на тестовой коллекции, чтобы убедиться, что всё настроено правильно.
Дамп-файл для основной коллекции (>35000 книг, >6800 директорий, >50Гб) находится в репозитории flibrary-main-collection.
Оба файла построены на базе библиотеки F.
Скрипты написаны на языке python 3 и используют библиотеки lxml и simplejson.
Основные скрипты дополнительно представлены в виде скомпилированных под Windows исполняемых файлов в разделе releases, которые не требуют дополнительной подготовки и могут быть запущены из проводника как обычные приложения.
При работе в другой ОС или при иной необходимости запускать непосредственно сами скрипты, python и библиотеки должны быть установлены пользователем.
Ссылки:
- pyhton 3 (в linux обычно установлен по умолчанию)
- lxml
- simplejson
Рекомендуется устанавливать библиотеки через менеджер pip. Скрипты проверялись на lxml версии 4.6.3 и simplejson версии 3.17.3.
Для запуска необходимы:
- скрипты (либо соответствующие исполняемые файлы)
- правильно заполненный файл конфигурационный файл (flibconfig.ini, см. ниже)
- сам дамп-файл (кроме того случая, когда он должен быть создан при помощи flibdump).
Проще всего всё положить в отдельную директорию, но при необходимости можно использовать абсолютные и относительные пути. Во время работы скрипты выводят информацию о прогрессе выполнения задачи. При наличии проблем, ошибки записываются в специальный файл.
Для полноценного использования скриптов может потребоваться доступ к заблокированным сайтам. Разные провайдеры используют разные методы блокировки, поэтому и способы обхода могут различаться, так что детальных инструкций в этом руководстве нет. Универсальные методы - использование VPN и TOR. Также, для заблокированных сайтов могут быть доступны зеркала. Неофициальными зеркалами можно пользоваться для загрузки книг, но авторизация через них не рекомендуется.
Если официальный адрес библиотеки не заблокирован провайдером, либо доступен через VPN для всей системы, то можно использовать его.
Иначе надо найти доступное зеркало. Список зеркал меняется со временем и может быть найден поиском в сети. Для использования зеркало должно поддерживать скачивание по прямым ссылкам вида [адрес_зеркала]/b/[id_книги]/fb2 (например, http://example.com/b/12345/fb2).
Скриптами можно пользоваться и без доступа к сайту или зеркалу, но нельзя будет автоматически загружать новые книги (отсутствующие в архивах).
Для воссоздания коллекции в файловой системе, необходимо предварительно скачать полный (fb2 или fb2+usr) архив библиотеки, который можно найти на некоторых популярных торрент-трекерах. Для загрузки torrent-файла обычно нужна регистрация, но для magnet-ссылки регистрация необязательна.
Раздачу архива бибилиотеки F можно найти, если на главной странице библиотеки найти ссылку "скачать библиотеку целиком", и проследовать по ней и далее.
Архив может занимает несколько сотен ГБ. Полная загрузка может занять до нескольких суток в зависимости от скорости интернет-соединения. Загруженный архив предаставляет собой директорию, в которой должно находиться большое количество zip-архивов и дополнительные файлы.
Конфигурационный файл содержит набор параметров, которые должны быть правильно заполнены перед использованием скриптов. Параметры, необходимые для каждого скрипта также указаны в соответствующих разделах.
Все скрипты могут принимать путь к конфигурационному файлу как (единственный) параметр командной строки. По умолчанию, в случае отсутствия параметра предполагается, что конфигурационный файл называется flibconfig.ini и лежит в текущей директории.
Параметры конфигурационного файла:
- FLIB_URL - адрес библиотеки либо доступного зеркала.
- ARCHIVE_PATH - путь к директории, в которой лежит предварительно загруженный архив библиотеки.
- DUMP_FILE_PATH - путь к дамп-файлу, либо существующему, либо ещё нет (для создания).
- DUMP_FROM_PATH - путь к директории с коллекцией книг для создания дамп-файла.
- EXTRACT_TO_PATH - путь к директории (при первом использовании желательно пустой, либо ещё не созданной) для воссоздания коллекции из дамп-файла и архива библиотеки.
- QUICK_DUMP и QUICK_EXTRACT - параметры, включающие "быстрый" режим чтения и записи библиотеки.
- TRANSLIT - параметр, включающий запись имени файлов транслитом. При выключенном параметре названия записываются кириллицей, но длинные имена файлов будут обрезаны для совместимости с файловой системой ext4.
- Группа параметров, начинающихся с MYSQL_ используется для обновления описания книг из базы данных.
Пути к директориям должны быть прописаны по правилам вашей операционной системы. Примеры заполненных файлов для Windows и Linux приведены в flibconfig.ini и flibconfig_linux.ini.
ВАЖНО: для коллекций с большим уровнем вложенности суммарная длина путей к файлам может превышать системное ограничение Windows в 260 символов. Поэтому настоятельно рекомендуется для Windows заполнять абсолютные пути с префиксом \\?\ который позволяет обойти это ограничение (см. документацию). В примере flibconfig.ini пути заполнены именно так. Также под Windows, некоторые сторонние программы могут некорректно работать с длинными путями. В Windows 10 можно вручную включить поддержку длинных путей без префикса (см. документацию).
- Скрипт использует параметры DUMP_FILE_PATH, DUMP_FROM_PATH, QUICK_DUMP и TRANSLIT, и создаёт в текущей директории дамп-файл коллекции книг.
- Книги в коллекции должны быть загружены из сетевой библиотеки в формате fb2.zip и не переименованы после загрузки (или переименованы с сохранением соответствия шаблону).
- Время работы пропорционально размеру коллекции. Для обновления дамп-файла при небольших изменениях коллекции можно включить "быстрый режим" ключом QUICK_DUMP, при этом будут обработаны только новые книги и удалены старые.
- В обычном режиме будет выведен список директорий в порядке прохода и добавленные файлы, в быстром - только список изменений.
- По окончании работы может быть создан файл flibdump_errors.log со списком ошибок. Основные типы ошибок:
-
- Пропущен файл - имя файла не соответствует шаблону для файлов, загруженных с библиотеки. Такой файл не будет добавлен в дамп-файл.
-
- Ошибка при чтении файла - при чтении файла возникла ошибка. Такой файл не будет добавлен в дамп-файл.
- Скрипт использует параметры DUMP_FILE_PATH, ARCHIVE_PATH, EXTRACT_TO_PATH, DUMP_FROM_PATH, QUICK_EXTRACT, TRANSLIT и FLIB_URL, и воссоздаёт коллекцию из дамп-файла и архива библиотеки.
- Все посторонние файлы из директории EXTRACT_TO_PATH будут удалены! При повторном запуске скрипта с тем же или обновлённым дамп-файлом будут распакованы тольно новые, изменённые или перемещённые файлы.
- Время работы пропорционально размеру коллекции. Для быстрого обновления коллекции можно использовать ключ QUICK_EXTRACT, при этом для уже имеющихся файлов будет проверено только совпадение имени.
- Сначала будет выведено число найденных архивов в директории ARCHIVE_PATH. Затем в обычном режиме будет выведен список директорий в порядке прохода и изменения для каждой, в быстром - только список изменений.
- В случае отстутствия некоторых книг в архиве (например, если они были добавлены после последнего обновления torrent-раздачи) будет предолжено попытаться загрузить их с сайта библиотеки или зеркала (параметр FLIB_URL).
-
- При несовпадении путей EXTRACT_TO_PATH и DUMP_FROM_PATH перед скачиванием будет произведён поиск отсутствующих книг в соответствующем месте в DUMP_FROM_PATH. Таким образом, можно создавать и обновлять копию коллекции без использования архивов.
-
- Для небольшой коллекции (несколько десятков книг) можно скачать все книги без предварительной загрузки архива. Для большой коллекции это займёт много времени и создаст слишком большую нагрузку на сервер. Поэтому скрипт загружает книги порциями по 25. После каждой порции необходимо вручную подтвердить дальнейшую загрузку.
-
- В случае ошибки загрузки из-за проблем сети или недоступности сайта библиотеки, можно перезапустить скрипт позже в режиме быстрого обновления. Тогда будут загружены только недостающие книги.
-
- Если не удаётся скачать недостающие файлы при помощи скрипта, можно скачать их вручную и положить в любое место внутри коллекции. При следующем запуске скрипта эти файлы будут найдены и переложены в нужное место.
- По окончании работы может быть создан файл flibextract_errors.log со списком ошибок. Основные типы ошибок:
-
- Контрольная сумма не совпадает - Контрольная сумма содержания книги не соответствует той, что была вычислена при создании дамп-файла. Либо у создателя дамп-файла книга была скачана с другой библиотеки, либо он использовал другую версию скрипта, либо файл книги содержит ошибки. Рекомендуется проверить, соответствует ли текст такой книги её описанию.
-
- Ошибка при загрузке - Книга не была найдена в архиве, и не была скачана по какой-то причине.
- Скрипт использует параметр DUMP_FILE_PATH и FLIB_URL и создаёт в текущей директории html-страничку (library.html) из дамп-файла.
- Время работы составляет несколько секунд.
- Html-страничка может быть открыта любым браузером и отображает коллекцию в виде разворачивающихся списков и ссылок на страницы книг на сайте библиотеки.
- Скрипт использует параметры DUMP_FILE_PATH, MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE и MYSQL_PORT и предназачен для обновления описания книг в дамп-файле. Для "обычных" пользователей необязателен. Для использования необходимо предварительно поднять локальный mysql-сервер, скачать и импортировать дампы базы данных. Поддерживается только формат БД библиотеки F.
- Модули не предназачены для запуска, но используются другими. Содержат общие определения и функции.
Дамп-файл представляет собой zip-архив, содержащий json-файл, в котором записана файловая структура и описание книг (название, авторы, жанры, серии, язык и год издания) для каждой книги. Также в архиве находится файл version, содержащий текущую версию формата.
Пользователи сетевых библиотек могут исправлять описание книг в библиотеке. В таком случае, файл, скачанный с сайта, получает исправленный заголовок (fb2 description), но в архиве остаётся исходный файл. Поэтому при создании дамп-файла описание каждой книги записывается, а при воссоздании коллекции перезаписывается в заголовок распакованного файла. Также, его можно обновить до актуального состояния при помощи скрипта libsqlupdate.
Директория supplementary содержит скрипты для установки зависимостей, получения и импорта sql-дампов, а также для компиляции под Windows в wine. Скрипты проверялись на Debian 10.
Конфигурационный файл и дамп-файл должны иметь кодировку UTF-8. В этой же кодировке записываются все распаковываемые книги.
Скрипты распространяются по лицензии Unlicense.
Как скрипты, так и дамп-файлы не содержат информации, защищённой авторским правом. Загрузка и хранение архива библиотеки и отдельных книг осуществляются пользователями на свой страх и риск.
Структурой коллекции можно пользоваться и не скачивая книги, например, для поиска книг по тематике с целью легального приобретения.
Автора можно найти под ником flibrarian на некоторых приватных почтовых сервисах и технических ресурсах.