From d904ebe254c2ce85c5a88bf53d47d9fe2caf8fa8 Mon Sep 17 00:00:00 2001
From: musabustun <musabyusufustun@outlook.com>
Date: Sun, 13 Sep 2026 02:08:42 +0300
Subject: [PATCH] docs: add a playlist-to-CSV recipe

Dumping a playlist to a spreadsheet is a common ask with no existing
recipe in the docs. Adds a ~15-line snippet using only the public API
and the stdlib csv module, following the same SpotifyClient pattern as
the other guides.

Verified: the exact snippet in the doc runs against a real playlist
(Spotify's own "Today's Top Hits", already used as the example ID
elsewhere in these docs) and produces correct rows, including the
tier-1-only album field falling back to "" instead of raising when
absent. `mkdocs build --strict` passes with the new page in the nav.

Closes #144

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/guides/playlist-to-csv.md | 32 ++++++++++++++++++++++++++++++++
 mkdocs.yml                     |  1 +
 2 files changed, 33 insertions(+)
 create mode 100644 docs/guides/playlist-to-csv.md

diff --git a/docs/guides/playlist-to-csv.md b/docs/guides/playlist-to-csv.md
new file mode 100644
index 0000000..161ec50
--- /dev/null
+++ b/docs/guides/playlist-to-csv.md
@@ -0,0 +1,32 @@
+# Playlist → CSV
+
+A common ask: dump a playlist's tracks to a spreadsheet. This fetches a
+playlist and writes `name, artist, album, duration_ms` rows with nothing but
+the public API and the standard library's `csv` module.
+
+```python
+import csv
+
+from spotify_scraper import SpotifyClient
+
+with SpotifyClient() as client:
+    playlist = client.get_playlist("37i9dQZF1DXcBWIGoYBM5M", max_tracks=None)
+
+with open("playlist.csv", "w", newline="", encoding="utf-8") as f:
+    writer = csv.writer(f)
+    writer.writerow(["name", "artist", "album", "duration_ms"])
+    for entry in playlist.tracks:
+        track = entry.track
+        artist = ", ".join(a.name for a in track.artists)
+        album = track.album.name if track.album is not None else ""
+        writer.writerow([track.name, artist, album, track.duration_ms])
+```
+
+`playlist.tracks` holds [`PlaylistTrack`](../reference/models.md#playlisttrack)
+entries, not `Track` directly — see [entities](entities.md#playlists) for why.
+`track.album` is a **tier-1-only** field (see [entities](entities.md)); it is
+`None` when the playlist could only be fetched from its embed page, so the
+recipe falls back to an empty string rather than raising.
+
+`max_tracks=None` fetches every track rather than the default 100 — drop it,
+or lower it, for a large playlist you only want to sample.
diff --git a/mkdocs.yml b/mkdocs.yml
index 7337f1d..5ce7e39 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -93,6 +93,7 @@ nav:
     - Quickstart: getting-started/quickstart.md
   - Guides:
     - Entities: guides/entities.md
+    - Playlist → CSV: guides/playlist-to-csv.md
     - Charts: guides/charts.md
     - Discovery: guides/discovery.md
     - Search: guides/search.md