(Side note: This would probably allow us to re-visit #3256 as well, after this PR, to get rid of some hardcoded HTML in result weather engine result templates)

I pushed this PR on my instance where you test it online: https://darmarit.org/searx

Since this PR does no functional search, everything should be as usual.

Except the translation results, which now have collapsible items and links to the origin translators:

• en-de The quick red fox jumped over the lazy dog

The translation results (inspired by #3925) has been included in this PR to demonstrate what we can do with typification / how it works ..

Let's take the following base example

results = []
...
Translations(results=results, translations=[foo], url=foo_url)
return results

• where is the url field we set here is defined? I couldn't find its definition anywhere in the classes Translations inherits from

The class searx.result_types.Result is the base class of all result types, here is the inheritance:

class Result(msgspec.Struct, ..):
    """Base class of all result types :ref:`result types`."""

    url: str | None = None
    """A link related to this *result*"""

    results: list = []   # in the future it will be of type EngineResults (read below)
    """Result list of an :origin:`engine <searx/engines>` .. to which the reulst item  should be added."""

class BaseAnswer(Result, ..):
   ...
class Translations(BaseAnswer, ..):
   ...

I have to admit I don't 100% understand how this works from looking at the code:

* we're creating a `Translations` class here, but its result is actually unused

* instead it does some magic and change the `results` list

Yeah that looks a bit strange, the alternative notation would be:

results = []
...
x = Translations(results=results, translations=[foo], url=foo_url)
results.append(x)
return results

but we are still at the beginning ... that's why it looks a bit strange at the moment ..

• Since this modifies the original results without returning anything, wouldn't that be more suitable for a function?

• I'd personally love something like return Translations(translations=[item], url=foo_url) and avoid having to create an empty results array first

In the future we will have a class for the result list, which will then offer a factory method for the typed results ... haven't thougth to its end but let assume we have a class like this:

from searx.result_types import Result, Answer, Translation, ...

class EngineResults(list):

    Answer = Answer
    Translation = Translation
    ... = ...

    def new_result(self, res: Result):
        res.results = self
        self.append(res)

And in the engine we have something like ..

from searx.xyz import EngineResults

def response(resp) -> EngineResults:
    results = EngineResults()
    results.new_result(result.Translations(translations=[foo], url=foo_url))
    return results

The above is just a 2min protototype to demonstrate wehre I want to go: (in the future) the engine developer:

• should have a factory method,
• should not need to import all the result types (they are already available from EngineResults.Answer, EngineResults.Translation, EngineResults.xyz).
• should not care much about a result list and how the result items are managed in.

So if you could please clarify the above point a bit,

Hope, the above helps .. but I'm open for suggestions .. but for now I would like to have a optional Result.results field .. I believe that we will be able to benefit from this in the future; if there is context information (an association) between the individual result item and the list in which it is added.

Thanks for the clarification, that explains how this worked.

results = []
...
result = Translations(translations=[foo], url=foo_url)
results.append(result)
return results

To be honest I do very much prefer this syntax to make the code more self-descriptive and just make it more clear to everyone that's working on implementing an engine.

It's very much more clean this way as calling Translation(...) doesn't have any side effects and you can directly see what is happening to results because you modified it yourself.

This probably shouldn't be that much too change, as you said, it's already possible and only documentation and the engines using it would need to be modified (let me know if you want me to handle this if you don't have time for it).

from searx.xyz import EngineResults

def response(resp) -> EngineResults:
results = EngineResults()
results.new_result(result.Translations(translations=[foo], url=foo_url))
return results

That'd indeed be a nice syntax. This is also much closer to the way described above using an array of results, and thus seems very intuitive for engine developers.

    results: list = []  # https://jcristharif.com/msgspec/structs.html#default-values
    """Result list of an :origin:`engine <searx/engines>` response or a
    :origin:`answerer <searx/answerers>` to which the answer should be added.

    This field is only present for the sake of simplicity.  Typically, the
    response function of an engine has a result list that is returned at the
    end. By specifying the result list in the constructor of the result, this
    result is then immediately added to the list (this parameter does not have
    another function).

    .. code:: python

       def response(resp):
           results = []
           ...
           Answer(results=results, answer=answer, url=url)
           ...
           return results

    """

I see that you actually documented this as well, I just missed that part because I didn't figure out that Translations inherits from the Result base class, sorry for not seeing that earlier.

That'd indeed be a nice syntax. This is also much closer to the way described above using an array of results, and thus seems very intuitive for engine developers.

@Bnyro I pushed a new commit on top .. in this patch class searx.result_types.EngineResults is implemented and used in the engines:

    from searx.result_types import EngineResults
    ...
    def response(resp) -> EngineResults:
        res = EngineResults()
        ...
        res.add( res.types.Answer(answer="lorem ipsum ..", url="https://example.org") )
        ...
        return res

BTW the property Result.results is no longer needed / I dropped this field.

@Bnyro I pushed a new commit on top .. in this patch class searx.result_types.EngineResults is implemented and used in the engines:

    from searx.result_types import EngineResults
    ...
    def response(resp) -> EngineResults:
        res = EngineResults()
        ...
        res.add( res.types.Answer(answer="lorem ipsum ..", url="https://example.org") )
        ...
        return res

BTW the property Result.results is no longer needed / I dropped this field.

Awesome, thanks for your work!