exportify-cli 1.0.0__tar.gz

exportify_cli-1.0.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: exportify-cli
+Version: 1.0.0
+Summary: Export Spotify playlists to CSV or JSON from the command line.
+Keywords: spotify,playlist,export,csv,json
+License-Expression: GPL-3.0-only
+Requires-Dist: click>=8.1
+Requires-Dist: click-option-group>=0.5
+Requires-Dist: pathvalidate>=3.0
+Requires-Dist: spotipy>=2.24
+Requires-Dist: tabulate>=0.9
+Requires-Dist: tqdm>=4.66
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/donmerendolo/exportify-cli

exportify_cli-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "exportify-cli"
+version = "v1.0.0"
+description = "Export Spotify playlists to CSV or JSON from the command line."
+requires-python = ">=3.13"
+license = "GPL-3.0-only"
+keywords = ["spotify", "playlist", "export", "csv", "json"]
+dependencies = [
+    "click>=8.1",
+    "click-option-group>=0.5",
+    "pathvalidate>=3.0",
+    "spotipy>=2.24",
+    "tabulate>=0.9",
+    "tqdm>=4.66",
+]
+
+[project.scripts]
+exportify-cli = "exportify_cli.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/donmerendolo/exportify-cli"
+
+[build-system]
+requires = ["uv_build>=0.6,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8"]

exportify_cli-1.0.0/src/exportify_cli/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("exportify-cli")
+except PackageNotFoundError:  # running from source without install
+    __version__ = "1.0.0+dev"

exportify_cli-1.0.0/src/exportify_cli/cli.py

