aio_taginfo.api.v4.key.combinations

  1"""`/api/4/key/combinations` endpoint."""
  2
  3from enum import Enum
  4
  5from aio_taginfo.api.v4 import ObjectType, 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    "KeyCombination",
 16    "KeyCombinationSorting",
 17)
 18
 19
 20@dataclass(kw_only=True, frozen=True)
 21class KeyCombination:
 22    """
 23    Combination statistics for a given key with another.
 24
 25    Attributes:
 26        other_key: Other key.
 27        together_count: Number of objects that have both keys.
 28        to_fraction: Fraction of objects with this key that also have the other key.
 29        from_fraction: Fraction of objects with other key that also have this key.
 30    """
 31
 32    other_key: str = Field(min_length=1, repr=True)
 33    together_count: int = Field(ge=0, repr=True)
 34    to_fraction: float = Field(ge=0.0, le=1.0, allow_inf_nan=False, repr=True)
 35    from_fraction: float = Field(ge=0.0, le=1.0, allow_inf_nan=False, repr=True)
 36
 37
 38class KeyCombinationSorting(str, Enum):
 39    """Sort options for key combination."""
 40
 41    TOGETHER_COUNT = "together_count"
 42    OTHER_KEY = "other_key"
 43    FROM_FRACTION = "from_fraction"
 44
 45
 46@dataclass(kw_only=True, frozen=True)
 47class _Params:
 48    key: NonEmptyString = Field(repr=True)
 49    query: NonEmptyString | None = Field(repr=True)
 50    sortname: KeyCombinationSorting = Field(repr=True)
 51    sortorder: SortOrder = Field(repr=True)
 52    filter: ObjectType = Field(repr=True)
 53    page: int = Field(gt=0, repr=True)
 54    rp: int = Field(ge=0, repr=True)
 55
 56
 57async def call(
 58    key: str,
 59    query: str | None = None,
 60    sortname: KeyCombinationSorting = KeyCombinationSorting.TOGETHER_COUNT,
 61    sortorder: SortOrder = SortOrder.DESC,
 62    filter: ObjectType = ObjectType.ALL,  # noqa: A002
 63    page: int = 1,
 64    rp: int = 0,
 65    session: ClientSession | None = None,
 66) -> Response[list[KeyCombination]]:
 67    """
 68    Find keys that are used together with a given key.
 69
 70    https://taginfo.openstreetmap.org/taginfo/apidoc#api_4_key_combinations
 71
 72    Args:
 73        key: tag key
 74        query: only show results where the ``other_key`` matches this query (substring match)
 75        sortname: what field to sort by
 76        sortorder: sort order
 77        filter: can be used to filter only values on tags used on nodes/ways/relations
 78        page: page number (starting at 1)
 79        rp: results per page
 80        session: request client session
 81
 82    Raises:
 83        TaginfoError
 84    """
 85    params = api_params(
 86        _Params,
 87        key=key,
 88        query=query,
 89        sortname=sortname,
 90        sortorder=sortorder,
 91        filter=filter,
 92        page=page,
 93        rp=rp,
 94    )
 95    return await api_get_json(
 96        path="key/combinations",
 97        cls=Response[list[KeyCombination]],
 98        session=session,
 99        params=params,
100    )
101
102
103__docformat__ = "google"