Coverage for downtify/library_import.py: 98%

49 statements  

« prev     ^ index     » next       coverage.py v7.17.4, created at 2026-11-21 22:18 +0000

1"""Parse library-export CSV files (Soundiiz, TuneMyMusic, Exportify, ...) 

2into song dicts the download pipeline can resolve. 

3 

4These tools all export "one row per track" CSVs, but use different column 

5names for the same data (e.g. Exportify's ``Track Name`` / ``Artist 

6Name(s)`` vs. a plain ``Title`` / ``Artist``). Rather than hard-coding one 

7tool's schema, headers are matched case-insensitively against a set of 

8known aliases, so the same importer works across exporters without the 

9user needing to rename columns. 

10 

11Title and artist are required. Album is copied onto ``album_name`` 

12when the CSV has a recognizable album column (Exportify's 

13``Album Name``, TuneMyMusic / Soundiiz ``Album``, ...). Other columns 

14some exporters include (ISRC, a Spotify track URI, duration) aren't 

15used here. Each row still goes through the same YouTube-Music 

16matching (:func:`downtify.providers.find_match`) that a free-text 

17search does today. 

18""" 

19 

20from __future__ import annotations 

21 

22import csv 

23import io 

24import re 

25from typing import Any 

26 

27MAX_CSV_ROWS = 5000 

28 

29_TITLE_HEADERS = { 

30 'title', 

31 'track', 

32 'track title', 

33 'track name', 

34 'song', 

35 'song title', 

36 'song name', 

37 'name', 

38} 

39_ARTIST_HEADERS = { 

40 'artist', 

41 'artists', 

42 'artist name', 

43 'artist name(s)', 

44 'track artist', 

45 'song artist', 

46 'performer', 

47} 

48_ALBUM_HEADERS = { 

49 'album', 

50 'album name', 

51 'album title', 

52 'release', 

53 'release name', 

54} 

55 

56_ARTIST_SPLIT_RE = re.compile(r'[,;]') 

57 

58 

59class LibraryCsvError(ValueError): 

60 """Raised when a CSV can't be parsed into track/artist rows.""" 

61 

62 

63def _find_column(fieldnames: list[str], aliases: set[str]) -> str | None: 

64 for name in fieldnames: 

65 if name and name.strip().lower() in aliases: 

66 return name 

67 return None 

68 

69 

70def _sniff_dialect(sample: str) -> type[csv.Dialect]: 

71 try: 

72 return csv.Sniffer().sniff(sample, delimiters=',;\t') 

73 except csv.Error: 

74 return csv.excel 

75 

76 

77def parse_library_csv(text: str) -> list[dict[str, Any]]: 

78 """Parse *text* (a CSV file's decoded content) into song dicts. 

79 

80 Each returned dict has ``name`` (track title), ``artists`` (a list 

81 of one or more artist names), a synthetic ``song_id`` (``csv:0``, 

82 ``csv:1``, ...), and ``album_name`` when the CSV has a non-empty 

83 album cell. ``name``/``artists`` are the minimum shape 

84 :meth:`downtify.downloader.Downloader.download` needs to resolve a 

85 track via YouTube Music search when no direct video/Spotify URL is 

86 known; ``album_name`` is optional and is omitted rather than set 

87 blank so YouTube Music can still fill it. ``song_id`` exists 

88 because the frontend's queue/progress tracking keys every song by 

89 it and would otherwise conflate every CSV row of one file into a 

90 single entry. They restart at ``csv:0`` on each call. 

91 ``POST /api/download/csv`` replaces them with a per-import token 

92 before the rows are queued, so two files do not share queue keys. 

93 

94 Raises :class:`LibraryCsvError` when the file has no rows, or its 

95 header doesn't contain a recognizable title and artist column, or 

96 it exceeds :data:`MAX_CSV_ROWS` rows (a sanity cap, not a real-world 

97 library size limit). 

98 """ 

99 dialect = _sniff_dialect(text[:4096]) 

100 reader = csv.DictReader(io.StringIO(text), dialect=dialect) 

101 fieldnames = reader.fieldnames or [] 

102 title_col = _find_column(fieldnames, _TITLE_HEADERS) 

103 artist_col = _find_column(fieldnames, _ARTIST_HEADERS) 

104 album_col = _find_column(fieldnames, _ALBUM_HEADERS) 

105 if not title_col or not artist_col: 

106 raise LibraryCsvError( 

107 'Could not find title/artist columns in the CSV. ' 

108 f'Columns found: {", ".join(fieldnames) or "(none)"}' 

109 ) 

110 

111 songs: list[dict[str, Any]] = [] 

112 for row in reader: 

113 if len(songs) >= MAX_CSV_ROWS: 

114 raise LibraryCsvError( 

115 f'CSV has more than {MAX_CSV_ROWS} rows; split it into ' 

116 'smaller files and import them separately.' 

117 ) 

118 title = (row.get(title_col) or '').strip() 

119 artist_field = (row.get(artist_col) or '').strip() 

120 if not title or not artist_field: 

121 continue 

122 artists = [ 

123 a.strip() 

124 for a in _ARTIST_SPLIT_RE.split(artist_field) 

125 if a.strip() 

126 ] 

127 if not artists: 

128 continue 

129 song: dict[str, Any] = { 

130 'song_id': f'csv:{len(songs)}', 

131 'name': title, 

132 'artists': artists, 

133 } 

134 album = (row.get(album_col) or '').strip() if album_col else '' 

135 if album: 

136 song['album_name'] = album 

137 songs.append(song) 

138 

139 if not songs: 

140 raise LibraryCsvError('No track/artist rows found in the CSV.') 

141 return songs