A simple Python wrapper for interacting with Hanime's API.
Project description
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
-
BASE_URL
Class AttributeTAGS
Class Attribute__init__(self, cookies={'in_d4': '1', 'in_m4': '1',}, client_identifier=None)
Methodcreate_default_headers(client_identifier: str = None)
Methodget_video_info(video_id)
Methodget_random_video()
Methodget_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:
bio@fbi.ac
- Discord:
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 :].
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.