aio_taginfo.api.v4.tag.projects

  1"""`/api/4/tag/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    "TagProject",
 22    "TagProjectSorting",
 23)
 24
 25
 26@dataclass(kw_only=True, frozen=True)
 27class TagProject:
 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: str | None = Field(min_length=1, repr=True)  # TODO: surprised this can be None
 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 TagProjectSorting(str, Enum):
 61    """Sort options for tag 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    value: NonEmptyString = Field(repr=True)
 71    query: NonEmptyString | None = Field(repr=True)
 72    sortname: TagProjectSorting = Field(repr=True)
 73    sortorder: SortOrder = Field(repr=True)
 74    filter: ObjectType = Field(repr=True)
 75    page: int = Field(gt=0, repr=True)
 76    rp: int = Field(ge=0, repr=True)
 77
 78
 79async def call(
 80    key: str,
 81    value: str,
 82    query: str | None = None,
 83    sortname: TagProjectSorting = TagProjectSorting.PROJECT_NAME,
 84    sortorder: SortOrder = SortOrder.ASC,
 85    filter: ObjectType = ObjectType.ALL,  # noqa: A002
 86    page: int = 1,
 87    rp: int = 0,
 88    session: ClientSession | None = None,
 89) -> Response[list[TagProject]]:
 90    """
 91    Get projects using a given tag.
 92
 93    https://taginfo.openstreetmap.org/taginfo/apidoc#api_4_tag_projects
 94
 95    Args:
 96        key: tag key
 97        value: tag value
 98        query: Only show results where the project name matches this query (substring match)
 99        sortname: what field to sort by
100        sortorder: sort order
101        filter: can be used to filter only values on tags used on nodes/ways/relations
102        page: page number (starting at 1)
103        rp: results per page
104        session: request client session
105
106    Raises:
107        TaginfoError
108    """
109    params = api_params(
110        _Params,
111        key=key,
112        value=value,
113        query=query,
114        sortname=sortname,
115        sortorder=sortorder,
116        filter=filter,
117        page=page,
118        rp=rp,
119    )
120    return await api_get_json(
121        path="tag/projects",
122        cls=Response[list[TagProject]],
123        session=session,
124        params=params,
125    )
126
127
128__docformat__ = "google"