melodic 2.1.0

A Python client for fetching artist lyrical discographies.

Melodic

Melodic is a Python client for fetching artist lyrical discographies. This library provides an asynchronous interface to retrieve complete artist discographies, including album metadata and song lyrics, with built-in database storage, proxy support, and robust error handling.

---

Features

• Complete Discography Fetching: Retrieves full album and track listings for any given artist.
• Asynchronous Interface: Built with modern async with patterns for efficient, safe I/O operations.
• Database Storage: Optional built-in storage system for organizing artist, album, and track metadata.
• Proxy Support: Easily pass a list of proxies to route requests through.
• Robust Error Handling: Comprehensive error handling and logging for reliable operation.
• Modern Development Tools: Includes ruff, mypy, pre-commit, and commitizen for high-quality code.

---

Installation

From PyPI (Recommended)

pip install melodic

From Source

You can install melodic by cloning the repository directly or using pre-built wheel files.

Prerequisites: This project requires uv for dependency management.

Option 1: Clone and Build

1. Clone the repository:

   git clone https://github.com/filming/melodic.git
   cd melodic
   

2. Install the project and its dependencies:

   uv sync
   

Option 2: Install from Pre-built Wheels

Pre-built wheel files are automatically generated and attached to each GitHub release. You can download and install them directly:

1. Go to the GitHub releases page
2. Download the .whl file from the latest release
3. Install using pip:

   pip install path/to/downloaded/melodic-*.whl
   

---

Usage

Usage examples will be shown in the future.

---

Configuration

Configuration is passed directly to the Melodic class instance during initialization.

• storage_dir: An optional string or Path object pointing to a directory where the database and other files will be stored. If not provided, no data will be saved to disk.
• proxies: An optional list of proxy strings (e.g., ["http://user:pass@host:port"]). If provided, all network requests will be routed through these proxies.

---

Development

This project uses modern Python development tools:

• uv for dependency management
• ruff for linting and formatting
• mypy for type checking
• pre-commit for git hooks
• commitizen for conventional commits

Setting up for development:

1. Clone the repository:

   git clone https://github.com/filming/melodic.git
   cd melodic
   

2. Install dependencies (including dev tools):

   uv sync --extra dev
   

3. Set up pre-commit hooks:

   uv run pre-commit install
   

4. Start developing!

---

Dependencies

All project dependencies are managed via pyproject.toml and use Python 3.10+.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Contributing

Contributions, bug reports, and feature requests are welcome! Please open an issue or submit a pull request on GitHub.