scrobbles 0.1.0__py3-none-any.whl

scrobbles/__init__.py

@@ -0,0 +1,76 @@
+# scrobbles/__init__.py
+#
+# You have to have your own unique two values for API_KEY and API_SECRET
+# Obtain yours from https://www.last.fm/api/account for Last.fm
+
+import os
+import sys
+import pylast
+
+API_KEY = os.environ["LASTFM_API_KEY"]
+API_SECRET = os.environ["LASTFM_API_SECRET"]
+username = os.environ["LASTFM_USERNAME"]
+password = os.environ["LASTFM_PASSWORD"]
+password_hash = pylast.md5(password)
+network = pylast.LastFMNetwork(
+    api_key=API_KEY,
+    api_secret=API_SECRET,
+    username=username,
+    password_hash=password_hash,
+)
+
+TRACK_SEPARATOR = " - "
+
+
+def get_user(network: pylast.LastFMNetwork, username: str) -> pylast.User:
+    return network.get_user(username)
+
+
+def track_and_timestamp(track):
+    return f"{track.playback_date}\t{track.track}"
+
+
+def print_track(track):
+    print(track_and_timestamp(track))
+
+
+def split_artist_track(artist_track):
+    artist_track = artist_track.replace(" – ", " - ")
+    artist_track = artist_track.replace("“", '"')
+    artist_track = artist_track.replace("”", '"')
+
+    (artist, track) = artist_track.split(TRACK_SEPARATOR)
+    artist = artist.strip()
+    track = track.strip()
+    print("Artist:\t\t'" + artist + "'")
+    print("Track:\t\t'" + track + "'")
+
+    # Validate
+    if len(artist) == 0 and len(track) == 0:
+        sys.exit("Error: Artist and track are blank")
+    if len(artist) == 0:
+        sys.exit("Error: Artist is blank")
+    if len(track) == 0:
+        sys.exit("Error: Track is blank")
+
+    return (artist, track)
+
+
+def get_now_playing(username: str) -> str:
+    user = get_user(network, username)
+    now_playing = user.get_now_playing()
+    if now_playing is None:
+        return "Nothing is currently playing."
+    return f"Now playing: {now_playing.artist} - {now_playing.title}"
+
+
+def get_recent_tracks(username, number):
+    recent_tracks = network.get_user(username).get_recent_tracks(limit=number)
+    for i, track in enumerate(recent_tracks):
+        printable = track_and_timestamp(track)
+        print(str(i + 1) + " " + printable)
+    return recent_tracks
+
+
+from scrobbles.albums import build_dashboard, dump_top_albums, get_top_albums, print_top_albums
+from scrobbles.spotify import create_all_playlists, create_playlist_from_albums

scrobbles/albums.py

