xhamster_api 2.0__tar.gz → 2.2__tar.gz

{xhamster_api-2.0 → xhamster_api-2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xhamster_api
-Version: 2.0
+Version: 2.2
 Summary: A Python API for the Porn Site xhamster.com
 Author: Johannes Habel
 Author-email: Johannes Habel <EchterAlsFake@proton.me>
@@ -14,9 +14,7 @@ Requires-Dist: eaf-base-api
 Requires-Dist: m3u8
 Requires-Dist: av ; python_full_version >= '3.10' and extra == 'av'
 Requires-Dist: lxml ; extra == 'full'
-Requires-Dist: httpx[http2] ; extra == 'full'
-Requires-Dist: httpx[socks] ; extra == 'full'
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Project-URL: Homepage, https://github.com/EchterAlsFake/xhamster_api
 Provides-Extra: av
 Provides-Extra: full
@@ -34,10 +32,45 @@ Description-Content-Type: text/markdown
 XHamster API is an API for xhamster.com. It allows you to fetch information from videos using regexes and requests.
 
 # Disclaimer
-> [!IMPORTANT] 
-> XHamster API is in violation to the ToS of xhamster.com!
-> If you are the website owner of xhamster.com, contact me at my E-Mail, and I'll take this repository immediately offline.
-> EchterAlsFake@proton.me
+> [!IMPORTANT]
+> This is an unofficial and unaffiliated project. Please read the full disclaimer before use:
+> **[DISCLAIMER.md](https://github.com/EchterAlsFake/API_Docs/blob/master/Disclaimer.md)**
+>
+> By using this project you agree to comply with the target site’s rules, copyright/licensing requirements,
+> and applicable laws. Do not use it to bypass access controls or scrape at disruptive rates.
+
+# Features
+- Fetch videos + metadata
+- Download videos
+- Fetch Channels
+- Fetch Pornstars
+- Fetch Creators
+- Fetch Shorts
+- Search for videos
+- Fetch playlists
+- Asynchronous
+- Built-in caching
+- Easy interface
+- Great type hinting
+
+#### Networking Features
+- HTTP 2.0 / HTTP 3.0
+- Browser impersonation
+- Custom JA3
+- All proxy types
+- Proxy authentication
+- Speed Limit
+- DNS over HTTPS
+- And even more...
+- All of this is configurable and can be adjusted as you like!
+
+# Supported Platforms
+This API has been tested and confirmed working on:
+
+- Windows 11 (x64) 
+- macOS Sequoia (x86_64)
+- Linux (Arch) (x86_64)
+- Android 16 (aarch64)
 
 # Quickstart
 
@@ -48,17 +81,19 @@ XHamster API is an API for xhamster.com. It allows you to fetch information from
 ```python
 from xhamster_api import Client
 # Initialize a Client object
-client = Client()
 
-# Fetch a video
-video_object = client.get_video("<insert_url_here>")
-
-# Information from Video objects
-print(video_object.title)
-print(video_object.likes)
-# Download the video
-
-video_object.download(downloader="threaded", quality="best", path="your_output_path + filename")
+async def main():
+    client = Client()
+    
+    # Fetch a video
+    video_object = await client.get_video("<insert_url_here>")
+    
+    # Information from Video objects
+    print(video_object.title)
+    print(video_object.likes)
+    # Download the video
+    
+    await video_object.download(downloader="threaded", quality="best", path="your_output_path + filename")
 
 # SEE DOCUMENTATION FOR MORE
 ```
@@ -82,4 +117,4 @@ Pull requests are also welcome.
 
 # License
 Licensed under the LGPLv3 License
-<br>Copyright (C) 2023–2025 Johannes Habel
+<br>Copyright (C) 2023–2026 Johannes Habel

{xhamster_api-2.0 → xhamster_api-2.2}/README.md

@@ -10,10 +10,45 @@
 XHamster API is an API for xhamster.com. It allows you to fetch information from videos using regexes and requests.
 
 # Disclaimer
-> [!IMPORTANT] 
-> XHamster API is in violation to the ToS of xhamster.com!
-> If you are the website owner of xhamster.com, contact me at my E-Mail, and I'll take this repository immediately offline.
-> EchterAlsFake@proton.me
+> [!IMPORTANT]
+> This is an unofficial and unaffiliated project. Please read the full disclaimer before use:
+> **[DISCLAIMER.md](https://github.com/EchterAlsFake/API_Docs/blob/master/Disclaimer.md)**
+>
+> By using this project you agree to comply with the target site’s rules, copyright/licensing requirements,
+> and applicable laws. Do not use it to bypass access controls or scrape at disruptive rates.
+
+# Features
+- Fetch videos + metadata
+- Download videos
+- Fetch Channels
+- Fetch Pornstars
+- Fetch Creators
+- Fetch Shorts
+- Search for videos
+- Fetch playlists
+- Asynchronous
+- Built-in caching
+- Easy interface
+- Great type hinting
+
+#### Networking Features
+- HTTP 2.0 / HTTP 3.0
+- Browser impersonation
+- Custom JA3
+- All proxy types
+- Proxy authentication
+- Speed Limit
+- DNS over HTTPS
+- And even more...
+- All of this is configurable and can be adjusted as you like!
+
+# Supported Platforms
+This API has been tested and confirmed working on:
+
+- Windows 11 (x64) 
+- macOS Sequoia (x86_64)
+- Linux (Arch) (x86_64)
+- Android 16 (aarch64)
 
 # Quickstart
 
@@ -24,17 +59,19 @@ XHamster API is an API for xhamster.com. It allows you to fetch information from
 ```python
 from xhamster_api import Client
 # Initialize a Client object
-client = Client()
 
-# Fetch a video
-video_object = client.get_video("<insert_url_here>")
-
-# Information from Video objects
-print(video_object.title)
-print(video_object.likes)
-# Download the video
-
-video_object.download(downloader="threaded", quality="best", path="your_output_path + filename")
+async def main():
+    client = Client()
+    
+    # Fetch a video
+    video_object = await client.get_video("<insert_url_here>")
+    
+    # Information from Video objects
+    print(video_object.title)
+    print(video_object.likes)
+    # Download the video
+    
+    await video_object.download(downloader="threaded", quality="best", path="your_output_path + filename")
 
 # SEE DOCUMENTATION FOR MORE
 ```
@@ -58,4 +95,4 @@ Pull requests are also welcome.
 
 # License
 Licensed under the LGPLv3 License
-<br>Copyright (C) 2023–2025 Johannes Habel
+<br>Copyright (C) 2023–2026 Johannes Habel

{xhamster_api-2.0 → xhamster_api-2.2}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "uv_build"
 
 [project]
 name = "xhamster_api"
-version = "2.0"
+version = "2.2"
 description = "A Python API for the Porn Site xhamster.com"
 readme = { file = "README.md", content-type = "text/markdown" }
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 license = "LGPL-3.0-only"
 license-files = ["LICENSE"]
 authors = [
@@ -28,7 +28,7 @@ classifiers = [
 
 [project.optional-dependencies]
 av = ["av; python_version >= '3.10'"]
-full = ["lxml", "httpx[http2]", "httpx[socks]"] # H2 for HTTP 2.0 support, LXML for faster parsing speed, though optional :)
+full = ["lxml"] # H2 for HTTP 2.0 support, LXML for faster parsing speed, though optional :)
 
 [project.urls]
 Homepage = "https://github.com/EchterAlsFake/xhamster_api"

xhamster_api-2.2/xhamster_api/modules/type_hints.py

@@ -0,0 +1,4 @@
+from typing import Callable, Awaitable
+
+type callback_hint = Callable[[int, int], None] | None
+type on_error_hint = Callable[[str, Exception, int], Awaitable[bool]] | None

{xhamster_api-2.0 → xhamster_api-2.2}/xhamster_api/xhamster_api.py

@@ -7,21 +7,21 @@ import threading
 
 from functools import cached_property
 from urllib.parse import urlencode, quote
-from base_api.modules.config import RuntimeConfig
-from base_api.modules.errors import NetworkingError, BotProtectionDetected, UnknownError, InvalidProxy
-from typing import Literal, AsyncGenerator, Any, Dict, List
-from base_api.base import BaseCore, setup_logger, Helper
 from curl_cffi import AsyncSession, Response
+from base_api.modules.config import RuntimeConfig
+from typing import Literal, AsyncGenerator, Any, Dict
 from base_api.modules.type_hints import DownloadReport
+from base_api.base import BaseCore, setup_logger, Helper
+from base_api.modules.errors import NetworkingError, BotProtectionDetected, UnknownError, InvalidProxy, ResourceGone
 
 try:
     from modules.consts import *
     from modules.errors import *
-    from modules.type_hints import callback_hint
+    from modules.type_hints import *
 except (ModuleNotFoundError, ImportError):
     from .modules.consts import *
     from .modules.errors import *
-    from .modules.type_hints import callback_hint
+    from .modules.type_hints import *
 
 try:
     import lxml
@@ -30,7 +30,15 @@ except (ModuleNotFoundError, ImportError):
     parser = "html.parser"
 
 
-async def get_html_content(core: BaseCore, url: str) -> str | None:
+async def on_error(url: str, error: Exception, attempt: int) -> bool:
+    print(f"URL: {url}, ERROR: {error}, Attempt: {attempt}")
+
+    if isinstance(error, ResourceGone):
+        return False
+
+    return True
+
+async def get_html_content(core: BaseCore, url: str) -> str | None | dict:
     # What should I do here?
     try:
         content = await core.fetch(url)
@@ -41,17 +49,17 @@ async def get_html_content(core: BaseCore, url: str) -> str | None:
             if content.status_code == 404:
                 raise NotFound(f"Server returned 404 for: {url}")
 
-    except NetworkingError:
-        raise NetworkError from NetworkingError
+    except NetworkingError as e:
+        raise NetworkError(str(e)) from e
 
-    except InvalidProxy:
-        raise ProxyError from InvalidProxy
+    except InvalidProxy as e:
+        raise ProxyError(str(e)) from e
 
-    except BotProtectionDetected:
-        raise BotDetection from BotProtectionDetected
+    except BotProtectionDetected as e:
+        raise BotDetection(str(e)) from e
 
-    except UnknownError:
-        raise UnknownNetworkError from UnknownError
+    except UnknownError as e:
+        raise UnknownNetworkError(str(e)) from e
 
 
 class Something(Helper):
@@ -116,14 +124,18 @@ class Something(Helper):
     def avatar_url(self) -> str:
         return REGEX_AVATAR.search(self.html_content).group(1)
 
-    async def videos(self, pages: int = 2, videos_concurrency: int | None = None, pages_concurrency: int | None = None) -> AsyncGenerator[Video, None]:
+    async def videos(self, pages: int = 2, videos_concurrency: int | None = None, pages_concurrency: int | None = None,
+                     on_video_error: on_error_hint = on_error,
+                     on_page_error: on_error_hint = None
+                     ) -> AsyncGenerator[Video, None]:
         page_urls = [build_page_url(url=self.url, is_search=False, idx=page) for page in range(1, pages + 1)]
         videos_concurrency = videos_concurrency or self.core.configuration.videos_concurrency
         pages_concurrency = pages_concurrency or self.core.configuration.pages_concurrency
         assert videos_concurrency and pages_concurrency
 
         async for video in self.iterator(use_alternative_constructor=True, video_link_extractor=extractor_shorts, target_page_urls=page_urls,
-                                 max_video_concurrency=videos_concurrency, max_page_concurrency=pages_concurrency):
+                                 max_video_concurrency=videos_concurrency, max_page_concurrency=pages_concurrency,
+                                         on_video_error=on_video_error, on_page_error=on_page_error):
             yield await video.init()
 
     @cached_property
@@ -148,14 +160,18 @@ class Something(Helper):
 
         return dictionary
 
-    async def get_shorts(self, pages: int = 2, videos_concurrency: int = 2, pages_concurrency: int = 1) -> AsyncGenerator[Short, None]:
+    async def get_shorts(self, pages: int = 2, videos_concurrency: int = 2, pages_concurrency: int = 1,
+                         on_video_error: on_error_hint = on_error,
+                         on_page_error: on_error_hint = None
+                         ) -> AsyncGenerator[Short, None]:
         if not self.url.endswith("/"):
             self.url += "/"
 
         self.url += "shorts"
         page_urls = [build_page_url(self.url, is_search=False, idx=page) for page in range(1, pages + 1)]
         async for short in self.iterator(use_alternative_constructor=True, video_link_extractor=extractor_shorts, target_page_urls=page_urls,
-                                 max_video_concurrency=videos_concurrency, max_page_concurrency=pages_concurrency):
+                                 max_video_concurrency=videos_concurrency, max_page_concurrency=pages_concurrency,
+                                         on_video_error=on_video_error, on_page_error=on_page_error):
             yield await short.init()
 
 class Channel(Something):
@@ -424,7 +440,10 @@ class Client(Helper):
         date: Literal["latest", "weekly", "monthly", "yearly"] | None = None,
         production: Literal["studios", "creators"] | None = None,
         fps: Literal["30", "60"] | None = None,
-        pages: int = 2, videos_concurrency: int | None = None, pages_concurrency: int | None = None,) -> AsyncGenerator[Video, None]:
+        pages: int = 2, videos_concurrency: int | None = None, pages_concurrency: int | None = None,
+                            on_video_error: on_error_hint = on_error,
+                            on_page_error: on_error_hint = None
+                            ) -> AsyncGenerator[Video, None]:
         path = quote(str(query), safe="")  # e.g. "4k cats & dogs" -> "4k%20cats%20%26%20dogs"
         base = f"https://xhamster.com/search/"
         url = base + path
@@ -468,5 +487,6 @@ class Client(Helper):
         assert isinstance(pages_concurrency, int)
 
         async for video in self.iterator(use_alternative_constructor=True, video_link_extractor=extractor_shorts, target_page_urls=page_urls,
-                                 max_video_concurrency=videos_concurrency, max_page_concurrency=pages_concurrency):
+                                 max_video_concurrency=videos_concurrency, max_page_concurrency=pages_concurrency,
+                                         on_video_error=on_video_error, on_page_error=on_page_error):
             yield await video.init()

xhamster_api-2.0/xhamster_api/modules/type_hints.py

@@ -1,3 +0,0 @@
-from typing import Callable
-
-type callback_hint = Callable[[int, int], None] | None