Skip to content

Plugin API Reference

This file contains important references to the latz API, especially ones relevant for writing plugins.

ImageSearchResult

Bases: NamedTuple

Represents an individual search result object. It holds all relevant data for a single search result including the image size and URL.

Source code in latz/image.py 
 6
 7
 8
 9
10
11
12
13
14
class ImageSearchResult(NamedTuple):
    """
    Represents an individual search result object. It holds all relevant data
    for a single search result including the image size and URL.
    """
    url: str | None
    width: int | None
    height: int | None
    search_backend: str | None

AppHookSpecs

Holds all hookspecs for this application

Source code in latz/plugins/hookspec.py 
86
87
88
89
90
91
92
93
94
95
96
97
class AppHookSpecs:
    """Holds all hookspecs for this application"""

    @hookspec
    def search_backend(self) -> Iterable[SearchBackendHook]:
        """
        Hookspec for the search backend hook.

        Check out the [creating plugins][creating-plugins] guide for more information on
        using this plugin hook.
        """
        return tuple()

search_backend()

Hookspec for the search backend hook.

Check out the creating plugins guide for more information on using this plugin hook.

Source code in latz/plugins/hookspec.py 
89
90
91
92
93
94
95
96
97
@hookspec
def search_backend(self) -> Iterable[SearchBackendHook]:
    """
    Hookspec for the search backend hook.

    Check out the [creating plugins][creating-plugins] guide for more information on
    using this plugin hook.
    """
    return tuple()

SearchBackendHook

Bases: NamedTuple

Holds the metadata and callable for using the image search hook.

Source code in latz/plugins/hookspec.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
class SearchBackendHook(NamedTuple):
    """
    Holds the metadata and callable for using the image search hook.
    """

    name: str
    """
    Namespace for the image API plugin; this is the value users will use in their
    config files to specify this particular plugin.

    **Example:**

    ```python
    from latz.plugins import SearchBackendHook

    @hookimpl
    def search_backend():
        return SearchBackendHook(
            name="custom",
            ...
        )
    ```

    This would later be referred to as `custom` in the settings file:

    ```json
    {
      "search_backends": ["custom"],
      "search_backend_settings": {
        "custom": {
          "param_one": "value"
        }
      }
    }
    ```
    """

    search: Callable[
        [httpx.AsyncClient, Any, str], Awaitable[tuple[ImageSearchResult, ...]]
    ]
    """
    Callable that implements the search hook.
    """

    config_fields: BaseModel
    """
    Pydantic model that defines all the settings that this plugin needs.

    **Example:**

    ```python

    from pydantic import BaseModel, Field

    PLUGIN_NAME = "custom"

    class CustomConfigFields(BaseModel):
        access_key: str = Field(description="Access key for the API")

    @hookimpl
    def image_api():
        return ImageAPIPlugin(
            name=PLUGIN_NAME,
            config_fields=CustomConfigFields(access_key=""),
            ...
        )
    ```
    """

config_fields: BaseModel class-attribute

Pydantic model that defines all the settings that this plugin needs.

Example:

from pydantic import BaseModel, Field

PLUGIN_NAME = "custom"

class CustomConfigFields(BaseModel):
    access_key: str = Field(description="Access key for the API")

@hookimpl
def image_api():
    return ImageAPIPlugin(
        name=PLUGIN_NAME,
        config_fields=CustomConfigFields(access_key=""),
        ...
    )

name: str class-attribute

Namespace for the image API plugin; this is the value users will use in their config files to specify this particular plugin.

Example:

from latz.plugins import SearchBackendHook

@hookimpl
def search_backend():
    return SearchBackendHook(
        name="custom",
        ...
    )

This would later be referred to as custom in the settings file:

{
  "search_backends": ["custom"],
  "search_backend_settings": {
    "custom": {
      "param_one": "value"
    }
  }
}

search: Callable[[httpx.AsyncClient, Any, str], Awaitable[tuple[ImageSearchResult, ...]]] class-attribute

Callable that implements the search hook.