Functions
	init (engine_settings=None)
dict[str, t.Any]	request (str query, dict[str, t.Any] params)
list[dict[str, t.Any]]	response ("SXNG_Response" resp)
dict[str, t.Any]	build_result (etree.Element item)
str\|None	_map_result_url (str\|None guid, str\|None comments)
str\|None	_map_leechers (str\|None leechers, str\|None seeders, str\|None peers)
datetime\|None	_map_published_date (str\|None pubDate)
str\|None	_map_torrent_file (str\|None link, str\|None enclosure_url)
str\|None	_map_magnet_link (str\|None magneturl, str\|None guid, str\|None enclosure_url, str\|None link)
str\|None	get_attribute (etree.Element item, str property_name)
str\|None	get_torznab_attribute (etree.Element item, str attribute_name)

Variables
dict	about
list	categories = ['files']
bool	paging = False
bool	time_range_support = False
str	base_url = ''
str	api_key = ''
list	torznab_categories = []
bool	show_torrent_files = False
bool	show_magnet_links = True

Detailed Description

Torznab_ is an API specification that provides a standardized way to query
torrent site for content. It is used by a number of torrent applications,
including Prowlarr_ and Jackett_.

Using this engine together with Prowlarr_ or Jackett_ allows you to search
a huge number of torrent sites which are not directly supported.

Configuration
=============

The engine has the following settings:

``base_url``:
  Torznab endpoint URL.

``api_key``:
  The API key to use for authentication.

``torznab_categories``:
  The categories to use for searching. This is a list of category IDs.  See
  Prowlarr-categories_ or Jackett-categories_ for more information.

``show_torrent_files``:
  Whether to show the torrent file in the search results.  Be careful as using
  this with Prowlarr_ or Jackett_ leaks the API key.  This should be used only
  if you are querying a Torznab endpoint without authentication or if the
  instance is private.  Be aware that private trackers may ban you if you share
  the torrent file.  Defaults to ``false``.

``show_magnet_links``:
  Whether to show the magnet link in the search results.  Be aware that private
  trackers may ban you if you share the magnet link.  Defaults to ``true``.

.. _Torznab:
   https://torznab.github.io/spec-1.3-draft/index.html
.. _Prowlarr:
   https://github.com/Prowlarr/Prowlarr
.. _Jackett:
   https://github.com/Jackett/Jackett
.. _Prowlarr-categories:
   https://wiki.servarr.com/en/prowlarr/cardigann-yml-definition#categories
.. _Jackett-categories:
   https://github.com/Jackett/Jackett/wiki/Jackett-Categories

Implementations
===============

Function Documentation

◆ _map_leechers()

str \| None searx.engines.torznab._map_leechers	(	str \| None	leechers,
		str \| None	seeders,
		str \| None	peers )

protected

Definition at line 179 of file torznab.py.

def _map_leechers(leechers: str | None, seeders: str | None, peers: str | None) -> str | None:
    if leechers:
        return leechers
    if seeders and peers:
        return str(int(peers) - int(seeders))
    return None
 
 

Referenced by build_result().

Here is the caller graph for this function:

◆ _map_magnet_link()

str \| None searx.engines.torznab._map_magnet_link	(	str \| None	magneturl,
		str \| None	guid,
		str \| None	enclosure_url,
		str \| None	link )

protected

Definition at line 204 of file torznab.py.

) -> str | None:
    if magneturl and magneturl.startswith('magnet'):
        return magneturl
    if guid and guid.startswith('magnet'):
        return guid
    if enclosure_url and enclosure_url.startswith('magnet'):
        return enclosure_url
    if link and link.startswith('magnet'):
        return link
    return None
 
 

Referenced by build_result().

Here is the caller graph for this function:

◆ _map_published_date()

datetime | None searx.engines.torznab._map_published_date ( str | None pubDate )

protected

Definition at line 187 of file torznab.py.

def _map_published_date(pubDate: str | None) -> datetime | None:
    if pubDate is not None:
        try:
            return datetime.strptime(pubDate, '%a, %d %b %Y %H:%M:%S %z')
        except (ValueError, TypeError) as e:
            logger.debug("ignore exception (publishedDate): %s", e)
    return None
 
 

Referenced by build_result().

Here is the caller graph for this function:

◆ _map_result_url()

