anicli_api 0.4.11__tar.gz

anicli_api-0.4.11/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.1
+Name: anicli_api
+Version: 0.4.11
+Summary: Anime extractor api implementation
+License: MIT
+Keywords: anime,api,ru,russia,asyncio,parser,httpx,dev
+Author: Georgiy aka Vypivshiy
+Requires-Python: >=3.8,<4.0
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Dist: chompjs (>=1.2.2,<2.0.0)
+Requires-Dist: httpx[http2] (>=0.24.0,<0.25.0)
+Requires-Dist: scrape-schema (>=0.5.0,<0.6.0)
+Project-URL: Bug Tracker, https://github.com/vypivshiy/anicli-api/issues
+Project-URL: Cli app, https://github.com/vypivshiy/ani-cli-ru
+Description-Content-Type: text/plain
+
+# anicli-api
+
+Программный интерфейс набора парсеров аниме с различных источников.
+
+Присутствует поддержка sync и async методов с помощью `httpx` библиотеки
+Парсеры работают на REST-API (если у источника есть доступ), parsel и обёртки scrape-schema
+
+# install
+`pip install anicli-api`
+
+# Overview
+Структура проекта
+```
+anicli_api
+├── base.py - базовый класс модуля-парсера
+├── _http.py - сконфигурированные классы httpx
+├── _logger.py - логгер
+├── player - модули получения ссылок на видео
+│     ├── __template__.py - шаблон модуля PlayerExtractor
+│     ├── ...  ready-made модули
+│     ...
+├── source - модули парсеров с источников
+│     ├── __template__.py
+│     ├─ ... ready-made парсеры
+│     ...
+└── tools - прочие модули
+
+```
+Модули имеют следующий алгоритм пошагового получения объектов:
+
+```shell
+# Extractor works schema:
+    [Extractor]  # результат поиска
+        | search(<query>)/ongoing()  -> List[Search | Ongoing]  
+        V                           
+  [Search | Ongoing]     # информация о тайтле      
+         | get_anime()  -> AnimeInfo  
+         V                          
+     [Anime]       # доступные эпизоды                
+        | get_episodes()  -> List[Episode]  
+        V                           
+    [Episode]  # доступ к доступным видео (озвучки + хост)    
+        | get_sources()  -> List[Video]   
+        V                           
+    [Source]  # прямые ссылки на видео, минимально необходимые заголовки, минимальная метаинформация
+        | get_videos()  -> Video
+        V
+    Video(type, quality, url, extra_headers)
+```
+
+# Quickstart example
+Демонстрация простого prompt-line приложения.
+```python
+from anicli_api.source.animejoy import Extractor # или любой другой источник
+
+
+if __name__ == '__main__':
+    ex = Extractor()
+    while True:
+        print("PRESS CTRL + C for exit")
+        results = ex.search(input("search query > "))
+        print(*[f"{i}) {r}" for i, r in enumerate(results)], sep="\n")
+        anime = results[int(input("anime > "))].get_anime()
+        episodes = anime.get_episodes()
+        print(*[f"{i}) {ep}" for i, ep in enumerate(episodes)], sep="\n")
+        episode = episodes[int(input("episode > "))]
+        sources = episode.get_sources()
+        print(*[f"{i}) {source}" for i, source in enumerate(sources)])
+        source = sources[int(input("source > "))]
+        videos = source.get_videos()
+        print(*videos, sep="\n")
+        video = videos[int(input("video > "))]
+        print(video.type, video.quality, video.url, video.headers)
+```
+С asyncio аналогично, но методы получения объектов имеют префикс `a_` 
+## Структура объектов
+
+> Эта информация не относится к прямым реализациям API интерфейсов таких как anilibria и animevost -
+> они передают все полученные значения
+> также, могут быть проблемы с получением дополнительной мета-информации
+> если необходимо её "обогатить" используйте дополнительные источники. Например, shikimori, animedb
+
+### История реализации структуры проекта
+
+Это была сложная проблема проекта, которая была решена с помощью реализации дополнительной
+библиотеки [scrape-schema](https://github.com/vypivshiy/scrape-schema) - dataclass-like 
+(также схожая с ORM) подходом написания парсеров. Ну... насколько получилось решить проблему, 
+ведь идет работа с html документами и сырым текстом, а не структурами json...
+
+Изначально планировалось все реализовывать на регулярных выражениях (как в yt-dlp), но
+выбрал css и xpath селекторы по следующим причинам:
+- CSS и XPath селекторы проще сопровождать: просто открыть браузер, зайти в инструменты разработчика,
+скопировать запрос и во вкладке `Elements` вставить в поиск. Или воспользоваться [тестер 1](http://xpather.com/), 
+[тестер 2](https://try.jsoup.org/)
+- Просты в написании. Нужен только chromium-based браузер, плагин [selectorGadget](https://chrome.google.com/webstore/detail/selectorgadget/mhjhnkcfbdhnjickkkdbjoemdmbfginb)
+и потом сгенерированный селектор идёт в код
+- Чуть меньше кода писать, удобнее читать. Ну, почти... Ведь работаем с сырым html, а не структурами!
+  Также, дополнительно присутствует лог работы (в проекте выключен по умолчанию) 
+и автоматическое приведение типов
+- Быстрее и удобнее добавлять дополнительные поля по необходимости
+
+### SearchResult
+- url: str - URL на тайтл
+- title: str - имя найденного тайтла
+- thumbnail: str - изображение
+
+### Ongoing
+- url: str - URL на тайтл
+- title: str - имя найденного тайтла
+- thumbnail: str - изображение
+
+### Anime
+В некоторых источниках поля могут возвращать None
+- title: str - имя тайтла (на русском)
+- alt_titles: List[str] - альтернативные названия (английский, японский...)
+- thumbnail: str - изображение
+- description: Optional[str] - описание тайтла
+- genres: List[str] - жанры
+- episodes_available: Optional[int] - доступных эпизодов
+- episodes_total: Optional[int] - максимальное число эпизодов
+- aired: Optional[str] - дата выхода (или год)
+
+### Episode
+- title: str - имя эпизода
+- num: str - номер эпизода
+
+### Source
+- url: str - ссылка на источник
+- name: str - даббер или имя источника
+
+### Video
+
+Объект `Video` (полученный из `Source.get_video` или `Source.a_get_video`) имеет следующую структуру:
+
+* type - тип видео
+* quality - разрешение видео
+* url - прямая ссылка на видео
+* headers - заголовки требуемые для воспроизведения видео. 
+Если возвращает пустой словарь - заголовки не нужны
+
+# Примечания
+
+- Проект разработан преимущественно на личное, некоммерческое использование с client-side 
+стороны. 
+Автор проекта не несет ответственности за поломки, убытки в высоко нагруженных проектах и решение
+предоставляется "Как есть" в соответствии с [MIT](LIENSE) лицензией.
+
+- Основная цель этого проекта — связать автоматизацию и эффективность извлечения того, 
+что предоставляется пользователю в Интернете. 
+Весь контент, доступный в рамках проекта, размещается на внешних неаффилированных источниках.
+
+**Этот проект не включает инструменты кеширования и сохранения всех полученных данных, 
+только готовые реализации парсеров**
+

anicli_api-0.4.11/README.MD

@@ -0,0 +1,153 @@
+# anicli-api
+
+Программный интерфейс набора парсеров аниме с различных источников.
+
+Присутствует поддержка sync и async методов с помощью `httpx` библиотеки
+Парсеры работают на REST-API (если у источника есть доступ), parsel и обёртки scrape-schema
+
+# install
+`pip install anicli-api`
+
+# Overview
+Структура проекта
+```
+anicli_api
+├── base.py - базовый класс модуля-парсера
+├── _http.py - сконфигурированные классы httpx
+├── _logger.py - логгер
+├── player - модули получения ссылок на видео
+│     ├── __template__.py - шаблон модуля PlayerExtractor
+│     ├── ...  ready-made модули
+│     ...
+├── source - модули парсеров с источников
+│     ├── __template__.py
+│     ├─ ... ready-made парсеры
+│     ...
+└── tools - прочие модули
+
+```
+Модули имеют следующий алгоритм пошагового получения объектов:
+
+```shell
+# Extractor works schema:
+    [Extractor]  # результат поиска
+        | search(<query>)/ongoing()  -> List[Search | Ongoing]  
+        V                           
+  [Search | Ongoing]     # информация о тайтле      
+         | get_anime()  -> AnimeInfo  
+         V                          
+     [Anime]       # доступные эпизоды                
+        | get_episodes()  -> List[Episode]  
+        V                           
+    [Episode]  # доступ к доступным видео (озвучки + хост)    
+        | get_sources()  -> List[Video]   
+        V                           
+    [Source]  # прямые ссылки на видео, минимально необходимые заголовки, минимальная метаинформация
+        | get_videos()  -> Video
+        V
+    Video(type, quality, url, extra_headers)
+```
+
+# Quickstart example
+Демонстрация простого prompt-line приложения.
+```python
+from anicli_api.source.animejoy import Extractor # или любой другой источник
+
+
+if __name__ == '__main__':
+    ex = Extractor()
+    while True:
+        print("PRESS CTRL + C for exit")
+        results = ex.search(input("search query > "))
+        print(*[f"{i}) {r}" for i, r in enumerate(results)], sep="\n")
+        anime = results[int(input("anime > "))].get_anime()
+        episodes = anime.get_episodes()
+        print(*[f"{i}) {ep}" for i, ep in enumerate(episodes)], sep="\n")
+        episode = episodes[int(input("episode > "))]
+        sources = episode.get_sources()
+        print(*[f"{i}) {source}" for i, source in enumerate(sources)])
+        source = sources[int(input("source > "))]
+        videos = source.get_videos()
+        print(*videos, sep="\n")
+        video = videos[int(input("video > "))]
+        print(video.type, video.quality, video.url, video.headers)
+```
+С asyncio аналогично, но методы получения объектов имеют префикс `a_` 
+## Структура объектов
+
+> Эта информация не относится к прямым реализациям API интерфейсов таких как anilibria и animevost -
+> они передают все полученные значения
+> также, могут быть проблемы с получением дополнительной мета-информации
+> если необходимо её "обогатить" используйте дополнительные источники. Например, shikimori, animedb
+
+### История реализации структуры проекта
+
+Это была сложная проблема проекта, которая была решена с помощью реализации дополнительной
+библиотеки [scrape-schema](https://github.com/vypivshiy/scrape-schema) - dataclass-like 
+(также схожая с ORM) подходом написания парсеров. Ну... насколько получилось решить проблему, 
+ведь идет работа с html документами и сырым текстом, а не структурами json...
+
+Изначально планировалось все реализовывать на регулярных выражениях (как в yt-dlp), но
+выбрал css и xpath селекторы по следующим причинам:
+- CSS и XPath селекторы проще сопровождать: просто открыть браузер, зайти в инструменты разработчика,
+скопировать запрос и во вкладке `Elements` вставить в поиск. Или воспользоваться [тестер 1](http://xpather.com/), 
+[тестер 2](https://try.jsoup.org/)
+- Просты в написании. Нужен только chromium-based браузер, плагин [selectorGadget](https://chrome.google.com/webstore/detail/selectorgadget/mhjhnkcfbdhnjickkkdbjoemdmbfginb)
+и потом сгенерированный селектор идёт в код
+- Чуть меньше кода писать, удобнее читать. Ну, почти... Ведь работаем с сырым html, а не структурами!
+  Также, дополнительно присутствует лог работы (в проекте выключен по умолчанию) 
+и автоматическое приведение типов
+- Быстрее и удобнее добавлять дополнительные поля по необходимости
+
+### SearchResult
+- url: str - URL на тайтл
+- title: str - имя найденного тайтла
+- thumbnail: str - изображение
+
+### Ongoing
+- url: str - URL на тайтл
+- title: str - имя найденного тайтла
+- thumbnail: str - изображение
+
+### Anime
+В некоторых источниках поля могут возвращать None
+- title: str - имя тайтла (на русском)
+- alt_titles: List[str] - альтернативные названия (английский, японский...)
+- thumbnail: str - изображение
+- description: Optional[str] - описание тайтла
+- genres: List[str] - жанры
+- episodes_available: Optional[int] - доступных эпизодов
+- episodes_total: Optional[int] - максимальное число эпизодов
+- aired: Optional[str] - дата выхода (или год)
+
+### Episode
+- title: str - имя эпизода
+- num: str - номер эпизода
+
+### Source
+- url: str - ссылка на источник
+- name: str - даббер или имя источника
+
+### Video
+
+Объект `Video` (полученный из `Source.get_video` или `Source.a_get_video`) имеет следующую структуру:
+
+* type - тип видео
+* quality - разрешение видео
+* url - прямая ссылка на видео
+* headers - заголовки требуемые для воспроизведения видео. 
+Если возвращает пустой словарь - заголовки не нужны
+
+# Примечания
+
+- Проект разработан преимущественно на личное, некоммерческое использование с client-side 
+стороны. 
+Автор проекта не несет ответственности за поломки, убытки в высоко нагруженных проектах и решение
+предоставляется "Как есть" в соответствии с [MIT](LIENSE) лицензией.
+
+- Основная цель этого проекта — связать автоматизацию и эффективность извлечения того, 
+что предоставляется пользователю в Интернете. 
+Весь контент, доступный в рамках проекта, размещается на внешних неаффилированных источниках.
+
+**Этот проект не включает инструменты кеширования и сохранения всех полученных данных, 
+только готовые реализации парсеров**

anicli_api-0.4.11/anicli_api/_http.py

@@ -0,0 +1,109 @@
+"""
+This module contains httpx.Client and httpx.AsyncClient classes with the following settings:
+
+1. User-agent: Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N)
+AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.114
+
+2. x-requested-with: XMLHttpRequest
+
+"""
+from typing import Dict
+
+from httpx import AsyncClient, Client, Response
+
+from anicli_api._logger import logger
+
+HEADERS: Dict[str, str] = {
+    "User-Agent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Mobile Safari/537.36",
+    # XMLHttpRequest required
+    "x-requested-with": "XMLHttpRequest",
+}
+# DDoS protection check by "Server" key header
+DDOS_SERVICES = ("cloudflare", "ddos-guard")
+
+__all__ = ("BaseHTTPSync", "BaseHTTPAsync", "HTTPSync", "HTTPAsync")
+
+
+class HttpxSingleton:
+    _client_instance = None
+    _client_instance_init = False
+
+    _async_client_instance = None
+    _async_client_instance_init = False
+
+    def __new__(cls, *args, **kwargs):
+        if issubclass(cls, HTTPSync):
+            if not cls._client_instance:
+                cls._client_instance = super().__new__(cls)
+            return cls._client_instance
+
+        elif issubclass(cls, HTTPAsync):
+            if not cls._async_client_instance:
+                cls._async_client_instance = super().__new__(cls)
+            return cls._async_client_instance
+
+
+class BaseHTTPSync(Client):
+    """httpx.Client class with configured user agent and enabled redirects"""
+
+    def __init__(self, **kwargs):
+        super().__init__(http2=kwargs.pop("http2", True), **kwargs)
+        self.headers.update(HEADERS.copy())
+        self.headers.update(kwargs.pop("headers", {}))
+        self.follow_redirects = kwargs.pop("follow_redirects", True)
+
+
+class BaseHTTPAsync(AsyncClient):
+    """httpx.AsyncClient class with configured user agent and enabled redirects"""
+
+    def __init__(self, **kwargs):
+        http2 = kwargs.pop("http2", True)
+        super().__init__(http2=http2, **kwargs)
+        self._headers.update(HEADERS.copy())
+        self._headers.update(kwargs.pop("headers", {}))
+        self.follow_redirects = kwargs.pop("follow_redirects", True)
+
+
+def check_ddos_protect_hook(resp: Response):
+    """
+    Simple ddos protect check hook.
+
+    If response return 403 code or server headers contains *cloudflare* or *ddos-guard* strings and
+    **Connection = close,** throw ConnectionError traceback
+    """
+    logger.debug("%s check DDOS protect :\nstatus [%s] %s", resp.url, resp.status_code, resp.headers)
+    if (
+        resp.headers.get("Server") in DDOS_SERVICES
+        and resp.headers.get("Connection", None) == "close"
+        or resp.status_code == 403
+    ):
+        logger.error("Ooops, %s have ddos protect :(", resp.url)
+        raise ConnectionError(f"{resp.url} have '{resp.headers.get('Server', 'unknown')}' and return 403 code.")
+
+
+class HTTPSync(HttpxSingleton, BaseHTTPSync):
+    """
+    Base singleton **sync** HTTP class with recommended config.
+
+    Used in extractors and can configure at any point in the program"""
+
+    def __init__(self, **kwargs):
+        if not self._client_instance_init:  # dirty hack for update arguments
+            super().__init__(**kwargs)
+            self.event_hooks.update({"response": [check_ddos_protect_hook]})
+            self._client_instance_init = True
+
+
+class HTTPAsync(HttpxSingleton, BaseHTTPAsync):
+    """
+    Base singleton **async** HTTP class with recommended config
+
+    Used in extractors and can configure at any point in the program
+    """
+
+    def __init__(self, **kwargs):
+        if not self._async_client_instance_init:  # dirty hack for update arguments
+            super().__init__(**kwargs)
+            self.event_hooks.update({"response": [check_ddos_protect_hook]})
+            self._async_client_instance_init = True

anicli_api-0.4.11/anicli_api/_logger.py

@@ -0,0 +1,20 @@
+import logging
+
+import colorlog
+
+__all__ = ["logger"]
+
+
+handler = colorlog.StreamHandler()
+_formatter = colorlog.ColoredFormatter(fmt="%(log_color)s %(asctime)s [%(levelname)-8s] %(name)s: %(message)s'")
+
+logger = logging.getLogger("anicli-api")  # type: ignore
+logger.addHandler(handler)
+logger.setLevel(logging.INFO)
+
+
+_logger_cast = logging.getLogger("type_caster")
+_logger_cast.setLevel(logging.ERROR)  # type: ignore
+
+_sc_schema_logger = logging.getLogger("scrape_schema")
+_sc_schema_logger.setLevel(logging.ERROR)

anicli_api-0.4.11/anicli_api/base.py

@@ -0,0 +1,135 @@
+import warnings
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, List, Optional
+
+from scrape_schema import BaseSchema
+
+from anicli_api._http import HTTPAsync, HTTPSync
+from anicli_api.player import ALL_DECODERS
+
+if TYPE_CHECKING:
+    from anicli_api.player.base import Video
+
+
+class MainSchema(BaseSchema):
+    HTTP = HTTPSync
+    HTTP_ASYNC = HTTPAsync
+
+    @classmethod
+    def from_kwargs(cls, **kwargs):
+        """ignore fields parse and set attrs directly"""
+        cls_ = cls("")
+        for k, v in kwargs.items():
+            setattr(cls_, k, v)
+        return cls_
+
+
+class BaseExtractor(ABC):
+    HTTP = HTTPSync
+    HTTP_ASYNC = HTTPAsync
+    BASE_URL: str = NotImplemented
+
+    @abstractmethod
+    def search(self, query: str):
+        pass
+
+    @abstractmethod
+    async def a_search(self, query: str):
+        pass
+
+    @abstractmethod
+    def ongoing(self):
+        pass
+
+    @abstractmethod
+    async def a_ongoing(self):
+        pass
+
+
+class BaseSearch(MainSchema):
+    url: str = NotImplemented
+    title: str = NotImplemented
+    thumbnail: str = NotImplemented
+
+    @abstractmethod
+    def get_anime(self):
+        pass
+
+    @abstractmethod
+    async def a_get_anime(self):
+        pass
+
+
+class BaseOngoing(BaseSearch):
+    url: str = NotImplemented
+    title: str = NotImplemented
+    thumbnail: str = NotImplemented
+
+    @abstractmethod
+    def get_anime(self):
+        pass
+
+    @abstractmethod
+    async def a_get_anime(self):
+        pass
+
+
+class BaseAnime(MainSchema):
+    title: str = NotImplemented
+    alt_titles: List[str] = NotImplemented
+    thumbnail: str = NotImplemented
+    description: Optional[str] = NotImplemented
+    genres: List[str] = NotImplemented
+    episodes_available: Optional[int] = NotImplemented
+    episodes_total: Optional[int] = NotImplemented
+    aired: Optional[str] = NotImplemented
+
+    @abstractmethod
+    def get_episodes(self):
+        pass
+
+    @abstractmethod
+    async def a_get_episodes(self):
+        pass
+
+
+class BaseEpisode(MainSchema):
+    title: str = NotImplemented
+    num: str = NotImplemented
+
+    @abstractmethod
+    def get_sources(self):
+        pass
+
+    @abstractmethod
+    async def a_get_sources(self):
+        pass
+
+
+class BaseSource(MainSchema):
+    ALL_VIDEO_EXTRACTORS = ALL_DECODERS
+    url: str = NotImplemented
+    name: str = NotImplemented
+
+    def _pre_validate_url_attr(self) -> None:
+        if self.url is NotImplemented:
+            raise AttributeError(f"{self.__class__.__name__} missing url attribute.")
+
+    def get_videos(self) -> List["Video"]:
+        self._pre_validate_url_attr()
+        for extractor in self.ALL_VIDEO_EXTRACTORS:
+            if self.url == extractor():
+                return extractor().parse(self.url)
+        warnings.warn(f"Failed extractor videos from {self.url}", stacklevel=4)
+        return []
+
+    async def a_get_videos(self) -> List["Video"]:
+        self._pre_validate_url_attr()
+        for extractor in self.ALL_VIDEO_EXTRACTORS:
+            if self.url == extractor():
+                return await extractor().a_parse(self.url)
+        warnings.warn(
+            f"Failed extractor videos from {self.url}. " f"Maybe needed video extractor not implemented?",
+            stacklevel=4,
+        )
+        return []

anicli_api-0.4.11/anicli_api/player/__init__.py

@@ -0,0 +1,23 @@
+from anicli_api.player.aniboom import Aniboom
+from anicli_api.player.animejoy import AnimeJoy
+from anicli_api.player.csst import CsstOnline
+from anicli_api.player.dzen import Dzen
+from anicli_api.player.kodik import Kodik
+from anicli_api.player.mailru import MailRu
+from anicli_api.player.okru import OkRu
+from anicli_api.player.sibnet import SibNet
+from anicli_api.player.sovetromantica import SovietRomanticaPlayer
+from anicli_api.player.vkcom import VkCom
+
+ALL_DECODERS = (
+    Kodik,
+    Aniboom,
+    SibNet,
+    AnimeJoy,
+    CsstOnline,
+    MailRu,
+    OkRu,
+    VkCom,
+    Dzen,
+    SovietRomanticaPlayer,
+)

anicli_api-0.4.11/anicli_api/player/__template__.py

@@ -0,0 +1,33 @@
+import re
+from typing import List
+
+from anicli_api.player.base import BaseVideoExtractor, Video, url_validator
+
+__all__ = ["PlayerExtractor"]
+# url validator pattern
+_URL_EQ = re.compile(r"https?://(www\.)?.")
+# url validate decorator
+player_validator = url_validator(_URL_EQ)
+
+
+class PlayerExtractor(BaseVideoExtractor):
+    URL_RULE = _URL_EQ
+
+    @player_validator
+    def parse(self, url: str, **kwargs) -> List[Video]:
+        response = self.http.get(url)
+        return self._extract(response)
+
+    @player_validator
+    async def a_parse(self, url: str, **kwargs) -> List[Video]:
+        async with self.a_http as client:
+            response = await client.get(url)
+            return self._extract(response)
+
+    def _extract(self, response) -> List[Video]:
+        # any extract logic
+        pass
+
+
+if __name__ == "__main__":
+    PlayerExtractor().parse("")