@@ -0,0 +1,392 @@
+# scrobbles/albums.py
+"""Fetch and display top albums for a Last.fm user."""
+
+import json
+import re
+from datetime import datetime, timedelta
+from pathlib import Path
+
+import pylast
+
+from scrobbles import network
+
+_PREDEFINED_PERIODS = {
+    "overall": pylast.PERIOD_OVERALL,
+    "7day": pylast.PERIOD_7DAYS,
+    "1month": pylast.PERIOD_1MONTH,
+    "3month": pylast.PERIOD_3MONTHS,
+    "6month": pylast.PERIOD_6MONTHS,
+    "12month": pylast.PERIOD_12MONTHS,
+}
+
+
+def _resolve_date_range(period: str) -> tuple[str, str]:
+    """Convert a human-readable period string to (from_ts, to_ts) Unix timestamps."""
+    now = datetime.now()
+    today = now.replace(hour=0, minute=0, second=0, microsecond=0)
+
+    if period == "today":
+        start, end = today, now
+    elif period == "yesterday":
+        start = today - timedelta(days=1)
+        end = today
+    elif period == "last_week":
+        # Monday of this week, then back 7 days
+        monday = today - timedelta(days=today.weekday())
+        start = monday - timedelta(weeks=1)
+        end = monday
+    elif period == "last_month":
+        first_of_month = today.replace(day=1)
+        end = first_of_month
+        # First of previous month
+        prev = first_of_month - timedelta(days=1)
+        start = prev.replace(day=1)
+    elif period == "last_year":
+        start = today.replace(month=1, day=1, year=today.year - 1)
+        end = today.replace(month=1, day=1)
+    elif re.fullmatch(r"\d{4}", period):
+        year = int(period)
+        start = today.replace(year=year, month=1, day=1)
+        end = today.replace(year=year + 1, month=1, day=1)
+    elif re.fullmatch(r"\d{4}-\d{2}", period):
+        year, month = (int(x) for x in period.split("-"))
+        start = today.replace(year=year, month=month, day=1)
+        if month == 12:
+            end = today.replace(year=year + 1, month=1, day=1)
+        else:
+            end = today.replace(year=year, month=month + 1, day=1)
+    elif re.fullmatch(r"\d{4}-\d{2}-\d{2}", period):
+        year, month, day = (int(x) for x in period.split("-"))
+        start = today.replace(year=year, month=month, day=day)
+        end = start + timedelta(days=1)
+    else:
+        raise ValueError(
+            f"Unrecognized period: {period!r}. "
+            f"Use a predefined period ({', '.join(_PREDEFINED_PERIODS)}), "
+            "or: today, yesterday, last_week, last_month, last_year, "
+            "YYYY, YYYY-MM, YYYY-MM-DD"
+        )
+
+    return str(int(start.timestamp())), str(int(end.timestamp()))
+
+
+def get_top_albums(username: str, period: str = "overall", limit: int = 10):
+    """Return top albums for a user over the given period."""
+    user = network.get_user(username)
+
+    if period in _PREDEFINED_PERIODS:
+        return user.get_top_albums(period=_PREDEFINED_PERIODS[period], limit=limit)
+
+    from_date, to_date = _resolve_date_range(period)
+    charts = user.get_weekly_album_charts(from_date=from_date, to_date=to_date)
+    charts.sort(key=lambda item: int(item.weight), reverse=True)
+    return charts[:limit]
+
+
+def format_top_albums(items) -> str:
+    """Format album items as a numbered list."""
+    lines = []
+    for i, item in enumerate(items, 1):
+        lines.append(f"{i}. {item.item.artist} - {item.item.title} ({item.weight} plays)")
+    return "\n".join(lines)
+
+
+def print_top_albums(username: str, period: str = "overall", limit: int = 10):
+    """Fetch, print, and return top albums for a user."""
+    items = get_top_albums(username, period, limit)
+    print(format_top_albums(items))
+    return items
+
+
+def top_item_to_dict(item) -> dict:
+    """Convert a pylast TopItem to a plain dict."""
+    return {
+        "artist": str(item.item.artist),
+        "album": str(item.item.title),
+        "plays": int(item.weight),
+    }
+
+
+def top_albums_to_json(items, **kwargs) -> str:
+    """Serialize a list of TopItems to a JSON string."""
+    return json.dumps([top_item_to_dict(i) for i in items], **kwargs)
+
+
+def dump_top_albums(
+    username: str,
+    period: str = "overall",
+    limit: int = 10,
+    path: str | Path | None = None,
+) -> Path:
+    """Fetch top albums and write them to a JSON file.
+
+    If path is None, writes to data/albums/topN-{period}.json
+    relative to the project root.
+    """
+    items = get_top_albums(username, period, limit)
+    if path is None:
+        path = Path("data/albums") / f"top{limit}-{period}.json"
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(top_albums_to_json(items, indent=2) + "\n")
+    print(f"Wrote {len(items)} albums to {path}")
+    return path
+
+
+def build_dashboard(data_dir: str | Path = "data/albums", output: str | Path | None = None) -> Path:
+    """Generate an interactive HTML dashboard from the JSON data files.
+
+    Reads all top100-*.json from *data_dir*, embeds the data inline,
+    and writes a self-contained HTML file with Chart.js charts, a year
+    selector, search, and a dark-themed album table.
+
+    Returns the output path.
+    """
+    data_dir = Path(data_dir)
+    if output is None:
+        output = data_dir / "index.html"
+    output = Path(output)
+
+    # Collect all top100 JSON files into a single {year: [...]} dict
+    all_data: dict[str, list[dict]] = {}
+    for f in sorted(data_dir.glob("top100-*.json")):
+        year = f.stem.split("-", 1)[1]
+        all_data[year] = json.loads(f.read_text())
+
+    if not all_data:
+        raise FileNotFoundError(f"No top100-*.json files found in {data_dir}")
+
+    years = sorted(all_data.keys())
+    data_blob = json.dumps(all_data, separators=(",", ":"))
+
+    html = f"""\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Last.fm Top Albums</title>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
+<style>
+  :root {{
+    --bg: #0d1117; --surface: #161b22; --border: #30363d;
+    --text: #e6edf3; --text-muted: #8b949e; --accent: #58a6ff;
+    --accent2: #f78166; --accent3: #7ee787; --accent4: #d2a8ff;
+  }}
+  * {{ box-sizing: border-box; margin: 0; padding: 0; }}
+  body {{
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    background: var(--bg); color: var(--text); line-height: 1.5;
+    padding: 2rem; max-width: 1200px; margin: 0 auto;
+  }}
+  h1 {{ font-size: 2rem; margin-bottom: 0.25rem; }}
+  .subtitle {{ color: var(--text-muted); margin-bottom: 2rem; font-size: 0.95rem; }}
+  .cards {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 1rem; margin-bottom: 2rem; }}
+  .card {{
+    background: var(--surface); border: 1px solid var(--border); border-radius: 8px;
+    padding: 1rem; text-align: center;
+  }}
+  .card .value {{ font-size: 1.8rem; font-weight: 700; color: var(--accent); }}
+  .card .label {{ font-size: 0.8rem; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.05em; }}
+  .chart-row {{ display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; margin-bottom: 2rem; }}
+  .chart-box {{
+    background: var(--surface); border: 1px solid var(--border); border-radius: 8px;
+    padding: 1.25rem;
+  }}
+  .chart-box h3 {{ font-size: 0.95rem; color: var(--text-muted); margin-bottom: 0.75rem; }}
+  .chart-box canvas {{ width: 100% !important; }}
+  .year-bar {{ display: flex; flex-wrap: wrap; gap: 0.5rem; margin-bottom: 1.5rem; }}
+  .year-btn {{
+    background: var(--surface); border: 1px solid var(--border); border-radius: 6px;
+    color: var(--text-muted); padding: 0.4rem 0.9rem; cursor: pointer; font-size: 0.85rem;
+    transition: all 0.15s;
+  }}
+  .year-btn:hover {{ border-color: var(--accent); color: var(--text); }}
+  .year-btn.active {{ background: var(--accent); color: var(--bg); border-color: var(--accent); font-weight: 600; }}
+  .table-wrap {{ background: var(--surface); border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }}
+  table {{ width: 100%; border-collapse: collapse; }}
+  th {{ text-align: left; padding: 0.75rem 1rem; font-size: 0.75rem; text-transform: uppercase;
+       letter-spacing: 0.05em; color: var(--text-muted); border-bottom: 1px solid var(--border); }}
+  td {{ padding: 0.6rem 1rem; border-bottom: 1px solid var(--border); font-size: 0.9rem; }}
+  tr:last-child td {{ border-bottom: none; }}
+  tr:hover td {{ background: rgba(88,166,255,0.05); }}
+  .rank {{ color: var(--text-muted); font-weight: 600; width: 3rem; }}
+  .plays {{ text-align: right; font-variant-numeric: tabular-nums; font-weight: 600; color: var(--accent3); }}
+  .bar-cell {{ width: 30%; }}
+  .bar-bg {{ background: var(--border); border-radius: 3px; height: 6px; }}
+  .bar-fill {{ background: var(--accent); border-radius: 3px; height: 6px; transition: width 0.3s; }}
+  .artist-col {{ color: var(--text-muted); }}
+  .top-artists {{ display: flex; flex-wrap: wrap; gap: 0.5rem; margin-bottom: 2rem; }}
+  .artist-badge {{
+    background: var(--surface); border: 1px solid var(--border); border-radius: 20px;
+    padding: 0.35rem 0.85rem; font-size: 0.82rem; display: flex; align-items: center; gap: 0.4rem;
+  }}
+  .artist-badge .count {{ color: var(--accent); font-weight: 600; }}
+  .search-wrap {{ margin-bottom: 1rem; }}
+  .search-wrap input {{
+    background: var(--surface); border: 1px solid var(--border); border-radius: 6px;
+    color: var(--text); padding: 0.5rem 0.75rem; font-size: 0.9rem; width: 100%; max-width: 360px;
+    outline: none;
+  }}
+  .search-wrap input:focus {{ border-color: var(--accent); }}
+  .search-wrap input::placeholder {{ color: var(--text-muted); }}
+  .year-stats {{ color: var(--text-muted); font-size: 0.85rem; margin-bottom: 1rem; }}
+  @media (max-width: 700px) {{ .chart-row {{ grid-template-columns: 1fr; }} body {{ padding: 1rem; }} }}
+</style>
+</head>
+<body>
+
+<h1>Last.fm Top Albums</h1>
+<p class="subtitle">Top 100 albums per year &middot; {years[0]} &ndash; {years[-1]}</p>
+
+<div class="cards" id="cards"></div>
+<div class="chart-row">
+  <div class="chart-box"><h3>Total Plays per Year (Top 100)</h3><canvas id="chartPlays"></canvas></div>
+  <div class="chart-box"><h3>Unique Artists per Year (Top 100)</h3><canvas id="chartArtists"></canvas></div>
+</div>
+<div class="chart-row">
+  <div class="chart-box"><h3>#1 Album Plays by Year</h3><canvas id="chartTop1"></canvas></div>
+  <div class="chart-box"><h3>Top 10 Artists (All Time by Appearances)</h3><canvas id="chartTopArtists"></canvas></div>
+</div>
+
+<h3 style="margin-bottom:0.75rem;">Albums by Year</h3>
+<div class="year-bar" id="yearBar"></div>
+<div class="search-wrap"><input type="text" id="search" placeholder="Filter by artist or album..."></div>
+<p class="year-stats" id="yearStats"></p>
+<h4 style="margin-bottom:0.5rem; color:var(--text-muted); font-size:0.8rem;">TOP ARTISTS THIS YEAR</h4>
+<div class="top-artists" id="topArtists"></div>
+<div class="table-wrap">
+<table>
+  <thead><tr><th>#</th><th>Album</th><th>Artist</th><th></th><th>Plays</th></tr></thead>
+  <tbody id="tbody"></tbody>
+</table>
+</div>
+
+<script>
+const DATA = {data_blob};
+
+const years = Object.keys(DATA).sort();
+let activeYear = years[years.length - 2];
+
+let totalPlaysAll = 0, totalAlbumsAll = 0;
+const allArtists = new Set();
+const artistYearCount = {{}};
+const yearStatsMap = {{}};
+
+years.forEach(y => {{
+  const albums = DATA[y];
+  const plays = albums.reduce((s, a) => s + a.plays, 0);
+  const artists = new Set(albums.map(a => a.artist));
+  totalPlaysAll += plays;
+  totalAlbumsAll += albums.length;
+  artists.forEach(a => {{ allArtists.add(a); artistYearCount[a] = (artistYearCount[a] || 0) + 1; }});
+  yearStatsMap[y] = {{ plays, artistCount: artists.size, top: albums[0] }};
+}});
+
+document.getElementById('cards').innerHTML = `
+  <div class="card"><div class="value">${{totalPlaysAll.toLocaleString()}}</div><div class="label">Total Plays</div></div>
+  <div class="card"><div class="value">${{years.length}}</div><div class="label">Years</div></div>
+  <div class="card"><div class="value">${{allArtists.size}}</div><div class="label">Unique Artists</div></div>
+  <div class="card"><div class="value">${{totalAlbumsAll.toLocaleString()}}</div><div class="label">Album Entries</div></div>
+`;
+
+const chartOpts = (ylabel) => ({{
+  responsive: true, plugins: {{ legend: {{ display: false }} }},
+  scales: {{
+    x: {{ ticks: {{ color: '#8b949e' }}, grid: {{ color: '#21262d' }} }},
+    y: {{ ticks: {{ color: '#8b949e' }}, grid: {{ color: '#21262d' }}, title: {{ display: true, text: ylabel, color: '#8b949e' }} }}
+  }}
+}});
+
+new Chart(document.getElementById('chartPlays'), {{
+  type: 'bar',
+  data: {{ labels: years, datasets: [{{ data: years.map(y => yearStatsMap[y].plays), backgroundColor: '#58a6ff88', borderColor: '#58a6ff', borderWidth: 1, borderRadius: 4 }}] }},
+  options: chartOpts('Plays')
+}});
+
+new Chart(document.getElementById('chartArtists'), {{
+  type: 'bar',
+  data: {{ labels: years, datasets: [{{ data: years.map(y => yearStatsMap[y].artistCount), backgroundColor: '#7ee78788', borderColor: '#7ee787', borderWidth: 1, borderRadius: 4 }}] }},
+  options: chartOpts('Artists')
+}});
+
+new Chart(document.getElementById('chartTop1'), {{
+  type: 'bar',
+  data: {{
+    labels: years.map(y => `${{y}}: ${{yearStatsMap[y].top.artist}}`),
+    datasets: [{{ data: years.map(y => yearStatsMap[y].top.plays), backgroundColor: '#d2a8ff88', borderColor: '#d2a8ff', borderWidth: 1, borderRadius: 4 }}]
+  }},
+  options: {{ ...chartOpts('Plays'),
+    scales: {{ ...chartOpts('Plays').scales, x: {{ ...chartOpts('Plays').scales.x, ticks: {{ ...chartOpts('Plays').scales.x.ticks, maxRotation: 45, minRotation: 45, font: {{ size: 10 }} }} }} }}
+  }}
+}});
+
+const topArtistsSorted = Object.entries(artistYearCount).sort((a, b) => b[1] - a[1]).slice(0, 10);
+new Chart(document.getElementById('chartTopArtists'), {{
+  type: 'bar',
+  data: {{
+    labels: topArtistsSorted.map(a => a[0]),
+    datasets: [{{ data: topArtistsSorted.map(a => a[1]), backgroundColor: '#f7816688', borderColor: '#f78166', borderWidth: 1, borderRadius: 4 }}]
+  }},
+  options: {{ indexAxis: 'y', ...chartOpts('Year Appearances'),
+    scales: {{ x: {{ ticks: {{ color: '#8b949e', stepSize: 1 }}, grid: {{ color: '#21262d' }}, title: {{ display: true, text: 'Year Appearances', color: '#8b949e' }} }},
+              y: {{ ticks: {{ color: '#8b949e' }}, grid: {{ color: '#21262d' }} }} }}
+  }}
+}});
+
+function renderYear(year, filter = '') {{
+  activeYear = year;
+  document.querySelectorAll('.year-btn').forEach(b => b.classList.toggle('active', b.dataset.year === year));
+
+  const albums = DATA[year];
+  const maxPlays = albums[0]?.plays || 1;
+  const q = filter.toLowerCase();
+  const filtered = q ? albums.filter(a => a.artist.toLowerCase().includes(q) || a.album.toLowerCase().includes(q)) : albums;
+
+  const stats = yearStatsMap[year];
+  document.getElementById('yearStats').textContent =
+    `${{stats.plays.toLocaleString()}} plays \\u00b7 ${{stats.artistCount}} unique artists \\u00b7 #1: ${{stats.top.artist}} \\u2013 ${{stats.top.album}} (${{stats.top.plays}} plays)`;
+
+  const artistPlays = {{}};
+  albums.forEach(a => {{ artistPlays[a.artist] = (artistPlays[a.artist] || 0) + a.plays; }});
+  const topA = Object.entries(artistPlays).sort((a, b) => b[1] - a[1]).slice(0, 8);
+  document.getElementById('topArtists').innerHTML = topA.map(([name, plays]) =>
+    `<span class="artist-badge">${{name}} <span class="count">${{plays}}</span></span>`
+  ).join('');
+
+  const tbody = document.getElementById('tbody');
+  tbody.innerHTML = filtered.map((a, i) => {{
+    const origIdx = albums.indexOf(a) + 1;
+    const pct = (a.plays / maxPlays * 100).toFixed(1);
+    return `<tr>
+      <td class="rank">${{origIdx}}</td>
+      <td>${{a.album}}</td>
+      <td class="artist-col">${{a.artist}}</td>
+      <td class="bar-cell"><div class="bar-bg"><div class="bar-fill" style="width:${{pct}}%"></div></div></td>
+      <td class="plays">${{a.plays}}</td>
+    </tr>`;
+  }}).join('');
+}}
+
+const yearBar = document.getElementById('yearBar');
+years.forEach(y => {{
+  const btn = document.createElement('button');
+  btn.className = 'year-btn';
+  btn.dataset.year = y;
+  btn.textContent = y;
+  btn.onclick = () => renderYear(y, document.getElementById('search').value);
+  yearBar.appendChild(btn);
+}});
+
+document.getElementById('search').addEventListener('input', e => renderYear(activeYear, e.target.value));
+
+renderYear(activeYear);
+</script>
+</body>
+</html>
+"""
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(html)
+    print(f"Wrote dashboard to {output} ({len(all_data)} years)")
+    return output

