crateport 1.0.3__tar.gz

crateport-1.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phillip Stockmann <ZyanKLee@users.noreply.github.com>
+
+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.

crateport-1.0.3/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: crateport
+Version: 1.0.3
+Summary: DJ-focused playlist tool: generate from artist/track lists or convert VirtualDJ exports to Soundiiz-ready CSVs with ISRC enrichment.
+License: MIT License
+         
+         Copyright (c) 2026 Phillip Stockmann <ZyanKLee@users.noreply.github.com>
+         
+         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.
+License-File: LICENSE
+Keywords: deezer,playlist,csv,music
+Author: Phillip Stockmann
+Author-email: ZyanKLee@users.noreply.github.com
+Requires-Python: >=3.14,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: click (>=8.1,<9.0)
+Requires-Dist: python-dotenv (>=1.0,<2.0)
+Requires-Dist: requests (>=2.32.5,<3.0.0)
+Requires-Dist: sqlalchemy (>=2.0,<3.0)
+Description-Content-Type: text/markdown
+
+# crateport
+
+A DJ-focused playlist tool with two workflows:
+
+- **`generate`** — build a playlist from a list of artists, albums, or tracks using the Deezer public API, then export it to XSPF / M3U / CSV / JSON. See [docs/generate.md](docs/generate.md) for details.
+- **`convert`** — take a VirtualDJ CSV export, enrich every track with an ISRC via Deezer (falling back to MusicBrainz), and produce a Soundiiz-compatible CSV ready for import into Deezer or any other streaming platform. See [docs/convert.md](docs/convert.md) for details.
+
+No Deezer application credentials required. API responses are cached locally in SQLite.
+
+---
+
+## Requirements
+
+- Python ≥ 3.14
+- [pipx](https://pipx.pypa.io/) for installation
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/ZyanKLee/crateport.git
+cd crateport
+pipx install .
+```
+
+The `crateport` command is then available globally.
+
+To upgrade after pulling new changes:
+
+```bash
+pipx install . --force
+```
+
+To uninstall:
+
+```bash
+pipx uninstall crateport
+```
+
+### Working directory
+
+crateport always reads and writes relative to **where you run the command**, regardless of where it is installed:
+
+| Path | Purpose |
+|------|---------|
+| `./output/` | Generated CSVs, XSPF, M3U, JSON, and `cache.db` — created automatically |
+| `./source_data/` | Convenient place for input files — created automatically, not required |
+| `./.env` | Optional configuration overrides (see [Configuration](#configuration)) |
+
+---
+
+## Quick start
+
+```bash
+# Convert a VirtualDJ set export to Soundiiz CSV with ISRC
+crateport convert "source_data/2026-03-13 My Set.csv" --name "My_Set_2026-03-13"
+
+# Generate a playlist from an artist list
+crateport generate source_data/artists.txt --name "My Techno Mix"
+```
+
+**Full command reference:** [docs/convert.md](docs/convert.md) · [docs/generate.md](docs/generate.md)
+
+---
+
+## Configuration
+
+Copy `.env.example` to `.env` and adjust as needed. All values are optional.
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DATABASE_URL` | `sqlite:///output/cache.db` | SQLAlchemy database URL — switch to `postgresql+psycopg2://…` for PostgreSQL |
+| `CACHE_TTL_HOURS` | `24` | How long cached API responses remain valid (hours) |
+| `MUSICBRAINZ_USER_AGENT` | built-in | User-Agent sent to MusicBrainz (identify your instance) |
+| `DEEZER_APP_ID` | *(empty)* | Reserved for future direct Deezer push (not required for file export) |
+| `DEEZER_SECRET` | *(empty)* | Reserved for future direct Deezer push |
+| `DEEZER_REDIRECT_URI` | `http://localhost:8080/callback` | Reserved for future direct Deezer push |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for project structure and development setup.
+
+---
+
+## License
+
+MIT License © 2026 Zyan K. Lee
+

crateport-1.0.3/README.md

@@ -0,0 +1,94 @@
+# crateport
+
+A DJ-focused playlist tool with two workflows:
+
+- **`generate`** — build a playlist from a list of artists, albums, or tracks using the Deezer public API, then export it to XSPF / M3U / CSV / JSON. See [docs/generate.md](docs/generate.md) for details.
+- **`convert`** — take a VirtualDJ CSV export, enrich every track with an ISRC via Deezer (falling back to MusicBrainz), and produce a Soundiiz-compatible CSV ready for import into Deezer or any other streaming platform. See [docs/convert.md](docs/convert.md) for details.
+
+No Deezer application credentials required. API responses are cached locally in SQLite.
+
+---
+
+## Requirements
+
+- Python ≥ 3.14
+- [pipx](https://pipx.pypa.io/) for installation
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/ZyanKLee/crateport.git
+cd crateport
+pipx install .
+```
+
+The `crateport` command is then available globally.
+
+To upgrade after pulling new changes:
+
+```bash
+pipx install . --force
+```
+
+To uninstall:
+
+```bash
+pipx uninstall crateport
+```
+
+### Working directory
+
+crateport always reads and writes relative to **where you run the command**, regardless of where it is installed:
+
+| Path | Purpose |
+|------|---------|
+| `./output/` | Generated CSVs, XSPF, M3U, JSON, and `cache.db` — created automatically |
+| `./source_data/` | Convenient place for input files — created automatically, not required |
+| `./.env` | Optional configuration overrides (see [Configuration](#configuration)) |
+
+---
+
+## Quick start
+
+```bash
+# Convert a VirtualDJ set export to Soundiiz CSV with ISRC
+crateport convert "source_data/2026-03-13 My Set.csv" --name "My_Set_2026-03-13"
+
+# Generate a playlist from an artist list
+crateport generate source_data/artists.txt --name "My Techno Mix"
+```
+
+**Full command reference:** [docs/convert.md](docs/convert.md) · [docs/generate.md](docs/generate.md)
+
+---
+
+## Configuration
+
+Copy `.env.example` to `.env` and adjust as needed. All values are optional.
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DATABASE_URL` | `sqlite:///output/cache.db` | SQLAlchemy database URL — switch to `postgresql+psycopg2://…` for PostgreSQL |
+| `CACHE_TTL_HOURS` | `24` | How long cached API responses remain valid (hours) |
+| `MUSICBRAINZ_USER_AGENT` | built-in | User-Agent sent to MusicBrainz (identify your instance) |
+| `DEEZER_APP_ID` | *(empty)* | Reserved for future direct Deezer push (not required for file export) |
+| `DEEZER_SECRET` | *(empty)* | Reserved for future direct Deezer push |
+| `DEEZER_REDIRECT_URI` | `http://localhost:8080/callback` | Reserved for future direct Deezer push |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for project structure and development setup.
+
+---
+
+## License
+
+MIT License © 2026 Zyan K. Lee

crateport-1.0.3/crateport/__main__.py

@@ -0,0 +1,12 @@
+"""Allow ``python -m crateport`` to run the CLI.
+
+Subcommands
+-----------
+``crateport generate <input_file>``   – generate a playlist from artist/track list
+``crateport convert  <vdj_csv>``      – convert VirtualDJ CSV → Soundiiz CSV with ISRC
+"""
+
+from crateport.cli import cli
+
+if __name__ == "__main__":
+    cli()

crateport-1.0.3/crateport/auth.py

@@ -0,0 +1,181 @@
+"""Deezer OAuth 2.0 authentication.
+
+Deezer uses a custom three-legged OAuth flow:
+
+1. Open the authorization URL in the user's browser.
+2. The user logs in and grants permissions.
+3. Deezer redirects to *redirect_uri* with ``?code=<auth_code>``.
+4. Exchange the code for an access token.
+
+A lightweight ``http.server`` is started locally to capture the callback
+when the redirect URI points to ``localhost``.
+
+.. note::
+
+    You must register an application at https://developers.deezer.com/ and
+    populate ``DEEZER_APP_ID`` and ``DEEZER_SECRET`` in your ``.env`` file.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import requests
+
+from .config import config
+
+logger = logging.getLogger(__name__)
+
+_AUTH_URL = "https://connect.deezer.com/oauth/auth.php"
+_TOKEN_URL = "https://connect.deezer.com/oauth/access_token.php"
+_TOKEN_FILE = config.output_dir / ".deezer_token"
+
+_PERMS = "basic_access,email,manage_library,delete_library"
+
+
+# ---------------------------------------------------------------------------
+# Token persistence
+# ---------------------------------------------------------------------------
+
+
+def load_saved_token() -> str | None:
+    """Return the access token saved from a previous session, or ``None``."""
+    if _TOKEN_FILE.exists():
+        return _TOKEN_FILE.read_text().strip() or None
+    return None
+
+
+def save_token(token: str) -> None:
+    """Persist *token* to disk for reuse across sessions."""
+    _TOKEN_FILE.write_text(token)
+    _TOKEN_FILE.chmod(0o600)
+    logger.debug("Saved access token to %s", _TOKEN_FILE)
+
+
+# ---------------------------------------------------------------------------
+# OAuth flow
+# ---------------------------------------------------------------------------
+
+
+def get_access_token(force_reauth: bool = False) -> str:
+    """Return a valid Deezer access token, prompting the user to log in if needed.
+
+    Raises
+    ------
+    ValueError
+        When ``DEEZER_APP_ID`` or ``DEEZER_SECRET`` are not configured.
+    RuntimeError
+        When the OAuth flow fails or times out.
+    """
+    if not force_reauth:
+        token = load_saved_token()
+        if token:
+            logger.debug("Using saved Deezer access token.")
+            return token
+
+    if not config.deezer_app_id or not config.deezer_secret:
+        raise ValueError(
+            "DEEZER_APP_ID and DEEZER_SECRET must be set in your .env file.\n"
+            "Register an application at https://developers.deezer.com/"
+        )
+
+    code = _run_local_oauth_flow()
+    token = _exchange_code_for_token(code)
+    save_token(token)
+    return token
+
+
+def _build_auth_url() -> str:
+    params = {
+        "app_id": config.deezer_app_id,
+        "redirect_uri": config.deezer_redirect_uri,
+        "perms": _PERMS,
+        "response_type": "code",
+    }
+    return f"{_AUTH_URL}?{urllib.parse.urlencode(params)}"
+
+
+def _run_local_oauth_flow() -> str:
+    """Open the browser and wait for the OAuth callback. Return the auth code."""
+    parsed = urllib.parse.urlparse(config.deezer_redirect_uri)
+    host = parsed.hostname or "localhost"
+    port = parsed.port or 8080
+
+    received_code: list[str] = []
+    done = threading.Event()
+
+    class Handler(BaseHTTPRequestHandler):  # pylint: disable=too-few-public-methods
+        """Minimal HTTP handler that captures the OAuth callback code."""
+
+        def do_GET(self) -> None:  # noqa: N802  # pylint: disable=invalid-name
+            """Handle the OAuth redirect GET request and extract the auth code."""
+            qs = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
+            code = qs.get("code", [""])[0]
+            if code:
+                received_code.append(code)
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            msg = (
+                "<h2>Authorization successful!</h2><p>You can close this tab.</p>"
+                if code
+                else "<h2>No code received.</h2>"
+            )
+            self.wfile.write(msg.encode())
+            done.set()
+
+        def log_message(self, *args) -> None:  # silence request logs
+            pass
+
+    server = HTTPServer((host, port), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    auth_url = _build_auth_url()
+    logger.info("Opening browser for Deezer authorization…")
+    print(f"\nIf your browser does not open automatically, visit:\n  {auth_url}\n")
+    webbrowser.open(auth_url)
+
+    if not done.wait(timeout=120):
+        server.shutdown()
+        raise RuntimeError("Timed out waiting for Deezer OAuth callback (120 s).")
+
+    server.shutdown()
+    if not received_code:
+        raise RuntimeError("OAuth callback received but no auth code was found.")
+    return received_code[0]
+
+
+def _exchange_code_for_token(code: str) -> str:
+    """Exchange an authorization code for an access token."""
+    params = {
+        "app_id": config.deezer_app_id,
+        "secret": config.deezer_secret,
+        "code": code,
+        "output": "json",
+    }
+    resp = requests.get(_TOKEN_URL, params=params, timeout=15)
+    resp.raise_for_status()
+    # Deezer may return JSON or URL-encoded depending on the ``output`` param
+    try:
+        data = resp.json()
+        token = data.get("access_token", "")
+    except ValueError:
+        qs = urllib.parse.parse_qs(resp.text)
+        token = qs.get("access_token", [""])[0]
+
+    if not token:
+        raise RuntimeError(f"Failed to obtain access token. Response: {resp.text}")
+    logger.info("Successfully obtained Deezer access token.")
+    return token
+
+
+def revoke_saved_token() -> None:
+    """Delete the locally saved token file."""
+    if _TOKEN_FILE.exists():
+        _TOKEN_FILE.unlink()
+        logger.info("Saved token deleted.")