aio_taginfo.api.v4.key.overview

  1"""`/api/4/key/overview` endpoint."""
  2
  3from aio_taginfo.api.v4 import ObjectType, PrintingDirection, Response
  4from aio_taginfo.api.v4._internal import NonEmptyString, api_get_json, api_params
  5
  6from aiohttp import ClientSession
  7from pydantic import Field
  8from pydantic.dataclasses import dataclass
  9
 10
 11__all__ = (
 12    "call",
 13    "KeyOverview",
 14    "KeyDescription",
 15    "KeyObjectCount",
 16    "KeyWikiPage",
 17)
 18
 19from aio_taginfo.api.v4.key.prevalent_values import PrevalentValue
 20
 21
 22@dataclass(kw_only=True, frozen=True)
 23class _Params:
 24    key: NonEmptyString = Field(repr=True)
 25
 26
 27async def call(
 28    key: str,
 29    session: ClientSession | None = None,
 30) -> Response["KeyOverview"]:
 31    """
 32    Show various data for given key.
 33
 34    https://taginfo.openstreetmap.org/taginfo/apidoc#api_4_key_overview
 35
 36    Args:
 37        key: tag key
 38        session: request client session
 39
 40    Raises:
 41        TaginfoError
 42    """
 43    return await api_get_json(
 44        path="key/overview",
 45        cls=Response[KeyOverview],
 46        session=session,
 47        params=api_params(_Params, key=key),
 48    )
 49
 50
 51@dataclass(kw_only=True, frozen=True)
 52class KeyObjectCount:
 53    """
 54    Usage statistic of a given key for a given type of object.
 55
 56    Attributes:
 57        type: Object type
 58        count: Number of objects with this type and key
 59        count_fraction: Number of objects in relation to all objects
 60        values: Number of different values for this key
 61    """
 62
 63    type: ObjectType = Field(repr=True)
 64    count: int = Field(ge=0, repr=True)
 65    count_fraction: float = Field(ge=0.0, le=1.0, allow_inf_nan=False, repr=True)
 66    values: int = Field(ge=0, repr=True)
 67
 68
 69@dataclass(kw_only=True, frozen=True)
 70class KeyDescription:
 71    """
 72    Description of a given key in some language.
 73
 74    Attributes:
 75        text: Description text
 76        dir: Printing direction for this language
 77    """
 78
 79    text: str = Field(min_length=1, repr=True)
 80    dir: PrintingDirection = Field(repr=False)
 81
 82
 83@dataclass(kw_only=True, frozen=True)
 84class KeyWikiPage:
 85    """
 86    Language code for which a wiki page about a given key are available.
 87
 88    Attributes:
 89        lang: Language code
 90        english: English name of this language
 91        native: Native name of this language
 92        dir: Printing direction for native name
 93    """
 94
 95    lang: str = Field(min_length=2, repr=True)
 96    english: str = Field(min_length=1, repr=True)
 97    native: str = Field(min_length=1, repr=True)
 98    dir: PrintingDirection = Field(repr=False)
 99
100
101@dataclass(kw_only=True, frozen=True)
102class KeyOverview:
103    """
104    Various data for a given key.
105
106    Attributes:
107        key: The tag key that was requested
108        users: Number of users last editing objects with this key
109        prevalent_values: Prevalent values ordered by count from most often used down
110        counts: Objects counts
111        description: Description of this key (hash key is language code)
112        wiki_pages: Language codes for which wiki pages about this key are available
113        has_map: Is a map with the geographical distribution of this key available?
114        projects: Number of projects mentioning this key
115    """
116
117    key: str = Field(min_length=1, repr=True)
118    prevalent_values: list[PrevalentValue] = Field(repr=False)
119    counts: list[KeyObjectCount] = Field(repr=False)
120    description: dict[str, KeyDescription] = Field(repr=False)
121    wiki_pages: list[KeyWikiPage] = Field(repr=False)
122    has_map: bool = Field(repr=False)
123    users: int = Field(default=0, ge=0, repr=True)
124    projects: int = Field(default=0, ge=0, repr=False)
125
126
127__docformat__ = "google"