Enma is a Python library designed to fetch manga and doujinshi data from many sources. It provides a unified interface to interact with different manga repositories, making it easier to retrieve manga details, search for manga, paginate through results, and fetch random manga.

❗ Important: Enma is not intended for mass querying or placing heavy loads on supported sources. Please use responsibly, adhering to the terms of service of the data sources. Misuse may result in service disruption or access denial.

• Python 3.9+

pip install --upgrade enma

Ensure you have the required Python version:

import sys

package_name = "enma"
python_major = "3"
python_minor = "9"

try:
    assert sys.version_info >= (int(python_major), int(python_minor))
except AssertionError:
    raise RuntimeError(f"{package_name!r} requires Python {python_major}.{python_minor}+ (You have Python {sys.version})")

You can consult full Enma documentation at https://enma.gitbook.io/enma.

from typing import cast
from enma import Enma, DefaultAvailableSources, CloudFlareConfig, NHentai, Sort

enma = Enma[DefaultAvailableSources]()

config = CloudFlareConfig(
    user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36',
    cf_clearance=''
)

enma.source_manager.set_source(source_name='nhentai')
nh_source = cast(NHentai, enma.source_manager.source)
nh_source.set_config(config=config)

doujin = enma.random()
print(doujin)

from typing import cast
from enma import Enma, SourcesEnum, Manganato, IMangaRepository

class AvailableSources(SourcesEnum):
    NHENTAI = 'nhentai'
    MANGANATO = 'manganato'
    NEW_SOURCE = 'new-source'

enma = Enma[AvailableSources]()

enma.source_manager.add_source(source_name='new-source', source=Manganato()) # Source MUST be an instance of IMangaRepository
enma.source_manager.set_source(source_name=AvailableSources.MANGANATO)

manga = enma.random()
print(manga)

Caching is a key feature in Enma that improves your application's efficiency by storing the results of data requests. This means when the same data is requested again, Enma can quickly retrieve it from the cache instead of repeatedly calling the external source. This results in faster response times and less strain on both your application and the external APIs.

• Speed: Retrieving data from the cache is faster than making a new request to a manga repository.
• Efficiency: Reduces the number of network requests, which is especially useful when dealing with rate-limited APIs.
• Reliability: Provides more consistent application performance even with varying network conditions.

While Enma provides default caching settings that suit most needs, you may want to customize these settings based on your specific requirements, like how often you expect data to change or specific API rate limits.

You can control how long data is kept in the cache by setting environment variables. This allows you to fine-tune the balance between data freshness and retrieval speed without modifying the core library code.

For example, to change the cache expiration for fetching chapters, you can set the ENMA_CACHING_FETCH_SYMBOLIC_LINK_TTL_IN_SECONDS environment variable:

# Sets the cache duration to 30 minutes
export ENMA_CACHING_FETCH_SYMBOLIC_LINK_TTL_IN_SECONDS=1800

This customization capability ensures that you can adapt the caching behavior to best fit your application's performance and efficiency needs.

By leveraging caching, Enma helps make your manga-related applications faster and more reliable, all while giving you the flexibility to tailor caching behavior as needed.

Using Enma you're able to download chapter pages to your local storage or any other storage that implements ISaverAdapter.

You can check it out how to do it right below:

from enma import (Enma,
                  CloudFlareConfig, 
                  ManganatoDownloader, 
                  Threaded, 
                  LocalStorage)

enma = Enma()
enma.source_manager.set_source('manganato')
manga = enma.get(identifier='manga-wb999684')

downloader = ManganatoDownloader()
local = LocalStorage()

if manga:
    enma.download_chapter(path=f'./download/{manga.title.english}',
                          chapter=manga.chapters[0],
                          downloader=downloader,
                          saver=local,
                          threaded=Threaded(use_threads=True,
                                            number_of_threads=5))

By default Enma sets logs as SILENT. But if you're needing to see what Enma outputs you can set log mode as NORMAL or DEBUG to deep logs.

from enma import logger, LogMode

logger.mode = LogMode.NORMAL

Enma normally retrieves all information about a manga, including the pages of each chapter. This process can be slow if the manga has many chapters. To speed it up, you can use symbolic links when getting a manga. This way, Enma creates a SymbolicLink instead of fetching all data immediately. You can then use this link to quickly access and fetch data for a specific chapter later.

from enma import Enma

enma = Enma()

enma.source_manager.set_source('manganato')
doujin = enma.get(identifier='manga-kb951984', with_symbolic_links=True)

if doujin is not None:
    chapter_ref = doujin.chapters[0]
    chapter = enma.fetch_chapter_by_symbolic_link(link=chapter_ref.link)

To retrieve the user-agent and cf_clearance for NHentai:

1. Open NHentai in your browser: Navigate to the NHentai website.
2. Open Developer Tools:
   • For Google Chrome: Right-click on the webpage and select Inspect or simply press Ctrl + Shift + I (or Cmd + Option + I on Mac).
   • For Firefox: Right-click on the webpage and select Inspect Element or press Ctrl + Shift + I (or Cmd + Option + I on Mac).
