Engine Guidelines

This document details the rough process of adding a new engine to retaggr.

Step 1: Making the engine class

  • Start by creating a new file in the engines folder.
  • In this file, import the base Engine class and subclass it. This class will be used as a base for the engine class.
  • Implement the search logic in the search_image() method. This method accepts one parameter, which is the image URL.
  • If your engine needs an API key or some other user defined variable, add it to the __init__() method.
  • Define if the engine needs to download the image locally in order to search it by setting the Engine.download_required attribute.
  • Define the Engine.host attribute. This should be a human-visitable URL that links to the engine itself.

Step 2: Expanding the config object.

This is purely documentation. Add your new parameters to ReverseSearchConfig, where their names should be prefixed with filename_, where filename is the file you made in step 1.

Step 3: Adding it to core

  • Add the filename you just created to ReverseSearch._all_engines.
  • In the __init__(), verify that the variables you need are in the config object and if they are, instantiate the class you just made in the __init__() and assign it to ReverseSearch.accessible_engines where the key is the variable you added to ReverseSearch._all_engines and the value the class.

Step 4: Writing tests

You only need to write one test. This test should search an image using the class you just created, directly instantiating it’s underlying object (so not through ReverseSearch) by calling the search_image() method and then asserting the results with an existing list.

If your engine needs an API key or a user defined variable, add it to an environment variable and load it in (reference the start of test_engine.py).

Step 5: PR the changes

As it says on the tin. Specify any new environment variables that are required for CI to work in your PR.