Coverage for downtify/download_log.py: 100%
46 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""How every download ended, for the library usage page.
3The queue only keeps its jobs until they are cleared, and a Playlist
4Monitor sweep keeps none at all, so neither can say how many downloads
5finished, were skipped or failed last month. :class:`DownloadLog` keeps
6one small row per attempt in ``downtify_library.db`` - when, how it
7ended (``OUTCOME_*``), which provider fetched the audio and how big the
8file was - for :data:`RETENTION_DAYS`.
10Rows come from ``Downloader.on_outcome`` (every download, from the queue
11or a monitor sweep alike: fetched, already in the library, or failed)
12and from the queue's own "already in library" check, which ends a job
13before the downloader is asked (see ``api.record_download_outcome``).
14``GET /api/library/usage`` (``downtify/library_usage.py``) sums them up.
15"""
17from __future__ import annotations
19from datetime import datetime, timedelta, timezone
20from pathlib import Path
21from typing import Any, Optional
23from .db.config import Dialect
24from .db.core import Database, as_database
26#: A new file was downloaded and tagged.
27OUTCOME_COMPLETED = 'completed'
28#: The song was already in the library; nothing was downloaded.
29OUTCOME_SKIPPED = 'skipped'
30#: The download failed (no match, too long, a provider error...).
31OUTCOME_FAILED = 'failed'
33OUTCOMES = (OUTCOME_COMPLETED, OUTCOME_SKIPPED, OUTCOME_FAILED)
35#: Long enough for the longest period the usage page shows (a year).
36RETENTION_DAYS = 400
39def _now() -> datetime:
40 return datetime.now(timezone.utc)
43class DownloadLog:
44 """One row per download attempt, oldest dropped after a while."""
46 def __init__(self, path_or_db: str | Path | Database) -> None:
47 self.db = as_database(path_or_db, 'library')
48 if isinstance(path_or_db, Database):
49 self._path = str(self.db.path) if self.db.path else None
50 else:
51 self._path = str(path_or_db)
52 if self.db.dialect is Dialect.SQLITE:
53 self._init_db()
55 def _init_db(self) -> None:
56 # On PostgreSQL the library_a migration already created the table.
57 with self.db.connect() as conn:
58 conn.execute("""
59 CREATE TABLE IF NOT EXISTS download_log (
60 id INTEGER PRIMARY KEY AUTOINCREMENT,
61 at TEXT NOT NULL,
62 outcome TEXT NOT NULL,
63 provider TEXT NOT NULL DEFAULT '',
64 bytes INTEGER NOT NULL DEFAULT 0,
65 filename TEXT NOT NULL DEFAULT ''
66 )
67 """)
68 conn.execute(
69 'CREATE INDEX IF NOT EXISTS idx_download_log_at '
70 'ON download_log (at)'
71 )
73 def _connect(self):
74 return self.db.connect()
76 def record(
77 self,
78 outcome: str,
79 *,
80 provider: str = '',
81 size: int = 0,
82 filename: str = '',
83 at: Optional[datetime] = None,
84 ) -> None:
85 """Note how one download ended; an unknown *outcome* is ignored."""
87 if outcome not in OUTCOMES:
88 return
89 with self._connect() as conn:
90 conn.execute(
91 'INSERT INTO download_log (at, outcome, provider, bytes, '
92 'filename) VALUES (?, ?, ?, ?, ?)',
93 (
94 (at or _now()).isoformat(),
95 outcome,
96 str(provider or '')[:32],
97 max(0, int(size or 0)),
98 str(filename or '')[:1000],
99 ),
100 )
102 def since(self, moment: datetime) -> list[dict[str, Any]]:
103 """Every row from *moment* on, oldest first."""
105 with self._connect() as conn:
106 rows = conn.execute(
107 'SELECT at, outcome, provider, bytes FROM download_log '
108 'WHERE at >= ? ORDER BY at',
109 (moment.isoformat(),),
110 ).fetchall()
111 return [
112 {
113 'at': row[0],
114 'outcome': row[1],
115 'provider': row[2],
116 'bytes': int(row[3]),
117 }
118 for row in rows
119 ]
121 def first_at(self) -> Optional[str]:
122 """When the oldest row still kept was written, if any."""
124 with self._connect() as conn:
125 row = conn.execute('SELECT MIN(at) FROM download_log').fetchone()
126 return row[0] if row and row[0] else None
128 def prune(self, days: int = RETENTION_DAYS) -> int:
129 cutoff = (_now() - timedelta(days=days)).isoformat()
130 with self._connect() as conn:
131 deleted = conn.execute(
132 'DELETE FROM download_log WHERE at < ?', (cutoff,)
133 ).rowcount
134 conn.commit()
135 return deleted