@@ -0,0 +1,444 @@
+"""Command line interface."""
+# In case a human reads this: AI (Fable) rewrote the program, then I read
+# and understood everything and made my own handwritten changes.
+
+import logging
+import re
+import shutil
+import sys
+from pathlib import Path
+
+import click
+import spotipy
+from click_option_group import OptionGroup, optgroup
+from pathvalidate import sanitize_filename
+from spotipy.oauth2 import SpotifyOauthError, SpotifyPKCE
+from tabulate import tabulate
+
+from . import __version__
+from .config import (
+    default_config_path,
+    load_config,
+    opt,
+    token_cache_path,
+)
+from .export import ALL_HEADERS, FIELD_ALIASES, SpotifyExporter, parse_fields
+
+logging.basicConfig(
+    level=logging.WARNING,
+    format="%(asctime)s | %(levelname)s | %(message)s",
+    handlers=[logging.StreamHandler(sys.stderr)],
+)
+logger = logging.getLogger(__name__)
+
+# ex: "37i9dQZF1DXcBWIGoYBM5M"
+PLAYLIST_ID_LENGTH = 22
+
+VALID_FORMATS = {"csv", "json"}
+
+
+def clean_playlist_input(playlists: list[str]) -> list[str]:
+    """Convert playlist URLs or URIs to bare IDs."""
+    cleaned = []
+    for p in playlists:
+        p = re.sub(r"^.*playlists?/([a-zA-Z0-9]{22}).*$", r"\1", p)
+        cleaned.append(p.replace("spotify:playlist:", ""))
+    return cleaned
+
+
+def clean_user_input(users: list[str]) -> list[str]:
+    """Convert user URLs or URIs to bare IDs."""
+    cleaned = []
+    for u in users:
+        u = re.sub(r"^.*users?/([a-zA-Z0-9]+).*$", r"\1", u)
+        cleaned.append(u.replace("spotify:user:", ""))
+    return cleaned
+
+
+def resolve_formats(format_param: tuple[str, ...], cfg: dict) -> list[str]:
+    """Resolve output formats, --format > config > default."""
+    if format_param:
+        return list(dict.fromkeys(format_param))
+    formats = [f.lower() for f in opt(cfg, "format")]
+    invalid = [f for f in formats if f not in VALID_FORMATS]
+    if invalid or not formats:
+        click.echo(
+            f"Error: invalid format(s) in config: {', '.join(invalid) or '(empty)'}. "
+            f"Valid formats: {', '.join(sorted(VALID_FORMATS))}.",
+            err=True,
+        )
+        sys.exit(1)
+    return list(dict.fromkeys(formats))
+
+
+def resolve_sort_key(sort_key: str) -> str:
+    """Match sort parameter with key or alias."""
+
+    def normalize(s: str) -> str:
+        return re.sub(r"[\s_()]", "", s.lower())
+
+    for key in ALL_HEADERS:
+        if normalize(key) == normalize(sort_key):
+            return key
+    for key in FIELD_ALIASES:
+        if normalize(key) == normalize(sort_key):
+            return FIELD_ALIASES[key]
+    click.echo(
+        f"Error: sort key '{sort_key}' not found. Available keys: {ALL_HEADERS}.",
+        err=True,
+    )
+    sys.exit(1)
+
+
+def init_spotify_client(cfg: dict, cache_path: Path) -> spotipy.Spotify:
+    """Initialize Spotify client with PKCE manager."""
+    creds = cfg["spotify"]
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    auth = SpotifyPKCE(
+        client_id=creds["client_id"],
+        redirect_uri=creds["redirect_uri"],
+        cache_path=str(cache_path),
+        scope=["user-library-read", "playlist-read-private"],
+    )
+    try:
+        auth.get_access_token(check_cache=True)
+    except SpotifyOauthError as err:
+        logger.error(f"Spotify authentication failed: {err}")
+        sys.exit(1)
+    return spotipy.Spotify(auth_manager=auth, retries=10)
+
+
+def list_playlists(playlists: list[dict]) -> None:
+    data = [[p["name"], p["id"], p["tracks"]["total"]] for p in playlists]
+    # shutil (unlike os.get_terminal_size) has a fallback when not a tty
+    terminal_width = shutil.get_terminal_size().columns
+    click.echo(
+        tabulate(
+            data,
+            headers=["Name", "ID", "Tracks"],
+            tablefmt="simple",
+            # 34 is the width of ID and Tracks columns + padding
+            maxcolwidths=[terminal_width - 34, None, None],
+        )
+    )
+
+
+def match_targets(
+    client: spotipy.Spotify, fetched_playlists: list[dict], terms: list[str]
+) -> tuple[list[dict], list[str]]:
+    """Match requested names/IDs against the user's playlists.
+
+    Exact name/ID match first, then unique prefix match, then a direct
+    fetch for anything that looks like a playlist ID. Returns the matched
+    playlists and the terms that couldn't be resolved.
+    """
+    targets: list[dict] = []
+    unmatched: list[str] = []
+    for term in terms:
+        exact = [p for p in fetched_playlists if term in (p["name"], p["id"])]
+        if exact:
+            targets.extend(exact)
+            continue
+
+        matches = [
+            p for p in fetched_playlists if p["name"].lower().startswith(term.lower())
+        ]
+
+        if len(matches) == 1:
+            targets.append(matches[0])
+
+        elif len(matches) > 1:
+            # Considered adding an extra case sensitive match here but decided against it
+            click.echo(
+                f"Ambiguous prefix '{term}': matches "
+                f"{', '.join(p['name'] for p in matches)}. Skipping.",
+            )
+            unmatched.append(term)
+
+        elif term.isalnum() and len(term) == PLAYLIST_ID_LENGTH:
+            # May be a playlist the user hasn't saved
+            try:
+                pl = client.playlist(term)
+                if pl:
+                    targets.append(pl)
+                    continue
+            except spotipy.SpotifyException as e:
+                logger.warning(f"Failed to fetch playlist {term}: {e}")
+            unmatched.append(term)
+
+        else:
+            unmatched.append(term)
+
+    # Deduplicate, preserving order
+    targets = list({p["id"]: p for p in targets}.values())
+    return targets, unmatched
+
+
+def fetch_user_targets(
+    client: spotipy.Spotify, exporter: SpotifyExporter, user_ids: list[str]
+) -> tuple[list[dict], list[str]]:
+    """Fetch public playlists for each user ID; returns (targets, failed_ids)."""
+    users_targets: list[dict] = []
+    failed: list[str] = []
+    for uid in user_ids:
+        try:
+            items = exporter.fetch_paginated(
+                client.user_playlists,
+                "items",
+                uid,
+                desc=f"Playlists of {uid}",
+                show_bar=False,
+            )
+            user_data = client.user(uid)
+            users_targets.append(
+                {
+                    "name": user_data.get("display_name") or uid,
+                    "uid": uid,
+                    "targets": [t for t in items if t.get("uri")],
+                }
+            )
+        except spotipy.SpotifyException as e:
+            logger.warning(f"Failed to fetch playlists for user {uid}: {e}")
+            failed.append(uid)
+    return users_targets, failed
+
+
+class CustomCommand(click.Command):
+    def format_usage(self, ctx, formatter) -> None:
+        formatter.write_text(
+            "Usage: exportify-cli (-a | -p NAME|ID|URL|URI [-p ...] "
+            "| -u ID|URL|URI | -l | --logout) [OPTIONS]\n",
+        )
+
+
+@click.command(cls=CustomCommand)
+@optgroup.group(cls=OptionGroup)
+@optgroup.option("-a", "--all", "export_all", is_flag=True, help="Export all playlists")
+@optgroup.option(
+    "-p",
+    "--playlist",
+    "playlist",
+    multiple=True,
+    metavar="NAME|ID|URL|URI",
+    help="Export a Spotify playlist given name, ID, URL, or URI; repeatable.",
+)
+@optgroup.option(
+    "-u",
+    "--user",
+    "user",
+    multiple=True,
+    metavar="ID|URL|URI",
+    help="Export all public playlists of a Spotify user given ID, URL, or URI; repeatable.",
+)
+@optgroup.option(
+    "-l", "--list", "list_only", is_flag=True, help="List available playlists."
+)
+@optgroup.option(
+    "--logout",
+    "logout",
+    is_flag=True,
+    help="Delete cached Spotify auth token and exit.",
+)
+@optgroup.option(
+    "-c",
+    "--config",
+    "config",
+    default=None,
+    type=click.Path(),
+    help="Path to configuration file (default: ./config.toml or "
+    "$XDG_CONFIG_HOME/exportify-cli/config.toml).",
+)
+@optgroup.option(
+    "-o",
+    "--output",
+    "output_param",
+    default=None,
+    type=click.Path(),
+    help="Directory to save exported files (default is ./playlists); '-' writes to stdout.",
+)
+@optgroup.option(
+    "-f",
+    "--format",
+    "format_param",
+    multiple=True,
+    type=click.Choice(sorted(VALID_FORMATS)),
+    help="Output file format (defaults to 'csv'); repeatable.",
+)
+@optgroup.option(
+    "--uris",
+    "uris_flag",
+    default=None,
+    is_flag=True,
+    help="(Deprecated: add the URI fields to --fields or the config instead.)",
+)
+@optgroup.option(
+    "--external-ids",
+    "external_ids_flag",
+    default=None,
+    is_flag=True,
+    help="(Deprecated: add 'Track ISRC'/'Album UPC' to --fields or the config instead.)",
+)
+@optgroup.option(
+    "--no-bar", "no_bar_flag", default=None, is_flag=True, help="Hide progress bar."
+)
+@optgroup.option(
+    "-s",
+    "--sort-key",
+    "sort_key",
+    default=None,
+    help="Key to sort tracks by (default is 'spotify_default').",
+)
+@optgroup.option(
+    "--reverse",
+    "reverse_order",
+    default=None,
+    is_flag=True,
+    help="Reverse the sort order.",
+)
+@optgroup.option(
+    "--fields",
+    "fields_param",
+    default=None,
+    help="Comma-separated list of fields to include.",
+)
+@click.help_option("-h", "--help")
+@click.version_option(
+    __version__,
+    "-v",
+    "--version",
+    prog_name="exportify-cli",
+    message="%(prog)s v%(version)s",
+)
+def main(
+    export_all: bool,
+    playlist: tuple[str, ...],
+    user: tuple[str, ...],
+    list_only: bool,
+    logout: bool,
+    config: str | None,
+    output_param: str | None,
+    format_param: tuple[str, ...],
+    uris_flag: bool | None,
+    external_ids_flag: bool | None,
+    fields_param: str | None,
+    no_bar_flag: bool | None,
+    sort_key: str | None,
+    reverse_order: bool | None,
+) -> None:
+    """Export Spotify playlists to CSV or JSON."""
+
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")  # type: ignore
+
+    # --- Config ---
+    if config:
+        cfg_path = Path(config).expanduser()
+        if cfg_path.is_dir():
+            cfg_path = cfg_path / "config.toml"
+    else:
+        cfg_path = default_config_path()
+    cfg = load_config(cfg_path, explicit=config is not None)
+    cache_path = token_cache_path(cfg_path)
+
+    if logout:
+        if cache_path.exists():
+            cache_path.unlink()
+            click.echo(f"Logged out successfully. Removed token cache '{cache_path}'.")
+        else:
+            click.echo(f"No token cache file '{cache_path}' was found.")
+        sys.exit(0)
+
+    # --- Resolve options: CLI beats config, config beats defaults ---
+    file_formats = resolve_formats(format_param, cfg)
+    output = output_param if output_param is not None else opt(cfg, "output")
+    include_uris = bool(uris_flag)
+    external_ids = bool(external_ids_flag)
+    if include_uris or external_ids:
+        logger.warning(
+            "--uris and --external-ids are deprecated; use --fields or the config's 'fields' instead."
+        )
+    with_bar = not (no_bar_flag if no_bar_flag is not None else opt(cfg, "no_bar"))
+    actual_key = resolve_sort_key(
+        sort_key if sort_key is not None else opt(cfg, "sort_key")
+    )
+    reverse = reverse_order if reverse_order is not None else opt(cfg, "reverse")
+    fields = parse_fields(
+        fields_param.split(",") if fields_param is not None else opt(cfg, "fields"),
+        include_uris,
+        external_ids,
+    )
+    if actual_key not in fields:
+        logger.warning(
+            f"Sort key '{actual_key}' is not in the exported fields; sort is ignored."
+        )
+
+    playlists = list(playlist) or opt(cfg, "playlists")
+    users = list(user) or opt(cfg, "users")
+
+    if not (export_all or playlists or users or list_only):
+        click.echo(main.get_help(ctx=click.get_current_context()))
+        sys.exit(1)
+
+    # --- Spotify ---
+    client = init_spotify_client(cfg, cache_path)
+    exporter = SpotifyExporter(
+        spotify_client=client,
+        file_formats=file_formats,
+        fields=fields,
+        with_bar=with_bar,
+        sort_key=actual_key,
+        reverse_order=reverse,
+    )
+    fetched_playlists = exporter.get_playlists()
+
+    if list_only:
+        list_playlists(fetched_playlists)
+        sys.exit(0)
+
+    # --- Determine targets ---
+    if export_all:
+        targets, unmatched = fetched_playlists, []
+    else:
+        targets, unmatched = match_targets(
+            client, fetched_playlists, clean_playlist_input(playlists)
+        )
+    users_targets, failed_users = fetch_user_targets(
+        client, exporter, clean_user_input(users)
+    )
+
+    if not (targets or users_targets):
+        click.echo("No matching playlists found.")
+        sys.exit(1)
+
+    # --- Export ---
+    to_stdout = output == "-"
+    if to_stdout and len(file_formats) > 1:
+        click.echo("Error: -o - requires a single format (use -f).", err=True)
+        sys.exit(1)
+    out_dir = None if to_stdout else Path(output)
+    for pl in targets:
+        exporter.export_playlist(pl, out_dir)
+    for ut in users_targets:
+        user_out_dir = (
+            out_dir / sanitize_filename(f"{ut['name']} [{ut['uid']}]")
+            if out_dir is not None
+            else None
+        )
+        for pl in ut["targets"]:
+            exporter.export_playlist(pl, user_out_dir)
+
+    if exporter.exported_playlists > 1:
+        click.echo(
+            f"Successfully exported {exporter.exported_tracks} tracks "
+            f"from {exporter.exported_playlists} playlists.",
+            err=to_stdout,
+        )
+    if unmatched or failed_users:
+        skipped = [*unmatched, *failed_users]
+        click.echo(f"Skipped (not found or failed): {', '.join(skipped)}", err=True)
+        sys.exit(2)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

