lastread 0.20.0__py3-none-any.whl

lastread/__init__.py

@@ -0,0 +1,21 @@
+"""lastread: reading progress from a stock Kobo to Hardcover.
+
+- engine: the Kobo database, the selection state, the plan, Hardcover and the
+  two-way sync. Knows nothing about the page, the commands or the computer.
+- server: what only server mode has (readers and their tokens, uploads, the
+  stats endpoint).
+- web: the page.
+- computer: the tool on the computer the Kobo is plugged into.
+- cli: the command.
+- doctor: the check of everything a sync depends on, for the command and
+  the page. logs: the log and its two levels.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("lastread")
+except PackageNotFoundError:  # run from a checkout that was never installed
+    __version__ = "0+unknown"
+
+ISSUES = "https://github.com/merlijntishauser/lastread/issues"

lastread/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

lastread/appbooks.py

@@ -0,0 +1,153 @@
+"""The Mac app's answers about books (`books --json`, `book ID --json`) and
+the changes it makes to them. The same in local mode, where the tool
+answers from this computer's database, and on the server (/api/app/),
+where a device's token answers for its own reader. The rows are the
+page's (booklist.py)."""
+
+from __future__ import annotations
+
+import json
+
+from . import booklist, start, tip
+from .engine import state
+from .term import plural
+from .web.strings import T
+
+
+class Refused(Exception):
+    """A change that is not made; str() says why, status as the server answers it."""
+
+    def __init__(self, message: str, status: int = 400):
+        super().__init__(message)
+        self.status = status
+
+
+def _quiet(con, reader: str) -> dict:
+    from .engine.plan import quiet_for
+
+    return quiet_for(con, reader) if con else {}
+
+
+def _start(con, reader: str, live: bool, connected, mode: str) -> dict:
+    """Getting started and Needs you (start.py), as the app shows them. The
+    app is the computer the Kobo is plugged into, also in server mode.
+    connected() is asked only while Getting started is there."""
+    found = start.facts(con, reader)
+    steps = (
+        None
+        if live and found["books"]
+        else start.steps(connected=connected(), books=found["books"], on=found["on"], live=live, mode=mode, app=True)
+    )
+    return {"start": steps, "needs_you": start.needs_you(live=live, **found)}
+
+
+def listing(con, reader: str, cover_of, connected, mode: str = "local") -> dict:
+    """Every book with its row and its Details, the filters it is in, the
+    page's sorts and words, and Getting started until the reader is live
+    (Needs you after). cover_of(row) is what the answer says of its cover;
+    connected() whether the reader has a Hardcover connection; mode "local",
+    or "server" when the server answers; con None before a Kobo was read."""
+    rows = booklist.query_rows(con, reader, "", "all", "last_read") if con else []
+    live = bool(con and booklist.summary(con, reader)["live"])
+    quiet = _quiet(con, reader)
+    member = {f: set(booklist.ids(con, reader, "", f)) if con else set() for f in booklist.FILTERS}
+    place = {r["content_id"]: n for n, r in enumerate(rows)}
+    books = [booklist.entry(r, live, quiet, [f for f in booklist.FILTERS if r["content_id"] in member[f]], cover_of(r)) for r in rows]
+    sorts = [  # each sort of the page, with its order as places in books
+        {
+            "key": k,
+            "label": T["sort_" + k],
+            "order": [place[r["content_id"]] for r in booklist.query_rows(con, reader, "", "all", k)] if con else [],
+        }
+        for k in booklist.SORTS
+    ]
+    summary = booklist.summary(con, reader) if con else {"user": "", "on": 0}
+    return {
+        "live": live,
+        "user": summary["user"],
+        **_start(con, reader, live, connected, mode),
+        "tip": tip.pick(con, reader) if con else None,
+        "books": books,
+        "sorts": sorts,
+        "words": {  # the page's words, so that the app says the same
+            "filters": [{"group": T["g_" + g], "keys": [[k, T["f_" + k]] for k in keys]} for g, keys in booklist.FILTER_GROUPS],
+            "sections": [T["d_section_kobo"], T["d_section_hardcover"]],
+            "syncs": [[m, T[m]] for m in state.MODES],
+            "states": [[s, T[booklist.STATE_LABEL[s]]] for s in state.STATES],
+            "legend": [[k, T["legend_" + k]] for k in ("next", "wait", "ok", "stet", "warn", "err", "none")],
+        },
+    }
+
+
+def _row(con, reader: str, cid: str):
+    row = con and con.execute("select * from reader_book where reader=? and content_id=?", (reader, cid)).fetchone()
+    if not row:
+        raise Refused(f"no book with the id '{cid}': `books --json` gives each book's id.", 404)
+    return row
+
+
+def one(con, reader: str, cid: str, cover_of, connected=lambda: False, mode: str = "local") -> dict:
+    """One book as listing() has it, the counts that changed with it, and the
+    tip, Getting started and Needs you, which may have."""
+    row = _row(con, reader, cid)
+    summary = booklist.summary(con, reader)
+    return {
+        "book": booklist.entry(row, summary["live"], _quiet(con, reader), booklist.filters_of(con, reader, cid), cover_of(row)),
+        "books": summary,
+        "tip": tip.pick(con, reader),
+        **_start(con, reader, summary["live"], connected, mode),
+    }
+
+
+def change(con, reader: str, cid: str, client, *, search="", pick="", sync="", state_="", date="", remove=False, not_now=False) -> None:
+    """The changes the page makes to one book. client(**kw) is a Hardcover
+    client, asked for only by a search and a removal; its HardcoverError
+    goes to the caller."""
+    from .engine import hardcover, job
+
+    row = _row(con, reader, cid)
+    if search:  # the books it could be, while it has no match
+        if row["hc_book_id"]:
+            raise Refused("this book has its match already.")
+        found = hardcover.shown(client(tries=1).search(search))
+        con.execute(
+            "update book set hc_how=?, hc_candidates=? where reader=? and content_id=? and hc_book_id is null",
+            ("uncertain" if found else "none", json.dumps(found), reader, cid),
+        )
+        con.commit()
+    if pick:
+        row = _row(con, reader, cid)
+        chosen = [c for c in json.loads(row["hc_candidates"] or "[]") if str(c["book_id"]) == str(pick)]
+        if not chosen:
+            raise Refused(f"{pick} is not one of the books it could be (`book ID --json`, details, candidates).")
+        job.pick(con, reader, cid, int(chosen[0]["book_id"]), chosen[0]["title"], chosen[0].get("pages") or None)
+    if sync:
+        if sync not in state.MODES:
+            raise Refused(f"Sync is one of {', '.join(state.MODES)}, not '{sync}'.")
+        state.set_mode(con, reader, [cid], sync)
+    if state_:
+        if state_ not in state.STATES:
+            raise Refused(f"State is one of {', '.join(state.STATES)}, not '{state_}'.")
+        try:
+            state.set_state(con, reader, cid, state_, date if state_ in ("finished", "rereading") else "")
+        except ValueError as ex:  # a date that is not one
+            raise Refused(str(ex)) from ex
+    if remove:  # off the Hardcover shelf now, and no longer synced
+        job.remove(con, reader, cid, client())
+    if not_now:  # not the tip for a month
+        tip.put_aside(con, reader, cid)
+
+
+def set_all(con, reader: str, sync: str, filter_: str, search: str, expect: int | None) -> None:
+    """Set all, as on the page: Sync for every book the filter and search
+    match; with expect, only while that is still that many books."""
+    if con is None:
+        raise Refused("no books yet: nothing was read from a Kobo so far.")
+    if sync not in state.MODES:
+        raise Refused(f"Sync is one of {', '.join(state.MODES)}, not '{sync}'.")
+    if filter_ not in booklist.FILTERS:
+        raise Refused(f"--filter is one of {', '.join(booklist.FILTERS)}, not '{filter_}'.")
+    ids = booklist.ids(con, reader, search, filter_)
+    if expect is not None and expect != len(ids):  # the list moved since it was counted: nothing changes
+        raise Refused(f"the list holds {plural(len(ids), 'book')} now, not {expect}: nothing was changed.", 409)
+    state.set_mode(con, reader, ids, sync)

