Перейти к содержанию

IQDB

Classes

IqdbItem

Bases: BaseSearchItem

Represents a single IQDB search result item.

Attributes:

Name Type Description
origin PyQuery

The raw PyQuery data of the search result item.
content str

Text content describing the match type (e.g., 'Best match', 'Additional match').
url str

URL of the webpage containing the matched image.
source str

Primary source platform name where the image was found.
other_source list[dict[str, str]]

Additional sources, each containing 'source' name and 'url'.
thumbnail str

URL of the result's thumbnail image.
size str

Dimensions and file size of the matched image.
similarity float

Percentage similarity between the search image and result (0-100).
Source code in PicImageSearch/model/iqdb.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
class IqdbItem(BaseSearchItem):
    """Represents a single IQDB search result item.

    Attributes:
        origin (PyQuery): The raw PyQuery data of the search result item.
        content (str): Text content describing the match type (e.g., 'Best match', 'Additional match').
        url (str): URL of the webpage containing the matched image.
        source (str): Primary source platform name where the image was found.
        other_source (list[dict[str, str]]): Additional sources, each containing 'source' name and 'url'.
        thumbnail (str): URL of the result's thumbnail image.
        size (str): Dimensions and file size of the matched image.
        similarity (float): Percentage similarity between the search image and result (0-100).
    """

    def __init__(self, data: PyQuery, **kwargs: Any):
        """Initializes an IqdbItem with data from a search result.

        Args:
            data (PyQuery): A PyQuery instance containing the search result item's data.
        """
        super().__init__(data, **kwargs)

    def _parse_data(self, data: PyQuery, **kwargs: Any) -> None:
        """Initialize and parse the search result data.

        Args:
            data (PyQuery): PyQuery object containing the HTML data for this result item.
            **kwargs (Any): Additional keyword arguments passed from parent class.
        """
        self.content: str = ""
        self.source: str = ""
        self.other_source: list[dict[str, str]] = []
        self.size: str = ""
        self._arrange(data)

    def _arrange(self, data: PyQuery) -> None:
        """Extract and organize search result data from HTML structure.

        Processes the HTML table rows to extract various attributes including:
        - Content description
        - Image URLs
        - Source information
        - Image size
        - Similarity percentage

        Args:
            data (PyQuery): PyQuery object containing the table structure of the result.

        Note:
            Handles special case for "No relevant matches" results.
        """
        tr_list = list(data("tr").items())
        if len(tr_list) >= 5:
            self.content = tr_list[0]("th").text()
            if self.content == "No relevant matches":
                return
            tr_list = tr_list[1:]
        self.url = self._get_url(tr_list[0]("td > a").attr("href"))
        self.thumbnail = "https://iqdb.org" + tr_list[0]("td > a > img").attr("src")
        source_list = [i.tail.strip() for i in tr_list[1]("img")]
        self.source = source_list[0]
        if other_source := tr_list[1]("td > a"):
            self.other_source.append(
                {
                    "source": source_list[1],
                    "url": self._get_url(other_source.attr("href")),
                }
            )
        self.size = tr_list[2]("td").text()
        similarity_raw = tr_list[3]("td").text()
        self.similarity = float(similarity_raw.removesuffix("% similarity"))

    @staticmethod
    def _get_url(url: str) -> str:
        """Convert a URL to its absolute form with proper protocol.

        Args:
            url (str): A URL string that may be protocol-relative (starting with //).

        Returns:
            str: Complete URL with 'https' protocol if necessary.

        Example:
            >>> _get_url("//example.com/image.jpg")
            "https://example.com/image.jpg"
        """
        return url if url.startswith("http") else f"https:{url}"

Functions

__init__(data, **kwargs)

Initializes an IqdbItem with data from a search result.

Parameters:

Name Type Description Default
data PyQuery

A PyQuery instance containing the search result item's data.

 required
Source code in PicImageSearch/model/iqdb.py 
23
24
25
26
27
28
29
def __init__(self, data: PyQuery, **kwargs: Any):
    """Initializes an IqdbItem with data from a search result.

    Args:
        data (PyQuery): A PyQuery instance containing the search result item's data.
    """
    super().__init__(data, **kwargs)
