librofm 0.1.0__tar.gz

librofm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bryan L. Fordham
+
+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.

librofm-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "librofm"
+version = "0.1.0"
+description = "A Python client library for downloading audiobooks from Libro.fm"
+authors = [
+    {name = "Bryan L. Fordham", email = "bryan@nativesavannah.com"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.32.4,<3.0.0",
+    "pydantic>=2.11.5,<3.0.0",
+    "pydantic-settings>=2.9.1,<3.0.0"
+]
+license = {text = "MIT"}
+keywords = ["audiobook", "libro.fm", "download", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.scripts]
+librofm-download = "librofm.download:main"
+
+[project.urls]
+"Homepage" = "https://codeberge.org/bfordham/librofm"
+"Bug Reports" = "https://codeberg.org/bfordham/librofm/issues"
+"Source" = "https://codeberg.org/bfordham/librofm"
+
+[tool.poetry]
+packages = [{include = "librofm", from = "src"}]
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.4.0"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

librofm-0.1.0/src/librofm/__main__.py

@@ -0,0 +1,7 @@
+"""
+Entry point for python -m librofm
+"""
+from librofm.download import main
+
+if __name__ == "__main__":
+    main()

librofm-0.1.0/src/librofm/client.py

@@ -0,0 +1,219 @@
+
+import os
+from urllib import parse
+import requests
+
+from librofm.models import Audiobook, Credentials, LibroFMClientSettings, Manifest, PackagedM4b, Page
+from librofm.util import get_isbn, requires_auth
+
+
+BASE_URL = "https://libro.fm"
+LOGIN_ENDPOINT = "/oauth/token"
+LIBRARY_ENDPOINT = "/api/v7/library"
+DOWNLOAD_ENDPOINT = "/api/v9/download-manifest"
+PACKAGED_M4B_ENDPOINT = "/api/v10/audiobooks/{isbn}/packaged_m4b"
+
+class LibroFMClient:
+    @staticmethod
+    def get_client():
+        settings = LibroFMClientSettings()
+        return LibroFMClient(settings.username, settings.password)
+    
+    def __init__(self, username:str, password:str) -> None:
+        """
+        Initializes the LibroFM client with the provided username and password.
+        
+        Args:
+            username (str): The username for the LibroFM account.
+            password (str): The password for the LibroFM account.
+        """
+        self.username = username
+        self.password = password
+        self.access_token = None
+
+    def authenticate(self) -> None:
+        """
+        Authenticates the user with the LibroFM API and retrieves an access token.
+        
+        Raises:
+            Exception: If authentication fails.
+        """
+        params = {
+            "grant_type": "password",
+            "username": self.username,
+            "password": self.password,
+        }
+        response = self._do_post(LOGIN_ENDPOINT, params)
+        token_data = Credentials(**response)
+
+        if not token_data.access_token:
+            raise Exception("Authentication failed. Please check your credentials.")
+        
+        self.access_token = token_data.access_token
+
+    @requires_auth
+    def get_library(self, page: int = 1) -> Page:
+        """
+        Retrieves the user's audiobook library from the LibroFM API.
+        
+        Args:
+            page (int): The page number to retrieve (default is 1).
+        
+        Returns:
+            dict: The response containing the user's audiobook library.
+        """
+        params = {"page": page}
+        data = self._do_get(LIBRARY_ENDPOINT, params=params)
+        return Page(**data)
+    
+    @requires_auth
+    def get_download_manifest(self, audiobook: Audiobook | str) -> Manifest:
+        """
+        Retrieves the download manifest for a specific audiobook.
+        
+        Args:
+            audiobook (Audiobook): The audiobook for which to retrieve the download manifest.
+        
+        Returns:
+            dict: The response containing the download manifest.
+        """
+        isbn = get_isbn(audiobook)
+        params = {"isbn": isbn}
+        data = self._do_get(DOWNLOAD_ENDPOINT, params=params)
+        return Manifest(**data)
+    
+    @requires_auth
+    def get_packaged_m4b_info(self, audiobook: Audiobook | str) -> PackagedM4b | None:
+        """
+        Retrieves information about the packaged M4B for a specific audiobook.
+        Args:
+            audiobook (Audiobook): The audiobook for which to retrieve the packaged M4B information.
+        Returns:
+            PackagedM4b: The packaged M4B information for the audiobook.
+        """
+        isbn = get_isbn(audiobook)
+        endpoint = PACKAGED_M4B_ENDPOINT.format(isbn=isbn)
+        data = self._do_get(endpoint)
+        if not data or "m4b_url" not in data:
+            return None
+        return PackagedM4b(**data)
+    
+    @requires_auth
+    def download(self, audiobook: Audiobook | str, output_dir: str = ".") -> bool:
+        """
+        Downloads the audiobook in either MP3 or M4B format based on availability.
+        
+        Args:
+            audiobook (Audiobook): The audiobook to download.
+            output_dir (str): The directory where the audiobook will be saved.
+        
+        Returns:
+            bool: True if the download was successful, False otherwise.
+        """
+        success = self.download_m4b(audiobook, output_dir)
+        if success:
+            return True
+        
+        return self.download_mp3(audiobook, output_dir)
+    
+    def download_mp3(self, audiobook: Audiobook | str, output_dir: str = ".") -> bool:
+        """
+        Downloads the audiobook by retrieving its download manifest.
+        
+        Args:
+            audiobook (Audiobook): The audiobook to download.
+        
+        Returns:
+            Manifest: The download manifest for the audiobook.
+        """
+        manifest = self.get_download_manifest(audiobook)
+        if not manifest:
+            return False
+        
+        for part in manifest.parts:
+            part_url = part.url
+            response = requests.get(part_url, stream=True)
+            if response.status_code == 200:
+                parsed = parse.urlparse(part_url)
+                filename = parse.unquote(parsed.path.split('/')[-1])
+                outpath = f"{output_dir}/{filename}"
+                if os.path.exists(outpath):
+                    return True
+                with open(outpath, "wb") as f:
+                    for chunk in response.iter_content(chunk_size=8192):
+                        f.write(chunk)
+            else:
+                print(f"Failed to download part: {part_url}")
+                return False
+        return True
+            
+    def download_m4b(self, audiobook: Audiobook | str, output_dir: str = ".") -> bool:
+        """
+        Downloads the audiobook in M4B format by retrieving its packaged info.
+        
+        Args:
+            audiobook (Audiobook): The audiobook to download.
+        
+        Returns:
+            PackagedM4B: The download manifest for the audiobook.
+        """
+        packaged = self.get_packaged_m4b_info(audiobook)
+        if not packaged or not packaged.m4b_url:
+            return False
+        
+        response = requests.get(packaged.m4b_url, stream=True)
+        if response.status_code == 200:
+            parsed = parse.urlparse(packaged.m4b_url)
+            filename = parse.unquote(parsed.path.split('/')[-1])
+            outpath = f"{output_dir}/{filename}"
+            if os.path.exists(outpath):
+                return True
+            with open(outpath, "wb") as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    f.write(chunk)
+        else:
+            print(f"Failed to download part: {packaged.m4b_url}")
+            return False
+        return True
+    
+    def _do_post(self, endpoint: str, data: dict) -> dict:
+        """
+        Makes a POST request to the specified endpoint with the provided data.
+        
+        Args:
+            endpoint (str): The API endpoint to send the request to.
+            data (dict): The data to include in the POST request.
+        
+        Returns:
+            dict: The response from the API.
+        """
+        return requests.post(f"{BASE_URL}{endpoint}", headers=self.headers, json=data).json()
+    
+    def _do_get(self, endpoint: str, params: dict = None) -> dict:
+        """
+        Makes a GET request to the specified endpoint with the provided parameters.
+        
+        Args:
+            endpoint (str): The API endpoint to send the request to.
+            params (dict, optional): The parameters to include in the GET request.
+        
+        Returns:
+            dict: The response from the API.
+        """
+        return requests.get(f"{BASE_URL}{endpoint}", headers=self.headers, params=params).json()
+    
+    @property
+    def headers(self) -> dict[str, str]:
+        """
+        Returns the headers required for API requests, including the access token.
+        
+        Returns:
+            dict[str, str]: The headers for the API request.
+        """
+        h = {
+            "Content-Type": "application/json",
+        }
+        if self.access_token:
+            h["Authorization"] = f"Bearer {self.access_token}"
+        return h
+        

librofm-0.1.0/src/librofm/download.py

@@ -0,0 +1,40 @@
+import argparse
+from pathlib import Path
+import sys
+from librofm.client import LibroFMClient
+from librofm.util import clean_filename
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Download audiobooks from Libro.fm")
+    parser.add_argument(
+        "base_path",
+        nargs="?",
+        default="~/Audiobooks",
+        help="Base path for audiobook downloads (default: ~/Audiobooks)"
+    )
+    
+    args = parser.parse_args()
+    
+    c = LibroFMClient.get_client()
+    BASE_PATH = Path(args.base_path).expanduser()
+    
+    page = c.get_library(page=1)
+    for idx, audiobook in enumerate(page.audiobooks):
+        authors = Path(clean_filename(', '.join(audiobook.authors)))
+        title = Path(clean_filename(audiobook.title))
+        path = BASE_PATH / authors / title
+        path.mkdir(parents=True, exist_ok=True)
+        sys.stdout.write(f"\r⏳ Downloading {audiobook.title} {idx}")
+        sys.stdout.flush()
+        try:
+            success = c.download(audiobook, path)
+            if not success:
+                print(f"\rFailed to download {audiobook.title}")
+        except Exception as e:
+            print(f"\rError downloading {audiobook.title}: {e}")
+        print(f"\r✓ Downloaded {audiobook.title} {idx}   ")
+
+
+if __name__ == "__main__":
+    main()

librofm-0.1.0/src/librofm/models.py

@@ -0,0 +1,98 @@
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings
+
+
+class Credentials(BaseModel):
+    """
+    Represents the credentials required to access the LibroFM API.
+    """
+    access_token: str
+    token_type: str
+    created_at: int
+
+class Audiobook(BaseModel):
+    """
+    Represents an audiobook with its metadata.
+    """
+    title: str
+    isbn: int
+    authors: list[str]
+    cover_url: str
+    catalog_info: dict
+    audiobook_info: dict
+    id: int
+    subtitle: str | None
+    publisher: str
+    publication_date: datetime
+    created_at: datetime
+    updated_at: datetime
+    description: str
+    genres: list[dict]
+    lead: str | None
+    abridged: bool
+    series: str | None
+    series_num: int | None
+    recommendations: list[dict]
+    user_metadata: dict | None
+
+
+class Page(BaseModel):
+    """
+    Represents pagination information for API responses.
+    """
+    page: int
+    total_pages: int
+    audiobooks: list[Audiobook]
+
+
+class ManifestPart(BaseModel):
+    """
+    Represents a part of an audiobook, including its URL and size in bytes.
+    """
+    url: str
+    size_bytes: int
+
+
+class ManifestTrack(BaseModel):
+    """
+    Represents a track of an audiobook, including its number, length, chapter title, and timestamps.
+    """
+    number: int
+    length_sec: int
+    chapter_title: str | None
+    created_at: datetime
+    updated_at: datetime
+
+
+class Manifest(BaseModel):
+    """
+    Represents metadata for an audiobook, including its parts and tracks.
+    """
+    isbn: int
+    parts: list[ManifestPart]
+    tracks: list[ManifestTrack]
+    expires_at: datetime
+    version: int
+    size_bytes: int
+
+
+class PackagedM4b(BaseModel):
+    """
+    Represents a packaged M4B file, including its URL and size in bytes.
+    """
+    m4b_url: str
+
+
+class LibroFMClientSettings(BaseSettings):
+    """
+    Settings for the LibroFM client, including API credentials and endpoints.
+    """
+    username: str
+    password: str
+
+    class Config:
+        env_file = ".env"
+        env_prefix = "LIBROFM_"

librofm-0.1.0/src/librofm/util.py

@@ -0,0 +1,20 @@
+from functools import wraps
+
+from librofm.models import Audiobook
+
+def requires_auth(func):
+    """Decorator that ensures authentication before method execution."""
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        if not self.access_token:
+            self.authenticate()
+        return func(self, *args, **kwargs)
+    return wrapper
+    
+def get_isbn(audiobook: Audiobook | str) -> str:
+    """Returns the ISBN of the audiobook, or the audiobook itself if it's a string."""
+    return audiobook.isbn if isinstance(audiobook, Audiobook) else audiobook
+
+
+def clean_filename(name: str) -> str:
+    return "".join(c for c in name if c.isalnum() or c in (' ', '-', '_', '(', ')', '.', ',')).rstrip()