msoc 0.2.0

Быстрый поисковик музыки

🎵 MSOC - Библиотека для быстрого и асинхронного поиска музыки

✨ Особенности

• ⚡ Асинхронный поиск музыки
• 🔍 Поддержка нескольких источников
• 🛠️ Простое расширение новыми движками
• 📦 Легкая интеграция в проекты
• 🚀 Быстрая установка через pip

---

🎵 MSOC - Библиотека для быстрого и асинхронного поиска музыки

MSOC - это библиотека на Python для быстрого и асинхронного поиска музыки в Интернете. Она позволяет искать треки на различных музыкальных сайтах и возвращает информацию о найденных треках, включая их названия и ссылки на скачивание.

📦 Установка

Для установки библиотеки можно использовать pip:

pip install msoc

Так же можно установить из исходников:

git clone https://github.com/paranoik1/msoc.git

cd MSOC

pip install .

🚀 Использование

💻 В консоле

Можно протестировать пакет обычным скриптом, который был установлен после установки самой библиотеки:

msoc <query or empty>
# or
python -m msoc <query or empty>

При запуске будет выведена информация о найденных треках: Name, Artist, URL, Engine (название движка) и Meta (дополнительные метаданные).

⌨️ В коде

Импортируйте модуль msoc и используйте функцию search() для поиска музыки:

from msoc import search
import asyncio


async def main():
    query = input("Запрос: ")

    async for sound in search(query):
        print(f"Name: {sound.title}\nArtist: {sound.artist}\nURL: {sound.url}")
        print("================================================")


asyncio.run(main())

Функция search() принимает поисковый запрос в качестве аргумента и возвращает асинхронный генератор, который генерирует объекты Sound с информацией о найденных треках.

🎶 Класс Sound

Класс Sound содержит информацию о песне.

Атрибуты:

• title (str): Название песни.
• url (str | None): Ссылка на скачивание песни. Может быть None, если ссылка недоступна (Необязательный атрибут).
• artist (str | None): Исполнитель песни. Может быть None, если информация об исполнителе недоступна (Необязательный атрибут).
• meta (dict[str, Any]): Дополнительные метаданные трека.
• _engine (str | None): Название движка, нашедшего трек (заполняется автоматически).

🔌 Реализованные движки поиска

В настоящее время библиотека MSOC поддерживает следующие движки поиска:

• mp3uk: Поиск на сайте mp3feel.net
• zaycev_net: Поиск на сайте zaycev.net
• trekson: Поиск на сайте trekson.net ⚠️ (требует обновления, сайт изменён)
• hitmo: Поиск на сайте rus.hitmotop.com - реализован на основе данного кода
• muzbomb: Поиск на сайте muzbomb.net - создан takilow

Вы можете добавлять новые движки поиска, создавая модули и загружая их с помощью функций load_search_engine() и unload_search_engine().

❌ Exceptions

Библиотека MSOC определяет следующие исключения:

• LoadedEngineNotFoundError: Выбрасывается, когда движок поиска не был найден в загруженных движках.

🛠️ Создание своих поисковых движков

Для создания собственных поисковых движков на Python вы можете использовать следующий подход:

1. Создайте новый Python-файл для вашего поискового движка:

   • Например, создайте файл my_search_engine.py.

2. Определите асинхронную функцию search(query), которая будет реализовывать поисковый алгоритм:

   • Реализуйте логику поиска, взаимодействуя с API или веб-страницами источников, которые вы хотите использовать.
   • Можете использовать библиотеки, такие как aiohttp, beautifulsoup4 и другие, для выполнения HTTP-запросов и парсинга HTML-страниц.

Функция search внутри движка должна возвращать генератор объектов Sound.
Пример реализации функции search(query) в my_search_engine.py:

import aiohttp
from bs4 import BeautifulSoup

from msoc.sound import Sound


async def search(query: str):
    async with aiohttp.ClientSession() as session:
        async with session.get(f"https://example.com/search?q={query}") as response:
            html = await response.text()

    soup = BeautifulSoup(html, "html.parser")

    for item in soup.find_all("div", class_="search-result"):
        name = item.find("h3").get_text(strip=True)
        artist = item.find("span", class_="artist").get_text(strip=True)
        url = item.find("a").get("href")
        yield Sound(name, url, artist)

3. Подключите ваш поисковый движок к системе:

from msoc import load_search_engine, engines

import my_search_engine


load_search_engine("my_search_engine", my_search_engine)
print(engines())

• Замените my_search_engine на название вашего python файла.
• Далее вызываем engines(), чтобы удостовериться, что движок был успешно загружен

4. Теперь при запуске основной search функции, ваш движок будет автоматически загружен и использован для поиска песен

ℹ️ P.S 1

Если вам нужно подключить поисковой движок, файл которого находится не в текущей папке проекта, можете воспользоваться встроенным python пакетом importlib

from msoc import load_search_engine
from importlib import util

spec = util.spec_from_file_location("my_search_engine", "/path/to/python/file/my_search_engine.py")
module = util.module_from_spec(spec)

spec.loader.exec_module(module)


load_search_engine("my_search_engine", module)

ℹ️ P.S 2

Если вам не нужен какой либо поисковой движок, используй unload_search_engine для его удаления из загруженных:

from msoc import unload_search_engine, engines

unload_search_engine("my_search_engine")
print(engines())

🤝 Contribution

Если вы хотите внести свой вклад в развитие библиотеки MSOC, вы можете:

• 🐞 Сообщить об ошибках или предложить новые функции
• 🎛️ Разработать и добавить новые движки поиска
• 📖 Улучшить документацию
• 🔧 Исправить существующие проблемы