3. Navigate to the Network Tab: In the Developer Tools panel, click on the Network tab. This tab captures all network requests made by the webpage.
4. Reload the Page: With the Network tab open, reload the NHentai website by pressing Ctrl + R (or Cmd + R on Mac). This ensures that all network requests are captured.
5. Select the nhentai.net Request: After reloading, you'll see a list of files on the left side of the Network tab. Click on the first file named nhentai.net. This represents the main request to the NHentai website.
6. Find the Request Headers: On the right side, you'll see several tabs like Headers, Preview, Response, etc. Make sure you're on the Headers tab. Scroll down until you find a section named Request Headers.
7. Copy the user-agent and cf_clearance:
   • user-agent: This is a string that tells the server which web browser is being used. Look for an entry named User-Agent and copy its value.
   • cf_clearance: This is a specific cookie set by CloudFlare for security purposes. Look for an entry named cf_clearance and copy its value.

config = CloudFlareConfig(
    user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36',
    cf_clearance=''
)

Note: The user-agent and cf_clearance values can change over time. If you encounter issues accessing NHentai through the Enma library, you might need to repeat the above steps to get updated values.

While using the library, you might encounter some specific errors. Here's a description of each:

1. InstanceError:

   • Description: Raised when an instance of an object is not of the expected type.
   • Common Cause: Trying to add a source that isn't an instance of IMangaRepository.

2. SourceNotAvailable:

   • Description: Raised when attempting to access a source that isn't available in the defined source list.
   • Common Cause: Trying to set a source that hasn't been previously added.

3. SourceWasNotDefined:

   • Description: Raised when trying to perform an action (like fetching a manga) without first defining a source.
   • Common Cause: Forgetting to set the source before performing an operation.

4. ExceedRetryCount:

   • Description: Specific to the NHentai adapter. Raised when the random method fails to fetch a random doujin after several attempts.
   • Common Cause: Consecutive failures when trying to fetch a random doujin from NHentai.

5. NhentaiSourceWithoutConfig:

   • Description: Raised when trying to make a request to NHentai without providing the necessary configurations.
   • Common Cause: Forgetting to provide the user-agent and cf_clearance when configuring the NHentai adapter.

6. InvalidResource:

   • Description: Raised when trying to perform an action with an invalid or inexistent resource.
   • Common Cause: Providing an inexistent folder path to downloader.

7. InvalidRequest:

   • Description: Raised when trying to perform an action with an invalid data type.
   • Common Cause: Making an action with wrong parameter data type.

8. Unknown:

   • Description: Raised when was not possible to determine the error root cause.
   • Common Cause: Not properly handled error.

9. NotFound:

   • Description: Raised when was not possible to find the requested resource..
   • Common Cause: Fetching an inexistent resource.

10. Forbidden:

    • Description: Raised when trying to perform a request to the source without right credentials.
    • Common Cause: Making a request with no or invalid credentials.

11. ExceedRateLimit:

    • Description: Raised when trying to perform more requests than a server can handle.
    • Common Cause: Looping through many pages without cooling down.

When encountering one of these errors, refer to the description and common cause to assist in troubleshooting.

We are actively working on introducing an asynchronous version of the Enma library to better cater to applications that require non-blocking operations. This version will be maintained in a separate repository to keep the core library lightweight. However, for ease of access and installation, you'll be able to install the asynchronous version directly using:

pip install enma[async]

Stay tuned for updates and ensure to check our repository for the latest advancements!

Q: Can I add more sources to Enma?
A: Yes! Enma is designed to be extensible. You can add more sources by extending the SourcesEnum and implementing IMangaRepository that contains the required methods for the new source.

Q: I'm facing issues with a specific source. What should I do?
A: Ensure you have the latest version of Enma. If the issue persists, please raise an issue on our GitHub repository detailing the problem.

Q: How often is Enma updated?
A: Enma is updated regularly as new sources are added or when there are significant changes to existing sources.

We welcome contributions! If you'd like to contribute:

1. Fork the repository.
2. Make your changes.
3. Submit a pull request.

Ensure you follow the coding standards and write tests for new features.

This software is provided "as is", without warranty of any kind, express or implied. The developers and contributors of the Enma library shall not be liable for any misuse, damages, or other consequences arising from the use of this software.

It is important to emphasize that the Enma library was developed with the goal of facilitating efficient and responsible access and manipulation of data. We do not encourage or support the use of this tool for conducting mass queries or accesses that could overload, harm, or in any way negatively affect the servers or services of the supported sources.

Users of the Enma library must always follow the guidelines, terms of use, and limitations imposed by the accessed data sources. We strongly recommend the implementation of responsible rate limiting practices and obtaining appropriate permissions when necessary, to ensure that the use of the library complies with all applicable laws and regulations, in addition to respecting ethical principles of data use.

By using the Enma library, you agree to use the tool in an ethical and responsible manner, acknowledging that the developers of Enma will not be responsible for any use that violates these guidelines.

We remind you that respect for the services and APIs of the supported sources is fundamental for the sustainability and longevity of both the Enma and the services used. We value the community and the development ecosystem and encourage all users to contribute to a safer, more respectful, and collaborative digital environment.

MIT