audiolibrarian 0.16.2__py3-none-any.whl

audiolibrarian/records.py

@@ -0,0 +1,259 @@
+"""Record (dataclass) definitions.
+
+Useful field reference: https://github.com/metabrainz/picard/blob/master/picard/util/tags.py
+"""
+
+#
+#  Copyright (c) 2020 Stephen Jibson
+#
+#  This file is part of audiolibrarian.
+#
+#  Audiolibrarian is free software: you can redistribute it and/or modify it under the terms of the
+#  GNU General Public License as published by the Free Software Foundation, either version 3 of the
+#  License, or (at your option) any later version.
+#
+#  Audiolibrarian is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+#  without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
+#  the GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License along with audiolibrarian.
+#  If not, see <https://www.gnu.org/licenses/>.
+#
+import dataclasses
+import enum
+import pathlib
+from typing import Any
+
+from audiolibrarian import text
+
+
+class BitrateMode(enum.Enum):
+    """Bitrate modes."""
+
+    UNKNOWN = 0
+    CBR = 1
+    VBR = 2
+
+
+class FileType(enum.Enum):
+    """Audio file types."""
+
+    UNKNOWN = 0
+    AAC = 1
+    FLAC = 2
+    MP3 = 3
+    WAV = 4
+
+
+class Source(enum.Enum):
+    """Information source."""
+
+    MUSICBRAINZ = 1
+    TAGS = 2
+
+
+class ListF(list[Any]):
+    """A list, with a first property."""
+
+    @property
+    def first(self) -> Any | None:  # noqa: ANN401
+        """Return the first element in the list (or None, if the list is empty)."""
+        return self[0] if self else None
+
+
+@dataclasses.dataclass(kw_only=True)
+class Record:
+    """Base class for records.
+
+    Overrides true/false test for records returning false if all fields are None.
+    """
+
+    def __bool__(self) -> bool:
+        """Return a boolean representation of the Record."""
+        return bool([x for x in dataclasses.asdict(self).values() if x is not None])
+
+    def asdict(self) -> dict[Any, Any]:
+        """Return a dict version of the record."""
+        return dataclasses.asdict(self)
+
+
+# Primitive Record Types
+@dataclasses.dataclass(kw_only=True)
+class FileInfo(Record):
+    """File information."""
+
+    bitrate: int | None = None
+    bitrate_mode: BitrateMode | None = None
+    path: pathlib.Path | None = None
+    type: FileType | None = None
+
+
+@dataclasses.dataclass(kw_only=True)
+class FrontCover(Record):
+    """A front cover."""
+
+    data: bytes | None = None
+    desc: str | None = None
+    mime: str | None = None
+
+
+@dataclasses.dataclass(kw_only=True)
+class Performer(Record):
+    """A performer with an instrument."""
+
+    name: str | None = None
+    instrument: str | None = None
+
+
+@dataclasses.dataclass(kw_only=True)
+class Track(Record):
+    """A track."""
+
+    artist: str | None = None
+    artists: ListF | None = None
+    artists_sort: list[str] | None = None
+    file_info: FileInfo | None = None
+    isrcs: list[str] | None = None
+    musicbrainz_artist_ids: ListF | None = None
+    musicbrainz_release_track_id: str | None = None
+    musicbrainz_track_id: str | None = None
+    title: str | None = None
+    track_number: int | None = None
+
+    def get_filename(self, suffix: str = "") -> str:
+        """Return a sane filename based on track number and title.
+
+        If suffix is included, it will be appended to the filename.
+        """
+        if self.title is None or self.track_number is None:
+            msg = "Unable to generate a filename for Track with missing number and/or title"
+            raise ValueError(msg)
+        return (
+            str(self.track_number).zfill(2) + "__" + text.filename_from_title(self.title) + suffix
+        )
+
+
+# Combined Record Types (fields + other record types)
+@dataclasses.dataclass(kw_only=True)
+class Medium(Record):
+    """A medium."""
+
+    formats: ListF | None = None
+    titles: list[str] | None = None
+    track_count: int | None = None
+    tracks: dict[int, Track] | None = None
+
+
+@dataclasses.dataclass(kw_only=True)
+class People(Record):
+    """People."""
+
+    arrangers: list[str] | None = None
+    composers: list[str] | None = None
+    conductors: list[str] | None = None
+    engineers: list[str] | None = None
+    lyricists: list[str] | None = None
+    mixers: list[str] | None = None
+    performers: list[Performer] | None = None
+    producers: list[str] | None = None
+    writers: list[str] | None = None
+
+
+@dataclasses.dataclass(kw_only=True)
+class Release(Record):
+    """A release."""
+
+    album: str | None = None
+    album_artists: ListF | None = None
+    album_artists_sort: ListF | None = None
+    asins: list[str] | None = None
+    barcodes: list[str] | None = None
+    catalog_numbers: list[str] | None = None
+    date: str | None = None
+    front_cover: FrontCover | None = dataclasses.field(default=None, repr=False)
+    genres: ListF | None = None
+    labels: list[str] | None = None
+    media: dict[int, Medium] | None = None
+    medium_count: int | None = None
+    musicbrainz_album_artist_ids: ListF | None = None
+    musicbrainz_album_id: str | None = None
+    musicbrainz_release_group_id: str | None = None
+    original_date: str | None = None
+    original_year: str | None = None
+    people: People | None = None
+    release_countries: list[str] | None = None
+    release_statuses: list[str] | None = None
+    release_types: list[str] | None = None
+    script: str | None = None
+    source: Source | None = None
+
+    def get_artist_album_path(self) -> pathlib.Path:
+        """Return a directory for the artist/album/disc combination.
+
+        Example:
+          -  artist__the/1969__the_album
+        """
+        if self.album_artists_sort is None or self.album_artists_sort.first is None:
+            msg = "Unable to determine artist path without artist(s)"
+            raise ValueError(msg)
+        artist_dir = pathlib.Path(text.filename_from_title(self.album_artists_sort.first))
+        if self.original_year is None or self.album is None:
+            msg = "Unable to determine album path without year and album"
+            raise ValueError(msg)
+        album_dir = pathlib.Path(text.filename_from_title(f"{self.original_year}__{self.album}"))
+        return artist_dir / album_dir
+
+    def pp(self, medium_number: int) -> str:
+        """Return a string summary of the Release."""
+        if self.media is None:
+            msg = "Missing release information"
+            raise ValueError(msg)
+        tracks = "\n".join(
+            (
+                f"  {str(n).zfill(2)}: {t.title}"
+                for n, t in sorted(self.media[medium_number].tracks.items())
+            )
+        )
+        return "\n".join(
+            (
+                f"Album: {self.album}",
+                f"Artist(s): {', '.join(self.album_artists)}",
+                f"Medium: {medium_number} of {self.medium_count}",
+                "Tracks:",
+                tracks,
+            )
+        )
+
+
+@dataclasses.dataclass(kw_only=True)
+class OneTrack(Record):
+    """A single track."""
+
+    release: Release | None = None
+    medium_number: int | None = None
+    track_number: int | None = None
+
+    @property
+    def medium(self) -> Medium | None:
+        """Return the Medium object (or None)."""
+        if self.release and self.release.media:
+            return self.release.media[self.medium_number]
+        return None
+
+    @property
+    def track(self) -> Track | None:
+        """Return the Track object (or None)."""
+        if self.medium and self.medium.tracks:
+            return self.medium.tracks[self.track_number]
+        return None
+
+    def get_artist_album_disc_path(self) -> pathlib.Path:
+        """Return a directory for the artist/album/disc combination.
+
+        Example:
+          - artist__the/1969__the_album
+          - artist__the/1969__the_album/disc2
+        """
+        if (self.medium_number, self.release.medium_count) == (1, 1):
+            return self.release.get_artist_album_path()
+        return self.release.get_artist_album_path() / f"disc{self.medium_number}"