_arrange(data)

Extract and organize search result data from HTML structure.

Processes the HTML table rows to extract various attributes including: - Content description - Image URLs - Source information - Image size - Similarity percentage

Parameters:

Name Type Description Default
data PyQuery

PyQuery object containing the table structure of the result.

 required
Note

Handles special case for "No relevant matches" results.

Source code in PicImageSearch/model/iqdb.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def _arrange(self, data: PyQuery) -> None:
    """Extract and organize search result data from HTML structure.

    Processes the HTML table rows to extract various attributes including:
    - Content description
    - Image URLs
    - Source information
    - Image size
    - Similarity percentage

    Args:
        data (PyQuery): PyQuery object containing the table structure of the result.

    Note:
        Handles special case for "No relevant matches" results.
    """
    tr_list = list(data("tr").items())
    if len(tr_list) >= 5:
        self.content = tr_list[0]("th").text()
        if self.content == "No relevant matches":
            return
        tr_list = tr_list[1:]
    self.url = self._get_url(tr_list[0]("td > a").attr("href"))
    self.thumbnail = "https://iqdb.org" + tr_list[0]("td > a > img").attr("src")
    source_list = [i.tail.strip() for i in tr_list[1]("img")]
    self.source = source_list[0]
    if other_source := tr_list[1]("td > a"):
        self.other_source.append(
            {
                "source": source_list[1],
                "url": self._get_url(other_source.attr("href")),
            }
        )
    self.size = tr_list[2]("td").text()
    similarity_raw = tr_list[3]("td").text()
    self.similarity = float(similarity_raw.removesuffix("% similarity"))
_get_url(url) staticmethod

Convert a URL to its absolute form with proper protocol.

Parameters:

Name Type Description Default
url str

