aio_taginfo.api.v4.key.similar

 1"""`/api/4/key/similar` endpoint."""
 2
 3from enum import Enum
 4
 5from aio_taginfo.api.v4 import Response, SortOrder
 6from aio_taginfo.api.v4._internal import NonEmptyString, api_get_json, api_params
 7
 8from aiohttp import ClientSession
 9from pydantic import Field
10from pydantic.dataclasses import dataclass
11
12
13__all__ = (
14    "call",
15    "SimilarKey",
16    "SimilarKeySorting",
17)
18
19
20@dataclass(kw_only=True, frozen=True)
21class SimilarKey:
22    """
23    Result of a key that is similar to a given key.
24
25    Attributes:
26        other_key: other key
27        count_all: number of objects that have the other key
28        similarity: integer measuring the similarity of the two keys (smaller is more similar)
29    """
30
31    other_key: str = Field(min_length=1, repr=True)
32    count_all: int = Field(ge=0, repr=True)
33    similarity: int = Field(ge=0, repr=True)
34
35
36class SimilarKeySorting(str, Enum):
37    """Sort options for similar keys."""
38
39    OTHER_KEY = "other_key"
40    COUNT_ALL = "count_all"
41    SIMILARITY = "similarity"
42
43
44@dataclass(kw_only=True, frozen=True)
45class _Params:
46    key: NonEmptyString = Field(repr=True)
47    query: NonEmptyString | None = Field(repr=True)
48    sortname: SimilarKeySorting = Field(repr=True)
49    sortorder: SortOrder = Field(repr=True)
50    page: int = Field(gt=0, repr=True)
51    rp: int = Field(ge=0, repr=True)
52
53
54async def call(
55    key: str,
56    query: str | None = None,
57    sortname: SimilarKeySorting = SimilarKeySorting.OTHER_KEY,
58    sortorder: SortOrder = SortOrder.ASC,
59    page: int = 1,
60    rp: int = 0,
61    session: ClientSession | None = None,
62) -> Response[list[SimilarKey]]:
63    """
64    Find keys that are similar to a given key.
65
66    https://taginfo.openstreetmap.org/taginfo/apidoc#api_4_key_similar
67
68    Args:
69        key: tag key
70        query: only show results where the ``other_key`` matches this query (substring match)
71        sortname: what field to sort by
72        sortorder: sort order
73        page: page number (starting at 1)
74        rp: results per page
75        session: request client session
76
77    Raises:
78        TaginfoError
79    """
80    params = api_params(
81        _Params, key=key, query=query, sortname=sortname, sortorder=sortorder, page=page, rp=rp
82    )
83    return await api_get_json(
84        path="key/similar",
85        cls=Response[list[SimilarKey]],
86        session=session,
87        params=params,
88    )
89
90
91__docformat__ = "google"