osmapi.note

  1"""
  2Note operations for the OpenStreetMap API.
  3"""
  4
  5from typing import Any, Optional, TYPE_CHECKING, cast
  6from xml.dom.minidom import Element
  7
  8from . import dom, errors, parser
  9
 10if TYPE_CHECKING:
 11    from .OsmApi import OsmApi
 12
 13
 14class NoteMixin:
 15    """Mixin providing note-related operations with pythonic method names."""
 16
 17    def notes_get(
 18        self: "OsmApi",
 19        min_lon: float,
 20        min_lat: float,
 21        max_lon: float,
 22        max_lat: float,
 23        limit: int = 100,
 24        closed: int = 7,
 25    ) -> list[dict[str, Any]]:
 26        """
 27        Returns a list of dicts of notes in the specified bounding box.
 28
 29        The limit parameter defines how many results should be returned.
 30
 31        closed specifies the number of days a bug needs to be closed
 32        to no longer be returned.
 33        The value 0 means only open bugs are returned,
 34        -1 means all bugs are returned.
 35
 36        All parameters are optional.
 37        """
 38        path = "/api/0.6/notes"
 39        params = {
 40            "bbox": f"{min_lon:f},{min_lat:f},{max_lon:f},{max_lat:f}",
 41            "limit": limit,
 42            "closed": closed,
 43        }
 44        data = self._session._get(path, params=params)
 45        return parser.parse_notes(data)
 46
 47    def note_get(self: "OsmApi", note_id: int) -> dict[str, Any]:
 48        """
 49        Returns a note as dict.
 50
 51        `note_id` is the unique identifier of the note.
 52        """
 53        uri = f"/api/0.6/notes/{note_id}"
 54        data = self._session._get(uri)
 55        note_element = cast(
 56            Element, dom.OsmResponseToDom(data, tag="note", single=True)
 57        )
 58        return dom.dom_parse_note(note_element)
 59
 60    def note_create(self: "OsmApi", note_data: dict[str, Any]) -> dict[str, Any]:
 61        """
 62        Creates a note based on the supplied `note_data` dict:
 63
 64            #!python
 65            {
 66                'lat': latitude of note,
 67                'lon': longitude of note,
 68                'text': text of the note,
 69            }
 70
 71        Returns updated note data.
 72        """
 73        uri = "/api/0.6/notes"
 74        return self._note_action(uri, params=note_data)
 75
 76    def note_comment(self: "OsmApi", note_id: int, comment: str) -> dict[str, Any]:
 77        """
 78        Adds a new comment to a note.
 79
 80        Returns the updated note.
 81        """
 82        path = f"/api/0.6/notes/{note_id}/comment"
 83        return self._note_action(path, comment)
 84
 85    def note_close(
 86        self: "OsmApi", note_id: int, comment: Optional[str] = None
 87    ) -> dict[str, Any]:
 88        """
 89        Closes a note.
 90
 91        Returns the updated note.
 92
 93        If no authentication information are provided,
 94        `OsmApi.UsernamePasswordMissingError` is raised.
 95        """
 96        path = f"/api/0.6/notes/{note_id}/close"
 97        return self._note_action(path, comment, optional_auth=False)
 98
 99    def note_reopen(
100        self: "OsmApi", note_id: int, comment: Optional[str] = None
101    ) -> dict[str, Any]:
102        """
103        Reopens a note.
104
105        Returns the updated note.
106
107        If no authentication information are provided,
108        `OsmApi.UsernamePasswordMissingError` is raised.
109
110        If the requested element has been deleted,
111        `OsmApi.ElementDeletedApiError` is raised.
112
113        If the requested element can not be found,
114        `OsmApi.ElementNotFoundApiError` is raised.
115        """
116        path = f"/api/0.6/notes/{note_id}/reopen"
117        return self._note_action(path, comment, optional_auth=False)
118
119    def notes_search(
120        self: "OsmApi", query: str, limit: int = 100, closed: int = 7
121    ) -> list[dict[str, Any]]:
122        """
123        Returns a list of dicts of notes that match the given search query.
124
125        The limit parameter defines how many results should be returned.
126
127        closed specifies the number of days a bug needs to be closed
128        to no longer be returned.
129        The value 0 means only open bugs are returned,
130        -1 means all bugs are returned.
131        """
132        uri = "/api/0.6/notes/search"
133        params: dict[str, Any] = {
134            "q": query,
135            "limit": limit,
136            "closed": closed,
137        }
138        data = self._session._get(uri, params=params)
139        return parser.parse_notes(data)
140
141    def _note_action(
142        self: "OsmApi",
143        path: str,
144        comment: Optional[str] = None,
145        optional_auth: bool = True,
146        params: Optional[dict[str, Any]] = None,
147    ) -> dict[str, Any]:
148        """
149        Performs an action on a Note with a comment
150
151        Return the updated note
152        """
153        uri = path
154        final_params = params.copy() if params else {}
155        if comment is not None:
156            final_params["text"] = comment
157        try:
158            result = self._session._post(
159                uri,
160                None,
161                optionalAuth=optional_auth,
162                params=final_params if final_params else None,
163            )
164        except errors.ApiError as e:
165            if e.status == 409:
166                raise errors.NoteAlreadyClosedApiError(
167                    e.status, e.reason, e.payload
168                ) from e
169            else:
170                raise
171
172        # parse the result
173        note_element = cast(
174            Element, dom.OsmResponseToDom(result, tag="note", single=True)
175        )
176        return dom.dom_parse_note(note_element)