Hackeando una app para marcadores web

Cuando comienzas un proyecto, lo haces porque consideras que va a ser algo fácil, que te va a llevar poco (diez minutos, un par de horas...). Cualquier proyecto, por pequeño que sea, siempre duplica, triplica o quintuplica el tiempo estimado para su realización.

Pero si no fuesemos tan positivos... ¡nunca comenzaríamos un proyecto! Veamos, ¿qué necesitamos para crear un marcador web en Python?

from typing import ClassVar
from datetime import datetime
from dataclasses import dataclass


@dataclass
class Bookmark:
    name: str
    url: str
    parent: object
    NUM: classvar[int] = 0

    def __init__(self, name, url, parent=None):
        Bookmark.NUM += 1

        if not url:
            url = "https://info.cern.ch/"

        name = name.strip()
        if not name:
            dt = datetime.now()
            name = f"name{Bookmark.NUM}-{dt.year:04}{dt:month:02}{dt.day:02}";

        self.name = name
        self.url = url
        self.parent = parent

    def __str__(self):
        return f"{self.name}: {self.url}"

También necesitamos una lista de Bookmarks:

class BookmarkList:
    """A list of bookmarks or other objects BookmarkList"""
    def __init__(self, name="", parent=None, initial_bml=None):
        self._parent = parent
        self._lb = {}

    @property
    def all(self):
        return self._lb.values()

    def add(self, bm: {Bookmark|BookmarkList}):
        """Adds a new entry, or a new list of bookmarks"""
        self._lb[bm.name] = bm
        bm.parent = self

    def get(self, name) -> {Bookmark|BookmarkList|None}:
        return self._lb.get(name)

    def delete(self, name: str):
        if name in self._lb:
            del self._lb[name]
            return True

        print("Not deleted")
        return False

    def at(self, i):
        return list(self._lb.values())[i]

    def __len__(self):
        return len(self._lb)    

Y ahora viene la parte realmente interesante, en la que grabamos y cargamos una lista de enlaces (que puede ser recursiva). Guardar es muy fácil. Solo tenemos que guardar las listas de enlaces entre marcas dl, y cada enlace (como un hiperenlace), dentro de una marca dt. Además, el nombre de cada lista va dentro de las marcas dl, como un dt que tiene dentro una marca h3 con el nombre.

class PersistentBookmarks:
    """Persistence for bookmarks, read/write."""
    INDENT = "    "

    def __init__(self, bms: BookmarkList):
        """Creates a new saving PersistentBookmarks.
            :param bms: a bookmarks list
        """
        self._bms = bms

    def save(self, nf: str):
        """Saves the list of bookmarks.
            :param bf: a path to save the BookmarkList to.
        """
        if self._bms is None:
            return

        with open(nf, "wt") as f:
            PersistentBookmarks.write_headers(f)
            self._save_bms_to(f, 1, self._bms)

    def _save_bms_to(self, f, lvl, bms: BookmarkList):
        """Recursively saves a given BookmarkList.
            :param f: the file to save.
            :param lvl: the indent level.
            :param bms: the BookmarkList to save.
        """
        indent = PersistentBookmarks.INDENT * lvl
        inner_indent = indent + PersistentBookmarks.INDENT
        f.write(f"\n{indent}<dl>\n")
        f.write(f"{indent}<dt><h3>{bms.name}</h3></dt>\n")

        for entry in bms:
            if isinstance(entry[1], BookmarkList):
                self._save_bms_to(f, lvl + 1, entry[1])
            else:
                f.write(f"{inner_indent}<dt><a href=\"{entry[1].url}\">"
                        + f"{entry[0]}</a></dt>\n")
        f.write(f"\n{indent}<dl>\n")

    @staticmethod
    def write_headers(f):
        """Writes the required headers pf the bookmarks file."""
        f.write("<!DOCType NETSCAPE-Bookmark-file-1>\n")
        f.write("<meta http-equiv=\"Content-Type\" ")
        f.write("content=\"text/html;charset=UTF-8\">\n")
        f.write("<title>Bookmarks</title>\n")
        f.write("<h1>Bookmarks</h1>\n\n")

