osmapi.node

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