aio_taginfo.api.v4.key.projects

  1"""`/api/4/key/projects` endpoint."""
  2
  3from enum import Enum
  4
  5from aio_taginfo.api.v4 import ObjectType, Response, SortOrder
  6from aio_taginfo.api.v4._internal import (
  7    NonEmptyString,
  8    OptionalHttpUrl,
  9    OptionalNonEmptyString,
 10    api_get_json,
 11    api_params,
 12)
 13
 14from aiohttp import ClientSession
 15from pydantic import Field
 16from pydantic.dataclasses import dataclass
 17
 18
 19__all__ = (
 20    "call",
 21    "KeyProject",
 22    "KeyProjectSorting",
 23)
 24
 25
 26@dataclass(kw_only=True, frozen=True)
 27class KeyProject:
 28    """
 29    TODO: https://wiki.openstreetmap.org/wiki/Taginfo/Projects.
 30
 31    Attributes:
 32        project_id: Project ID
 33        project_name: Project name
 34        project_icon_url: Project icon URL
 35        key: Key
 36        value: Value
 37        on_node: For nodes?
 38        on_way: For ways?
 39        on_relation: For relations?
 40        on_relation: For areas?
 41        description: Description
 42        doc_url: Documentation URL
 43        icon_url: Icon URL
 44    """
 45
 46    project_id: str = Field(min_length=1, repr=True)
 47    project_name: str = Field(min_length=1, repr=True)
 48    project_icon_url: OptionalHttpUrl = Field(repr=False)
 49    key: str = Field(min_length=1, repr=True)
 50    value: OptionalNonEmptyString = Field(repr=True)
 51    on_node: bool = Field(repr=False)
 52    on_way: bool = Field(repr=False)
 53    on_relation: bool = Field(repr=False)
 54    on_area: bool = Field(repr=False)
 55    description: OptionalNonEmptyString = Field(repr=False)
 56    doc_url: OptionalHttpUrl = Field(repr=False)
 57    icon_url: OptionalHttpUrl = Field(repr=False)
 58
 59
 60class KeyProjectSorting(str, Enum):
 61    """Sort options for key projects."""
 62
 63    PROJECT_NAME = "project_name"
 64    TAG = "tag"
 65
 66
 67@dataclass(kw_only=True, frozen=True)
 68class _Params:
 69    key: NonEmptyString = Field(repr=True)
 70    query: NonEmptyString | None = Field(repr=True)
 71    sortname: KeyProjectSorting = Field(repr=True)
 72    sortorder: SortOrder = Field(repr=True)
 73    filter: ObjectType = Field(repr=True)
 74    page: int = Field(gt=0, repr=True)
 75    rp: int = Field(ge=0, repr=True)
 76
 77
 78async def call(
 79    key: str,
 80    query: str | None = None,
 81    sortname: KeyProjectSorting = KeyProjectSorting.PROJECT_NAME,
 82    sortorder: SortOrder = SortOrder.ASC,
 83    filter: ObjectType = ObjectType.ALL,  # noqa: A002
 84    page: int = 1,
 85    rp: int = 0,
 86    session: ClientSession | None = None,
 87) -> Response[list[KeyProject]]:
 88    """
 89    Get projects using a given key.
 90
 91    https://taginfo.openstreetmap.org/taginfo/apidoc#api_4_key_projects
 92
 93    Args:
 94        key: tag key
 95        query: only show results where the project name or tag value matches this query
 96               (substring match)
 97        sortname: what field to sort by
 98        sortorder: sort order
 99        filter: can be used to filter only values on tags used on nodes/ways/relations
100        page: page number (starting at 1)
101        rp: results per page
102        session: request client session
103
104    Raises:
105        TaginfoError
106    """
107    params = api_params(
108        _Params,
109        key=key,
110        query=query,
111        sortname=sortname,
112        sortorder=sortorder,
113        filter=filter,
114        page=page,
115        rp=rp,
116    )
117    return await api_get_json(
118        path="key/projects",
119        cls=Response[list[KeyProject]],
120        session=session,
121        params=params,
122    )
123
124
125__docformat__ = "google"