scrobbles/cli.py

@@ -0,0 +1,95 @@
+"""CLI for scrobbles."""
+
+import sys
+
+USAGE = """\
+Usage: scrobbles <command> [options]
+
+Commands:
+  top-albums [period] [--limit N]          Print top albums
+  dump-albums [period] [--limit N]         Export top albums to JSON
+  dashboard                                Generate HTML dashboard
+  spotify-playlists [--dry-run] [--skip YEAR...]  Create Spotify playlists
+"""
+
+
+def _parse_args(argv: list[str], defaults: dict) -> dict:
+    """Minimal argv parser. Supports --key value and --flag patterns."""
+    opts = dict(defaults)
+    i = 0
+    positional_keys = [k for k in defaults if not k.startswith("_")]
+    pos_idx = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--limit" and i + 1 < len(argv):
+            opts["limit"] = int(argv[i + 1])
+            i += 2
+        elif arg == "--dry-run":
+            opts["dry_run"] = True
+            i += 1
+        elif arg == "--skip":
+            i += 1
+            skip = []
+            while i < len(argv) and not argv[i].startswith("--"):
+                skip.append(argv[i])
+                i += 1
+            opts["skip"] = skip
+        elif not arg.startswith("--") and pos_idx < len(positional_keys):
+            opts[positional_keys[pos_idx]] = arg
+            pos_idx += 1
+            i += 1
+        else:
+            i += 1
+    return opts
+
+
+def cmd_top_albums(argv: list[str]):
+    import os
+    from scrobbles.albums import print_top_albums
+
+    opts = _parse_args(argv, {"period": "overall", "limit": 10})
+    username = os.environ["LASTFM_USERNAME"]
+    print_top_albums(username, period=opts["period"], limit=opts["limit"])
+
+
+def cmd_dump_albums(argv: list[str]):
+    import os
+    from scrobbles.albums import dump_top_albums
+
+    opts = _parse_args(argv, {"period": "overall", "limit": 100})
+    username = os.environ["LASTFM_USERNAME"]
+    dump_top_albums(username, period=opts["period"], limit=opts["limit"])
+
+
+def cmd_dashboard(argv: list[str]):
+    from scrobbles.albums import build_dashboard
+
+    build_dashboard()
+
+
+def cmd_spotify_playlists(argv: list[str]):
+    from scrobbles.spotify import create_all_playlists
+
+    opts = _parse_args(argv, {"dry_run": False, "skip": []})
+    create_all_playlists(dry_run=opts["dry_run"], skip_years=set(opts["skip"]))
+
+
+def main():
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
+        print(USAGE)
+        sys.exit(0)
+
+    commands = {
+        "top-albums": cmd_top_albums,
+        "dump-albums": cmd_dump_albums,
+        "dashboard": cmd_dashboard,
+        "spotify-playlists": cmd_spotify_playlists,
+    }
+
+    cmd = sys.argv[1]
+    if cmd not in commands:
+        print(f"Unknown command: {cmd}\n")
+        print(USAGE)
+        sys.exit(1)
+
+    commands[cmd](sys.argv[2:])

