Public Member Functions
	__init__ (self, str engine_name, int\|None expire=None)
bool	set (self, str key, t.Any value, int\|None expire=None)
t.Any	get (self, str key, t.Any default=None)
str	secret_hash (self, str\|bytes name)

Public Attributes
int	expire = expire or ENGINES_CACHE.cfg.MAXHOLD_TIME
str	table_name = "".join([c if c in _valid else "_" for c in engine_name])

Detailed Description

Persistent (SQLite) key/value cache that deletes its values again after
``expire`` seconds (default/max: :py:obj:`MAXHOLD_TIME
<searx.cache.ExpireCacheCfg.MAXHOLD_TIME>`).  This class is a wrapper around
:py:obj:`ENGINES_CACHE` (:py:obj:`ExpireCacheSQLite
<searx.cache.ExpireCacheSQLite>`).

In the :origin:`searx/engines/demo_offline.py` engine you can find an
exemplary implementation of such a cache other examples are implemented
in:

- :origin:`searx/engines/radio_browser.py`
- :origin:`searx/engines/soundcloud.py`
- :origin:`searx/engines/startpage.py`

.. code: python

   from searx.enginelib import EngineCache
   CACHE: EngineCache

   def init(engine_settings):
       global CACHE
       CACHE = EngineCache(engine_settings["name"])

   def request(query, params):
       token = CACHE.get(key="token")
       if token is None:
           token = get_token()
           # cache token of this engine for 1h
           CACHE.set(key="token", value=token, expire=3600)
       ...

For introspection of the DB, jump into developer environment and run command to
show cache state::

    $ ./manage pyenv.cmd bash --norc --noprofile
    (py3) python -m searx.enginelib cache state

    cache tables and key/values
    ===========================
    [demo_offline        ] 2025-04-22 11:32:50 count        --> (int) 4
    [startpage           ] 2025-04-22 12:32:30 SC_CODE      --> (str) fSOBnhEMlDfE20
    [duckduckgo          ] 2025-04-22 12:32:31 4dff493e.... --> (str) 4-128634958369380006627592672385352473325
    [duckduckgo          ] 2025-04-22 12:40:06 3e2583e2.... --> (str) 4-263126175288871260472289814259666848451
    [radio_browser       ] 2025-04-23 11:33:08 servers      --> (list) ['https://de2.api.radio-browser.info',  ...]
    [soundcloud          ] 2025-04-29 11:40:06 guest_client_id --> (str) EjkRJG0BLNEZquRiPZYdNtJdyGtTuHdp
    [wolframalpha        ] 2025-04-22 12:40:06 code         --> (str) 5aa79f86205ad26188e0e26e28fb7ae7
    number of tables: 6
    number of key/value pairs: 7

In the "cache tables and key/values" section, the table name (engine name) is at
first position on the second there is the calculated expire date and on the
third and fourth position the key/value is shown.

About duckduckgo: The *vqd coode* of ddg depends on the query term and therefore
the key is a hash value of the query term (to not to store the raw query term).

In the "properties of ENGINES_CACHE" section all properties of the SQLiteAppl /
ExpireCache and their last modification date are shown::

    properties of ENGINES_CACHE
    ===========================
    [last modified: 2025-04-22 11:32:27] DB_SCHEMA           : 1
    [last modified: 2025-04-22 11:32:27] LAST_MAINTENANCE    :
    [last modified: 2025-04-22 11:32:27] crypt_hash          : ca612e3566fdfd7cf7efe...
    [last modified: 2025-04-22 11:32:30] CACHE-TABLE--demo_offline: demo_offline
    [last modified: 2025-04-22 11:32:30] CACHE-TABLE--startpage: startpage
    [last modified: 2025-04-22 11:32:31] CACHE-TABLE--duckduckgo: duckduckgo
    [last modified: 2025-04-22 11:33:08] CACHE-TABLE--radio_browser: radio_browser
    [last modified: 2025-04-22 11:40:06] CACHE-TABLE--soundcloud: soundcloud
    [last modified: 2025-04-22 11:40:06] CACHE-TABLE--wolframalpha: wolframalpha

These properties provide information about the state of the ExpireCache and
control the behavior.  For example, the maintenance intervals are controlled by
the last modification date of the LAST_MAINTENANCE property and the hash value
of the password can be used to detect whether the password has been changed (in
this case the DB entries can no longer be decrypted and the entire cache must be
discarded).

Definition at line 79 of file __init__.py.

Constructor & Destructor Documentation

◆ init()

searx.enginelib.EngineCache.__init__	(		self,
		str	engine_name,
		int \| None	expire = None )

Definition at line 159 of file __init__.py.

    def __init__(self, engine_name: str, expire: int | None = None):
        self.expire: int = expire or ENGINES_CACHE.cfg.MAXHOLD_TIME
        _valid = "-_." + string.ascii_letters + string.digits
        self.table_name: str = "".join([c if c in _valid else "_" for c in engine_name])
 

Member Function Documentation

◆ get()

t.Any searx.enginelib.EngineCache.get	(		self,
		str	key,
		t.Any	default = None )

Definition at line 172 of file __init__.py.

    def get(self, key: str, default: t.Any = None) -> t.Any:
        return ENGINES_CACHE.get(key, default=default, ctx=self.table_name)
 

References table_name.

Referenced by searx.result_types._base.LegacyResult.__init__(), searx.result_types._base.LegacyResult.defaults_from(), and searx.answerers._core.AnswerStorage.register().

Here is the caller graph for this function:

◆ secret_hash()

str searx.enginelib.EngineCache.secret_hash	(		self,
		str \| bytes	name )

Definition at line 175 of file __init__.py.

    def secret_hash(self, name: str | bytes) -> str:
        return ENGINES_CACHE.secret_hash(name=name)

◆ set()

bool searx.enginelib.EngineCache.set	(		self,
		str	key,
		t.Any	value,
		int \| None	expire = None )

Definition at line 164 of file __init__.py.

    def set(self, key: str, value: t.Any, expire: int | None = None) -> bool:
        return ENGINES_CACHE.set(
            key=key,
            value=value,
            expire=expire or self.expire,
            ctx=self.table_name,
        )
 

References expire, and table_name.

Member Data Documentation

◆ expire

int searx.enginelib.EngineCache.expire = expire or ENGINES_CACHE.cfg.MAXHOLD_TIME

Definition at line 160 of file __init__.py.

Referenced by set().

◆ table_name

str searx.enginelib.EngineCache.table_name = "".join([c if c in _valid else "_" for c in engine_name])

Definition at line 162 of file __init__.py.

Referenced by get(), and set().

The documentation for this class was generated from the following file:

/home/andrew/Documents/code/public/searxng/searx/enginelib/__init__.py

Public Member Functions

Public Attributes