hanime 1.0.0

A simple Python wrapper for interacting with Hanime's API.

Introduction

The Hanime Python Library allows you to interact with Hanime's API, fetching information about videos, images, channels, and performing searches. You can use this library to build applications or tools that make use of Hanime's data. The library is designed to be easy to use and provides a variety of features.

Requirements

Before using this library, you should ensure that you have the following requirements:

• Python 3.6 or later
• Requests library (pip install requests)
• Beautiful Soup library (pip install beautifulsoup4)

Table of Contents

1. HanimeUser Class

2. UserClient Class

   • BASE_URL Class Attribute
   • __init__(self, cookies={'in_d4': '1', 'in_m4': '1'}, headers={}) Method
   • create_default_headers() Method
   • get_channel_info(channel_id) Method

3. HanimeImage Data Class

4. ImageClient Class

   • create_default_headers() Method
   • build_query(channel_names: List[str], offset: int) Method
   • parse_community_uploads(data: dict) Method
   • get_community_uploads(channel_names: List[str], offset: int) Method

5. SearchPayload Data Class

   • create_default_payload() Method
   • convert_ordering(ordering) Method
   • convert_order_by(order_by) Method

6. BaseSearchHeaders Data Class

   • create_default_headers() Method

7. ParsedData Class

8. SearchClient Class

   • __init__(client_identifier=None) Method
   • search(payload) Method
   • filter_response(base_response, filter_options) Method
   • parse_hits_data(response) Method

9. HanimeVideo Class

10. VideoClient Class

    • BASE_URL Class Attribute
    • TAGS Class Attribute
    • __init__(self, cookies={'in_d4': '1', 'in_m4': '1',}, client_identifier=None) Method
    • create_default_headers(client_identifier: str = None) Method
    • get_video_info(video_id) Method
    • get_random_video() Method
    • get_random_video_tag(num_tags: int = 1, include_tags: Optional[List[str]] = None, exclude_tags: Optional[List[str]] = None) Method

HanimeImage (Data Class)

HanimeImage is a data class used to represent information about an image from Hanime. It contains the following attributes:

• id (int): The unique identifier for the image.
• channel_name (str): The name of the channel associated with the image.
• username (str): The username of the uploader.
• url (str): The URL of the image.
• proxy_url (str): The proxy URL of the image.
• extension (str): The file extension of the image (e.g., "jpg", "png").
• width (int): The width of the image in pixels.
• height (int): The height of the image in pixels.
• filesize (int): The size of the image file in bytes.
• created_at_unix (int): The timestamp when the image was created in Unix time format.
• updated_at_unix (int): The timestamp when the image was last updated in Unix time format.
• discord_user_id (str): The Discord user ID associated with the image.
• user_avatar_url (str): The URL of the user's avatar.
• canonical_url (str): The canonical URL of the image.

ImageClient Class

ImageClient is a class that provides methods for interacting with Hanime's community image uploads. It includes utility methods for building requests and parsing responses.

create_default_headers() Method

This method returns a dictionary of default HTTP headers that can be used for making requests to Hanime's API.

Example:

headers = ImageClient.create_default_headers()

build_query(channel_names: List[str], offset: int) Method

This method builds a query dictionary for fetching community uploads based on channel names and an offset value.

• channel_names (List[str]): A list of channel names to filter the uploads.
• offset (int): The offset value for pagination.

Example:

query = ImageClient.build_query(['channel1', 'channel2'], 10)

parse_community_uploads(data: dict) Method

This method parses the data returned from a Hanime API response and returns a list of HanimeImage objects.

• data (dict): The API response data.

Example:

data = {"data": [...] }  # API response data
images = ImageClient.parse_community_uploads(data)

get_community_uploads(channel_names: List[str], offset: int) Method

This method makes an HTTP GET request to fetch community uploads based on channel names and an offset value.

• channel_names (List[str]): A list of channel names to filter the uploads.
• offset (int): The offset value for pagination.

Example:

images_data = ImageClient.get_community_uploads(['channel1', 'channel2'], 10)

---

SearchPayload (Data Class)

SearchPayload is a data class used to represent a payload for searching on Hanime. It contains the following attributes:

• search_text (str): The search text or query.
• tags (list): A list of tags to filter the search results.
• tags_mode (str): The mode for combining tags ("AND" or "OR").
• brands (list): A list of brands to filter the search results.
• blacklist (list): A list of items to blacklist from search results.
• order_by (str): The field to order search results by.
• ordering (str): The ordering direction for search results (e.g., "desc" for descending).
• page (int): The page number for paginating search results.

create_default_payload() Method

This method creates a default payload with default values for searching.

Example:

default_payload = SearchPayload.create_default_payload()

convert_ordering(ordering) Method

This method converts an ordering option into the corresponding value used in the payload.

Example:

ordering_value = SearchPayload.convert_ordering('recent_uploads')

convert_order_by(order_by) Method

This method converts an order-by option into the corresponding value used in the payload.

Example:

order_by_value = SearchPayload.convert_order_by('most_views')

BaseSearchHeaders Data Class

BaseSearchHeaders is a data class used to represent HTTP headers for making search requests. It contains attributes for common HTTP headers.

create_default_headers() Method

This method creates a default set of HTTP headers for making search requests.

Example:

default_headers = BaseSearchHeaders.create_default_headers()

ParsedData Class

ParsedData is a class used to parse and work with data returned in search responses. It provides a way to access attributes in a dictionary-like manner and parse HTML descriptions.

Example:

parsed_data = ParsedData(data)
description = parsed_data.description

SearchClient Class