scrobbles/spotify.py

@@ -0,0 +1,164 @@
+# scrobbles/spotify.py
+"""Create Spotify playlists from Last.fm top-album JSON data."""
+
+import json
+import os
+import time
+from pathlib import Path
+
+import spotipy
+from spotipy.oauth2 import SpotifyOAuth
+
+
+def get_spotify_env():
+    """Set SPOTIPY_* env vars from SPOTIFY_* if needed.
+
+    Spotipy reads SPOTIPY_CLIENT_ID / SPOTIPY_CLIENT_SECRET automatically,
+    but many users export SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET instead.
+    This bridges the gap so either naming convention works.
+    """
+    mapping = {
+        "SPOTIPY_CLIENT_ID": "SPOTIFY_CLIENT_ID",
+        "SPOTIPY_CLIENT_SECRET": "SPOTIFY_CLIENT_SECRET",
+    }
+    for spotipy_key, alt_key in mapping.items():
+        if not os.environ.get(spotipy_key) and os.environ.get(alt_key):
+            os.environ[spotipy_key] = os.environ[alt_key]
+
+
+def get_spotify_client() -> spotipy.Spotify:
+    """Authenticate and return a Spotify client with playlist-modify scope."""
+    get_spotify_env()
+    return spotipy.Spotify(auth_manager=SpotifyOAuth(
+        scope="playlist-modify-public playlist-modify-private",
+    ))
+
+
+def _truncate_query(query: str, max_len: int = 240) -> str:
+    """Truncate a search query to fit Spotify's 250-char limit."""
+    if len(query) <= max_len:
+        return query
+    return query[:max_len]
+
+
+def search_album_tracks(sp: spotipy.Spotify, artist: str, album: str) -> list[str]:
+    """Search Spotify for an album and return its track URIs."""
+    try:
+        query = _truncate_query(f"album:{album} artist:{artist}")
+        results = sp.search(q=query, type="album", limit=5)
+        items = results["albums"]["items"]
+        if not items:
+            # Fallback: broader search without field prefixes
+            query = _truncate_query(f"{artist} {album}")
+            results = sp.search(q=query, type="album", limit=5)
+            items = results["albums"]["items"]
+        if not items:
+            return []
+
+        # Pick the best match (first result)
+        album_id = items[0]["id"]
+        tracks = sp.album_tracks(album_id)
+        return [t["uri"] for t in tracks["items"]]
+    except Exception:
+        return []
+
+
+def create_playlist_from_albums(
+    albums: list[dict],
+    name: str,
+    description: str = "",
+    dry_run: bool = False,
+) -> dict:
+    """Create a Spotify playlist from a list of album dicts.
+
+    Each dict should have ``artist``, ``album``, and ``plays`` keys.
+    Returns a summary dict with playlist URL, track count, and missed albums.
+    """
+    sp = get_spotify_client()
+    user_id = sp.current_user()["id"]
+
+    all_uris: list[str] = []
+    missed: list[str] = []
+
+    for i, entry in enumerate(albums):
+        artist, album_name, plays = entry["artist"], entry["album"], entry["plays"]
+        print(f"  [{i+1:3d}/{len(albums)}] {artist} - {album_name} ({plays} plays) ... ", end="", flush=True)
+
+        track_uris = search_album_tracks(sp, artist, album_name)
+        if track_uris:
+            all_uris.extend(track_uris)
+            print(f"{len(track_uris)} tracks")
+        else:
+            missed.append(f"{artist} - {album_name}")
+            print("NOT FOUND")
+
+        time.sleep(0.1)
+
+    if dry_run:
+        print(f"  [DRY RUN] Would create '{name}' with {len(all_uris)} tracks ({len(missed)} albums not found)")
+        return {"name": name, "tracks": len(all_uris), "missed": missed, "url": None}
+
+    playlist = sp.user_playlist_create(user_id, name, public=False, description=description)
+    playlist_url = playlist["external_urls"]["spotify"]
+    print(f"  Created playlist: {playlist_url}")
+
+    for batch_start in range(0, len(all_uris), 100):
+        batch = all_uris[batch_start:batch_start + 100]
+        sp.playlist_add_items(playlist["id"], batch)
+
+    print(f"  Added {len(all_uris)} tracks ({len(missed)} albums not found)")
+    return {"name": name, "tracks": len(all_uris), "missed": missed, "url": playlist_url}
+
+
+def create_year_playlist(
+    year: str,
+    albums: list[dict],
+    dry_run: bool = False,
+) -> dict:
+    """Create a Spotify playlist for one year of top albums.
+
+    Thin wrapper around :func:`create_playlist_from_albums`.
+    """
+    name = f"Last.fm Top 100 Albums — {year}"
+    description = f"Top 100 most-played albums of {year} from Last.fm, all tracks included."
+    result = create_playlist_from_albums(albums, name, description, dry_run=dry_run)
+    result["year"] = year
+    return result
+
+
+def create_all_playlists(
+    data_dir: str | Path = "data/albums",
+    dry_run: bool = False,
+    skip_years: set[str] | None = None,
+) -> list[dict]:
+    """Create Spotify playlists for every top100-YYYY.json file."""
+    data_dir = Path(data_dir)
+    skip_years = skip_years or set()
+
+    results = []
+    for f in sorted(data_dir.glob("top100-*.json")):
+        year = f.stem.split("-")[1]
+        if year in skip_years:
+            print(f"\n  Skipping {year} (already created)")
+            continue
+        albums = json.loads(f.read_text())
+        print(f"\n{'='*60}")
+        print(f" {year} — {len(albums)} albums")
+        print(f"{'='*60}")
+        result = create_year_playlist(year, albums, dry_run=dry_run)
+        results.append(result)
+
+    # Summary
+    print(f"\n{'='*60}")
+    print(" SUMMARY")
+    print(f"{'='*60}")
+    total_tracks = 0
+    total_missed = 0
+    for r in results:
+        status = r["url"] or "DRY RUN"
+        print(f"  {r['year']}: {r['tracks']} tracks, {len(r['missed'])} missed — {status}")
+        total_tracks += r["tracks"]
+        total_missed += len(r["missed"])
+    print(f"\n  Total: {total_tracks} tracks, {total_missed} albums not found")
+
+    return results