audiolibrarian/settings.py

@@ -0,0 +1,79 @@
+"""Configuration module for AudioLibrarian.
+
+This module provides configuration management using pydantic-settings, supporting multiple
+sources of configuration:
+
+1. Environment Variables (highest precedence):
+   - Prefix: "AUDIOLIBRARIAN__"
+   - Nested fields: Use "__" as delimiter (e.g., AUDIOLIBRARIAN__MUSICBRAINZ__USERNAME)
+
+2. YAML Configuration File:
+   - Location: $XDG_CONFIG_HOME/audiolibrarian/config.yaml
+   - Supports nested structure for MusicBrainz settings
+
+3. Default Values:
+   - Defined in Settings class
+   - Lowest precedence
+
+The configuration is immutable (frozen=True) and follows XDG base directory standards for
+configuration and cache locations.
+
+Sensitive fields (like passwords) are handled using pydantic.SecretStr for security.
+"""
+
+import logging
+import pathlib
+from typing import Literal
+
+import pydantic
+import xdg_base_dirs
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    YamlConfigSettingsSource,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MusicBrainzSettings(BaseSettings):
+    """Configuration settings for MusicBrainz."""
+
+    password: pydantic.SecretStr = pydantic.SecretStr("")
+    username: str = ""
+    rate_limit: pydantic.PositiveFloat = 1.5  # Seconds between requests.
+
+
+class Settings(BaseSettings):
+    """Configuration settings for AudioLibrarian."""
+
+    discid_device: str | None = None  # Use default device.
+    library_dir: pathlib.Path = pathlib.Path("library").resolve()
+    musicbrainz: MusicBrainzSettings = MusicBrainzSettings()
+    normalize_gain: int = 5  # dB
+    normalize_preset: Literal["album", "radio"] = "radio"
+    work_dir: pathlib.Path = xdg_base_dirs.xdg_cache_home() / "audiolibrarian"
+
+    model_config = SettingsConfigDict(
+        env_nested_delimiter="__",
+        env_prefix="AUDIOLIBRARIAN__",
+        yaml_file=str(xdg_base_dirs.xdg_config_home() / "audiolibrarian" / "config.yaml"),
+        frozen=True,  # Make settings immutable.
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        del dotenv_settings, file_secret_settings  # Unused.
+        return env_settings, YamlConfigSettingsSource(settings_cls), init_settings
+
+
+SETTINGS = Settings()
+__all__ = ["SETTINGS"]

audiolibrarian/sh.py

@@ -0,0 +1,55 @@
+"""Command execution helpers."""
+
+#
+#  Copyright (c) 2020 Stephen Jibson
+#
+#  This file is part of audiolibrarian.
+#
+#  Audiolibrarian is free software: you can redistribute it and/or modify it under the terms of the
+#  GNU General Public License as published by the Free Software Foundation, either version 3 of the
+#  License, or (at your option) any later version.
+#
+#  Audiolibrarian is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+#  without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
+#  the GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License along with audiolibrarian.
+#  If not, see <https://www.gnu.org/licenses/>.
+#
+import pathlib
+import subprocess
+from collections.abc import Iterable
+from multiprocessing import Pool
+
+from audiolibrarian import output
+
+
+def _run_command(command: tuple[str, ...]) -> None:
+    """Run a single command."""
+    subprocess.run(command, check=True)  # noqa: S603
+
+
+def parallel(
+    message: str, commands: list[tuple[str, ...]], max_workers: int | None = None
+) -> None:
+    """Execute commands in parallel using multiprocessing.
+
+    Args:
+        message: Progress message to display
+        commands: List of commands to execute
+        max_workers: Maximum number of parallel processes (None for system default)
+    """
+    with output.Dots(message) as dots, Pool(max_workers) as pool:
+        # Start all processes
+        results = [pool.apply_async(_run_command, (command,)) for command in commands]
+
+        # Wait for all processes to complete
+        for result in results:
+            result.get()  # Will raise any exceptions from the subprocess
+            dots.dot()
+
+
+def touch(paths: Iterable[pathlib.Path]) -> None:
+    """Touch all files in a given path."""
+    for path in paths:
+        path.touch(exist_ok=True)

audiolibrarian/text.py

@@ -0,0 +1,115 @@
+"""Text utilities."""
+
+#
+#  Copyright (c) 2020 Stephen Jibson
+#
+#  This file is part of audiolibrarian.
+#
+#  Audiolibrarian is free software: you can redistribute it and/or modify it under the terms of the
+#  GNU General Public License as published by the Free Software Foundation, either version 3 of the
+#  License, or (at your option) any later version.
+#
+#  Audiolibrarian is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+#  without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
+#  the GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License along with audiolibrarian.
+#  If not, see <https://www.gnu.org/licenses/>.
+#
+import pathlib
+import re
+import sys
+from typing import Any
+
+import picard_src
+
+_DIGIT_REGEX = re.compile(r"([0-9]+)")
+_UUID_REGEX = re.compile(
+    r"[a-f0-9]{8}-?[a-f0-9]{4}-?[a-f0-9]{4}-?[a-f0-9]{4}-?[a-f0-9]{12}", re.IGNORECASE
+)
+
+
+def alpha_numeric_key(text: str | pathlib.Path) -> list[Any]:
+    """Return a key that can be used for sorting alphanumeric strings numerically.
+
+    Example:
+        from audiolibrarian import text
+
+        l = ["8__eight", "7__seven", "10__ten", "11__eleven"]
+        sorted(l)
+        # ['10__ten', '11__eleven', '7__seven', '8__eight']
+        sorted(l, key=text.alpha_numeric_key)
+        # ['7__seven', '8__eight', '10__ten', '11__eleven']
+    """
+    return [int(x) if x.isdigit() else x for x in _DIGIT_REGEX.split(str(text))]
+
+
+def filename_from_title(title: str) -> str:
+    """Convert a title into a filename."""
+    escape_required = "'!\"#$&'()*;<>?[]\\`{}|~\t\n); "
+    invalid = "/"
+    no_underscore_replace = "'!\""
+    results: list[str] = []
+    for char in picard_src.replace_non_ascii(title):  # type: ignore[no-untyped-call]
+        if char == "&":
+            results.extend("and")
+        elif char.isascii() and char not in escape_required and char not in invalid:
+            results.append(char)
+        elif char not in no_underscore_replace:
+            results.append("_")
+    result = "".join(results).rstrip("_")
+    # Strip tailing dots, unless we end with an upper-case letter, then put one dot back.
+    if result.endswith(".") and result.rstrip(".")[-1].isupper():
+        return result.rstrip(".") + "."
+    return result.rstrip(".")
+
+
+def fix(text: str) -> str:
+    """Replace some special characters."""
+    text = picard_src.unicode_simplify_combinations(text)  # type: ignore[no-untyped-call]
+    text = picard_src.unicode_simplify_punctuation(text)  # type: ignore[no-untyped-call]
+    return picard_src.unicode_simplify_compatibility(text)  # type: ignore[no-untyped-call, no-any-return]
+
+
+def get_numbers(text: str) -> list[int]:
+    """Get a list of all the numbers in the given string."""
+    return [int(x) for x in _DIGIT_REGEX.findall(text)]
+
+
+def get_track_number(filename: str) -> int:
+    """Get a track number from a filename or from the user."""
+    if numbers := get_numbers(filename):
+        return numbers[0]
+    while True:  # pragma: no cover
+        try:
+            return int(input_(f"Enter the track number for: {filename}"))
+        except ValueError:
+            pass
+
+
+def get_uuid(text: str) -> str | None:
+    """Return the first UUID found within a given string."""
+    if (match := _UUID_REGEX.search(text)) is not None:
+        return match.group()
+    return None
+
+
+def input_(prompt: str) -> str:  # pragma: no cover
+    """Sound a terminal bell then prompt the user for input."""
+    sys.stdout.write("\a")  # Terminal bell escape char.
+    sys.stdout.flush()
+    return input(prompt)
+
+
+def join(strings: list[str], joiner: str = ", ", word: str = "and") -> str:
+    """Join string with joiner and word.
+
+    Example:
+        text.join(["eggs", "bacon", "spam"])
+        # "eggs, bacon and spam"
+    """
+    if not strings:
+        return ""
+    if len(strings) == 1:
+        return strings[0]
+    return joiner.join(strings[:-1]) + " " + word + " " + strings[-1]