lastread/booklist.py

@@ -0,0 +1,302 @@
+"""The list of books as the reader sees it, in words and not in markup:
+which books a view holds and in what order, and per book the Hardcover
+status line and the correction the next sync makes. The page draws it
+(web/app.py), and so will the Mac app, through the tool's JSON; what a
+sync does with a book is decided in engine/plan.py, once, for both."""
+
+from __future__ import annotations
+
+import json
+
+from .engine import state
+from .engine.plan import action, desired, quiet_for
+from .web.fmt import fmt_date, fmt_dt, fmt_dur
+from .web.strings import T
+
+FILTERS = {
+    "all": "1=1",
+    "reading": "((status=1 or (status=0 and percent>0)) and coalesce(finished_at,'')='' and state!='finished') or state='rereading'",
+    "finished": "(status=2 or coalesce(finished_at,'')!='' or state='finished') and state!='rereading'",
+    "unread": "(status=0 and coalesce(percent,0)=0)",
+    "history": "history=1",
+    "new": "history=0",
+    "on": "(mode='on' or (mode='auto' and history=0))",
+    "off": "not (mode='on' or (mode='auto' and history=0))",
+    "needs_match": "(mode='on' or (mode='auto' and history=0)) and hc_book_id is null and hc_how in ('uncertain','none')",
+    # On the Hardcover shelf with an edition that is not marked Ebook: to fix there.
+    "not_ebook": "(mode='on' or (mode='auto' and history=0)) and last_sent is not null and coalesce(hc_format_id,0)!=4",
+}
+FILTER_GROUPS = [
+    ("progress", ["all", "reading", "finished", "unread"]),
+    ("kobo", ["history", "new"]),
+    ("hardcover", ["on", "off", "needs_match", "not_ebook"]),
+]
+
+# Each way round. A book never opened has no last-read date: it comes last either way. content_id ends
+# every order, so that the list is the same list from one "Show more" to the next.
+SORTS = {
+    "last_read": "last_read is null, last_read desc, content_id",
+    "last_read_old": "last_read is null, last_read asc, content_id",
+    "author": "author collate nocase, title collate nocase, content_id",
+    "author_za": "author collate nocase desc, title collate nocase desc, content_id",
+    "title": "title collate nocase, content_id",
+    "title_za": "title collate nocase desc, content_id",
+}
+
+
+def where(reader, q, f):
+    """The SQL condition of a view, a search q in filter f, and its arguments."""
+    # Each filter in its own parentheses: some contain a top-level OR, which
+    # would otherwise escape the reader condition.
+    parts, args = [f"({FILTERS.get(f, '1=1')})", "reader=?"], [reader]
+    if q:
+        parts.append("(title like ? or author like ?)")
+        args += [f"%{q}%", f"%{q}%"]
+    return " and ".join(parts), args
+
+
+def query_rows(con, reader, q, f, sort, limit: int = -1, offset: int = 0):
+    """The books of a view, in its order; `limit` of them from `offset` (-1: all)."""
+    w, args = where(reader, q, f)
+    order = SORTS.get(sort, SORTS["last_read"])
+    return con.execute(f"select * from reader_book where {w} order by {order} limit ? offset ?", [*args, limit, offset]).fetchall()
+
+
+def place_of(con, reader, q, f, sort, cid: str) -> int:
+    """Where a book stands in a view (0 = first), or -1 when the view does not hold it."""
+    w, args = where(reader, q, f)
+    order = SORTS.get(sort, SORTS["last_read"])
+    found = con.execute(
+        f"select n from (select content_id, row_number() over (order by {order}) - 1 as n from reader_book where {w}) where content_id=?",
+        [*args, cid],
+    ).fetchone()
+    return found[0] if found else -1
+
+
+def filter_counts(con, reader, q):
+    out = {}
+    for k in FILTERS:
+        w, args = where(reader, q, k)
+        out[k] = con.execute(f"select count(*) from reader_book where {w}", args).fetchone()[0]
+    return out
+
+
+def filters_of(con, reader, cid: str) -> list[str]:
+    """The filters a book is in."""
+    out = []
+    for f in FILTERS:
+        w, args = where(reader, "", f)
+        if con.execute(f"select 1 from reader_book where {w} and content_id=?", [*args, cid]).fetchone():
+            out.append(f)
+    return out
+
+
+def ids(con, reader, q, f) -> list[str]:
+    """Every book a search and filter match, shown or not: what Set all changes."""
+    w, args = where(reader, q, f)
+    return [r[0] for r in con.execute(f"select content_id from reader_book where {w}", args)]
+
+
+def hc_status(r, live: bool, quiet: dict) -> tuple[str, str]:
+    """(kind, text) of the Hardcover status line: what the next sync does.
+    kind: ok | next | wait | warn | err | none (marks.py). `quiet`: plan.quiet for this reader."""
+    if r["hc_error"]:
+        return "err", T["status_error"]
+    if (r["device"], r["content_id"]) in quiet:
+        return "none", T["other_copy"]
+    a = action(r)
+    if a.startswith("needs"):
+        return "warn", T["needs_match"]
+    if a.startswith("match pending"):
+        return "next", T["match_pending"]
+    if a:
+        return "next", f"{T['next_sync'] if live else T['would_send']}: {a}"
+    if state.syncs(r) and r["last_sent"]:
+        return "ok", T["up_to_date"]
+    if state.syncs(r):
+        return "wait", T["not_yet_sent"]
+    return "none", T["not_syncing"]
+
+
+def marked(con, reader: str, live: bool, quiet: dict) -> int:
+    """How many books carry the red mark: what the next sync sends."""
+    return sum(1 for r in con.execute("select * from reader_book where reader=?", (reader,)) if hc_status(r, live, quiet)[0] == "next")
+
+
+# The State a reader sets, in the page's words.
+STATE_LABEL = {"kobo": "kobo", "finished": "finished_pin", "rereading": "rereading", "want": "want", "dnf": "dnf"}
+
+
+def progress(r) -> tuple[int, bool, list[str]]:
+    """How far the book is, under its title: (percent, finished, the facts
+    in words: when it was finished or last read, and the time read)."""
+    want = desired(r)
+    done = bool(want and want["status"] == "read")
+    pct = 100 if done else max(0, min(100, int(r["percent"] or 0)))
+    meta = []
+    if done:
+        when = fmt_date(want.get("finished"))
+        meta.append(f"{T['finished_on']} {when}" if when else T["finished_pin"])
+    elif pct or r["status"] == 1:
+        meta.append(f"{pct}%")
+        if r["last_read"]:
+            meta.append(f"{T['last_read']} {fmt_date(r['last_read'])}")
+    else:
+        meta.append(T["not_started"])
+    if r["seconds_read"]:
+        meta.append(f"{fmt_dur(r['seconds_read'])} {T['read_time']}")
+    return pct, done, meta
+
+
+def edition(r) -> tuple[str, bool]:
+    """('Blindness, Ebook', stet): the match and its edition, and whether
+    the edition was chosen on Hardcover, so that it is kept as it is."""
+    if not r["hc_book_id"]:
+        return "", False
+    sent = json.loads(r["last_sent"]) if r["last_sent"] else {}
+    parts = [r["hc_title"] or ""]
+    if r["hc_format"] or sent.get("user_book_id"):
+        parts.append(r["hc_format"] or T["format_unknown"])
+    return ", ".join(x for x in parts if x), r["hc_edition_by"] == "hardcover"
+
+
+def details(r) -> dict:
+    """What Details shows of a book, in words: what the Kobo says and what
+    Hardcover has, as (label, value) pairs without the empty ones; the
+    link to the book on Hardcover; the books it could be, while it waits
+    for a match; and whether it is on the Hardcover shelf (so it can be
+    taken off)."""
+    sent = json.loads(r["last_sent"]) if r["last_sent"] else {}
+    kobo = [
+        (T["col_mode"], T[r["mode"]]),
+        (T["col_state"], T[STATE_LABEL[r["state"] or "kobo"]] + (f", {r['state_date']}" if r["state_date"] else "")),
+        (
+            T["d_kobo_status"],
+            {0: T["d_unread"], 1: T["d_reading"], 2: T["d_finished"]}.get(r["status"], "") + (f", {r['percent']}%" if r["percent"] else ""),
+        ),
+        (T["d_finished_on"], fmt_date(r["finished_at"])),
+        (T["d_last_read"], fmt_date(r["last_read"])),
+        (T["d_read_time"], fmt_dur(r["seconds_read"]) if r["seconds_read"] else ""),
+        (T["d_language"], r["language"] or ""),
+        ("ISBN", r["isbn"] or ""),
+    ]
+    hc = []
+    if r["hc_book_id"]:
+        how = T.get("how_" + (r["hc_how"] or ""), "")
+        hc.append((T["d_book"], (r["hc_title"] or "") + (f" ({how})" if how else "")))
+        if r["hc_format"] or r["hc_pages"]:
+            words = (r["hc_format"] or T["format_unknown"]) + (f", {r['hc_pages']} {T['d_pages']}" if r["hc_pages"] else "")
+            hc.append((T["d_edition"], words + (f" ({T['how_hardcover']})" if r["hc_edition_by"] == "hardcover" else "")))
+    if sent.get("user_book_id"):
+        shelf = T["hc_" + sent.get("status", "reading")]
+        if sent.get("status") == "reading" and sent.get("progress") is not None:
+            shelf += f", {sent['progress']}%"
+        if sent.get("finished"):
+            shelf += f", {fmt_date(sent['finished'])}"
+        hc.append((T["d_on_shelf"], shelf))
+        hc.append((T["d_last_sync"], fmt_dt(sent.get("at"))))
+    if r["hc_error"]:
+        hc.append((T["d_error"], r["hc_error"]))
+    waiting = not r["hc_book_id"] and r["hc_how"] in ("uncertain", "none")
+    return {
+        "kobo": [[k, v] for k, v in kobo if v],
+        "hardcover": [[k, v] for k, v in hc if v],
+        "link": f"https://hardcover.app/id/book/{int(r['hc_book_id'])}" if r["hc_book_id"] else "",
+        "candidates": [
+            {"id": int(c["book_id"]), "title": c["title"], "author": (c.get("authors") or [""])[0]}
+            for c in json.loads(r["hc_candidates"] or "[]")
+        ]
+        if waiting
+        else [],
+        "on_shelf": bool(sent.get("user_book_id")),
+    }
+
+
+def opened(r) -> bool:
+    """Whether the book was ever opened on the Kobo: a status, a percentage
+    or any time read. Not its last read date: the Kobo sets that on books
+    never opened too (seen on a real Kobo, 2026-10-26)."""
+    return bool(r["status"] or r["percent"] or r["seconds_read"])
+
+
+def entry(r, live: bool, quiet: dict, filters: list[str], cover: str = "") -> dict:
+    """A book as the tool's JSON has it (`books --json`, `book --json`):
+    its row, its Details, and the filters it is in. `cover`: its
+    thumbnail's file, when there is one."""
+    pct, done, meta = progress(r)
+    kind, words = hc_status(r, live, quiet)
+    words_of_edition, kept = edition(r)
+    return {
+        "id": r["content_id"],
+        "title": r["title"] or "",
+        "author": r["author"] or "",
+        "cover": cover,
+        "new": not r["history"],
+        "percent": pct,
+        "finished": done,
+        "opened": done or opened(r),
+        "facts": meta,
+        "last_read": r["last_read"] or "",
+        "sync": r["mode"],
+        "syncs": state.syncs(r),
+        "state": r["state"] or "kobo",
+        "state_date": r["state_date"] or "",
+        "status": {"kind": kind, "text": words},
+        "correction": list(correction(r) or []) if kind == "next" else [],
+        "edition": words_of_edition,
+        "stet": kept,
+        "filters": filters,
+        "details": details(r),
+    }
+
+
+def summary(con, reader: str) -> dict:
+    """The books in a few counts, for the Mac app's overview: how many the
+    Kobo told of, how many are switched on, how many the next sync changes
+    and how many wait for a match; whether it sends (live) or only says
+    what it would, as whom, and the collection the switched-on books go to."""
+    counts = filter_counts(con, reader, "")
+    row = con.execute("select hardcover_live, hardcover_user, kobo_collection from reader where name=?", (reader,)).fetchone()
+    return {
+        "total": counts["all"],
+        "on": counts["on"],
+        "next": marked(con, reader, bool(row and row[0]), quiet_for(con, reader)),
+        "needs_match": counts["needs_match"],
+        "live": bool(row and row[0]),
+        "user": (row[1] if row else "") or "",
+        "collection": ((row[2] if row else "") or "").strip(),
+    }
+
+
+def shelf_words(d: dict) -> str:
+    """'Currently reading, 37%' / 'Read, finished 30 Sep 2026': a shelf entry
+    in the page's words, for what Hardcover has (last_sent) or will get (desired)."""
+    st = d.get("status") if d else None
+    if not st:
+        return ""
+    words = T.get("hc_" + st, st)
+    if st == "reading" and d.get("progress") is not None:
+        words += f", {d['progress']}%"
+    if st == "read" and d.get("finished"):
+        words += ", " + T["shelf_finished"].format(date=fmt_date(d["finished"]))
+    return words
+
+
+def correction(r) -> tuple[str, str, str] | None:
+    """The proof mark for a row the next sync changes: (kept, struck, inserted),
+    'Currently reading,' '35%' '37%'. None when there is no shelf change to show
+    (no match yet, or only the edition changes)."""
+    a = action(r)
+    if not a or not r["hc_book_id"] or a.startswith(("needs", "match pending")):
+        return None
+    sent = json.loads(r["last_sent"]) if r["last_sent"] else {}
+    now = shelf_words(desired(r) or {})
+    was = shelf_words(sent) if sent.get("user_book_id") else ""
+    if not now or now == was:
+        return None
+    if was:
+        h1, _, t1 = was.partition(", ")
+        h2, _, t2 = now.partition(", ")
+        if h1 == h2 and t1 and t2:
+            return h1 + ",", t1, t2
+    return "", was, now