SearchClient is a class that allows you to interact with Hanime's search functionality. It provides methods for searching, filtering responses, and parsing hits data.

__init__(client_identifier=None) Method

This method initializes a SearchClient with an optional client identifier.

Example:

search_client = SearchClient(client_identifier='my-client')

search(payload) Method

This method sends a search request using the provided payload and returns the JSON response.

Example:

search_payload = SearchPayload(search_text='hentai', tags=['tag1', 'tag2'])
response = search_client.search(search_payload)

filter_response(base_response, filter_options) Method

This static method filters the response data based on specified filter options.

Example:

filtered_response = SearchClient.filter_response(base_response, ['hits', 'total'])

parse_hits_data(response) Method

This static method parses hits data from the response and returns a list of ParsedData objects.

Example:

hits_data = SearchClient.parse_hits_data(response)

---

Here's the markdown documentation for the provided Python code:

HanimeUser Class

HanimeUser is a class used to represent a user's information from Hanime. It is initialized with user data and provides a dynamic way to access user attributes.

__init__(self, data) Method

• data (dict): User data containing various attributes.

Example:

user_data = {"username": "example_user", "id": 12345, "avatar_url": "https://example.com/avatar.jpg"}
hanime_user = HanimeUser(user_data)
username = hanime_user.username

UserClient Class

UserClient is a class that interacts with Hanime's user-related API endpoints. It provides methods for fetching user-related information.

BASE_URL Class Attribute

• BASE_URL (str): The base URL for Hanime's API.

__init__(self, cookies={'in_d4': '1', 'in_m4': '1'}, headers={}) Method

• cookies (dict): Custom cookies to include in requests.
• headers (dict): Custom HTTP headers to include in requests.

Example:

user_client = UserClient() # Leave cookies & headers as none, therefore the library can use the correct ones. Unless you have fresh ones, that work maybe with `x-signature`.

create_default_headers() Method

This method returns a dictionary of default HTTP headers for making requests to Hanime's API.

Example:

default_headers = UserClient.create_default_headers()

get_channel_info(channel_id) Method

This method retrieves information about a Hanime channel based on the provided channel ID.

• channel_id (int): The ID of the channel to fetch information for.

Example:

channel_info = user_client.get_channel_info('test-123')

The returned value is a HanimeUser object representing the channel's information.

In case of an error, the method will return None.

---

Here's the markdown documentation for the provided Python code:

HanimeVideo Class

HanimeVideo is a class used to represent information about a video on Hanime. It is initialized with video data and provides a dynamic way to access video attributes.

__init__(self, data) Method

• data (dict): Video data containing various attributes.

Example:

video_data = {"title": "Example Video", "duration": 1200, "tags": ["tag1", "tag2"]}
hanime_video = HanimeVideo(video_data)
title = hanime_video.title

__getattr__(self, name) Method

This method allows dynamic access to video attributes. It returns the value of the requested attribute if it exists in the video data.

Example:

duration = hanime_video.duration

description Property

This property parses and returns the description of the video from the HTML description provided in the data.

Example:

description = hanime_video.description

VideoClient Class

VideoClient is a class that interacts with Hanime's video-related API endpoints. It provides methods for fetching video information and random videos based on tags.

BASE_URL Class Attribute

• BASE_URL (str): The base URL for Hanime's API.

TAGS Class Attribute

• TAGS (List[str]): A list of valid tags used for filtering videos.

__init__(self, cookies={'in_d4': '1', 'in_m4': '1',}, client_identifier=None) Method

• cookies (dict): Custom cookies to include in requests.
• client_identifier (str): An optional client identifier used in headers.

Example:

video_client = VideoClient(client_identifier='my-client')

create_default_headers(client_identifier: str = None) Method

This method returns a dictionary of default HTTP headers for making requests to Hanime's API. It allows you to include a client identifier in the headers.

Example:

default_headers = VideoClient.create_default_headers(client_identifier='my-client')

get_video_info(video_id) Method

This method retrieves information about a Hanime video based on the provided video ID.

• video_id (int): The ID of the video to fetch information for.

Example:

video_info = video_client.get_video_info(123)

The returned value is a HanimeVideo object representing the video's information.

In case of an error, the method will return None.

get_random_video() Method

This method fetches a random Hanime video.

Example:

random_video = video_client.get_random_video()

The returned value is a HanimeVideo object representing the random video.

In case of an error, the method will return None.

get_random_video_tag(num_tags: int = 1, include_tags: Optional[List[str]] = None, exclude_tags: Optional[List[str]] = None) Method

This method fetches a random Hanime video based on specified tags.

• num_tags (int): The number of tags to include in the search.
• include_tags (Optional[List[str]]): A list of tags to include in the search.
• exclude_tags (Optional[List[str]]): A list of tags to exclude from the search.

Example:

random_video = video_client.get_random_video_tag(num_tags=3, include_tags=['tag1', 'tag2'])

The method returns a list of ParsedData objects representing the search results based on the specified tags.

In case of an error, the method will raise InvalidTagsError if invalid tags are provided or raise a ValueError if there are not enough valid tags available after filtering.

---

Credits

• Author: lolpuud
  • Discord: dancers.
  • Email: [e-mail]

Author Note

I created this out of sheer boredom. However, this doesn't mean I won't update and maintain it. While it's not my top priority, I won't abandon the project. If there are issues that need fixing, I'll address them. I'll also work on new features if the need arises. I already have some plans for future updates, but for now, it's in good shape.

If you'd like to contribute, please feel free to create issues or pull requests. You can add new features, fix code, and more. I'll review them and accept if I find them beneficial or helpful :].