Hentai

Constructor

insert_link hentai.Hentai(RequestHandler)

Implements a wrapper class around nhentai 's RESTful API that inherits from RequestHandler. Note that the content of this module is generally considered NSFW. Use at your own discretion.

insert_link Hentai.__init__(self, id_: int=0, timeout: Tuple[float, float]=RequestHandler._timeout, total: int=RequestHandler._total, status_forcelist: List[int]=RequestHandler._status_forcelist, backoff_factor: int=RequestHandler._backoff_factor, json: dict=None) -> Hentai

Although this constructor takes many arguments, you can easily get by by using the pre-defined values. At the most basic level, you usually want to instantiate a new hentai object by id:

            
                from hentai import Hentai

                doujin = Hentai(177013)
            
        

This numbers roughly corresponds to a doujin's upload date, or rather, they reflect the order in which this item was added to the database. In addition to that, Hentai objects may also be instantiated from their GET response, in other words their original raw JSON content. But more often than not, you won't have to worry about that because this library already does all the heavy lifting for you. Also note that you can you compare Hentai objects whose comparison operators are based on their id:

            
                from hentai import Hentai

                doujin1 = Hentai(177013)
                doujin2 = Hentai(177014)

                # False
                print(doujin1 == doujin2)

                doujin2 = Hentai(177013)

                # False
                print(doujin1 != doujin2)
            
        
info Note
Only a constructor instantiated by ID inherits RequestHandler properties and methods. Head over to the RequestHandler page to learn more about this class.
insert_link Hentai.__str__(self) -> str

This magic method is equivalent to calling the title method:

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # True
                print(str(doujin) == doujin.title())

                # [ShindoLA] METAMORPHOSIS (Complete) [English]
                print(doujin)
            
        
insert_link Hentai.__repr__(self) -> str

Returns the Hentai object representation.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # Hentai(ID=177013)
                print(repr(doujin))
            
        

Fields

insert_link Hentai.HOME -> str

Returns the URL of the homepage of nhentai.

            
                from hentai import Hentai
                
                # https://nhentai.net/
                print(Hentai.HOME)
            
        
insert_link Hentai._URL -> str

Returns the base URL of doujins on nhentai.

            
                from hentai import Hentai
                
                # https://nhentai.net/g/
                print(Hentai._URL)
            
        
insert_link Hentai._API -> str

Returns the base API of doujins on nhentai.

            
                from hentai import Hentai
                
                # https://nhentai.net/api/gallery/
                print(Hentai._API)
            
        

Properties

insert_link self.id -> int

Returns the ID of this Hentai object.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # 177013
                print(doujin.id)
            
        
insert_link self.json -> dict

Returns the raw JSON response of this Hentai object.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # same as: https://nhentai.net/api/gallery/177013
                print(doujin.json)
            
        
insert_link self.url -> str

Returns the URL of this Hentai object.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # https://nhentai.net/g/177013
                print(doujin.url)
            
        
insert_link self.api -> str

Return the API endpoint of this Hentai object.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # https://nhentai.net/api/gallery/177013
                print(doujin.api)
            
        
insert_link self.media_id -> int

Returns the media ID of this Hentai object.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # 987560
                print(doujin.media_id)
            
        
insert_link self.scanlator -> str

Returns the scanlator of this Hentai object. This property has been recently added to the API. As a result of this, many items don't necessarily populate this value yet.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # empty string
                print(doujin.scanlator)
            
        
insert_link self.cover -> str

Returns the cover URL of this Hentai object.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # https://t.nhentai.net/galleries/987560/cover.jpg
                print(doujin.cover)
            
        
insert_link self.thumbnail -> str

Returns the thumbnail URL of this Hentai object. It returns the same image as the cover property but in a lower resolution.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # https://t.nhentai.net/galleries/987560/thumb.jpg
                print(doujin.thumbnail)
            
        
insert_link self.epos -> int

Returns the epos of this Hentai object.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # 1476793729
                print(doujin.epos)
            
        
insert_link self.upload_date -> datetime

Returns the upload date of this Hentai object as UTC timezone aware datetime object. Note that this is not the same as the release date.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # 2016-10-18 12:28:49+00:00
                print(doujin.upload_date)
            
        
insert_link self.tag -> List[Tag]

Returns all tags of type tag of this Hentai object. See also the methods implemented in the Tag class to help you parse this data.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # [Tag(id=19018, type='tag', name='dark skin', url='/tag/dark-skin/', count=21056), ... ]
                print(doujin.tag)
            
        
insert_link self.group -> List[Tag]

Returns all tags of type group of this Hentai object. This tag is sometimes not specified by the provider. See also the methods implemented in the Tag class to help you parse this data.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # []
                print(doujin.group)

                doujin = Hentai(123)

                # [Tag(id=13432, type='group', name='nakayohi mogudan', url='/group/nakayohi-mogudan/', count=157)]
                print(doujin.group)
            
        
insert_link self.parody -> List[Tag]

Returns all tags of type parody of this Hentai object. This tag is sometimes not specified by the provider. See also the methods implemented in the Tag class to help you parse this data.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # []
                print(doujin.parody)

                doujin = Hentai(123)

                # [Tag(id=17137, type='parody', name='neon genesis evangelion', url='/parody/neon-genesis-evangelion/', count=2489)]
                print(doujin.parody)
            
        
insert_link self.character -> List[Tag]

Returns all tags of type character of this Hentai object. This tag is sometimes not specified by the provider. See also the methods implemented in the Tag class to help you parse this data.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # []
                print(doujin.character)

                doujin = Hentai(123)

                # [Tag(id=21779, type='character', name='rei ayanami', url='/character/rei-ayanami/', count=1195)]
                print(doujin.character)
            
        
