dev(narugo): add pydocs (adf96ebb) · Commits · git-mirror / Imgutils

docs/source/api_doc/data/index.rst

+1 −0

Original line number	Diff line number	Diff line
		@@ -15,3 +15,4 @@ imgutils.data
		decode
		image
		layer
		url

docs/source/api_doc/data/url.rst

0 → 100644

+22 −0

Original line number	Diff line number	Diff line
		imgutils.data.url
		==========================

		.. currentmodule:: imgutils.data.url

		.. automodule:: imgutils.data.url


		download_image_from_url
		-----------------------------------------------------

		.. autofunction:: download_image_from_url



		is_http_url
		-----------------------------------------------------

		.. autofunction:: is_http_url

imgutils/data/url.py

+91 −2

Original line number	Diff line number	Diff line
		"""
		This module provides utilities for downloading and handling images from URLs, with special support for GitHub and Hugging Face URLs.

		The module includes functions for:

		- Downloading images from URLs with progress tracking
		- URL validation and processing
		- Special handling for GitHub and Hugging Face hosted images

		Main components:

		- download_image_from_url: Downloads and returns an image from a given URL
		- is_http_url: Checks if a given URL is a valid HTTP/HTTPS URL
		- Internal utilities for processing GitHub and Hugging Face URLs
		"""

		import io
		from typing import Optional

		@@ -16,6 +32,28 @@ __all__ = [

		def download_image_from_url(url: str, silent: bool = False, expected_size: Optional[int] = None,
		**kwargs) -> Image.Image:
		"""
		Download an image from a URL and return it as a PIL Image object.

		:param url: URL of the image to download
		:type url: str
		:param silent: If True, suppress progress bar display
		:type silent: bool
		:param expected_size: Expected file size in bytes, used for progress bar
		:type expected_size: Optional[int]
		:param kwargs: Additional keyword arguments passed to the session.get() method

		:return: Downloaded image as PIL Image object
		:rtype: Image.Image

		:raises ValueError: If the URL is not supported (especially for HF URLs)
		:raises requests.RequestException: If download fails
		:raises PIL.UnidentifiedImageError: If downloaded content is not a valid image

		:example:
		>>> image = download_image_from_url('https://example.com/image.jpg')
		>>> image.show()
		"""
		if _is_github_url(url):
		url = _process_github_url_for_downloading(url)
		elif _is_hf_url(url):
		@@ -44,6 +82,21 @@ def download_image_from_url(url: str, silent: bool = False, expected_size: Optio


		def is_http_url(url: str) -> bool:
		"""
		Check if a given URL is a valid HTTP or HTTPS URL.

		:param url: URL to check
		:type url: str

		:return: True if URL is a valid HTTP/HTTPS URL, False otherwise
		:rtype: bool

		:example:
		>>> is_http_url('https://example.com')
		True
		>>> is_http_url('ftp://example.com')
		False
		"""
		if not isinstance(url, str):
		return False

		@@ -55,11 +108,28 @@ _GITHUB_SUFFIX = {('github', 'com')}


		def _is_github_url(url: str) -> bool:
		# assume that is_http_url(url) is True
		"""
		Check if a URL is a GitHub URL.

		:param url: URL to check
		:type url: str

		:return: True if URL is a GitHub URL, False otherwise
		:rtype: bool
		"""
		return tuple(urlsplit(url).host.split('.')[-2:]) in _GITHUB_SUFFIX


		def _process_github_url_for_downloading(url: str) -> str:
		"""
		Process a GitHub URL to make it suitable for raw file downloading.

		:param url: GitHub URL to process
		:type url: str

		:return: Processed URL for downloading
		:rtype: str
		"""
		return str(URLObject(url).with_query('raw=True'))


		@@ -67,11 +137,30 @@ _HF_SUFFIX = {('hf', 'co'), ('huggingface', 'co')}


		def _is_hf_url(url: str) -> bool:
		# assume that is_http_url(url) is True
		"""
		Check if a URL is a Hugging Face URL.

		:param url: URL to check
		:type url: str

		:return: True if URL is a Hugging Face URL, False otherwise
		:rtype: bool
		"""
		return tuple(urlsplit(url).host.split('.')[-2:]) in _HF_SUFFIX


		def _process_hf_url_for_downloading(url: str) -> str:
		"""
		Process a Hugging Face URL to make it suitable for file downloading.

		:param url: Hugging Face URL to process
		:type url: str

		:return: Processed URL for downloading
		:rtype: str

		:raises ValueError: If the URL format is not supported
		"""
		split = urlsplit(url)
		segments = split.path_segments
		if len(segments) >= 2 and (segments[1] == 'datasets' or segments[1] == 'spaces'):