str \| None searx.engines.torznab._map_result_url	(	str \| None	guid,
		str \| None	comments )

protected

Definition at line 171 of file torznab.py.

def _map_result_url(guid: str | None, comments: str | None) -> str | None:
    if guid and guid.startswith('http'):
        return guid
    if comments and comments.startswith('http'):
        return comments
    return None
 
 

Referenced by build_result().

Here is the caller graph for this function:

◆ _map_torrent_file()

str \| None searx.engines.torznab._map_torrent_file	(	str \| None	link,
		str \| None	enclosure_url )

protected

Definition at line 196 of file torznab.py.

def _map_torrent_file(link: str | None, enclosure_url: str | None) -> str | None:
    if link and link.startswith('http'):
        return link
    if enclosure_url and enclosure_url.startswith('http'):
        return enclosure_url
    return None
 
 

Referenced by build_result().

Here is the caller graph for this function:

◆ build_result()

dict[str, t.Any] searx.engines.torznab.build_result ( etree.Element item )

Build a result from a XML item.

Definition at line 127 of file torznab.py.

def build_result(item: etree.Element) -> dict[str, t.Any]:
    """Build a result from a XML item."""
 
    # extract attributes from XML
    # see https://torznab.github.io/spec-1.3-draft/torznab/Specification-v1.3.html#predefined-attributes
    enclosure: etree.Element | None = item.find('enclosure')
    enclosure_url: str | None = None
    if enclosure is not None:
        enclosure_url = enclosure.get('url')
 
    filesize = get_attribute(item, 'size')
    if not filesize and enclosure:
        filesize = enclosure.get('length')
 
    guid = get_attribute(item, 'guid')
    comments = get_attribute(item, 'comments')
    pubDate = get_attribute(item, 'pubDate')
    seeders = get_torznab_attribute(item, 'seeders')
    leechers = get_torznab_attribute(item, 'leechers')
    peers = get_torznab_attribute(item, 'peers')
 
    # map attributes to SearXNG result
    result: dict[str, t.Any] = {
        'template': 'torrent.html',
        'title': get_attribute(item, 'title'),
        'filesize': humanize_bytes(int(filesize)) if filesize else None,
        'files': get_attribute(item, 'files'),
        'seed': seeders,
        'leech': _map_leechers(leechers, seeders, peers),
        'url': _map_result_url(guid, comments),
        'publishedDate': _map_published_date(pubDate),
        'torrentfile': None,
        'magnetlink': None,
    }
 
    link = get_attribute(item, 'link')
    if show_torrent_files:
        result['torrentfile'] = _map_torrent_file(link, enclosure_url)
    if show_magnet_links:
        magneturl = get_torznab_attribute(item, 'magneturl')
        result['magnetlink'] = _map_magnet_link(magneturl, guid, enclosure_url, link)
    return result
 
 

References _map_leechers(), _map_magnet_link(), _map_published_date(), _map_result_url(), _map_torrent_file(), get_attribute(), and get_torznab_attribute().

Referenced by response().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_attribute()

str \| None searx.engines.torznab.get_attribute	(	etree.Element	item,
		str	property_name )

Get attribute from item.

Definition at line 221 of file torznab.py.

def get_attribute(item: etree.Element, property_name: str) -> str | None:
    """Get attribute from item."""
    property_element: etree.Element | None = item.find(property_name)
    if property_element is not None:
        return property_element.text
    return None
 
 

Referenced by build_result().

Here is the caller graph for this function:

◆ get_torznab_attribute()

str \| None searx.engines.torznab.get_torznab_attribute	(	etree.Element	item,
		str	attribute_name )

Get torznab special attribute from item.

Definition at line 229 of file torznab.py.

def get_torznab_attribute(item: etree.Element, attribute_name: str) -> str | None:
    """Get torznab special attribute from item."""
    element: etree.Element | None = item.find(
        './/torznab:attr[@name="{attribute_name}"]'.format(attribute_name=attribute_name),
        {'torznab': 'http://torznab.com/schemas/2015/feed'},
    )
    if element is not None:
        return element.get("value")
    return None

Referenced by build_result().

Here is the caller graph for this function:

◆ init()

searx.engines.torznab.init ( engine_settings = None )

Initialize the engine.

Definition at line 86 of file torznab.py.

