fetchtune 0.1.0__tar.gz

fetchtune-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Reza Maleki
+
+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.

fetchtune-0.1.0/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: fetchtune
+Version: 0.1.0
+Summary: Universal music metadata resolver for Python
+Author: Mohammad Reza Maleki
+License: MIT
+Project-URL: Homepage, https://github.com/momalekiii/fetchtune
+Project-URL: Repository, https://github.com/momalekiii/fetchtune
+Project-URL: Issues, https://github.com/momalekiii/fetchtune/issues
+Keywords: music,metadata,music-metadata,spotify,apple-music,resolver,music-resolver,track,album,artist
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🎵 FetchTune
+
+> Universal music metadata resolver for Python.
+
+FetchTune is a lightweight Python library and CLI for resolving music URLs into clean, structured metadata.
+
+It provides a unified interface for working with music data across different platforms, including tracks, artists, albums, artwork, release dates, durations, and platform information.
+
+**Supported:** Spotify · Apple Music
+
+---
+
+## ✨ Features
+
+| Feature | Status |
+|---|---|
+| Track metadata | ✅ |
+| Artist metadata | ✅ |
+| Album metadata | ✅ |
+| Artwork & images | ✅ |
+| Release date | ✅ |
+| Duration | ✅ |
+| Explicit status | ✅ |
+| Platform IDs & URLs | ✅ |
+| JSON serialization | ✅ |
+| Cross-provider enrichment | ✅ |
+| CLI | ✅ |
+| Interactive URL input | ✅ |
+
+---
+
+## 🧱 Architecture
+
+FetchTune uses a provider-based architecture. Each platform has its own provider responsible for resolving and normalizing platform-specific data.
+
+```text
+                         FetchTune
+                            │
+                         Resolver
+                            │
+                ┌───────────┴───────────┐
+                │                       │
+        SpotifyProvider          AppleProvider
+                │                       │
+                └───────────┬───────────┘
+                            │
+                          Models
+                     ┌──────┼──────┐
+                     │      │      │
+                   Artist  Album  Track
+```
+
+The core models remain platform-independent, making it possible to add new providers without changing the rest of the library.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install fetchtune
+```
+
+---
+
+## 🚀 Usage
+
+### CLI
+
+Pass a supported music URL:
+
+```bash
+fetchtune "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
+```
+
+For JSON output:
+
+```bash
+fetchtune --json "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
+```
+
+### Python
+
+```python
+from fetchtune import resolve
+
+track = resolve(
+    "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
+)
+
+print(track.title)
+print(track.to_json(indent=2))
+```
+
+---
+
+## 🎵 Example
+
+FetchTune resolving a real Spotify track:
+
+<p align="center">
+  <img
+    src="https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9"
+    width="320"
+    alt="Fooroodgah - HEEN's Reinterpretation"
+  >
+</p>
+
+<h3 align="center">Fooroodgah - HEEN's Reinterpretation</h3>
+
+<p align="center">
+  <strong>Mehrad Hidden · HEEN</strong>
+</p>
+
+<p align="center">
+  <a href="https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc">
+    Open on Spotify ↗
+  </a>
+</p>
+
+### Metadata
+
+| Field | Value |
+|---|---|
+| **Title** | `Fooroodgah - HEEN's Reinterpretation` |
+| **Artists** | Mehrad Hidden, HEEN |
+| **Platform** | Spotify |
+| **Track ID** | `4a0yULThaKQTm0hYPGEMOc` |
+| **Release Date** | `2026-08-28` |
+| **Duration** | `3:27` |
+| **Duration (ms)** | `207875` |
+| **Explicit** | `No` |
+| **Album** | `null` |
+
+### Artists
+
+| Artist | Spotify ID |
+|---|---|
+| Mehrad Hidden | `0jCVTRvQkILbJvpviTpvd1` |
+| HEEN | `3dt8LORgsqjLP8hAYsFKdY` |
+
+### Artwork
+
+| Size | URL |
+|---|---|
+| 640 × 640 | `https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9` |
+| 300 × 300 | `https://image-cdn-ak.spotifycdn.com/image/ab67616d00001e029a1801fbe63582bc1b0678d9` |
+| 64 × 64 | `https://image-cdn-ak.spotifycdn.com/image/ab67616d000048519a1801fbe63582bc1b0678d9` |
+
+### JSON
+
+```json
+{
+  "title": "Fooroodgah - HEEN's Reinterpretation",
+  "artists": [
+    {
+      "name": "Mehrad Hidden",
+      "id": "0jCVTRvQkILbJvpviTpvd1",
+      "url": "https://open.spotify.com/artist/0jCVTRvQkILbJvpviTpvd1"
+    },
+    {
+      "name": "HEEN",
+      "id": "3dt8LORgsqjLP8hAYsFKdY",
+      "url": "https://open.spotify.com/artist/3dt8LORgsqjLP8hAYsFKdY"
+    }
+  ],
+  "album": null,
+  "cover_url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9",
+  "images": [
+    {
+      "url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d00001e029a1801fbe63582bc1b0678d9",
+      "width": 300,
+      "height": 300
+    },
+    {
+      "url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d000048519a1801fbe63582bc1b0678d9",
+      "width": 64,
+      "height": 64
+    },
+    {
+      "url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9",
+      "width": 640,
+      "height": 640
+    }
+  ],
+  "release_date": "2026-08-28T00:00:00Z",
+  "duration_ms": 207875,
+  "is_explicit": false,
+  "platform": "spotify",
+  "platform_id": "4a0yULThaKQTm0hYPGEMOc",
+  "url": "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
+}
+```
+
+---
+
+## 🔄 Album Enrichment
+
+FetchTune can enrich incomplete track metadata using other providers.
+
+For example:
+
+```json
+{
+  "album": null
+}
+```
+
+can potentially become:
+
+```json
+{
+  "album": {
+    "name": "Innerlight EP",
+    "id": "1582831419",
+    "release_date": "2021-07-30T12:00:00Z",
+    "total_tracks": 4
+  }
+}
+```
+
+This keeps the final `Track` model useful even when the original platform doesn't provide complete release information.
+
+---
+
+## 🧪 Testing
+
+FetchTune includes tests for providers, models, resolver behavior, URL parsing, artwork handling, matching, enrichment, and serialization.
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+Current status:
+
+```text
+18 passed
+```
+
+---
+
+## 🛠️ Development
+
+```bash
+git clone https://github.com/momalekiii/fetchtune.git
+cd fetchtune
+
+python3 -m venv .venv
+source .venv/bin/activate
+
+pip install -e .
+pytest
+```
+
+Build the package:
+
+```bash
+python -m build
+```
+
+Check the distribution:
+
+```bash
+python -m twine check dist/*
+```
+
+---
+
+## 📄 License
+
+MIT License
+
+---
+
+<p align="center">
+  <strong>FetchTune</strong>
+  <br>
+  <sub>Music metadata, resolved.</sub>
+  <br><br>
+  <sub>© @momalekiii · 2026</sub>
+</p>
+```

fetchtune-0.1.0/README.md

@@ -0,0 +1,283 @@
+# 🎵 FetchTune
+
+> Universal music metadata resolver for Python.
+
+FetchTune is a lightweight Python library and CLI for resolving music URLs into clean, structured metadata.
+
+It provides a unified interface for working with music data across different platforms, including tracks, artists, albums, artwork, release dates, durations, and platform information.
+
+**Supported:** Spotify · Apple Music
+
+---
+
+## ✨ Features
+
+| Feature | Status |
+|---|---|
+| Track metadata | ✅ |
+| Artist metadata | ✅ |
+| Album metadata | ✅ |
+| Artwork & images | ✅ |
+| Release date | ✅ |
+| Duration | ✅ |
+| Explicit status | ✅ |
+| Platform IDs & URLs | ✅ |
+| JSON serialization | ✅ |
+| Cross-provider enrichment | ✅ |
+| CLI | ✅ |
+| Interactive URL input | ✅ |
+
+---
+
+## 🧱 Architecture
+
+FetchTune uses a provider-based architecture. Each platform has its own provider responsible for resolving and normalizing platform-specific data.
+
+```text
+                         FetchTune
+                            │
+                         Resolver
+                            │
+                ┌───────────┴───────────┐
+                │                       │
+        SpotifyProvider          AppleProvider
+                │                       │
+                └───────────┬───────────┘
+                            │
+                          Models
+                     ┌──────┼──────┐
+                     │      │      │
+                   Artist  Album  Track
+```
+
+The core models remain platform-independent, making it possible to add new providers without changing the rest of the library.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install fetchtune
+```
+
+---
+
+## 🚀 Usage
+
+### CLI
+
+Pass a supported music URL:
+
+```bash
+fetchtune "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
+```
+
+For JSON output:
+
+```bash
+fetchtune --json "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
+```
+
+### Python
+
+```python
+from fetchtune import resolve
+
+track = resolve(
+    "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
+)
+
+print(track.title)
+print(track.to_json(indent=2))
+```
+
+---
+
+## 🎵 Example
+
+FetchTune resolving a real Spotify track:
+
+<p align="center">
+  <img
+    src="https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9"
+    width="320"
+    alt="Fooroodgah - HEEN's Reinterpretation"
+  >
+</p>
+
+<h3 align="center">Fooroodgah - HEEN's Reinterpretation</h3>
+
+<p align="center">
+  <strong>Mehrad Hidden · HEEN</strong>
+</p>
+
+<p align="center">
+  <a href="https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc">
+    Open on Spotify ↗
+  </a>
+</p>
+
+### Metadata
+
+| Field | Value |
+|---|---|
+| **Title** | `Fooroodgah - HEEN's Reinterpretation` |
+| **Artists** | Mehrad Hidden, HEEN |
+| **Platform** | Spotify |
+| **Track ID** | `4a0yULThaKQTm0hYPGEMOc` |
+| **Release Date** | `2026-08-28` |
+| **Duration** | `3:27` |
+| **Duration (ms)** | `207875` |
+| **Explicit** | `No` |
+| **Album** | `null` |
+
+### Artists
+
+| Artist | Spotify ID |
+|---|---|
+| Mehrad Hidden | `0jCVTRvQkILbJvpviTpvd1` |
+| HEEN | `3dt8LORgsqjLP8hAYsFKdY` |
+
+### Artwork
+
+| Size | URL |
+|---|---|
+| 640 × 640 | `https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9` |
+| 300 × 300 | `https://image-cdn-ak.spotifycdn.com/image/ab67616d00001e029a1801fbe63582bc1b0678d9` |
+| 64 × 64 | `https://image-cdn-ak.spotifycdn.com/image/ab67616d000048519a1801fbe63582bc1b0678d9` |
+
+### JSON
+
+```json
+{
+  "title": "Fooroodgah - HEEN's Reinterpretation",
+  "artists": [
+    {
+      "name": "Mehrad Hidden",
+      "id": "0jCVTRvQkILbJvpviTpvd1",
+      "url": "https://open.spotify.com/artist/0jCVTRvQkILbJvpviTpvd1"
+    },
+    {
+      "name": "HEEN",
+      "id": "3dt8LORgsqjLP8hAYsFKdY",
+      "url": "https://open.spotify.com/artist/3dt8LORgsqjLP8hAYsFKdY"
+    }
+  ],
+  "album": null,
+  "cover_url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9",
+  "images": [
+    {
+      "url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d00001e029a1801fbe63582bc1b0678d9",
+      "width": 300,
+      "height": 300
+    },
+    {
+      "url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d000048519a1801fbe63582bc1b0678d9",
+      "width": 64,
+      "height": 64
+    },
+    {
+      "url": "https://image-cdn-ak.spotifycdn.com/image/ab67616d0000b2739a1801fbe63582bc1b0678d9",
+      "width": 640,
+      "height": 640
+    }
+  ],
+  "release_date": "2026-08-28T00:00:00Z",
+  "duration_ms": 207875,
+  "is_explicit": false,
+  "platform": "spotify",
+  "platform_id": "4a0yULThaKQTm0hYPGEMOc",
+  "url": "https://open.spotify.com/track/4a0yULThaKQTm0hYPGEMOc"
+}
+```
+
+---
+
+## 🔄 Album Enrichment
+
+FetchTune can enrich incomplete track metadata using other providers.
+
+For example:
+
+```json
+{
+  "album": null
+}
+```
+
+can potentially become:
+
+```json
+{
+  "album": {
+    "name": "Innerlight EP",
+    "id": "1582831419",
+    "release_date": "2021-07-30T12:00:00Z",
+    "total_tracks": 4
+  }
+}
+```
+
+This keeps the final `Track` model useful even when the original platform doesn't provide complete release information.
+
+---
+
+## 🧪 Testing
+
+FetchTune includes tests for providers, models, resolver behavior, URL parsing, artwork handling, matching, enrichment, and serialization.
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+Current status:
+
+```text
+18 passed
+```
+
+---
+
+## 🛠️ Development
+
+```bash
+git clone https://github.com/momalekiii/fetchtune.git
+cd fetchtune
+
+python3 -m venv .venv
+source .venv/bin/activate
+
+pip install -e .
+pytest
+```
+
+Build the package:
+
+```bash
+python -m build
+```
+
+Check the distribution:
+
+```bash
+python -m twine check dist/*
+```
+
+---
+
+## 📄 License
+
+MIT License
+
+---
+
+<p align="center">
+  <strong>FetchTune</strong>
+  <br>
+  <sub>Music metadata, resolved.</sub>
+  <br><br>
+  <sub>© @momalekiii · 2026</sub>
+</p>
+```

fetchtune-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fetchtune"
+version = "0.1.0"
+description = "Universal music metadata resolver for Python"
+readme = "README.md"
+requires-python = ">=3.10"
+
+license = { text = "MIT" }
+
+authors = [
+    { name = "Mohammad Reza Maleki" }
+]
+
+keywords = [
+    "music",
+    "metadata",
+    "music-metadata",
+    "spotify",
+    "apple-music",
+    "resolver",
+    "music-resolver",
+    "track",
+    "album",
+    "artist"
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+
+    "License :: OSI Approved :: MIT License",
+
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/momalekiii/fetchtune"
+Repository = "https://github.com/momalekiii/fetchtune"
+Issues = "https://github.com/momalekiii/fetchtune/issues"
+
+[project.scripts]
+fetchtune = "fetchtune.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

fetchtune-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fetchtune-0.1.0/src/fetchtune/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from fetchtune.models import Album, Artist, Track
+from fetchtune.resolver import (
+    Resolver,
+    ResolverError,
+    get_default_resolver,
+    resolve,
+    try_resolve,
+)
+
+__all__ = [
+    "Album",
+    "Artist",
+    "Track",
+    "Resolver",
+    "ResolverError",
+    "get_default_resolver",
+    "resolve",
+    "try_resolve",
+]
+
+__version__ = "0.1.0"