El trabajo duro lo hace la función _save_bms_to(lvl, bms), que guarda la lista de enlaces con un nivel (lvl), determinado. Este parámetro sería totalmente opcinal, solo se usa, en realidad, para crear la indentación adecuada y tener un archivo que sea agradeblemente legible. Esto lo conseguimos asignando a la variable inner_indent la expresión " " * lvl. Así, tendremos cuatro espacios de indentación, tantas veces como el nivel en el de lista anidada en el que estemos.

Así conseguimos algo como esto:

    <dl>
    <dt><h3>Bookmarks</h3></dt>
        <dl>
        <dt><h3>News</h3></dt>
            <dt><a href="https://www.youtube.com/">YouTube</a></dt>
            <dt><a href="http://thedailywtf.com/">The Daily WTF: Curious Perversions in Information Technology</a></dt>
            <dt><a href="http://www.facebook.com/">fb</a></dt>
            <dt><a href="https://slashdot.org/">Slashdot: News for nerds, stuff that matters</a></dt>
        </dl>
        <dl>
        <dt><h3>Tools</h3></dt>
            <dt><a href="http://www.ilovepdf.com/">I Love PDF</a></dt>
            <dt><a href="http://ideone.com/">Ideone.com | Online IDE & Debugging Tool</a></dt>
        </dl>
    </dl>

Recuperar los bookmarks es un pelín más complicado. Lo lógico es utilizar la extensa librería estándar de Python, y esta nos provee de la clase HTMLParser en el módulo html.parser. Esta librería funciona como eventos, es decir, el método handle_starttag()' es llamado cuando se encuentra una marca o _tag_ abierta, y otro (handle_endtag()'), cuando se encuentra cerrada.

class BookmarksFileParser(HTMLParser):
    """Parses a bookmarks file."""
    class Status(Enum):
        """State for the finite machine."""
        TOP_LEVEL = auto()
        READ_ENTRY = auto()
        READ_NAME = auto()
        READ_BOOKMARK = auto()

    def handle_starttag(self, tag, attrs):
        ...

    def handle_endtag(self, tag):
        ...

    def handle_data(self, data):
        data = data.strip()

        if data:
            match self._status:
                case BookmarksFileParser.Status.READ_NAME:
                    self._current_name = data
                case BookmarksFileParser.Status.READ_BOOKMARK:
                    self._curr.add(Bookmark(data, self._url))

Así que tenemos que crearnos un pequeña máquina de estados para saber en qué punto estamos (de ahí el enumerado Status). Por ejemplo, no es lo mismo encontrarse con un h3 cuando se espera el nombre de una lista, o un a cuando se espera encontrarnos con un enlace.

En el método start_tag():

class BookmarksFileParser(HTMLParser):
    # más cosas...
    def handle_starttag(self, tag, attrs):
        match tag.lower():
            case "dl":
                new_list = BookmarkList(self._current_name, self._curr)

                if self._bms is None:
                    self._bms = new_list

                if self._curr is not None:
                    self._curr.add(new_list)

                self._curr = new_list
                log.info(f"Created new list: {self._curr=}")
                log.info(f"Previous list: {self._curr.parent=}")
                self._status = BookmarksFileParser.Status.TOP_LEVEL
            case "dt":
                self._status = BookmarksFileParser.Status.READ_ENTRY
            case "h3":
                self._status = BookmarksFileParser.Status.READ_NAME
            case "a":
                self._status = BookmarksFileParser.Status.READ_BOOKMARK
                href = [v for (k, v) in attrs if k == "href"]
                if len(href) < 1:
                    raise Exception("couldn't find HREF in a")
                self._url = href[0]
                log.debug(f"{self._url=}")
                log.info(f"Status: {self._status}")

¿Por qué es necesario self._bms is None, o self._curr is not None, cuando normalmente escribiríamos self._bms o not self._curr? Pues porque _bms y _curr son listas, retornarán False no solo cuando son None, sino también cuando están vacías, es decir, no tienen elementos.

El código completo de (así he llamado esta app), Bookmank está en Github.