diglibrary 1.1.1__py3-none-any.whl

diglibrary/__init__.py

@@ -0,0 +1,5 @@
+"""DigLibrary's production-quality infrastructure foundation."""
+
+from diglibrary.application.composition import Application, create_application
+
+__all__ = ["Application", "create_application"]

diglibrary/__main__.py

@@ -0,0 +1,107 @@
+"""``diglibrary`` opens the window, and its two other words do the two jobs a
+checkout used to have scripts for."""
+
+import argparse
+import sys
+from pathlib import Path
+
+# The words that mean something other than *open the window*. Anything else,
+# including nothing at all and including every option the window takes, goes to
+# the window exactly as it did before there were any words here — a default that
+# is usually right must not be what refuses an explicit request (ADR-109), and
+# the reverse holds too: a word nobody typed must not change what happens.
+COMMANDS = ("make-icon", "restore-copy")
+
+
+def main() -> None:
+    """Parse the command line and hand over to the window, or to a command."""
+    if len(sys.argv) > 1 and sys.argv[1] in COMMANDS:
+        raise SystemExit(_command(sys.argv[1], sys.argv[2:]))
+
+    parser = argparse.ArgumentParser(
+        prog="diglibrary",
+        description="Open the DigLibrary window.",
+        epilog=(
+            "Other things it can do: "
+            "`diglibrary make-icon` puts an icon in your Dock so you never need "
+            "this terminal again; "
+            "`diglibrary restore-copy` lists the copies of your database and "
+            "puts one back."
+        ),
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=None,
+        help=(
+            "Path to the configuration file. Without one: ./config.toml when it "
+            "is there, otherwise ~/.diglibrary/config.toml, written on first run."
+        ),
+    )
+    parser.add_argument(
+        "--debug", action="store_true", help="Open the window with developer tools enabled."
+    )
+    arguments = parser.parse_args()
+
+    from diglibrary.ui.app import run
+
+    # Resolved inside `run` rather than here, because choosing the file can fail
+    # the same way reading it can — a directory holding a database and no
+    # settings is refused — and there is one place that turns a configuration
+    # failure into a window someone can read.
+    run(arguments.config, debug=arguments.debug)
+
+
+def _command(name: str, arguments: list[str]) -> int:
+    """Run one of the words above, and say what happened in words a person reads."""
+    if name == "make-icon":
+        return _make_icon(arguments)
+    return _restore_copy(arguments)
+
+
+def _make_icon(arguments: list[str]) -> int:
+    """Assemble the Dock icon for whichever installation is running."""
+    parser = argparse.ArgumentParser(
+        prog="diglibrary make-icon",
+        description=(
+            "Put DigLibrary in your Dock. The icon launches the copy of "
+            "DigLibrary you are running this from, on this Mac only — it is not "
+            "an application you can send to anybody."
+        ),
+    )
+    parser.add_argument(
+        "destination",
+        nargs="?",
+        type=Path,
+        default=None,
+        help="Where to put it. Default: ~/Applications",
+    )
+    chosen = parser.parse_args(arguments)
+
+    if sys.platform != "darwin":
+        print("A Dock is a macOS thing, and this is not macOS. Nothing was written.")
+        return 1
+
+    from diglibrary.desktop.bundle import make_icon
+
+    print("Drawing the icon at every size it needs. About nine seconds.")
+    try:
+        bundle = make_icon(chosen.destination)
+    except FileNotFoundError:
+        # `iconutil` ships with macOS and with the developer tools, and saying
+        # which command was missing beats a traceback about a path nobody typed.
+        print("refused: macOS's own `iconutil` is not on the path. Nothing was written.")
+        return 1
+    print(f"Done. {bundle} — open it once from Finder, then keep it in your Dock.")
+    return 0
+
+
+def _restore_copy(arguments: list[str]) -> int:
+    """List the copies of the database, or put one back."""
+    from diglibrary.desktop.restore import restore
+
+    return restore(arguments)
+
+
+if __name__ == "__main__":
+    main()