A URL string that may be protocol-relative (starting with //).

 required

Returns:

Name Type Description
str str

Complete URL with 'https' protocol if necessary.
Example

_get_url("//example.com/image.jpg") "https://example.com/image.jpg"

Source code in PicImageSearch/model/iqdb.py 
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
@staticmethod
def _get_url(url: str) -> str:
    """Convert a URL to its absolute form with proper protocol.

    Args:
        url (str): A URL string that may be protocol-relative (starting with //).

    Returns:
        str: Complete URL with 'https' protocol if necessary.

    Example:
        >>> _get_url("//example.com/image.jpg")
        "https://example.com/image.jpg"
    """
    return url if url.startswith("http") else f"https:{url}"
_parse_data(data, **kwargs)

Initialize and parse the search result data.

Parameters:

Name Type Description Default
data PyQuery

PyQuery object containing the HTML data for this result item.

 required
**kwargs Any

Additional keyword arguments passed from parent class.

 {}
Source code in PicImageSearch/model/iqdb.py 
31
32
33
34
35
36
37
38
39
40
41
42
def _parse_data(self, data: PyQuery, **kwargs: Any) -> None:
    """Initialize and parse the search result data.

    Args:
        data (PyQuery): PyQuery object containing the HTML data for this result item.
        **kwargs (Any): Additional keyword arguments passed from parent class.
    """
    self.content: str = ""
    self.source: str = ""
    self.other_source: list[dict[str, str]] = []
    self.size: str = ""
    self._arrange(data)

IqdbResponse

Bases: BaseSearchResponse[IqdbItem]

Represents a complete IQDB reverse image search response.

Attributes:

Name Type Description
origin PyQuery

Raw PyQuery data of the entire response.
raw list[IqdbItem]

Primary search results with high similarity.
more list[IqdbItem]

Additional results with lower similarity.
saucenao_url str

URL to search the same image on SauceNao.
ascii2d_url str

URL to search the same image on Ascii2D.
google_url str

URL to search the same image on Google Images.
tineye_url str

URL to search the same image on TinEye.
url str

URL of the original IQDB search results page.
Source code in PicImageSearch/model/iqdb.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
class IqdbResponse(BaseSearchResponse[IqdbItem]):
    """Represents a complete IQDB reverse image search response.

    Attributes:
        origin (PyQuery): Raw PyQuery data of the entire response.
        raw (list[IqdbItem]): Primary search results with high similarity.
        more (list[IqdbItem]): Additional results with lower similarity.
        saucenao_url (str): URL to search the same image on SauceNao.
        ascii2d_url (str): URL to search the same image on Ascii2D.
        google_url (str): URL to search the same image on Google Images.
        tineye_url (str): URL to search the same image on TinEye.
        url (str): URL of the original IQDB search results page.
    """

    def __init__(self, resp_data: str, resp_url: str, **kwargs: Any):
        """Initializes with the response text.

        Args:
            resp_data (str): The text of the response.
            resp_url (str): URL to the search result page.
        """
        super().__init__(resp_data, resp_url, **kwargs)

    def _parse_response(self, resp_data: str, **kwargs: Any) -> None:
        """Initialize and parse the complete search response.

        Args:
            resp_data (str): Raw HTML response string from IQDB.
            **kwargs (Any): Additional keyword arguments passed from parent class.
        """
        data = parse_html(resp_data)
        self.origin: PyQuery = data
        self.raw: list[IqdbItem] = []
        self.more: list[IqdbItem] = []
        self.saucenao_url: str = ""
        self.ascii2d_url: str = ""
        self.google_url: str = ""
        self.tineye_url: str = ""
        self._arrange(data)

    def _arrange(self, data: PyQuery) -> None:
        """Process and organize the complete search response data.

        Handles the following tasks:
        - Determines the correct IQDB host (regular or 3D)
        - Extracts the original search image URL
        - Processes primary search results
        - Collects URLs for other search engines
        - Handles cases with no relevant matches

        Args:
            data (PyQuery): PyQuery object containing the complete search response.
        """
        host = (
            "https://iqdb.org"
            if data('a[href^="//3d.iqdb.org"]')
            else "https://3d.iqdb.org"
        )
        tables = list(data("#pages > div > table").items())
        self.url = f"{host}/?url=https://iqdb.org{tables[0].find('img').attr('src')}"
        if len(tables) > 1:
            tables = tables[1:]
            self.raw.extend([IqdbItem(i) for i in tables])
        if tables[0].find("th").text() == "No relevant matches":
            self._get_other_urls(tables[0].find("a"))
        else:
            self._get_other_urls(data("#show1 > a"))
        self._get_more(data("#more1 > div.pages > div > table"))

    def _get_more(self, data: PyQuery) -> None:
        """Extract additional lower-similarity search results.

        Args:
            data (PyQuery): PyQuery object containing the 'more results' section.
        """
        self.more.extend([IqdbItem(i) for i in data.items()])

    def _get_other_urls(self, data: PyQuery) -> None:
        """Extract URLs for searching the image on other platforms.

        Processes links to other search engines and stores their URLs in corresponding attributes.
        Handles protocol-relative URLs by adding 'https:' prefix when needed.

        Args:
            data (PyQuery): PyQuery object containing the external search links.

        Note:
            Supports links to SauceNao, ascii2d.net, Google Images, and TinEye.
        """
        urls_with_name = {
            "SauceNao": ["https:", "saucenao"],
            "ascii2d.net": ["", "ascii2d"],
            "Google Images": ["https:", "google"],
            "TinEye": ["https:", "tineye"],
        }

        for link in data.items():
            href = link.attr("href")
            text = link.text()

            if href == "#":
                continue

            if text in urls_with_name:
                prefix, attr_name = urls_with_name[text]
                # Check if the href already contains the `https:` prefix
                full_url = href if href.startswith("https:") else prefix + href
                setattr(self, f"{attr_name}_url", full_url)

Functions

__init__(resp_data, resp_url, **kwargs)

Initializes with the response text.

Parameters:

Name Type Description Default
resp_data str

The text of the response.

 required
resp_url str

URL to the search result page.

 required
Source code in PicImageSearch/model/iqdb.py 
112
113
114
115
116
117
118
119
def __init__(self, resp_data: str, resp_url: str, **kwargs: Any):
    """Initializes with the response text.

    Args:
        resp_data (str): The text of the response.
        resp_url (str): URL to the search result page.
    """
    super().__init__(resp_data, resp_url, **kwargs)
_arrange(data)

Process and organize the complete search response data.

Handles the following tasks: - Determines the correct IQDB host (regular or 3D) - Extracts the original search image URL - Processes primary search results - Collects URLs for other search engines - Handles cases with no relevant matches

Parameters:

Name Type Description Default
data PyQuery

PyQuery object containing the complete search response.

 required
Source code in PicImageSearch/model/iqdb.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def _arrange(self, data: PyQuery) -> None:
    """Process and organize the complete search response data.

    Handles the following tasks:
    - Determines the correct IQDB host (regular or 3D)
    - Extracts the original search image URL
    - Processes primary search results
    - Collects URLs for other search engines
    - Handles cases with no relevant matches

    Args:
        data (PyQuery): PyQuery object containing the complete search response.
    """
    host = (
        "https://iqdb.org"
        if data('a[href^="//3d.iqdb.org"]')
        else "https://3d.iqdb.org"
    )
    tables = list(data("#pages > div > table").items())
    self.url = f"{host}/?url=https://iqdb.org{tables[0].find('img').attr('src')}"
    if len(tables) > 1:
        tables = tables[1:]
        self.raw.extend([IqdbItem(i) for i in tables])
    if tables[0].find("th").text() == "No relevant matches":
        self._get_other_urls(tables[0].find("a"))
    else:
        self._get_other_urls(data("#show1 > a"))
    self._get_more(data("#more1 > div.pages > div > table"))
_get_more(data)

Extract additional lower-similarity search results.

Parameters:

Name Type Description Default
data PyQuery

PyQuery object containing the 'more results' section.

 required
Source code in PicImageSearch/model/iqdb.py 
167
168
169
170
171
172
173
def _get_more(self, data: PyQuery) -> None:
    """Extract additional lower-similarity search results.

    Args:
        data (PyQuery): PyQuery object containing the 'more results' section.
    """
    self.more.extend([IqdbItem(i) for i in data.items()])
_get_other_urls(data)

Extract URLs for searching the image on other platforms.

Processes links to other search engines and stores their URLs in corresponding attributes. Handles protocol-relative URLs by adding 'https:' prefix when needed.

Parameters:

Name Type Description Default
data PyQuery

PyQuery object containing the external search links.

 required
Note

Supports links to SauceNao, ascii2d.net, Google Images, and TinEye.

Source code in PicImageSearch/model/iqdb.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
def _get_other_urls(self, data: PyQuery) -> None:
    """Extract URLs for searching the image on other platforms.

    Processes links to other search engines and stores their URLs in corresponding attributes.
    Handles protocol-relative URLs by adding 'https:' prefix when needed.

    Args:
        data (PyQuery): PyQuery object containing the external search links.

    Note:
        Supports links to SauceNao, ascii2d.net, Google Images, and TinEye.
    """
    urls_with_name = {
        "SauceNao": ["https:", "saucenao"],
        "ascii2d.net": ["", "ascii2d"],
        "Google Images": ["https:", "google"],
        "TinEye": ["https:", "tineye"],
    }

    for link in data.items():
        href = link.attr("href")
        text = link.text()

        if href == "#":
            continue

        if text in urls_with_name:
            prefix, attr_name = urls_with_name[text]
            # Check if the href already contains the `https:` prefix
            full_url = href if href.startswith("https:") else prefix + href
            setattr(self, f"{attr_name}_url", full_url)
_parse_response(resp_data, **kwargs)

Initialize and parse the complete search response.

Parameters:

Name Type Description Default
resp_data str

Raw HTML response string from IQDB.

 required
**kwargs Any

Additional keyword arguments passed from parent class.

 {}
Source code in PicImageSearch/model/iqdb.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def _parse_response(self, resp_data: str, **kwargs: Any) -> None:
    """Initialize and parse the complete search response.

    Args:
        resp_data (str): Raw HTML response string from IQDB.
        **kwargs (Any): Additional keyword arguments passed from parent class.
    """
    data = parse_html(resp_data)
    self.origin: PyQuery = data
    self.raw: list[IqdbItem] = []
    self.more: list[IqdbItem] = []
    self.saucenao_url: str = ""
    self.ascii2d_url: str = ""
    self.google_url: str = ""
    self.tineye_url: str = ""
    self._arrange(data)

Functions