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
« 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.
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.
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"""
20from __future__ import annotations
22import csv
23import io
24import re
25from typing import Any
27MAX_CSV_ROWS = 5000
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}
56_ARTIST_SPLIT_RE = re.compile(r'[,;]')
59class LibraryCsvError(ValueError):
60 """Raised when a CSV can't be parsed into track/artist rows."""
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
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
77def parse_library_csv(text: str) -> list[dict[str, Any]]:
78 """Parse *text* (a CSV file's decoded content) into song dicts.
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.
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 )
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)
139 if not songs:
140 raise LibraryCsvError('No track/artist rows found in the CSV.')
141 return songs