def init(engine_settings=None):  # pylint: disable=unused-argument
    """Initialize the engine."""
    if len(base_url) < 1:
        raise ValueError('missing torznab base_url')
 
 

◆ request()

dict[str, t.Any] searx.engines.torznab.request	(	str	query,
		dict[str, t.Any]	params )

Build the request params.

Definition at line 92 of file torznab.py.

def request(query: str, params: dict[str, t.Any]) -> dict[str, t.Any]:
    """Build the request params."""
    search_url: str = base_url + '?t=search&q={search_query}'
 
    if len(api_key) > 0:
        search_url += '&apikey={api_key}'
    if len(torznab_categories) > 0:
        search_url += '&cat={torznab_categories}'
 
    params['url'] = search_url.format(
        search_query=quote(query), api_key=api_key, torznab_categories=",".join([str(x) for x in torznab_categories])
    )
 
    return params
 
 

◆ response()

list[dict[str, t.Any]] searx.engines.torznab.response ( "SXNG_Response" resp )

Parse the XML response and return a list of results.

Definition at line 108 of file torznab.py.

def response(resp: "SXNG_Response") -> list[dict[str, t.Any]]:
    """Parse the XML response and return a list of results."""
    results = []
    search_results = etree.XML(resp.content)
 
    # handle errors:  https://newznab.readthedocs.io/en/latest/misc/api/#newznab-error-codes
    if search_results.tag == "error":
        raise SearxEngineAPIException(search_results.get("description"))
 
    channel: etree.Element = search_results[0]
 
    item: etree.Element
    for item in channel.iterfind('item'):
        result: dict[str, t.Any] = build_result(item)
        results.append(result)
 
    return results
 
 

References build_result().

Here is the call graph for this function:

Variable Documentation

◆ about

dict searx.engines.torznab.about

Initial value:

=  {
    "website": None,
    "wikidata_id": None,
    "official_api_documentation": "https://torznab.github.io/spec-1.3-draft",
    "use_official_api": True,
    "require_api_key": False,
    "results": 'XML',
}

Definition at line 64 of file torznab.py.

◆ api_key

str searx.engines.torznab.api_key = ''

Definition at line 79 of file torznab.py.

◆ base_url

str searx.engines.torznab.base_url = ''

Definition at line 78 of file torznab.py.

◆ categories

list searx.engines.torznab.categories = ['files']

Definition at line 72 of file torznab.py.

◆ paging

bool searx.engines.torznab.paging = False

Definition at line 73 of file torznab.py.

◆ show_magnet_links

bool searx.engines.torznab.show_magnet_links = True

Definition at line 83 of file torznab.py.

◆ show_torrent_files

bool searx.engines.torznab.show_torrent_files = False

Definition at line 82 of file torznab.py.

◆ time_range_support

bool searx.engines.torznab.time_range_support = False

Definition at line 74 of file torznab.py.

◆ torznab_categories

list searx.engines.torznab.torznab_categories = []

Definition at line 81 of file torznab.py.

Functions
	init (engine_settings=None)
dict[str, t.Any]	request (str query, dict[str, t.Any] params)
list[dict[str, t.Any]]	response ("SXNG_Response" resp)
dict[str, t.Any]	build_result (etree.Element item)
str\|None	_map_result_url (str\|None guid, str\|None comments)
str\|None	_map_leechers (str\|None leechers, str\|None seeders, str\|None peers)
datetime\|None	_map_published_date (str\|None pubDate)
str\|None	_map_torrent_file (str\|None link, str\|None enclosure_url)
str\|None	_map_magnet_link (str\|None magneturl, str\|None guid, str\|None enclosure_url, str\|None link)
str\|None	get_attribute (etree.Element item, str property_name)
str\|None	get_torznab_attribute (etree.Element item, str attribute_name)

Functions

Variables

Detailed Description

Function Documentation

◆ _map_leechers()

◆ _map_magnet_link()

◆ _map_published_date()

◆ _map_result_url()

◆ _map_torrent_file()

◆ build_result()

◆ get_attribute()

◆ get_torznab_attribute()

◆ init()

◆ request()

◆ response()

Variable Documentation

◆ about

◆ api_key

◆ base_url

◆ categories

◆ paging

◆ show_magnet_links

◆ show_torrent_files

◆ time_range_support

◆ torznab_categories