usdb-syncer 0.13.0__tar.gz

usdb_syncer-0.13.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Markus Böhning
+
+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.

usdb_syncer-0.13.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.3
+Name: usdb_syncer
+Version: 0.13.0
+Summary: A download manager for USDB songs.
+Author: Markus Böhning
+Author-email: markus.boehning@gmail.com
+Requires-Python: >3.10,<3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: PySide6
+Requires-Dist: appdirs
+Requires-Dist: attrs
+Requires-Dist: beautifulsoup4
+Requires-Dist: ffmpeg-normalize (>=1.27)
+Requires-Dist: filetype
+Requires-Dist: importlib-metadata
+Requires-Dist: keyring
+Requires-Dist: lxml
+Requires-Dist: mutagen
+Requires-Dist: packaging
+Requires-Dist: pillow (>=10)
+Requires-Dist: reportlab
+Requires-Dist: requests
+Requires-Dist: rookiepy (>=0.5.3,<0.6.0)
+Requires-Dist: send2trash
+Requires-Dist: setuptools (>=75.8.0,<76.0.0)
+Requires-Dist: unidecode
+Requires-Dist: yt-dlp[curl-cffi,default]
+Project-URL: Repository, https://github.com/bohning/usdb_syncer
+Description-Content-Type: text/markdown
+
+# USDB Syncer
+
+[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat)](https://pycqa.github.io/isort/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Release](https://github.com/bohning/usdb_syncer/actions/workflows/release.yaml/badge.svg)](https://github.com/bohning/usdb_syncer/actions/workflows/release.yaml)
+[![tox](https://github.com/bohning/usdb_syncer/actions/workflows/tox.yaml/badge.svg)](https://github.com/bohning/usdb_syncer/actions/workflows/tox.yaml)
+
+**USDB Syncer** is an app to download and synchronize UltraStar songs hosted on [USDB](https://usdb.animux.de).
+The project [extensively uses the `#VIDEO` tag](https://github.com/bohning/usdb_syncer/wiki/Meta-Tags#format) to automaticly retrieve the resources (audio, video, images, etc...) to make the UltraStar song complete.
+Once a song is downloaded it can be synchronized (new notes, audio, video, images...) by redownloading the song. If a resource didn't change it's skipped.
+
+## Installation
+
+There are three ways to run USDB Syncer:
+
+1. To run from source, see [Development](#Development).
+2. Use your favourite package manager to install the Python package, e.g. [pipx](https://pipx.pypa.io/stable/): `pipx install usdb_syncer`
+3. We provide [ready-to-run executables](https://github.com/bohning/usdb_syncer/releases) for all major operating systems.
+
+## Development
+
+**USDB Syncer** is written in Python, and uses Poetry to manage its dependencies.
+The following explains how to set up a development environment.
+
+### Prerequisites
+
+- [git](https://www.git-scm.com/downloads)
+- [Python 3.12](https://www.python.org/downloads/) (3.11 should work as well)
+- [Poetry](https://python-poetry.org/docs/#installation)
+
+### Project Setup
+
+Clone the project:
+
+```bash
+git clone https://github.com/bohning/usdb_syncer.git
+cd usdb_syncer
+```
+
+<details>
+
+<summary>If you're on <b>Linux</b>, make sure required packages for Qt are installed.</summary>
+
+```bash
+apt install -y libgstreamer-gl1.0-0 libxcb-glx0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-render0 libxcb-shape0 libxcb-shm0 libxcb-sync1 libxcb-util1 libxcb-xfixes0 libxcb1 libxkbcommon-dev libxkbcommon-x11-0 libxcb-cursor0 libva-dev libva-drm2 libva-x11-2
+```
+
+</details>
+
+Now make sure the Python 3.12 environment you installed Poetry to is activated and run:
+
+```bash
+poetry install
+```
+
+### Run usdb_syncer
+
+The package has a defined entry point for the GUI. Simply type in `poetry run usdb_syncer` in your terminal.
+
+### Run tests
+
+[tox](https://github.com/tox-dev/tox) makes it easy to run the full CI pipeline on your local machine, i.e., if the pipeline passes on your machine there is a good chance it will also pass on the build server.
+
+Run `poetry run tox` to execute the test pipeline. The tox pipelines are configured in the tox.ini file.
+Configurations for specific tools in the pipeline are maintained in the `pyproject.toml` file.
+Tox is configured to create its own virtual environments, install test dependencies and the package you are developing, and run all tests.
+If you changed the test requirements or want to perform a clean run for some reason, you can run `poetry run tox -r` to recreate tox's virtual environment.
+
+The following tools are part of the test pipeline:
+
+- [mypy](https://github.com/python/mypy): Statically checks your type hints.
+
+- [ruff](https://docs.astral.sh/ruff/): A linter and code formatter.
+
+- [pytest](https://github.com/pytest-dev/pytest): Provides a framework for functional unit tests.
+
+- [unittest](https://docs.python.org/3/library/unittest.html): A built-in objective unittest framework
+  with extensive support for mocking.
+
+If you don’t want to run the whole test pipeline, you can also use single commands from the pipeline, e.g., `poetry run pytest`. The tools will automatically pick up the correct configuration from the `pyproject.toml` file.
+
+## Versioning
+
+**USDB Syncer** uses [semantic versioning (semver)](https://semver.org/) as versioning scheme.
+However, since **USDB Syncer** is not a library/API but a user-facing application, we use `MAJOR`, `MINOR` and `PATCH`
+versions according to the following scheme:
+
+- `MAJOR` version increments mean a breaking change for the end user, be it the need to install additional
+  (3rd party) tools or changes that make it necessary to make changes to the already downloaded songs.
+- `MINOR` version increments only involve adding backward compatible features.
+- `PATCH` version increments bring bugfixes.
+
+We will try to avoid `MAJOR` version increments whenever possible, but since the project is still in the
+startup phase, they cannot be completely ruled out.
+
+## Support
+
+<a href="https://www.buymeacoffee.com/usdbsyncer"><img src="https://img.buymeacoffee.com/button-api/?text=Buy us some vegan pizza!&emoji=🍕&slug=usdbsyncer&button_colour=40DCA5&font_colour=ffffff&font_family=Cookie&outline_colour=000000&coffee_colour=FFDD00" /></a>
+
+## Troubleshooting
+
+- The `keyring` package auto-detects an appropriate installed keyring backend (see [PyPI - keyring](https://pypi.org/project/keyring/)). Thus may require following additional package if no backend can be detected, see #136
+
+  ```bash
+  apt install gnome-keyring
+  ```
+
+  If using KDE, a Wallet will have to be activated in the system settings.
+
+- One user using KDE Plasma experiencing an [issue with the menu bar](https://github.com/bohning/usdb_syncer/issues/198)
+  solved it by forcing XWayland instead of Wayland being used: `env WAYLAND_DISPLAY=`.
+
+## Linux Distributions
+
+Linux bundles are generated on AlmaLinux 9. They should be compatible with any modern distribution. If not, please open an issue.
+
+The only known requirement for the binary is `glibc >= 2.34`. The current `glibc` version can be checked with:
+
+```bash
+ldd --version
+```
+
+Support for the following distributions has been manually confirmed as of March 2025:
+
+- Ubuntu 22.04 and 24.04
+- Debian 12
+- Manjaro 24.2
+- Fedora 41
+

usdb_syncer-0.13.0/README.md

@@ -0,0 +1,130 @@
+# USDB Syncer
+
+[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat)](https://pycqa.github.io/isort/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Release](https://github.com/bohning/usdb_syncer/actions/workflows/release.yaml/badge.svg)](https://github.com/bohning/usdb_syncer/actions/workflows/release.yaml)
+[![tox](https://github.com/bohning/usdb_syncer/actions/workflows/tox.yaml/badge.svg)](https://github.com/bohning/usdb_syncer/actions/workflows/tox.yaml)
+
+**USDB Syncer** is an app to download and synchronize UltraStar songs hosted on [USDB](https://usdb.animux.de).
+The project [extensively uses the `#VIDEO` tag](https://github.com/bohning/usdb_syncer/wiki/Meta-Tags#format) to automaticly retrieve the resources (audio, video, images, etc...) to make the UltraStar song complete.
+Once a song is downloaded it can be synchronized (new notes, audio, video, images...) by redownloading the song. If a resource didn't change it's skipped.
+
+## Installation
+
+There are three ways to run USDB Syncer:
+
+1. To run from source, see [Development](#Development).
+2. Use your favourite package manager to install the Python package, e.g. [pipx](https://pipx.pypa.io/stable/): `pipx install usdb_syncer`
+3. We provide [ready-to-run executables](https://github.com/bohning/usdb_syncer/releases) for all major operating systems.
+
+## Development
+
+**USDB Syncer** is written in Python, and uses Poetry to manage its dependencies.
+The following explains how to set up a development environment.
+
+### Prerequisites
+
+- [git](https://www.git-scm.com/downloads)
+- [Python 3.12](https://www.python.org/downloads/) (3.11 should work as well)
+- [Poetry](https://python-poetry.org/docs/#installation)
+
+### Project Setup
+
+Clone the project:
+
+```bash
+git clone https://github.com/bohning/usdb_syncer.git
+cd usdb_syncer
+```
+
+<details>
+
+<summary>If you're on <b>Linux</b>, make sure required packages for Qt are installed.</summary>
+
+```bash
+apt install -y libgstreamer-gl1.0-0 libxcb-glx0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-render0 libxcb-shape0 libxcb-shm0 libxcb-sync1 libxcb-util1 libxcb-xfixes0 libxcb1 libxkbcommon-dev libxkbcommon-x11-0 libxcb-cursor0 libva-dev libva-drm2 libva-x11-2
+```
+
+</details>
+
+Now make sure the Python 3.12 environment you installed Poetry to is activated and run:
+
+```bash
+poetry install
+```
+
+### Run usdb_syncer
+
+The package has a defined entry point for the GUI. Simply type in `poetry run usdb_syncer` in your terminal.
+
+### Run tests
+
+[tox](https://github.com/tox-dev/tox) makes it easy to run the full CI pipeline on your local machine, i.e., if the pipeline passes on your machine there is a good chance it will also pass on the build server.
+
+Run `poetry run tox` to execute the test pipeline. The tox pipelines are configured in the tox.ini file.
+Configurations for specific tools in the pipeline are maintained in the `pyproject.toml` file.
+Tox is configured to create its own virtual environments, install test dependencies and the package you are developing, and run all tests.
+If you changed the test requirements or want to perform a clean run for some reason, you can run `poetry run tox -r` to recreate tox's virtual environment.
+
+The following tools are part of the test pipeline:
+
+- [mypy](https://github.com/python/mypy): Statically checks your type hints.
+
+- [ruff](https://docs.astral.sh/ruff/): A linter and code formatter.
+
+- [pytest](https://github.com/pytest-dev/pytest): Provides a framework for functional unit tests.
+
+- [unittest](https://docs.python.org/3/library/unittest.html): A built-in objective unittest framework
+  with extensive support for mocking.
+
+If you don’t want to run the whole test pipeline, you can also use single commands from the pipeline, e.g., `poetry run pytest`. The tools will automatically pick up the correct configuration from the `pyproject.toml` file.
+
+## Versioning
+
+**USDB Syncer** uses [semantic versioning (semver)](https://semver.org/) as versioning scheme.
+However, since **USDB Syncer** is not a library/API but a user-facing application, we use `MAJOR`, `MINOR` and `PATCH`
+versions according to the following scheme:
+
+- `MAJOR` version increments mean a breaking change for the end user, be it the need to install additional
+  (3rd party) tools or changes that make it necessary to make changes to the already downloaded songs.
+- `MINOR` version increments only involve adding backward compatible features.
+- `PATCH` version increments bring bugfixes.
+
+We will try to avoid `MAJOR` version increments whenever possible, but since the project is still in the
+startup phase, they cannot be completely ruled out.
+
+## Support
+
+<a href="https://www.buymeacoffee.com/usdbsyncer"><img src="https://img.buymeacoffee.com/button-api/?text=Buy us some vegan pizza!&emoji=🍕&slug=usdbsyncer&button_colour=40DCA5&font_colour=ffffff&font_family=Cookie&outline_colour=000000&coffee_colour=FFDD00" /></a>
+
+## Troubleshooting
+
+- The `keyring` package auto-detects an appropriate installed keyring backend (see [PyPI - keyring](https://pypi.org/project/keyring/)). Thus may require following additional package if no backend can be detected, see #136
+
+  ```bash
+  apt install gnome-keyring
+  ```
+
+  If using KDE, a Wallet will have to be activated in the system settings.
+
+- One user using KDE Plasma experiencing an [issue with the menu bar](https://github.com/bohning/usdb_syncer/issues/198)
+  solved it by forcing XWayland instead of Wayland being used: `env WAYLAND_DISPLAY=`.
+
+## Linux Distributions
+
+Linux bundles are generated on AlmaLinux 9. They should be compatible with any modern distribution. If not, please open an issue.
+
+The only known requirement for the binary is `glibc >= 2.34`. The current `glibc` version can be checked with:
+
+```bash
+ldd --version
+```
+
+Support for the following distributions has been manually confirmed as of March 2025:
+
+- Ubuntu 22.04 and 24.04
+- Debian 12
+- Manjaro 24.2
+- Fedora 41

usdb_syncer-0.13.0/pyproject.toml

@@ -0,0 +1,154 @@
+[build-system]
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"
+
+[tool.poetry]
+name = "usdb_syncer"
+version = "0.13.0"  # will be replaced by current git tag via poetry-dynamic-versioning
+authors = ["Markus Böhning <markus.boehning@gmail.com>"]
+description = "A download manager for USDB songs."
+readme = ["README.md"]
+repository = "https://github.com/bohning/usdb_syncer"
+include = [
+    { path = "src/usdb_syncer/gui/forms/*.py", format = ["sdist", "wheel"] },
+    { path = "src/usdb_syncer/gui/resources/qt/*.py", format = ["sdist", "wheel"] },
+    { path = "src/usdb_syncer/data/*.json", format = ["sdist", "wheel"] },
+]
+
+[tool.poetry.requires-plugins]
+poetry-dynamic-versioning = { version = ">=1.0.0,<2.0.0", extras = ["plugin"] }
+
+[tool.poetry.dependencies]
+python = ">3.10,<3.13"
+appdirs = "*"
+attrs = "*"
+beautifulsoup4 = "*"
+ffmpeg-normalize = ">=1.27"
+filetype = "*"
+importlib-metadata = "*"
+keyring = "*"
+lxml = "*"
+mutagen = "*"
+packaging = "*"
+pillow = ">=10"
+PySide6 = "*"
+reportlab = "*"
+requests = "*"
+rookiepy = "^0.5.3"
+send2trash = "*"
+setuptools = "^75.8.0"
+unidecode = "*"
+yt-dlp = {version = "*", extras = ["default", "curl_cffi"]}
+
+[tool.poetry.group.dev.dependencies]
+tox = "*"
+# lint
+ruff = "0.11.6"
+mypy = "*"
+types-setuptools = "*"
+types-requests = "*"
+# test
+pytest = "*"
+# benchmark
+snakeviz = "*"
+
+[tool.poetry.group.build.dependencies]
+PySide6 = "*"  # for file generation
+dunamai = "*"
+
+[tool.poetry.group.bundle.dependencies]
+pyinstaller = "*"
+pyinstaller-hooks-contrib = "*"
+# specifically required for pyinstaller (Note: darwin -> macos)
+altgraph = "*"
+macholib = {version = "*", markers="sys_platform == 'darwin'"}
+pywin32-ctypes = {version = "*", markers="sys_platform == 'win32'"}
+
+[tool.poetry.scripts]
+usdb_syncer = "usdb_syncer.gui:main"
+
+[tool.poetry-dynamic-versioning]
+enable = false
+substitution.files = []
+
+[tool.ruff]
+extend-exclude = [
+    "forms",
+    "resources",
+]
+target-version = "py312"
+preview = true
+
+[tool.ruff.format]
+skip-magic-trailing-comma = true
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "B",
+    "BLE",
+    "C4",
+    "C90",
+    "COM",
+    "E",
+    "F",
+    "I",
+    "LOG",
+    "N",
+    "PTH",
+    "Q",
+    "RUF",
+    "S",
+    "TRY",
+    "W",
+]
+ignore = [
+    # Since we're using the ruff formatter, we follow ruff's official guide on what
+    # rules to skip: https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
+    "W191",
+    "E111",
+    "E114",
+    "E117",
+    "D206",
+    "D300",
+    "Q000",
+    "Q001",
+    "Q002",
+    "Q003",
+    "COM812",
+    "COM819",
+    # We're fine with `assert`s if they're not used for validation, but state facts
+    "S101",
+    # Allow `subprocess` and starting without shell.
+    "S404",
+    "S603",
+    "S606",
+    # Maybe investigate in the future, if it is possible to do this more safely.
+    "S607",
+    # This flags _all_ dynamic SQL constructions, so it's pointless.
+    "S608",
+]
+
+# Allow fix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.isort]
+# For consistency with the formatter, see https://docs.astral.sh/ruff/settings/#lint_isort_split-on-trailing-comma 
+split-on-trailing-comma = false
+
+[tool.mypy]
+ignore_missing_imports = true
+disallow_untyped_defs = true
+follow_imports = "silent"
+exclude = ["src/usdb_syncer/gui/forms", "src/usdb_syncer/gui/resources"]
+
+[tool.pyright]
+# generates a lot of false positives for mutagen
+reportPrivateImportUsage = false
+exclude = [
+    "src/usdb_syncer/gui/forms",
+    "src/usdb_syncer/gui/resources",
+    "venv",
+    ".tox",
+]

usdb_syncer-0.13.0/src/usdb_syncer/__init__.py

@@ -0,0 +1,81 @@
+"""A download manager for USDB songs."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import random
+from pathlib import Path
+
+from usdb_syncer import errors
+from usdb_syncer._version import __version__ as __version__
+from usdb_syncer.constants import Usdb
+
+
+class SongId(int):
+    """Bounded int representing an id on USDB.
+
+    Use builtin str to get the canonical zero-padded five-digit str.
+    """
+
+    def __init__(self, value: int) -> None:
+        if value not in range(100_000):
+            raise errors.SongIdError(value)
+
+    def __str__(self) -> str:
+        return f"{self:05}"
+
+    @classmethod
+    def parse(cls, value: str) -> SongId:
+        return cls(int(value))
+
+    @classmethod
+    def try_parse(cls, value: str) -> SongId | None:
+        try:
+            return cls.parse(value)
+        except ValueError:
+            return None
+
+    def usdb_gettxt_url(self) -> str:
+        return f"{Usdb.GETTXT_URL}{self:d}"
+
+    def usdb_detail_url(self) -> str:
+        return f"{Usdb.DETAIL_URL}{self:d}"
+
+
+class SyncMetaId(int):
+    """8-byte signed integer with str encoding."""
+
+    _len_bytes = 8
+    # chars needed to base64-encode _len_bytes bytes without padding
+    _len_chars = 11
+
+    @classmethod
+    def new(cls) -> SyncMetaId:
+        return cls(random.randint(-(2**63), 2**63 - 1))  # noqa: S311
+
+    def encode(self) -> str:
+        value = base64.urlsafe_b64encode(
+            self.to_bytes(self._len_bytes, "big", signed=True)
+        ).decode()
+        # strip padding
+        return value[:-1]
+
+    @classmethod
+    def decode(cls, value: str) -> SyncMetaId | None:
+        if len(value) != cls._len_chars:
+            return None
+        try:
+            number = base64.urlsafe_b64decode(f"{value}=")
+        except (binascii.Error, ValueError):
+            return None
+        if len(number) != cls._len_bytes:
+            return None
+        return cls.from_bytes(number, "big", signed=True)
+
+    @classmethod
+    def from_path(cls, path: Path) -> SyncMetaId | None:
+        return cls.decode(path.stem)
+
+    def to_filename(self) -> str:
+        return f"{self.encode()}.usdb"

usdb_syncer-0.13.0/src/usdb_syncer/_version.py

@@ -0,0 +1 @@
+__version__ = '0.13.0'

usdb_syncer-0.13.0/src/usdb_syncer/addons.py

@@ -0,0 +1,23 @@
+"""Utilities for managing dynamically loaded add-ons."""
+
+import importlib
+import pkgutil
+import sys
+
+from usdb_syncer import utils
+from usdb_syncer.logger import logger
+
+
+def load_all() -> None:
+    addons_path = utils.AppPaths.addons
+    sys.path.append(str(addons_path))
+
+    # Search for zip files in the addons directory and add them to the path
+    zip_files = [str(z) for z in addons_path.glob("*.zip")]
+    for zip_file in zip_files:
+        sys.path.append(zip_file)
+
+    # Import everything
+    for _, mod, is_pkg in pkgutil.iter_modules([*zip_files, str(addons_path)]):
+        importlib.import_module(mod)
+        logger.debug(f"Imported add-on {'package' if is_pkg else 'module'} '{mod}'.")