Changelog

Introducción

Mi biblioteca digital ha crecido últimamente de manera rápida, conteniendo en este momento más de 600 libros. Me resultaba imposible llevar un registro de todos los libros que tengo.

Por eso decidí crear una herramienta sencilla para subir todos los libros (solo metadatos, no el libro en sí) a una base de datos en Notion. Gracias a eso, sería capaz de asignar estados, prioridades, etiquetas, filtrar por propiedad o autor y agregar comentarios a los libros.

La herramienta utiliza la API de Notion y tiene las siguientes características principales:

• Detecta todos los libros digitales de una ruta dada y todas las subcarpetas.
• Agrega, actualiza o elimina entradas en la base de datos de Notion para que coincidan con el estado de la carpeta local.
• Posibilidad de crear un archivo .paper para agregar libros no digitales que también se quieran rastrear.
• Extrae metadatos de archivos .pdf y .epub.

Instalación

Con Homebrew (Recomendado para MacOS)

brew install helguera/tap/library2notion

Con PIPX (Recomendado para Linux y Windows)

pipx install library2notion

Con PIP

pip install --user library2notion

Nota: Python 3.7 o posterior requerido.

Desde la fuente

Este proyecto utiliza poetry para la gestión de dependencias y empaquetado. Primero, tendremos que instalarlo. Consulta la documentación oficial para obtener instrucciones.

git clone https://github.com/helguera/library2notion.git
cd library2notion/
poetry install 
poetry run library2notion

Uso

$ library2notion --help
usage: library2notion [-h] -p PATH -t NOTIONTOKEN -d NOTIONDBID [-f FORMATS [FORMATS ...]] [--only_new | --only_updated | --only_deleted]

library2notion created by Javier Helguera (github.com/helguera) © 2023 MIT License

Opciones generales:
  -p, --Path PATH                    Ruta donde empezar a buscar libros. También revisará todas las subcarpetas.
  -t, --NotionToken NOTIONTOKEN      Token de Notion.
  -d, --NotionDbId  NOTIONDBURL      ID de la base de datos de Notion.
  -f, --Formats     FORMATS          Lista de formatos a tener en cuenta. En este momento, se admiten .PDF, .EPUB y .PAPER.
  --only_new,                        Solo verificar libros nuevos.
  --only_updated                     Solo verificar cambios en libros existentes (no incluye eliminaciones).
  --only_deleted                     Solo verificar libros eliminados.
  -h, --help                         Mostrar este mensaje de ayuda y salir.

Datos de entrada

-p, --Path

La ruta donde buscar archivos (y subcarpetas). Es altamente recomendable utilizar rutas relativas. Esto es realmente importante, ya que también se utilizará para generar las etiquetas de cada libro. (Consulta la sección "Metadatos" para obtener más información).

Por ejemplo, si tu biblioteca se ve así:

/home/your_user/Documents/books/Programming/Python
/home/your_user/Documents/books/Programming/C
/home/your_user/Documents/books/History/Spanish History

La forma ideal de proceder es, primero, moverse a la carpeta books, ya que es la común para todos los libros.

cd /home/your_user/Documents/books

Y desde aquí, ejecutar l2n con una ruta relativa:

library2notion -p "./"

⚠️ Importante: La manera en que se identifica de manera única un libro es mediante su ruta. Esto es crucial porque el libro ./books/Programming/Python/PythonCookbook se tratará como uno diferente de ./Programming/Python/PythonCookbook.

-t, --NotionToken

Es el token secreto de Notion cuando se crea una integración. Visita la documentación oficial para obtener más información. No olvides darle permisos a la página de tu integración.

También puedes echar un vistazo a esta publicación que he creado y que explica todo lo que necesitas saber para crear una integración de Notion y conectarla con tu aplicación.

-d, --NotionDbId

El ID de la base de datos de Notion donde se cargarán todas las informaciones. Esta base de datos debe existir previamente y las columnas que necesita tener son fijas y no se pueden cambiar. Estas son:

Para obtener el valor del ID de la base de datos, abre la base de datos como una página completa en Notion. Utiliza el menú Compartir para Copiar enlace. Ahora pega el enlace en tu editor de texto para examinarlo más de cerca. La URL tiene el siguiente formato:

