Class Store

explainshell/store.py:107–679

read/write processed man pages from sqlite

class Store:
    """read/write processed man pages from sqlite"""

    def __init__(self, db_path: str, read_only: bool = False) -> None:
        logger.info("creating store, db_path = %r, read_only = %s", db_path, read_only)
        # check_same_thread=False: the default sqlite3 driver raises if a
        # connection is used from a thread other than the one that created it.
        # Plain Store instances are expected to be used by one caller at a
        # time. Production web serving uses CachingStore, which supplies
        # per-thread read-only connections around the shared lookup cache.
        if read_only:
            self._conn = sqlite3.connect(
                f"file:{db_path}?mode=ro", uri=True, check_same_thread=False
            )
            self._conn.row_factory = sqlite3.Row
        else:
            self._conn = sqlite3.connect(db_path, check_same_thread=False)
            self._conn.row_factory = sqlite3.Row
            self._conn.execute("PRAGMA foreign_keys = ON")

    @classmethod
    def create(cls, db_path: str) -> "Store":
        """Create a new (or open an existing) writable database and return a Store."""
        s = cls(db_path)
        s._conn.executescript(_CREATE_SCHEMA)
        return s

    def close(self) -> None:
        if self._conn:
            self._conn.close()
            self._conn = None

    def drop(self, confirm: bool = False) -> None:
        if not confirm:
            return

        logger.info("dropping mappings, parsed_manpages, manpages tables")
        self._conn.executescript("""
            DELETE FROM mappings;
            DELETE FROM parsed_manpages;
            DELETE FROM manpages;
        """)
        self._conn.commit()

    def find_man_page(
        self, name: str, distro: str | None = None, release: str | None = None
    ) -> list[ParsedManpage]:
        """find a man page by its name, everything following the last dot (.) in name,
        is taken as the section of the man page

        we return the man page found with the highest score, and a list of
        suggestions that also matched the given name (only the first item
        is prepopulated with the option data)

        when distro and release are set, filter results to manpages whose
        source starts with ``distro/release/``."""
        if name.endswith(".gz"):
            logger.debug("name ends with .gz, looking up an exact match by source")