aio_taginfo.api.v4.relation.projects

  1"""`/api/4/relation/projects` endpoint."""
  2
  3from enum import Enum
  4
  5from aio_taginfo.api.v4 import 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    "RelationProject",
 22    "RelationProjectSorting",
 23)
 24
 25
 26@dataclass(kw_only=True, frozen=True)
 27class RelationProject:
 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        rtype: Relation type
 36        description: Description
 37        doc_url: Documentation URL
 38        icon_url: Icon URL
 39    """
 40
 41    project_id: str = Field(min_length=1, repr=True)
 42    project_name: str = Field(min_length=1, repr=True)
 43    project_icon_url: OptionalHttpUrl = Field(repr=False)
 44    rtype: str = Field(min_length=1, repr=True)
 45    description: OptionalNonEmptyString = Field(repr=False)
 46    doc_url: OptionalHttpUrl = Field(repr=False)
 47    icon_url: OptionalHttpUrl = Field(repr=False)
 48
 49
 50class RelationProjectSorting(str, Enum):
 51    """Sort options for relation projects."""
 52
 53    PROJECT_NAME = "project_name"
 54
 55
 56@dataclass(kw_only=True, frozen=True)
 57class _Params:
 58    rtype: NonEmptyString = Field(repr=True)
 59    query: NonEmptyString | None = Field(repr=True)
 60    sortname: RelationProjectSorting = Field(repr=True)
 61    sortorder: SortOrder = Field(repr=True)
 62    page: int = Field(gt=0, repr=True)
 63    rp: int = Field(ge=0, repr=True)
 64
 65
 66async def call(
 67    rtype: str,
 68    query: str | None = None,
 69    sortname: RelationProjectSorting = RelationProjectSorting.PROJECT_NAME,
 70    sortorder: SortOrder = SortOrder.ASC,
 71    page: int = 1,
 72    rp: int = 0,
 73    session: ClientSession | None = None,
 74) -> Response[list[RelationProject]]:
 75    """
 76    Get projects using a given relation type.
 77
 78    https://taginfo.openstreetmap.org/taginfo/apidoc#api_4_relation_projects
 79
 80    Args:
 81        rtype: Relation type
 82        query: Only show results where the value matches this query (substring match)
 83        sortname: what field to sort by
 84        sortorder: sort order
 85        page: page number (starting at 1)
 86        rp: results per page
 87        session: request client session
 88
 89    Raises:
 90        TaginfoError
 91    """
 92    params = api_params(
 93        _Params,
 94        rtype=rtype,
 95        query=query,
 96        sortname=sortname,
 97        sortorder=sortorder,
 98        page=page,
 99        rp=rp,
100    )
101    return await api_get_json(
102        path="relation/projects",
103        cls=Response[list[RelationProject]],
104        session=session,
105        params=params,
106    )
107
108
109__docformat__ = "google"