exportify_cli-1.0.0/src/exportify_cli/config.py

@@ -0,0 +1,240 @@
+"""Configuration: file locations, loading, validation and first-run creation.
+
+Config lives in TOML (config.toml). Legacy config.cfg files are migrated
+automatically. The file is never rewritten by the program after creation;
+missing options simply fall back to defaults at read time.
+"""
+
+import configparser
+import logging
+import os
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import click
+
+logger = logging.getLogger(__name__)
+
+APP_NAME = "exportify-cli"
+
+# Read-time defaults for the [exportify-cli] table (nothing is written back).
+CLI_DEFAULTS: dict[str, Any] = {
+    "format": ["csv"],
+    "output": "./playlists",
+    "playlists": [],
+    "users": [],
+    "no_bar": False,
+    "sort_key": "spotify_default",
+    "reverse": False,
+    "fields": [],
+}
+
+DEFAULT_FIELDS = [
+    "Position",
+    "Track Name",
+    "Album Name",
+    "Artist Name(s)",
+    "Release Date",
+    "Duration_ms",
+    "Popularity",
+    "Added By",
+    "Added At",
+    "Record Label",
+]
+
+CONFIG_TEMPLATE = """\
+[spotify]
+client_id = "{client_id}"
+redirect_uri = "{redirect_uri}"
+
+[exportify-cli]
+# Output format(s): "csv", "json".
+format = ["csv"]
+
+# Directory where exports are written.
+output = "./playlists"
+
+# Playlists exported when no -a/-p/-u is given (names or IDs).
+playlists = []
+
+# Users whose public playlists to export (IDs).
+users = []
+
+# Hide the progress bar.
+no_bar = false
+
+# Key to sort tracks by ("spotify_default" keeps Spotify's order).
+sort_key = "spotify_default"
+
+# Reverse the sort order.
+reverse = false
+
+# Fields to export. All available fields:
+# "Position", "Track URI", "Artist URI(s)", "Album URI", "Track Name",
+# "Album Name", "Artist Name(s)", "Release Date", "Duration_ms", "Popularity",
+# "Added By", "Added At", "Record Label", "Track ISRC", "Album UPC"
+fields = {fields}
+"""
+
+
+def app_base_dir() -> Path:
+    """Directory next to the running program (script or frozen binary)."""
+    if getattr(sys, "frozen", False):  # PyInstaller --onefile
+        return Path(sys.executable).resolve().parent
+    return Path(__file__).resolve().parent
+
+
+def xdg_config_dir() -> Path:
+    base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    return base / APP_NAME
+
+
+def xdg_cache_dir() -> Path:
+    base = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
+    return base / APP_NAME
+
+
+def default_config_path() -> Path:
+    """First existing of: ./config.toml, legacy locations, XDG path.
+    A config.cfg found where no config.toml exists gets migrated.
+    If nothing exists, the XDG path (where a new one is created)."""
+    dirs = [Path.cwd(), app_base_dir(), xdg_config_dir()]
+    for d in dirs:
+        if (d / "config.toml").is_file():
+            return d / "config.toml"
+    for d in dirs:
+        if (d / "config.cfg").is_file():
+            return migrate_legacy_config(d / "config.cfg")
+    return xdg_config_dir() / "config.toml"
+
+
+def migrate_legacy_config(cfg_path: Path) -> Path:
+    """Convert an INI config.cfg to config.toml next to it. Keeps the .cfg."""
+    toml_path = cfg_path.with_name("config.toml")
+    old = configparser.ConfigParser(inline_comment_prefixes=("#", ";"))
+    old.read(cfg_path)
+
+    def _split(value: str) -> list[str]:
+        return [v.strip() for v in value.replace(",", "\n").splitlines() if v.strip()]
+
+    spotify = dict(old["spotify"]) if old.has_section("spotify") else {}
+    cli = dict(old["exportify-cli"]) if old.has_section("exportify-cli") else {}
+
+    fields = _split(cli.get("fields", "")) or DEFAULT_FIELDS
+    # old format option allowed space *or* comma separation
+    formats = cli.get("format", "csv").replace(",", " ").split() or ["csv"]
+    lines = [
+        "[spotify]",
+        f'client_id = "{spotify.get("client_id", "")}"',
+        f'redirect_uri = "{spotify.get("redirect_uri", "")}"',
+        "",
+        "[exportify-cli]",
+        f"format = {formats!r}".replace("'", '"'),
+        f'output = "{cli.get("output", "./playlists")}"',
+        f"playlists = {_split(cli.get('playlists', ''))!r}".replace("'", '"'),
+        f"users = {_split(cli.get('users', ''))!r}".replace("'", '"'),
+        f"no_bar = {cli.get('no_bar', 'false').lower()}",
+        f'sort_key = "{cli.get("sort_key", "spotify_default")}"',
+        f"reverse = {cli.get('reverse', 'false').lower()}",
+        f"fields = {fields!r}".replace("'", '"'),
+        "",
+    ]
+    toml_path.write_text("\n".join(lines), encoding="utf-8")
+    click.echo(f"Migrated legacy config '{cfg_path}' to '{toml_path}'.")
+    return toml_path
+
+
+def validate_config(config: dict) -> bool:
+    """Spotify table exists, has the required keys and a sane redirect URI."""
+    spotify = config.get("spotify")
+    if not isinstance(spotify, dict):
+        logger.error("Configuration missing [spotify] section.")
+        return False
+    missing = [
+        k for k in ("client_id", "redirect_uri") if not str(spotify.get(k, "")).strip()
+    ]
+    if missing:
+        logger.error(
+            f"Missing or empty keys in [spotify] section: {', '.join(missing)}"
+        )
+        return False
+    if not str(spotify["redirect_uri"]).strip().startswith(("http://", "https://")):
+        logger.error(f"Invalid redirect URI: {spotify['redirect_uri']}.")
+        return False
+    return True
+
+
+def create_config(config_path: Path) -> None:
+    """Interactive first-run wizard; writes a commented template."""
+    click.echo(
+        f'No valid config found. Creating "{config_path}".\n'
+        "Use a Client ID and Redirect URI that belong to the same Spotify app.\n"
+    )
+    client_id = click.prompt("Spotify Client ID", type=str).strip()
+    redirect_uri = click.prompt("Redirect URI", type=str).strip()
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    fields_toml = "[" + ", ".join(f'"{f}"' for f in DEFAULT_FIELDS) + "]"
+    config_path.write_text(
+        CONFIG_TEMPLATE.format(
+            client_id=client_id, redirect_uri=redirect_uri, fields=fields_toml
+        ),
+        encoding="utf-8",
+    )
+    logger.info(f"Wrote new config to {config_path}")
+
+
+def read_toml(config_path: Path) -> dict:
+    try:
+        with config_path.open("rb") as f:
+            return tomllib.load(f)
+    except tomllib.TOMLDecodeError as e:
+        click.echo(f"Error: could not parse '{config_path}': {e}", err=True)
+        sys.exit(1)
+
+
+def load_config(config_path: Path, explicit: bool) -> dict:
+    """Load and validate config; run the creation wizard if needed.
+
+    An explicitly passed path (-c) that doesn't exist is an error, not a
+    silent wizard in an unexpected location. An explicit .cfg gets migrated.
+    """
+    if explicit and config_path.suffix == ".cfg" and config_path.is_file():
+        config_path = migrate_legacy_config(config_path)
+
+    if config_path.is_file():
+        config = read_toml(config_path)
+        if validate_config(config):
+            return config
+        if explicit:
+            click.echo(f"Error: config file '{config_path}' is invalid.", err=True)
+            sys.exit(1)
+    elif explicit:
+        click.echo(f"Error: config file '{config_path}' does not exist.", err=True)
+        sys.exit(1)
+
+    create_config(config_path)
+    config = read_toml(config_path)
+    if not validate_config(config):
+        logger.error("Invalid Spotify configuration.")
+        sys.exit(1)
+    return config
+
+
+def opt(config: dict, key: str) -> Any:
+    """Read an [exportify-cli] option, falling back to CLI_DEFAULTS.
+    String values for list options are coerced (comma-separated)."""
+    value = config.get("exportify-cli", {}).get(key, CLI_DEFAULTS[key])
+    if isinstance(CLI_DEFAULTS[key], list) and isinstance(value, str):
+        value = [v.strip() for v in value.split(",") if v.strip()]
+    return value
+
+
+def token_cache_path(config_path: Path) -> Path:
+    """Spotipy token cache. Reuse a legacy `.cache` next to the config if
+    present (avoids forcing re-auth), otherwise use the XDG cache dir."""
+    legacy = config_path.parent / ".cache"
+    if legacy.is_file():
+        return legacy
+    return xdg_cache_dir() / "token.cache"