insert_link self.language -> List[Tag]

Returns all tags of type language of this Hentai object. See also the methods implemented in the Tag class to help you parse this data.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # [Tag(id=12227, type='language', name='english', url='/language/english/', count=69378), ... ]
                print(doujin.language)
            
        
insert_link self.artist -> List[Tag]

Returns all tags of type artist of this Hentai object. See also the methods implemented in the Tag class to help you parse this data.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # [Tag(id=3981, type='artist', name='shindol', url='/artist/shindol/', count=279)]
                print(doujin.artist)
            
        
insert_link self.category -> List[Tag]

Returns all tags of type category of this Hentai object. See also the methods implemented in the Tag class to help you parse this data.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # [Tag(id=33173, type='category', name='manga', url='/category/manga/', count=77142)]
                print(doujin.category)
            
        
insert_link self.num_pages -> int

Returns the total number of pages of this Hentai object.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # 225
                print(doujin.num_pages)
            
        
insert_link self.num_favorites -> int

Returns the number of times this Hentai object has been favorited. Because the API does not populate num_favorites of recently uploaded doujins, it will try to parse its HTML file as a fallback measure.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # 44548
                print(doujin.num_favorites)
            
        
insert_link self.pages -> List[Page]

Returns a collection of pages detailing URL, file extension, width, height and filename of this Hentai object. See also the properties implemented in the Page class to help you access this data.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # [Page(url='https://i.nhentai.net/galleries/987560/1.jpg', ext='.jpg', width=1275, height=1844), ... ]
                print(doujin.pages)
            
        
insert_link self.image_urls -> List[str]

Returns all image URLs of this Hentai object, excluding cover and thumbnail. To be more precise, the first image in this list is the cover image but in a higher resolution. The order of resolution goes as followed (from lower to higher resolution):

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # ['https://i.nhentai.net/galleries/987560/1.jpg', ... ]
                print(doujin.image_urls)
            
        
insert_link self.related -> List[Hentai]

Returns a list of five related doujins.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # 113554
                # 53122
                # 32979
                # 12585
                # 221592
                for related in doujin.related:
                    print(related.id)
            
        
insert_link self.thread -> List[Comment]

Returns a list of comments of this Hentai object. See also Comment and User for detailed information about these dataclasses.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # print comments posted in doujin
                for comment in doujin.thread:
                    print(comment.body)
            
        

Methods

insert_link self.title(format_: Format=Format.English) -> str

You can use the Format option to change the format of the title. It defaults to English, because the other two options, namely Japanese and Pretty, are not always guaranteed to exist.

            
                from hentai import Hentai, Format
                
                doujin = Hentai(177013)
                
                # format=English  [ShindoLA] METAMORPHOSIS (Complete) [English]
                # format=Japanese
                # format=Pretty   METAMORPHOSIS
                for f in Format:
                    print(f"format={f.name}\t{doujin.title(f)}")
            
        
insert_link self.download(folder: Path=None, delay: float=0, progressbar: bool=False) -> None

Synchronous method to download all images in self.image_urls . The destination path is the current working directory where all images will be stored in a folder corresponding to its id if folder is None, else in folder as specified in the keyword argument. Provides a delay parameter that suspends the download in-between images given in seconds. Set progressbar to True to enable progressbar feedback for terminal applications.

            
                from hentai import Hentai
                
                doujin = Hentai(177013)
                
                # stores all images in ./177013/
                doujin.download(progressbar=True)
            
        
            
                |-- cwd/
                |   |-- script.py
                |   `-- 177013/
                |       `-- 1.jpg
                |       `-- 2.jpg
                |       `-- 3.jpg
                |       `-- ...
            
        
insert_link self.export(filename: Path, options: List[Option]=None) -> None

Stores user-customized data about this Hentai object as a JSON file. Includes all available options (with the exception of Option.Raw) by default. If Option.Raw is passed as an option to options, the original unaltered JSON response will be stored instead.

            
                from hentai import Hentai, Format, Option
                from pathlib import Path
                
                doujin = Hentai(177013)
                
                # {[{"id": 177013, "title": "METAMORPHOSIS", "epos": 1476800929}]}
                custom = [Option.ID, Option.Title, Option.Epos]
                doujin.export(filename=Path(f"{doujin.title(Format.Pretty)}.json"), options=custom)

                # same as: https://nhentai.net/api/gallery/177013
                doujin.export(filename=Path(f"{doujin.title(Format.Pretty)}-raw.json"), options=[Option.Raw])
            
        

If the options list does not contain Option.Raw, the resulting file structure based on the example above will always takes the form of a list of dictionaries:

            
                {
                    [
                        {
                            "id": 177013,
                            "title": "METAMORPHOSIS",
                            "epos": 1476800929
                        },
                        {
                            "id": 177014,
                            "title": "Jintsuu Kyoujou",
                            "epos": 1476795696
                        },
                        ...
                    ]
                }
            
        
insert_link self.dictionary(options: List[Option]=None) -> dict

Return a dictionary for this Hentai object whose key-value pairs are determined by the options list.

            
                from hentai import Hentai, Format, Option
                from pathlib import Path
                
                doujin = Hentai(177013)
                
                # {"id": 177013, "title": "METAMORPHOSIS", "epos": 1476800929}
                doujin.dictionary([Option.ID, Option.Title, Option.Epos])
            
        

The content of this method yields the same content as produced by self.export with the difference that this method returns a dict without writing the result of this operation to disk.

insert_link Hentai.exists(id_: int) -> bool

Checks whether or not the id exists on nhentai.net.

            
                from hentai import Hentai
                
                # True
                print(Hentai.exists(177013))