diglibrary/application/__init__.py

@@ -0,0 +1 @@
+"""Application composition and cross-boundary contracts."""

diglibrary/application/acoustic.py

@@ -0,0 +1,289 @@
+"""Identifying an album by what its audio is, when its names say nothing usable."""
+
+import logging
+from collections import Counter
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from diglibrary.application.contracts import MetadataSourceId, MetadataSources, ReleaseMetadata
+from diglibrary.library.audio_key import audio_key
+from diglibrary.library.fingerprint import AudioFingerprint
+from diglibrary.library.models import AlbumUnit
+from diglibrary.metadata.acoustid import AcousticMatch, AcoustIdClient
+from diglibrary.metadata.service import MetadataService
+
+DEFAULT_SAMPLE_SIZE = 3
+"""How many tracks of an album are fingerprinted before it is asked about.
+
+Measured on the owner's library (ADR-125): one track names nine to nineteen
+release groups, and three tracks agreeing narrow that to one or two. Fewer than
+three leaves the intersection wide; more spends lookups at three a second to
+confirm what three already said.
+"""
+
+DEFAULT_GROUP_LIMIT = 2
+"""How many release groups are browsed for pressings. Each one costs a request."""
+
+
+class Fingerprinter(Protocol):
+    """Produce one file's acoustic fingerprint, or nothing when it cannot."""
+
+    def fingerprint(self, path: object) -> AudioFingerprint | None:
+        """Return the fingerprint of the audio at ``path``."""
+
+
+class FingerprintStore(Protocol):
+    """Remember a fingerprint against the audio it was computed from.
+
+    Keyed by content signature rather than by path (ADR-125), which is what
+    makes it survive the rename that organizing performs — and by the audio's
+    own key as well (migration 19), because a signature is a declared shape and
+    two different recordings can wear one.
+    """
+
+    def fingerprint_for(
+        self, content_signature: str, audio_key: str | None = None
+    ) -> AudioFingerprint | None:
+        """Return a stored fingerprint, or ``None``."""
+
+    def remember_fingerprint(
+        self, content_signature: str, audio_key: str | None, value: AudioFingerprint
+    ) -> None:
+        """Store a fingerprint against the audio it belongs to."""
+
+
+@dataclass(frozen=True, slots=True)
+class _OneFile:
+    """One file put to the service by itself, in the shape the helpers read.
+
+    `_fingerprint` and `_remember_answer` were written against the scanner's
+    `AudioFileFacts` and need exactly two of its fields. Naming that here beats
+    passing the whole scanned unit for one file.
+    """
+
+    path: Path
+    content_signature: str
+
+
+class AcousticIdentification:
+    """Purpose: turn an album's audio into the releases it might be.
+
+    Responsibilities: fingerprint a sample of an album's tracks, ask AcoustID
+    what they are, find the release group its tracks agree on, and return that
+    group's pressings. Boundaries: it decides nothing and writes no metadata —
+    what comes back are candidates, scored and chosen exactly like any other
+    (the owner's ruling on 2026-07-30). Dependencies: an injected fingerprinter,
+    AcoustID client, and metadata service. Collaborators: the identification
+    workflow, which asks only when an album did not settle. Constraints: every
+    failure is an empty answer, because acoustic identification never blocks
+    organizing (ADR-016).
+    """
+
+    def __init__(
+        self,
+        fingerprinter: Fingerprinter,
+        acoustid: AcoustIdClient,
+        metadata: MetadataService,
+        logger: logging.Logger,
+        store: FingerprintStore | None = None,
+        sample_size: int = DEFAULT_SAMPLE_SIZE,
+        group_limit: int = DEFAULT_GROUP_LIMIT,
+        source: MetadataSourceId = MetadataSources.MUSICBRAINZ,
+        audio_key_of: Callable[[Path], str | None] = audio_key,
+    ) -> None:
+        """Create the acoustic path over already-assembled infrastructure."""
+        self._fingerprinter = fingerprinter
+        self._acoustid = acoustid
+        self._metadata = metadata
+        self._logger = logger
+        self._store = store
+        self._sample_size = sample_size
+        self._group_limit = group_limit
+        self._source = source
+        self._audio_key_of = audio_key_of
+        self._keys: dict[object, str | None] = {}
+
+    @property
+    def is_available(self) -> bool:
+        """Return whether the audio can be asked at all, so the window can say why not."""
+        return self._acoustid.is_configured
+
+    def releases_for(self, unit: AlbumUnit) -> tuple[ReleaseMetadata, ...]:
+        """Return the pressings this album's own audio points at."""
+        if not self._acoustid.is_configured or not unit.audio_files:
+            return ()
+        groups = self._groups_named_by(unit)
+        if not groups:
+            return ()
+        releases: list[ReleaseMetadata] = []
+        for group_id in groups:
+            releases.extend(self._metadata.releases_in_group(self._source, group_id))
+        self._logger.info(
+            "The audio named an album.",
+            extra={
+                "operation": "acoustic.identified",
+                "groups": len(groups),
+                "releases": len(releases),
+            },
+        )
+        return tuple(releases)
+
+    def _groups_named_by(self, unit: AlbumUnit) -> tuple[str, ...]:
+        """Return the release groups this album's sampled tracks agree on.
+
+        Agreement is the whole instrument. One track of the owner's `Construção`
+        named nine release groups and one named two; the groups all three
+        sampled tracks shared were two. A group named by more of the sample is a
+        better answer than one named by less, and only the best are browsed
+        because each browse is a request.
+        """
+        named: Counter[str] = Counter()
+        answered = 0
+        for file in self._sample(unit.audio_files):
+            fingerprint = self._fingerprint(file)
+            if fingerprint is None:
+                continue
+            matches = self._acoustid.lookup(fingerprint)
+            # Written down whichever way it went. Everything this service says
+            # used to be consumed and dropped, so nothing could ever be shown
+            # about it and the engine read as a rumour: measured on his library
+            # on 2026-08-01, 29 fingerprints computed and not one row saying
+            # what any of them was told (ADR-155).
+            self._remember_answer(file, matches[0] if matches else None)
+            if not matches:
+                continue
+            answered += 1
+            # One track's own best answer, not every answer it has: a fingerprint
+            # that matches two recordings is one recording published twice, and
+            # counting both would let a single track outvote its neighbours.
+            named.update(dict.fromkeys(matches[0].release_group_ids, 1))
+        if not named:
+            # Asked and answered nothing, which is a different state from never
+            # asked and has to say so (ADR-101). Measured on his own library the
+            # day this shipped: the nine tracks of `Missinho — Esquinas de São
+            # Salvador` returned eight blanks and one fingerprint AcoustID holds
+            # with no MusicBrainz recording behind it. The service not knowing a
+            # record is the ordinary case for the catalogue he collects, and an
+            # app that goes quiet there reads as an app that did not try.
+            self._logger.info(
+                "The audio was asked and the service does not know this album.",
+                extra={"operation": "acoustic.unknown", "tracks": answered},
+            )
+            return ()
+        best = max(named.values())
+        agreed = [group for group, count in named.items() if count == best]
+        if best < 2 and answered > 1:
+            # Every sampled track named a different album, which is what a
+            # folder of unrelated files looks like. Saying so is more useful
+            # than browsing an arbitrary one of them.
+            self._logger.info(
+                "The audio did not agree with itself about this album.",
+                extra={"operation": "acoustic.disagreed", "tracks": answered},
+            )
+            return ()
+        return tuple(sorted(agreed)[: self._group_limit])
+
+    def recognize(self, path: Path, content_signature: str) -> str | None:
+        """Put one file to the service because he asked, and keep what came back.
+
+        The identification path asks about an *album*, and only when its names
+        failed (ADR-123, ADR-125) — which is why 29 of his 2,073 registered
+        files had ever been asked. This is the other door: one file, on a gesture
+        he made, so the bench can find out what the service knows about the
+        catalogue he actually collects (ADR-155).
+
+        Returns the recording it named, or ``None`` for every other outcome. The
+        answer is written down either way, and *that* is what the screens read —
+        a return value cannot tell "asked and unknown" from "could not ask".
+        """
+        if not self._acoustid.is_configured:
+            return None
+        probe = _OneFile(path=path, content_signature=content_signature)
+        fingerprint = self._fingerprint(probe)
+        if fingerprint is None:
+            return None
+        try:
+            matches = self._acoustid.lookup(fingerprint)
+        except Exception:
+            self._logger.exception(
+                "One file could not be put to the service.",
+                extra={"operation": "acoustic.lookup.failure"},
+            )
+            return None
+        self._remember_answer(probe, matches[0] if matches else None)
+        if matches and matches[0].recording_ids:
+            return matches[0].recording_ids[0]
+        return None
+
+    def _remember_answer(self, file: object, match: AcousticMatch | None) -> None:
+        """Keep what the service answered about this file, including nothing at all.
+
+        A lookup costs a request against a service that allows about three a
+        second, so its answer is worth exactly as much as the fingerprint it was
+        drawn from — and the fingerprint was the only half being kept.
+
+        Written against the audio, not merely the shape: an answer filed under a
+        signature two recordings share is an answer one of them is wearing
+        without having earned it (migration 19).
+        """
+        signature = getattr(file, "content_signature", "")
+        if self._store is None or not signature:
+            return
+        recording = match.recording_ids[0] if match and match.recording_ids else None
+        self._store.remember_lookup(
+            signature, self._audio_key(file), recording, match.score if match else None
+        )
+
+    def _sample(self, files: Sequence[object]) -> tuple[object, ...]:
+        """Return tracks spread across the album rather than its first few.
+
+        A compilation's opening tracks are the ones most likely to appear on
+        other compilations; taking the first, a middle and the last asks about
+        three different points of the record.
+        """
+        if len(files) <= self._sample_size:
+            return tuple(files)
+        last = len(files) - 1
+        positions = {
+            round(index * last / (self._sample_size - 1)) for index in range(self._sample_size)
+        }
+        return tuple(files[position] for position in sorted(positions))
+
+    def _fingerprint(self, file: object) -> AudioFingerprint | None:
+        """Return this file's fingerprint, from the store when it is known to be this file's.
+
+        The audio is named first because naming it is nearly free — 0.4 ms for a
+        FLAC that declares its own digest, 3.7 ms for one that does not, against
+        121 ms to fingerprint the file afresh, both measured on his own `The
+        Griot` pair on 2026-08-02. A stored print is reused only when it was
+        drawn from this same audio; a print left over from before the audio had
+        a name is recomputed rather than trusted, and comes back to claim that
+        row when it proves to be the same (migration 19).
+        """
+        signature = getattr(file, "content_signature", "")
+        key = self._audio_key(file)
+        if self._store is not None and signature:
+            remembered = self._store.fingerprint_for(signature, key)
+            if remembered is not None:
+                return remembered
+        computed = self._fingerprinter.fingerprint(getattr(file, "path", file))
+        if computed is not None and self._store is not None and signature:
+            self._store.remember_fingerprint(signature, key, computed)
+        return computed
+
+    def _audio_key(self, file: object) -> str | None:
+        """Return the identity of this file's audio, or ``None`` when it cannot be read.
+
+        Memoized per file because both halves of one visit ask for it — the
+        print is looked up before the service is asked and the answer is written
+        after — and reading the same 128 KB twice for one lookup is waste with
+        no upside.
+        """
+        path = getattr(file, "path", file)
+        if path in self._keys:
+            return self._keys[path]
+        key = self._audio_key_of(path) if isinstance(path, Path) else None
+        self._keys[path] = key
+        return key