scrobbles-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: scrobbles
+Version: 0.1.0
+Summary: Fetch, export, and visualize Last.fm listening data — plus create Spotify playlists from your top albums
+Project-URL: Homepage, https://github.com/saforem2/scrobbles
+Project-URL: Repository, https://github.com/saforem2/scrobbles
+Project-URL: Issues, https://github.com/saforem2/scrobbles/issues
+Author-email: Sam Foreman <saforem2@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: audioscrobbler,last.fm,lastfm,music,scrobble,spotify
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.12
+Requires-Dist: pylast>=7.0.2
+Requires-Dist: spotipy>=2.26.0
+Description-Content-Type: text/markdown
+
+# scrobbles
+
+Fetch, export, and visualize [Last.fm](https://www.last.fm/) listening data — plus create Spotify playlists from your top albums.
+
+## Setup
+
+### Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+### Install
+
+```bash
+pip install scrobbles
+# or
+uv add scrobbles
+```
+
+#### From source
+
+```bash
+git clone https://github.com/saforem2/scrobbles.git
+cd lastfm
+uv sync
+```
+
+### Environment Variables
+
+#### Last.fm
+
+Get API credentials at <https://www.last.fm/api/account>.
+
+```bash
+export LASTFM_API_KEY="..."
+export LASTFM_API_SECRET="..."
+export LASTFM_USERNAME="..."
+export LASTFM_PASSWORD="..."
+```
+
+#### Spotify (optional — only needed for playlist creation)
+
+1. Create an app at <https://developer.spotify.com/dashboard>
+2. Add `http://127.0.0.1:8888/callback` as a Redirect URI in your app settings
+3. Export your credentials:
+
+```bash
+export SPOTIFY_CLIENT_ID="..."       # or SPOTIPY_CLIENT_ID
+export SPOTIFY_CLIENT_SECRET="..."   # or SPOTIPY_CLIENT_SECRET
+export SPOTIPY_REDIRECT_URI="http://127.0.0.1:8888/callback"
+```
+
+Either `SPOTIFY_*` or `SPOTIPY_*` naming works — the library maps them automatically.
+
+## Usage
+
+### CLI
+
+```bash
+# Via entry point (after install)
+scrobbles top-albums overall --limit 25
+scrobbles top-albums 2024
+scrobbles dashboard
+
+# Via main.py (development)
+uv run python main.py top-albums overall --limit 25
+uv run python main.py top-albums 2024
+uv run python main.py top-albums last_month
+
+# Export top albums to JSON
+uv run python main.py dump-albums 2024 --limit 100
+
+# Generate the HTML dashboard from existing JSON files
+uv run python main.py dashboard
+
+# Create Spotify playlists from all top100-YYYY.json files
+uv run python main.py spotify-playlists --dry-run
+uv run python main.py spotify-playlists --skip 2020 2021
+```
+
+### Python API
+
+```python
+import scrobbles
+
+# Recent tracks & now playing
+scrobbles.get_recent_tracks("username", 10)
+print(scrobbles.get_now_playing("username"))
+
+# Top albums — predefined periods
+scrobbles.print_top_albums("username", period="7day", limit=20)
+
+# Top albums — arbitrary date ranges
+scrobbles.print_top_albums("username", period="2024")       # full year
+scrobbles.print_top_albums("username", period="2024-06")    # single month
+scrobbles.print_top_albums("username", period="last_week")
+
+# Export to JSON
+scrobbles.dump_top_albums("username", period="2024", limit=100)
+
+# Generate interactive HTML dashboard
+from scrobbles.albums import build_dashboard
+build_dashboard()  # reads data/albums/top100-*.json → data/albums/index.html
+
+# Spotify: create a playlist from any album list
+from scrobbles.spotify import create_playlist_from_albums
+albums = [{"artist": "Radiohead", "album": "OK Computer", "plays": 50}]
+create_playlist_from_albums(albums, "My Playlist", dry_run=True)
+
+# Spotify: bulk-create yearly playlists
+from scrobbles.spotify import create_all_playlists
+create_all_playlists(dry_run=True)
+```
+
+### Supported Period Strings
+
+| Period | Description |
+|---|---|
+| `overall` | All time |
+| `7day`, `1month`, `3month`, `6month`, `12month` | Rolling windows |
+| `today`, `yesterday`, `last_week`, `last_month`, `last_year` | Calendar-relative |
+| `2024` | Full calendar year |
+| `2024-06` | Single month |
+| `2024-06-15` | Single day |
+
+## Project Structure
+
+```
+lastfm/
+├── src/scrobbles/
+│   ├── __init__.py      # Network setup, track utils, re-exports
+│   ├── albums.py        # Top albums: fetch, format, export, dashboard
+│   ├── cli.py           # CLI entry point
+│   └── spotify.py       # Spotify playlist creation
+├── data/albums/         # Generated JSON + HTML dashboard
+│   ├── top100-YYYY.json
+│   └── index.html
+├── main.py              # Thin shim (calls scrobbles.cli:main)
+├── pyproject.toml
+└── README.md
+```
+
+## Publishing
+
+```bash
+# Bump version
+uv version --bump patch
+
+# Build
+uv build
+
+# Publish to PyPI
+uv publish
+```

scrobbles-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+scrobbles/__init__.py,sha256=9h8uGXoGsIGBZqID8be9xuo7LxN0HHn1sWkcKh48Ma0,2232
+scrobbles/albums.py,sha256=OUbru-be9OqD96FnS0v2nR0OvdLiWGq7DGgyL8fl324,16515
+scrobbles/cli.py,sha256=rGEtr52obYI0QdQpZKwyxFlwFG29lcrrD7vNeXSjhO0,2727
+scrobbles/spotify.py,sha256=BYAS1CPwO1BmhSW4Hhj6A49Yv9jz8VbtRJRISDBoEeg,5619
+scrobbles-0.1.0.dist-info/METADATA,sha256=q51NtQBohpXXI5tytrfLbhO5m1mHOlZMoAj6xC_HtAY,4834
+scrobbles-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+scrobbles-0.1.0.dist-info/entry_points.txt,sha256=Sr4FPiEuyIWpA43jS0O4hUbosF3Q7S3bpN8ovoSbPjY,49
+scrobbles-0.1.0.dist-info/licenses/LICENSE,sha256=XdTXLjEKBNTBqjyjVWs1MIQBryn4Fq5lPvzMMW9biKo,1068
+scrobbles-0.1.0.dist-info/RECORD,,

scrobbles-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

scrobbles-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scrobbles = scrobbles.cli:main

scrobbles-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Foreman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.