CYBERDEViL
/
searx-qt


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450
							<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.16: http://docutils.sourceforge.net/" />
<title>searx-qt documentation</title>
<style type="text/css">

/*
:Author: CYBERDEViL
:Contact: cyberdevilnl at protonmail d0t com
:Copyright: This stylesheet has been placed in the public domain.

Stylesheet for use with Docutils.

https://docutils.sourceforge.io/docs/howto/html-stylesheets.html
*/

@import url(html4css1.css);

/*indent sections a little*/
.section {
  margin-left: 12px;
}

/*indent section contents a little*/
p, pre, table {
  margin-left: 12px;
}

pre {
  background-color: #efefef;
  border: 1px solid #dfdfdf;
}

h1 {
  background-color: #cfcfcf;
}

img.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em
}

</style>
</head>
<body>
<div class="document">


<div class="section" id="searx-qt">
<h1>searx-qt</h1>
<div class="section" id="lightweight-desktop-application-for-searx">
<h2>Lightweight desktop application for searx</h2>
<p>This document is work in progress; as is the searx-qt project.</p>
</div>
</div>
<div class="section" id="id1">
<span id="index"></span><h1>Index</h1>
<ul class="simple">
<li><a class="reference internal" href="#index">Index</a></li>
<li><a class="reference internal" href="#about">About</a></li>
<li><ul class="first">
<li><a class="reference internal" href="#about-summary">Summary</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#about-source">Source</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#about-license">License</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#about-dependencies">Dependencies</a></li>
</ul>
</li>
<li><a class="reference internal" href="#getting-started">Getting started</a></li>
<li><ul class="first">
<li><a class="reference internal" href="#getting-started-install-dependencies">Install dependencies</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#getting-started-installation">Installation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#usage">Usage</a></li>
<li><ul class="first">
<li><a class="reference internal" href="#usage-settings">Settings</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#usage-instances">Instances</a></li>
</ul>
</li>
<li><ul class="first">
<li><a class="reference internal" href="#usage-search">Search</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="id2">
<span id="about"></span><h1>About</h1>
<div class="section" id="summary">
<span id="about-summary"></span><h2>Summary</h2>
<p>searx-qt is a lightweight desktop application that lets you search on
public searx instances listed on <cite>https://searx.space</cite>.</p>
<p>Technically searx-qt is a client application that does magic with the searx
API and searx-stats2 it's instances.json</p>
<div class="section" id="searx">
<h3>searx</h3>
<p>Actual search requests will be made to a server running searx software, there
are many public available. We call such servers 'instances'.</p>
<p>If you are not familiar with the searx project; you can checkout their page
here: <a class="reference external" href="https://asciimoo.github.io/searx/">https://asciimoo.github.io/searx/</a> or <a class="reference external" href="https://searx.me/">https://searx.me/</a></p>
<ul class="simple">
<li>API Docs: <a class="reference external" href="https://asciimoo.github.io/searx/dev/search_api.html">https://asciimoo.github.io/searx/dev/search_api.html</a></li>
<li>Source: <a class="reference external" href="https://github.com/asciimoo/searx">https://github.com/asciimoo/searx</a></li>
<li>License: GPLv3</li>
</ul>
</div>
<div class="section" id="searx-stats2">
<h3>searx-stats2</h3>
<p>The searx-stats2 project lists public searx instances with statistics. The
original instance is running at <a class="reference external" href="https://searx.space/">https://searx.space/</a>. This is where searx-qt
will request a list with instances when the update button is pressed.</p>
<ul class="simple">
<li>Source: <a class="reference external" href="https://github.com/dalf/searx-stats2">https://github.com/dalf/searx-stats2</a></li>
<li>License: GPLv3</li>
</ul>
</div>
</div>
<div class="section" id="source">
<span id="about-source"></span><h2>Source</h2>
<ul class="simple">
<li>git: <a class="reference external" href="https://notabug.org/CYBERDEViL/searx-qt">https://notabug.org/CYBERDEViL/searx-qt</a></li>
<li>ssh: <a class="reference external" href="mailto:git&#64;notabug.org">git&#64;notabug.org</a>:CYBERDEViL/searx-qt.git</li>
</ul>
</div>
<div class="section" id="license">
<span id="about-license"></span><h2>License</h2>
<ul class="simple">
<li>GPLv3</li>
<li><a class="reference external" href="https://www.gnu.org/licenses/gpl-3.0.en.html">https://www.gnu.org/licenses/gpl-3.0.en.html</a></li>
</ul>
</div>
<div class="section" id="dependencies">
<span id="about-dependencies"></span><h2>Dependencies</h2>
<table border="1" class="docutils">
<colgroup>
<col width="10%" />
<col width="11%" />
<col width="11%" />
<col width="68%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">version</th>
<th class="head">license</th>
<th class="head">URL</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>python</td>
<td>3</td>
<td>PSFL</td>
<td><a class="reference external" href="https://docs.python.org/3/license.html">https://docs.python.org/3/license.html</a></td>
</tr>
<tr><td>requests</td>
<td>&nbsp;</td>
<td>Apache 2</td>
<td><a class="reference external" href="http://docs.python-requests.org/en/master/">http://docs.python-requests.org/en/master/</a></td>
</tr>
<tr><td>PyQt5</td>
<td>&nbsp;</td>
<td>GPLv3</td>
<td><a class="reference external" href="https://www.riverbankcomputing.com/software/pyqt/intro">https://www.riverbankcomputing.com/software/pyqt/intro</a></td>
</tr>
</tbody>
</table>
<p>Optional for socks proxy support:</p>
<table border="1" class="docutils">
<colgroup>
<col width="14%" />
<col width="15%" />
<col width="15%" />
<col width="56%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">name</th>
<th class="head">version</th>
<th class="head">license</th>
<th class="head">URL</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>pysocks</td>
<td>&nbsp;</td>
<td>BSD</td>
<td><a class="reference external" href="https://github.com/Anorov/PySocks">https://github.com/Anorov/PySocks</a></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="id3">
<span id="getting-started"></span><h1>Getting started</h1>
<div class="section" id="install-dependencies">
<span id="getting-started-install-dependencies"></span><h2>Install dependencies</h2>
<div class="section" id="debian-ubuntu-based">
<h3>Debian / Ubuntu based</h3>
<p>Install required dependencies:</p>
<pre class="literal-block">
# apt update
# apt upgrade
# apt install python3 python3-requests python3-pyqt5
</pre>
<p><strong>Optional</strong> for socks proxy support:</p>
<pre class="literal-block">
# apt install python3-socks
</pre>
</div>
<div class="section" id="arch-based">
<h3>Arch based</h3>
<p>Install required dependencies:</p>
<pre class="literal-block">
# pacman -Syu python python-requests python-pyqt5
</pre>
<p><strong>Optional</strong> for socks proxy support:</p>
<pre class="literal-block">
# pacman -S python-pysocks
</pre>
</div>
</div>
<div class="section" id="installation">
<span id="getting-started-installation"></span><h2>Installation</h2>
<p>TODO</p>
</div>
</div>
<div class="section" id="id4">
<span id="usage"></span><h1>Usage</h1>
<div class="section" id="settings">
<span id="usage-settings"></span><h2>Settings</h2>
<img alt="images/settings.png" class="align-right" src="images/settings.png" />
<div class="section" id="verify-ssl">
<h3>Verify (SSL)</h3>
<p>Request will fail on a invalid SSL/TLS certificate.</p>
<p>Leave checked if unsure.</p>
<p>See <a class="reference external" href="https://requests.readthedocs.io/en/master/user/advanced/#ssl-cert-verification">https://requests.readthedocs.io/en/master/user/advanced/#ssl-cert-verification</a>
for a more technical description.</p>
</div>
<div class="section" id="timeout">
<h3>Timeout</h3>
<p>Timeout in seconds for a single request.</p>
<p>Leave it at the default value of 10 seconds if unsure.</p>
<p>See <a class="reference external" href="https://requests.readthedocs.io/en/master/user/advanced/#timeouts">https://requests.readthedocs.io/en/master/user/advanced/#timeouts</a> for a
more technical description.</p>
</div>
<div class="section" id="proxy">
<h3>Proxy</h3>
<p>Here you can set a proxy that will be used for every connection searx-qt
makes. Leave the input field blank to use no proxy.</p>
<p>The 'Http' section can be used to proxy plain <a class="reference external" href="http://">http://</a> requests to for
example instances without a certificate. The 'Https' section can be used
to proxy all <a class="reference external" href="https://">https://</a> requests to instances (including fetching the
instances list data from <a class="reference external" href="https://searx.space">https://searx.space</a>) with a certificate. So you
can use a separate proxy for both protocols.</p>
<p>If you use a socks4 or socks5 proxy you probably want to make sure the
'Proxy DNS' checkbox is checked so DNS requests will also go through the
proxy. DNS proxy is not available for a http proxy type.</p>
</div>
</div>
<div class="section" id="instances">
<span id="usage-instances"></span><h2>Instances</h2>
<img alt="images/instances.png" class="align-right" src="images/instances.png" />
<p>A instance is a server running the searx project. Since we want to
preform searches to searx instance(s) we need addresses of those
instance(s); those will be fetched from
<tt class="docutils literal"><span class="pre">https://searx.space/data/instances.json</span></tt>. The <tt class="docutils literal">instances.json</tt>
from <tt class="docutils literal">search.space</tt> also contains a lot of other data about the
instances it lists which we can use to filter instances based on our
preferences.</p>
<p>The interface to manage instances is on the right. This is used to update
the instances data with a press on the 'Update' button; filter the
instances and browse/use the leftover instances in the instances table.</p>
<div class="section" id="update-instances-table">
<h3>Update instances table</h3>
<p>If searx-qt is used for the first time you will need to update the
instances table. There is a 'Update' button between the Filter and the
Table that can be used for this. searx-qt will not update this automatically!</p>
<p>It maybe useful to update the instances data so now and then since public
instances appear, disappear and their stats change over time.</p>
</div>
<div class="section" id="instances-table">
<h3>Instances table</h3>
<p>The instances table can be used to browse instances with their data that
remain after all filters. The table is also used to set the current
instance by left-clicking on one.</p>
<p>Right-clicking in the table opens a context-menu from where you can do the following:</p>
<ul class="simple">
<li>Blacklist selected instance(s).</li>
<li>Copy selected instance(s) it's/their URL(s).</li>
<li>Select All instances (CTRL+A should do the same).</li>
<li>Hide or show columns.</li>
</ul>
<p>The currently used instance should also be visible bottom right in the
application it's status-bar.</p>
</div>
<div class="section" id="filter-instances">
<h3>Filter instances</h3>
<p>When a filter is enabled and the instance it's value that is being
matched is unknown then it is excluded by default!</p>
<div class="section" id="network">
<h4>Network</h4>
<p>Filter instances on network type. Only instances that match one of the
checked network types remain.</p>
</div>
<div class="section" id="require-asn-privacy">
<h4>Require ASN privacy</h4>
<p>Excludes instances that use a known MITM reverse proxy service like
CloudFlare.</p>
</div>
<div class="section" id="require-ipv6">
<h4>Require IPv6</h4>
<p>Exclude instances that don't have at least one IPv6 address.</p>
</div>
<div class="section" id="version">
<h4>Version</h4>
<p>Include only instances that have a searx version that has been added to
this widget. Leave empty to allow all searx version.</p>
</div>
<div class="section" id="blacklist">
<h4>Blacklist</h4>
<p>Here are the URLs of the instances that have been manually blacklisted
listed. There is a button right to each blacklist item to remove it from
the blacklist.</p>
<p>You can manually blacklist a instance by right clicking on a instance in
the instances table and click 'Add to blacklist'; multiple instances can
be blacklisted at once.</p>
</div>
</div>
</div>
<div class="section" id="search">
<span id="usage-search"></span><h2>Search</h2>
<div class="section" id="search-bar">
<h3>Search bar</h3>
<img alt="images/search_bar.png" src="images/search_bar.png" />
<div class="section" id="fallback">
<h4>Fallback</h4>
<p>If checked it will pick a random instance from the instances table if a
search request fails one way or another and re-try the same request with
the freshly picked instance. There is a maximum amount of 10 tries (10
different instances to try the same request on).</p>
<p>What is fail?</p>
<ul class="simple">
<li>Connection errors including timeout.</li>
<li>Wrong status code (not 200).</li>
<li>No or malformed results returned.</li>
</ul>
</div>
<div class="section" id="random-every">
<h4>Random every</h4>
<p>If checked it will automatically pick a random instance on a search request,
it will also hide the 'Random search button' because it makes it obsolete.</p>
<p>If not checked it will do search requests on the same instance unless the
request fails somehow and 'Fallback' is checked. Exception is when the
'Random search button' is used for the search request.</p>
</div>
<div class="section" id="random-search-button">
<h4>Random search button</h4>
<p>When pressed it will pick a random instance from the list and preform the
search request.</p>
</div>
<div class="section" id="reload-button">
<h4>Reload button</h4>
<p>When pressed it basically preforms a search request without 'Fallback'
whenever it is enabled or not, it also doesn't reset the page number. So
it can act as a reload button thus it's name, but it does more.</p>
<p>Note: When a search argument like the search query, instance URL,
categories/engines etc. has changed by user interaction it will do the
request with those changes, that isn't a real reload of the previous
request.</p>
<p>Dev-note: Probably this behavior should change or the name/icon should
change to something more fitting.</p>
</div>
<div class="section" id="search-button">
<h4>Search button</h4>
<p>Preform a search request on the currently selected instance.</p>
<p>Page number is reset, 'Fallback' and 'Random Every' options are honored.</p>
</div>
<div class="section" id="search-query-input">
<h4>Search query input</h4>
<p>The query you like to search for.</p>
<p>See <a class="reference external" href="https://asciimoo.github.io/searx/user/search_syntax.html">https://asciimoo.github.io/searx/user/search_syntax.html</a> for what is
possible.</p>
<p>It will do a search request on <tt class="docutils literal">enter</tt> key pressed, same behavior as when the 'Search button' has been pressed.</p>
</div>
</div>
<div class="section" id="search-options">
<h3>Search options</h3>
<img alt="images/search_options.png" src="images/search_options.png" />
<p>Right clicking in (on the picture above) the dark area opens a
context-menu where you can manage what options you want to be visible or
not.</p>
<div class="section" id="categories">
<span id="usage-search-options-categories"></span><h4>Categories</h4>
<p>These are predefined by searx but can vary by instance. Example if
'Images' is checked it will only use engines with images enabled. If
'Files' is checked it will only use engines with files enabled.</p>
<p>searx-qt only passes this info to a searx instance with a search request,
it will not automatically filter the instances table (yet).</p>
</div>
<div class="section" id="engines">
<h4>Engines</h4>
<p>Here you can toggle what search engines should be enabled. It will
automatically filter out all instances from the instances table that doesn't
have at least one of the checked engines enabled. The checked engines will
be send with a search request to a searx instance with the <cite>enabled_engines</cite>
param. You should only get results from engines that are checked.</p>
<p>If no engine is checked it means that it may return results of any engine
in the list, unless one or more of the <a class="reference internal" href="#usage-search-options-categories">categories</a> are checked.</p>
<p>The list with engines is created with data from the instances table, so
only engines are listed that are available from the instances table.</p>
</div>
<div class="section" id="period">
<h4>Period</h4>
<p>Search period you like results from. Options are <tt class="docutils literal">Last day</tt>,
<tt class="docutils literal">Last week</tt>, <tt class="docutils literal">Last month</tt> or <tt class="docutils literal">Last year</tt>.</p>
</div>
<div class="section" id="language">
<h4>Language</h4>
<p>If you want results in a specific language than you can select one here.</p>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="https://notabug.org/CYBERDEViL/searx-qt/raw/master/docs/index.rst">View document source</a>.
Generated on: 2020-06-30 21:30 UTC.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.

</div>
</body>
</html>