Sources

The Enma library is a powerful tool for accessing and managing manga data from various sources. To further enhance its capabilities and functionalities, Enma allows for contributions by extending it with custom sources. This guide provides an overview of how you can contribute to the Enma library by adding your own manga sources.

Defining a New Source [ Optional ]

Create Custom Sources Enum

First, create an enumeration (enum) that extends SourcesEnum from Enma, including all existing sources and your new custom source.

Python

from enum import Enum

class AvailableSources(Enum):
    NHENTAI = 'nhentai'
    MANGANATO = 'manganato'
    YOUR_CUSTOM_SOURCE = 'your-custom-source'  # Add your custom source here

Implement the IMangaRepository Interface

For your source to be compatible with Enma, it must implement the IMangaRepository interface. This means your source class to respect the contract shown below:

Python

from abc import ABC, abstractmethod
from typing import Any, Union

from enma.domain.entities.author_page import AuthorPage
from enma.domain.entities.manga import Chapter, Manga, SymbolicLink
from enma.domain.entities.pagination import Pagination
from enma.domain.entities.search_result import SearchResult

class IMangaRepository(ABC):

    @abstractmethod
    def set_config(self,
                   config: Any) -> None:
        ...

    @abstractmethod
    def get(self,
            identifier: str,
            with_symbolic_links: bool) -> Union[Manga, None]:
        ...

    @abstractmethod
    def search(self,
               query: str,
               page: int,
               **kwargs) -> SearchResult:
        ...

    @abstractmethod
    def paginate(self,
                 page: int) -> Pagination: ...

    @abstractmethod
    def random(self) -> Manga:
        ...

    @abstractmethod
    def author_page(self,
                    author: str,
                    page: int) -> AuthorPage:
        ...

    @abstractmethod
    def fetch_chapter_by_symbolic_link(self,
                                       link: SymbolicLink) -> Chapter:
        ...

Each method should be implemented according to the specifications and operational logic of your custom source.

Enhance with Caching

Integrate caching into your custom source to improve performance. For instance, you can decorate methods like get, search, or paginate with caching logic, specifying the TTL (time to live) through environment variables to control cache expiration dynamically.

Python

from enma.infra.core.utils.cache import Cache

class YourCustomSourceClass(IMangaRepository):
    @Cache(max_age_seconds=300, max_size=20).cache
    def get(self, identifier: str, with_symbolic_links: bool = False) -> Manga:
        # Implementation goes here
        pass

Registering and Using Your New Source

After defining your source and implementing IMangaRepository, you need to register this new source with the Enma instance and set when to use it.

Instantiate Enma with Your Custom Source

Python

from enma import Enma

enma = Enma()

Add Your Source to the Source Manager

Python

enma.source_manager.add_source(source_name='your-custom-source', source=YourCustomSourceClass())

Ensure that YourCustomSourceClass() is an instance of your source class that implements IMangaRepository.

Set Your Source as Active

Python

enma.source_manager.set_source(source_name=AvailableSources.YOUR_CUSTOM_SOURCE)

Testing Your Source

After registering your custom source, it's important to test it to ensure it functions as expected. You can test basic functionalities like searching, getting a random manga, and more

Python

# Testing search
search_results = enma.search("One Piece")
print(search_results)

# Getting a random manga
random_manga = enma.random()
print(random_manga)

Contributing custom sources to the Enma library not only enriches the tool with more options and diversity of content but also offers the opportunity to customize the manga browsing and reading experience. By following the steps outlined, you can easily add your own source, contributing to the Enma community and expanding the library's reach.

If you encounter any challenges or have improvements to suggest, consider contributing to the Enma project on GitHub, where the community can benefit from your contributions.