https://www.notion.so/{nombre_del_espacio_de_trabajo}/{id_de_la_base_de_datos}?v={id_de_la_vista}

-f, --Formats

These are the formats that will be taken into account. At this moment, .epub, .pdf and .paper are supported and used by default.

library2notion -f EPUB PAPER  -> only look for .epub and .paper files
library2notion -f PDF         -> only look for .pdf files

-c, --Config

Un fichero config.json puede ser utilizado como parámetro de entrada. Dicho fichero contendrá todos las configuraciones necesarias para el funcionamiento. De esta manera, las futuras ejecuciones serán más simples. La herramienta preguntará si se quiere crear el fichero automáticamente en la primera ejecución.

{
    "notion_secret_token": "",
    "notion_db_id": "",
    "path": "",
    "ignore": []
}

-i, --Ignore

Permite ignorar directorios o subdirectorios que no se quieren analizar. Por ejemplo:

-i History "./Tech Books/Programming" 

La carpeta "History" será ignorada. Lo mismo para "Tech Books/Programming", pero no para el resto de libros en "Tech Books".

--only_new

Verifica solo los libros nuevos que se han agregado a la ruta desde la última ejecución. Omite aquellos que se han actualizado o eliminado.

--only_updated

Verifica solo los libros que se han actualizado desde la última ejecución. Omite los nuevos y los eliminados.

--only_deleted

Verifica solo los libros que se han eliminado desde la última ejecución. Omite los nuevos y los actualizados.

Metadatos

La herramienta extraerá los siguientes datos para cargar en Notion:

• Nombre del Archivo: es la ruta completa al archivo. Se utiliza como clave principal de la tabla en Notion, por lo que no puede duplicarse.
• Título: título del libro.
• Etiquetas: las categorías del libro. Se generan automáticamente a partir de la ruta. Por ejemplo, si la ruta es ./Libros de Tecnología/Programación/Python/milibro.pdf, las etiquetas serán Libros de Tecnología, Programación, Python.
• Autor: el autor o autores del libro.
• Editorial: la editorial del libro.
• Formatos: los formatos disponibles del libro. Un libro disponible en varios formatos solo aparecerá una vez en la base de datos.
• ISBN: el ISBN.

Libros no digitales (.paper)

Con la actualización 0.2.0, la herramienta admite libros no digitales. Solo tienes que crear un archivo .paper en una carpeta por cada libro no digital que desees agregar con el siguiente contenido:

{
    "Título": "",
    "Autor": "",
    "Editorial": "",
    "ISBN": ""
}

Ficheros de log

Se creará un archivo de registro después de cada ejecución en la carpeta ./library2notion-logs. Incluirá información sobre los libros creados, actualizados y eliminados.

Ejemplos

Supongamos que nuestra biblioteca local está ubicada en /home/user/Documents/mis-libros.

cd /home/user/Documents/mis-libros

Ejecución normal

La ejecución normal funcionará en cualquier escenario, pero tarda más en finalizar porque se deben verificar más archivos. Es por eso que existen las opciones --only_new, --only_updated y --only_deleted.

library2notion -p "./" -t TOKEN_DE_NOTION -d ID_DE_LA_BASE_DE_DATOS_DE_NOTION

Algunos libros se han agregado a la carpeta local

library2notion -p "./" -t TOKEN_DE_NOTION -d ID_DE_LA_BASE_DE_DATOS_DE_NOTION --only_new

Se ha agregado una nueva extensión a un libro existente en la carpeta local

library2notion -p "./" -t TOKEN_DE_NOTION -d ID_DE_LA_BASE_DE_DATOS_DE_NOTION --only_update

Algunos libros se han eliminado de la carpeta local

library2notion -p "./" -t TOKEN_DE_NOTION -d ID_DE_LA_BASE_DE_DATOS_DE_NOTION --only_deleted

Tomar en cuenta solo archivos PDF

library2notion -p "./" -t TOKEN_DE_NOTION -d ID_DE_LA_BASE_DE_DATOS_DE_NOTION -f PDF

Repositorio en GitHub

Puedes encontrar el repositorio completo de la herramienta en mi GitHub.

Ayuda

Si necesitas ayuda con cómo usar la herramienta o has encontrado algún problema, puedes contactarme en javier@javierhelguera. Espero que encuentres útil esta publicación.

Javier Helguera.