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

1"""How every download ended, for the library usage page. 

2 

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`. 

9 

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""" 

16 

17from __future__ import annotations 

18 

19from datetime import datetime, timedelta, timezone 

20from pathlib import Path 

21from typing import Any, Optional 

22 

23from .db.config import Dialect 

24from .db.core import Database, as_database 

25 

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' 

32 

33OUTCOMES = (OUTCOME_COMPLETED, OUTCOME_SKIPPED, OUTCOME_FAILED) 

34 

35#: Long enough for the longest period the usage page shows (a year). 

36RETENTION_DAYS = 400 

37 

38 

39def _now() -> datetime: 

40 return datetime.now(timezone.utc) 

41 

42 

43class DownloadLog: 

44 """One row per download attempt, oldest dropped after a while.""" 

45 

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() 

54 

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 ) 

72 

73 def _connect(self): 

74 return self.db.connect() 

75 

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.""" 

86 

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 ) 

101 

102 def since(self, moment: datetime) -> list[dict[str, Any]]: 

103 """Every row from *moment* on, oldest first.""" 

104 

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 ] 

120 

121 def first_at(self) -> Optional[str]: 

122 """When the oldest row still kept was written, if any.""" 

123 

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 

127 

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