exportify_cli-1.0.0/src/exportify_cli/export.py

@@ -0,0 +1,377 @@
+"""Fetching from Spotify and writing playlist exports."""
+
+import csv
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+import click
+import spotipy
+from pathvalidate import sanitize_filename
+from tqdm.auto import tqdm
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BAR_FORMAT = (
+    "{desc}{percentage:3.0f}%|{bar}| {n_fmt:>4}"
+    "/{total_fmt:>4} [{elapsed:>6}<{remaining:>6}]"
+)
+
+# Max length for playlist name in progress bar
+DESC_LENGTH = 21
+
+# All exportable fields, in output order
+ALL_HEADERS = [
+    "Position",
+    "Track URI",
+    "Artist URI(s)",
+    "Album URI",
+    "Track Name",
+    "Album Name",
+    "Artist Name(s)",
+    "Release Date",
+    "Duration_ms",
+    "Popularity",
+    "Added By",
+    "Added At",
+    "Record Label",
+    "Track ISRC",
+    "Album UPC",
+]
+
+FIELD_ALIASES = {
+    "position": "Position",
+    "default": "Position",
+    # In previous versions of exportify-cli, spotify_default was
+    # separate code-wise from Position, but it's the same thing
+    "spotify_default": "Position",
+    "track_uri": "Track URI",
+    "uri": "Track URI",
+    "artist_uris": "Artist URI(s)",
+    "artist_uri": "Artist URI(s)",
+    "album_uri": "Album URI",
+    "name": "Track Name",
+    "album": "Album Name",
+    "artist": "Artist Name(s)",
+    "artists": "Artist Name(s)",
+    "artists name": "Artist Name(s)",
+    "date": "Release Date",
+    "duration": "Duration_ms",
+    "popularity": "Popularity",
+    "added_by": "Added By",
+    "added_at": "Added At",
+    "label": "Record Label",
+    "isrc": "Track ISRC",
+    "upc": "Album UPC",
+}
+
+URI_HEADERS = ["Track URI", "Artist URI(s)", "Album URI"]
+EXTERNAL_ID_HEADERS = ["Track ISRC", "Album UPC"]
+
+
+def parse_fields(
+    fields_value: list[str], include_uris: bool, external_ids: bool
+) -> list[str]:
+    """Resolve export headers from a list of field names/aliases.
+
+    --uris / --external-ids add their headers on top; when no fields are
+    given, the default is every header minus the URI/external-id ones.
+    """
+    headers: list[str] = []
+    for field in (f.strip() for f in fields_value if f.strip()):
+        if field in ALL_HEADERS:
+            headers.append(field)
+        elif field.lower() in FIELD_ALIASES:
+            headers.append(FIELD_ALIASES[field.lower()])
+        else:
+            logger.warning(f"Unknown field: {field}")
+
+    if not headers:
+        excluded = URI_HEADERS + EXTERNAL_ID_HEADERS
+        headers = [h for h in ALL_HEADERS if h not in excluded]
+
+    if include_uris:
+        headers += [h for h in URI_HEADERS if h not in headers]
+    if external_ids:
+        headers += [h for h in EXTERNAL_ID_HEADERS if h not in headers]
+
+    return list(dict.fromkeys(headers))
+
+
+def sort_value(value: Any) -> tuple:
+    """Sort key that handles None and compares numbers numerically."""
+    if value is None:
+        return (0, 0.0, "")
+    try:
+        return (1, float(value), "")
+    except (TypeError, ValueError):
+        return (2, 0.0, str(value).lower())
+
+
+def _write_csv(stream, headers: list[str], data: list[dict]) -> None:
+    writer = csv.DictWriter(stream, fieldnames=headers)
+    writer.writeheader()
+    for row in data:
+        writer.writerow(
+            {k: ", ".join(v) if isinstance(v, list) else v for k, v in row.items()}
+        )
+
+
+def write_stdout(headers: list[str], data: list[dict], file_format: str) -> None:
+    """Write a single export to stdout."""
+    if file_format == "csv":
+        _write_csv(sys.stdout, headers, data)
+    else:
+        json.dump(data, sys.stdout, ensure_ascii=False, indent=4)
+        sys.stdout.write("\n")
+
+
+def write_file(
+    file_path: Path, headers: list[str], data: list[dict], file_formats: list[str]
+) -> None:
+    """Write list of dicts to CSV and/or JSON files."""
+    if "csv" in file_formats:
+        csv_path = file_path.with_name(file_path.name + ".csv")
+        with csv_path.open("w", newline="", encoding="utf-8") as csvfile:
+            _write_csv(csvfile, headers, data)
+        logger.info(f"Exported to {csv_path}")
+
+    if "json" in file_formats:
+        json_path = file_path.with_name(file_path.name + ".json")
+        with json_path.open("w", encoding="utf-8") as jsonfile:
+            json.dump(data, jsonfile, ensure_ascii=False, indent=4)
+        logger.info(f"Exported to {json_path}")
+
+
+class SpotifyExporter:
+    """Exports Spotify playlists to files."""
+
+    def __init__(
+        self,
+        spotify_client: spotipy.Spotify,
+        file_formats: list[str],
+        fields: list[str],
+        with_bar: bool,
+        sort_key: str,
+        reverse_order: bool,
+    ) -> None:
+        self.spotify = spotify_client
+        self.file_formats = file_formats
+        self.fields = fields
+        self.with_bar = with_bar
+        self.sort_key = sort_key
+        self.reverse_order = reverse_order
+        self.exported_playlists = 0
+        self.exported_tracks = 0
+        self.album_cache: dict[str, dict] = {}
+
+    def _progress_bar(
+        self, total: int | None, desc: str, unit: str, show_bar: bool
+    ) -> tqdm | None:
+        if not (show_bar and self.with_bar):
+            return None
+        return tqdm(total=total, desc=desc, unit=unit, bar_format=DEFAULT_BAR_FORMAT)
+
+    def fetch_paginated(
+        self,
+        fetch_func: Callable,
+        key: str,
+        *args: Any,
+        desc: str | None = None,
+        show_bar: bool = True,
+        **kwargs: Any,
+    ) -> list[dict]:
+        """Fetch all pages from a paginated endpoint (playlist_tracks, etc.)."""
+        results = fetch_func(*args, **kwargs)
+        items: list[dict] = list(results.get(key, []))
+
+        pbar = self._progress_bar(
+            results.get("total"),
+            desc or results.get("name") or fetch_func.__name__,  # type: ignore
+            "track",
+            show_bar,
+        )
+        if pbar:
+            pbar.update(len(items))
+
+        while results.get("next"):
+            results = self.spotify.next(results)
+            page_items = results.get(key, [])
+            items.extend(page_items)
+            if pbar:
+                pbar.update(len(page_items))
+
+        if pbar:
+            pbar.close()
+        return items
+
+    def fetch_albums(self, album_ids: list[str], already_cached: int = 0) -> list[dict]:
+        """Fetch album details in batches of 20; IDs that aren't albums are
+        retried as shows (podcasts saved in playlists)."""
+        items: list[dict] = []
+        total = len(album_ids) + already_cached
+        pbar = self._progress_bar(total, "Fetching album details: ", "album", True)
+        if pbar and already_cached:
+            pbar.update(already_cached)
+
+        for start in range(0, len(album_ids), 20):
+            batch = album_ids[start : start + 20]
+            page_items = [a for a in self.spotify.albums(batch).get("albums", []) if a]
+
+            fetched_ids = {a["id"] for a in page_items if a.get("id")}
+            for show_id in set(batch) - fetched_ids:
+                try:
+                    show = self.spotify.show(show_id)
+                    show["label"] = show.get("publisher")
+                    page_items.append(show)
+                except spotipy.SpotifyException as e:
+                    logger.warning(f"Failed to fetch show for ID {show_id}: {e}")
+
+            items.extend(page_items)
+            if pbar:
+                pbar.update(len(page_items))
+
+        if pbar:
+            pbar.close()
+        return items
+
+    def _fix_episode(self, item: dict) -> None:
+        """Fill in release date and artist names for podcast episodes."""
+        track = item.get("track")
+        if not track or track.get("type") != "episode":
+            return
+        episode = self.spotify.episode(track.get("id"))
+        track["release_date"] = episode.get("release_date")
+        for artist in track.get("artists", []):
+            artist["name"] = artist.get("type")
+
+    def get_playlists(self) -> list[dict]:
+        """Retrieve all user playlists plus liked songs."""
+        items = self.fetch_paginated(
+            self.spotify.current_user_playlists,
+            "items",
+            desc="Playlists",
+            show_bar=False,
+        )
+        liked_total = self.spotify.current_user_saved_tracks(limit=1)["total"]
+        liked = {
+            "name": "Liked Songs",
+            "id": "liked_songs",
+            "tracks": {"total": liked_total},
+        }
+        return [liked, *items]
+
+    def _fetch_tracks(self, playlist: dict) -> list[dict]:
+        name, pid = playlist["name"], playlist["id"]
+        desc = (
+            name[: DESC_LENGTH - 2] + "...: "
+            if len(name) > DESC_LENGTH - 2
+            else f"{name}: ".ljust(DESC_LENGTH + 3)
+        )
+        if pid == "liked_songs":
+            items = self.fetch_paginated(
+                self.spotify.current_user_saved_tracks, "items", desc=desc
+            )
+        else:
+            items = self.fetch_paginated(
+                self.spotify.playlist_tracks, "items", pid, desc=desc
+            )
+        for item in items:
+            self._fix_episode(item)
+        return items
+
+    def _album_lookup(self, items: list[dict]) -> dict[str, dict]:
+        """Batch-fetch album details for all tracks, using the cache."""
+        album_ids = {
+            i["track"]["album"]["id"]
+            for i in items
+            if i.get("track")
+            and i["track"].get("album")
+            and i["track"]["album"].get("id")
+        }
+        ids_to_fetch = [aid for aid in album_ids if aid not in self.album_cache]
+        if ids_to_fetch:
+            for alb in self.fetch_albums(
+                ids_to_fetch, already_cached=len(album_ids) - len(ids_to_fetch)
+            ):
+                if alb.get("id"):
+                    self.album_cache[alb["id"]] = {
+                        "id": alb.get("id"),
+                        "uri": alb.get("uri"),
+                        "name": alb.get("name"),
+                        "release_date": alb.get("release_date"),
+                        "label": alb.get("label"),
+                        "external_ids": alb.get("external_ids", {}),
+                    }
+        return {
+            aid: self.album_cache[aid] for aid in album_ids if aid in self.album_cache
+        }
+
+    def _build_record(self, position: int, item: dict, albums: dict) -> dict:
+        # Playlists can contain items with 'track': None (seen in the wild;
+        # no idea how it got generated). We keep them as mostly-empty rows
+        # instead of dropping them: they carry no track info, but one could
+        # hypothetically do detective work out of 'added_at'/'added_by' to
+        # find what they originally were.
+        track = item.get("track") or {}
+        album = albums.get(track.get("album", {}).get("id"), {})
+        artists = [a.get("name") for a in track.get("artists", []) if a.get("name")]
+        artist_uris = [a.get("uri") for a in track.get("artists", []) if a.get("uri")]
+        record = dict(
+            zip(
+                ALL_HEADERS,
+                [
+                    position,
+                    track.get("uri"),
+                    artist_uris,
+                    album.get("uri"),
+                    track.get("name"),
+                    album.get("name"),
+                    artists,
+                    album.get("release_date") or track.get("release_date"),
+                    track.get("duration_ms"),
+                    track.get("popularity"),
+                    item.get("added_by", {}).get("id"),
+                    item.get("added_at"),
+                    album.get("label"),
+                    track.get("external_ids", {}).get("isrc"),
+                    album.get("external_ids", {}).get("upc"),
+                ],
+            )
+        )
+        return {k: v for k, v in record.items() if k in self.fields}
+
+    def export_playlist(self, playlist: dict, output_dir: Path | None) -> None:
+        """Export a single playlist to the configured formats.
+
+        A None output_dir writes to stdout (status messages go to stderr).
+        """
+        name, pid = playlist["name"], playlist["id"]
+        to_stdout = output_dir is None
+        if not to_stdout:
+            output_dir.mkdir(parents=True, exist_ok=True)
+            filepath = output_dir / sanitize_filename(f"{name} [{pid}]")
+
+        items = self._fetch_tracks(playlist)
+        albums = self._album_lookup(items)
+        export_data = [
+            self._build_record(i, item, albums) for i, item in enumerate(items, start=1)
+        ]
+
+        export_data.sort(key=lambda x: sort_value(x.get(self.sort_key)))
+        if self.reverse_order:
+            export_data.reverse()
+
+        self.exported_playlists += 1
+        self.exported_tracks += len(export_data)
+        if to_stdout:
+            write_stdout(self.fields, export_data, self.file_formats[0])
+            click.echo(f"Exported {len(export_data)} tracks from '{name}'.", err=True)
+            return
+        write_file(filepath, self.fields, export_data, self.file_formats)
+        for ext in self.file_formats:
+            click.echo(
+                f"Exported {len(export_data)} tracks from '{name}' to {filepath}.{ext}",
+            )