osmapi.way

  1"""
  2Way operations for the OpenStreetMap API.
  3
  4This module provides pythonic (snake_case) methods for working with OSM ways.
  5"""
  6
  7from typing import Any, TYPE_CHECKING, cast
  8from xml.dom.minidom import Element
  9
 10from . import dom, parser
 11
 12if TYPE_CHECKING:
 13    from .OsmApi import OsmApi
 14
 15
 16class WayMixin:
 17    """Mixin providing way-related operations with pythonic method names."""
 18
 19    def way_get(self: "OsmApi", way_id: int, way_version: int = -1) -> dict[str, Any]:
 20        """
 21        Returns way with `way_id` as a dict:
 22
 23            #!python
 24            {
 25                'id': id of way,
 26                'tag': {} tags of this way,
 27                'nd': [] list of nodes belonging to this way
 28                'changeset': id of changeset of last change,
 29                'version': version number of way,
 30                'user': username of user that made the last change,
 31                'uid': id of user that made the last change,
 32                'timestamp': timestamp of last change,
 33                'visible': True|False
 34            }
 35
 36        If `way_version` is supplied, this specific version is returned,
 37        otherwise the latest version is returned.
 38
 39        If the requested element has been deleted,
 40        `OsmApi.ElementDeletedApiError` is raised.
 41
 42        If the requested element can not be found,
 43        `OsmApi.ElementNotFoundApiError` is raised.
 44        """
 45        uri = f"/api/0.6/way/{way_id}"
 46        if way_version != -1:
 47            uri += f"/{way_version}"
 48        data = self._session._get(uri)
 49        way = cast(Element, dom.OsmResponseToDom(data, tag="way", single=True))
 50        return dom.dom_parse_way(way)
 51
 52    def way_create(self: "OsmApi", way_data: dict[str, Any]) -> dict[str, Any] | None:
 53        """
 54        Creates a way based on the supplied `way_data` dict:
 55
 56            #!python
 57            {
 58                'nd': [] list of nodes,
 59                'tag': {} dict of tags,
 60            }
 61
 62        Returns updated `way_data` (without timestamp):
 63
 64            #!python
 65            {
 66                'id': id of node,
 67                'nd': [] list of nodes,
 68                'tag': {} dict of tags,
 69                'changeset': id of changeset of last change,
 70                'version': version number of way,
 71                'user': username of last change,
 72                'uid': id of user of last change,
 73                'visible': True|False
 74            }
 75
 76        If no session is provided to authenticate the request,
 77        `OsmApi.AuthenticationMissingError` is raised.
 78
 79        If the supplied information contain an existing node,
 80        `OsmApi.OsmTypeAlreadyExistsError` is raised.
 81
 82        If there is no open changeset,
 83        `OsmApi.NoChangesetOpenError` is raised.
 84
 85        If there is already an open changeset,
 86        `OsmApi.ChangesetAlreadyOpenError` is raised.
 87
 88        If the changeset is already closed,
 89        `OsmApi.ChangesetClosedApiError` is raised.
 90        """
 91        return self._do("create", "way", way_data)
 92
 93    def way_update(self: "OsmApi", way_data: dict[str, Any]) -> dict[str, Any] | None:
 94        """
 95        Updates way with the supplied `way_data` dict:
 96
 97            #!python
 98            {
 99                'id': id of way,
100                'nd': [] list of nodes,
101                'tag': {},
102                'version': version number of way,
103            }
104
105        Returns updated `way_data` (without timestamp):
106
107            #!python
108            {
109                'id': id of node,
110                'nd': [] list of nodes,
111                'tag': {} dict of tags,
112                'changeset': id of changeset of last change,
113                'version': version number of way,
114                'user': username of last change,
115                'uid': id of user of last change,
116                'visible': True|False
117            }
118
119        If no session is provided to authenticate the request,
120        `OsmApi.AuthenticationMissingError` is raised.
121
122        If there is no open changeset,
123        `OsmApi.NoChangesetOpenError` is raised.
124
125        If there is already an open changeset,
126        `OsmApi.ChangesetAlreadyOpenError` is raised.
127
128        If the changeset is already closed,
129        `OsmApi.ChangesetClosedApiError` is raised.
130        """
131        return self._do("modify", "way", way_data)
132
133    def way_delete(self: "OsmApi", way_data: dict[str, Any]) -> dict[str, Any] | None:
134        """
135        Delete way with `way_data`:
136
137            #!python
138            {
139                'id': id of way,
140                'nd': [] list of nodes,
141                'tag': dict of tags,
142                'version': version number of way,
143            }
144
145        Returns updated `way_data` (without timestamp):
146
147            #!python
148            {
149                'id': id of way,
150                'nd': [] list of nodes,
151                'tag': dict of tags,
152                'changeset': id of changeset of last change,
153                'version': version number of way,
154                'user': username of last change,
155                'uid': id of user of last change,
156                'visible': True|False
157            }
158
159        If no session is provided to authenticate the request,
160        `OsmApi.AuthenticationMissingError` is raised.
161
162        If there is no open changeset,
163        `OsmApi.NoChangesetOpenError` is raised.
164
165        If the changeset is already closed,
166        `OsmApi.ChangesetClosedApiError` is raised.
167        """
168        return self._do("delete", "way", way_data)
169
170    def way_history(self: "OsmApi", way_id: int) -> dict[int, dict[str, Any]]:
171        """
172        Returns dict with version as key:
173
174            #!python
175            {
176                1: dict of way version 1,
177                2: dict of way version 2,
178                ...
179            }
180
181        If the requested element can not be found,
182        `OsmApi.ElementNotFoundApiError` is raised.
183        """
184        uri = f"/api/0.6/way/{way_id}/history"
185        data = self._session._get(uri)
186        ways = cast(list[Element], dom.OsmResponseToDom(data, tag="way"))
187        result: dict[int, dict[str, Any]] = {}
188        for way in ways:
189            way_data = dom.dom_parse_way(way)
190            result[way_data["version"]] = way_data
191        return result
192
193    def way_relations(self: "OsmApi", way_id: int) -> list[dict[str, Any]]:
194        """
195        Returns a list of dicts of relation data containing way `way_id`:
196
197            #!python
198            [
199                {
200                    'id': id of Relation,
201                    'member': [
202                        {
203                            'ref': ID of referenced element,
204                            'role': optional description of role in relation
205                            'type': node|way|relation
206                        },
207                        {
208                            ...
209                        }
210                    ]
211                    'tag': {} dict of tags,
212                    'changeset': id of changeset of last change,
213                    'version': version number of Way,
214                    'user': username of user that made the last change,
215                    'uid': id of user that made the last change,
216                    'visible': True|False
217                },
218                {
219                    ...
220                },
221            ]
222
223        The `way_id` is a unique identifier for a way.
224        """
225        uri = f"/api/0.6/way/{way_id}/relations"
226        data = self._session._get(uri)
227        relations = cast(
228            list[Element], dom.OsmResponseToDom(data, tag="relation", allow_empty=True)
229        )
230        result: list[dict[str, Any]] = []
231        for relation in relations:
232            relation_data = dom.dom_parse_relation(relation)
233            result.append(relation_data)
234        return result
235
236    def way_full(self: "OsmApi", way_id: int) -> list[dict[str, Any]]:
237        """
238        Returns the full data for way `way_id` as list of dicts:
239
240            #!python
241            [
242                {
243                    'type': node|way|relation,
244                    'data': {} data dict for node|way|relation
245                },
246                { ... }
247            ]
248
249        The `way_id` is a unique identifier for a way.
250
251        If the requested element has been deleted,
252        `OsmApi.ElementDeletedApiError` is raised.
253
254        If the requested element can not be found,
255        `OsmApi.ElementNotFoundApiError` is raised.
256        """
257        uri = f"/api/0.6/way/{way_id}/full"
258        data = self._session._get(uri)
259        return parser.parse_osm(data)
260
261    def ways_get(self: "OsmApi", way_id_list: list[int]) -> dict[int, dict[str, Any]]:
262        """
263        Returns dict with the id of the way as a key for
264        each way in `way_id_list`:
265
266            #!python
267            {
268                '1234': dict of way data,
269                '5678': dict of way data,
270                ...
271            }
272
273        `way_id_list` is a list containing unique identifiers for multiple ways.
274        """
275        way_list = ",".join([str(x) for x in way_id_list])
276        uri = f"/api/0.6/ways?ways={way_list}"
277        data = self._session._get(uri)
278        ways = cast(list[Element], dom.OsmResponseToDom(data, tag="way"))
279        result: dict[int, dict[str, Any]] = {}
280        for way in ways:
281            way_data = dom.dom_parse_way(way)
282            result[way_data["id"]] = way_data
283        return result