Merge pull request #26 from docentYT/development

v3.0.0

Author: docentYT

.coveragerc

@@ -2,4 +2,12 @@
 source = src/osm_easy_api/*
 
 [run]
-omit = tests/*
+omit = 
+    tests/*
+    */__init__.py
+
+[report]
+exclude_lines =
+    pragma: no cover
+    # This covers both typing.TYPE_CHECKING and plain TYPE_CHECKING, with any amount of whitespace
+    if\s+(typing\.)?TYPE_CHECKING:

API.txt

@@ -5,20 +5,60 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.2.0]
+## [3.0.0] - 2024-03-19
+### Added
+- Support for `oAuth2`: `access_token` parameter in `Api` class constructor.
+- `Unauthorized` exception. (No access token.)
+- `Forbidden` exception. (The access token does not support the needed scope or you must be a moderator.)
+- `gpx.create()` endpoint.
+- `GpxFile` data class.
+- `Visibility` enum.
+- `gpx.update()` endpoint.
+- `gpx.delete()` endpoint.
+- `gpx.get_details()` endpoint.
+- `gpx.get_file()` endpoint.
+- `gpx.list_details()` endpoint.
+- `order` parameter in `changeset.get_query()`.
+
+### Fixed
+- Types in `elements` endpoint.
+- Missing documentation.
+- `misc.get_map_in_bbox()` endpoint should not yield `string`.
+
+### Changed
+- The way http errors are handled.
+- In `elements.get()` endpoint the `element` parameter has been renamed to `element_type`.
+- In `elements.history()` endpoint the `element` parameter has been renamed to `element_type`.
+- In `elements.version()` endpoint the `element` parameter has been renamed to `element_type`.
+- In `elements.getQuery()` endpoint the `element` parameter has been renamed to `element_type`.
+- In `elements.relations()` endpoint the `element` parameter has been renamed to `element_type`.
+- In `elements.full()` endpoint the `element` parameter has been renamed to `element_type`.
+- Type of `user_id` parameter in `changeset.get_query()` was changed from `str` to `int`.
+- `OsmChange_parser_generator()` and `OsmChange_parser()` from `diff` module are now 'private' functions. Use `Diff.get()` instead.
+- `notes.search()` endpoint throws `LimitsExceeded` exception instead of `ValueError`.
+- `page_number` paremeter in `gpx.get()` has now default value 0.
+- Now classes are imported from individual modules - not from the main library. See examples in the `README.md`.
+- `gpx.get()` renamed to `gpx.get_gps_points()`
+
+### Removed
+- Support for `HTTP Basic authentication`: `username` and `password` parameters in `Api` class constructor.
+- Most `# type: ignore`.
+- `NotAModerator` exception. It is now replaced by `Forbidden` exception.
+
+## [2.2.0] - 2024-02-23
 ### Added
 - Exception for `410` status code in notes endpoint.
 
-## [2.1.1]
+## [2.1.1] - 2024-01-04
 ### Fixed
 - Percent-encoding was not applied on texts entered by the user. [#22](https://github.com/docentYT/osm_easy_api/issues/22)
 
-## [2.1.0]
+## [2.1.0] - 2023-09-06
 ### Added
 - `TooManyRequests` exception.
 - Support for `429` status code in `api.changeset.discussion.comment()`.
 
-## [2.0.0]
+## [2.0.0] - 2023-08-29
 ### Added
 - Missing status code handling in `notes.get()`.
 - Support for hide note endpoint.
@@ -35,27 +75,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `EmptyResult` api exception, which was used in endpoints `notes`, `user` and `changeset`. From now on when the results are empty an empty list will be returned.
 - Unused imports.
 
-## [1.1.1]
+## [1.1.1] - 2023-08-03
 ### Fixed
 - Corrected character when adding parameters in endpoint `api.notes.get_bbox()` (from `?` to `&`).
 - Fixed the `limit` parameter restrictions in `api.notes.get_bbox()` documentation.
 
-## [1.1.0]
+## [1.1.0] - 2023-08-28
 ### Added
 - `limit` parameter for `api.changeset.get_query()` endpoint.
 
 ### Fixed
 - Corrected character when adding parameters in endpoint `api.changeset.get_query()` (from `;` to `&`).
 
-## [1.0.2]
+## [1.0.2] - 2023-07-26
 ### Fixed
 - Auth problems in API when using characters unsupported by latin-1 codec.
 
-## [1.0.1]
+## [1.0.1] - 2023-07-24
 ### Fixed
 - `api.notes.create()` created only anonymous notes.
 
-## [1.0.0]
+## [1.0.0] - 2023-06-18
 ### Added
 - `to_xml()` method in `OsmChange`.
 - `upload()` method in `changeset` `endpoint` has new optional arguments.
@@ -65,7 +105,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Private `_to_xml()` method in `OsmChange` is now static.
 
-## [0.4.2]
+## [0.4.2] - 2023-06-11
 
 ### Changed
 - Order of elements in xml generated by `Way._to_xml()`. First tags, then nodes.
@@ -75,11 +115,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Deleted disused variable in `Node._to_xml()`.
 - Fixed incorrect relation parsing of data recived by `full` endpoint.
 
-## [0.4.1]
+## [0.4.1] - 2023-05-23
 ### Changed
 - Updated `requests` from `2.28.1` to `2.31.0`.
 
-## [0.4.0]
+## [0.4.0] - 2023-05-03
 ### Added
 - `to_dict()` method and `from_dict()` class method to `Note`.  
 - `to_dict()` method and `from_dict()` class method to `Comment`.

CHANGELOG.md

@@ -15,16 +15,13 @@
 
 <p align="center"><a href="https://www.openstreetmap.org/user/kwiatek_123">Me on OpenStreetMap</a></p>
 
-Python package for parsing osm diffs and communicating with the OpenStreetMap api. See API.txt for list of supported endpoints.
+> Python package for parsing osm diffs and communicating with the OpenStreetMap api.
 
-## What's the point of this package?
+### What's the point of this package?
 
 This package was created to provide an easy way to create automated scripts and programs that use diff and/or osm api. The main advantage is the classes (data_classes) that provide data of elements (node, way, relation, OsmChange, etc.) in a readable way and the possibility to use them in diff and api without worrying about missing data or dictionaries. You can easily find nodes in diff, add a tag to them and send the corrected version to osm.
 
-## What next?
-The plan is to optimise and improve the code, add support for gpx traces, rss support and overpass api.
-
-# Installation
+## Installation
 
 Works on python >= 3.10. (Due to new typehints standard)
 
@@ -33,21 +30,26 @@ Install `osm_easy_api` from [PyPi](https://pypi.org/project/osm-easy-api/):
 pip install osm_easy_api
 ``` 
 
-# Documentation
+## Documentation
 
 You can view documentation on [github-pages](https://docentyt.github.io/osm_easy_api/osm_easy_api.html).
 
 Documentation is build using [pdoc](https://pdoc.dev).
 To run docs on your machine use preferred command: `pdoc --docformat google --no-show-source osm_easy_api !osm_easy_api.utils`.
 
-# Examples
+## OAuth 2.0
+Due to the deprecation of HTTP Basic Auth you need an access token to use most api endpoints. To obtain an access token we recommend using https://tools.interactivemaps.xyz/token/.
+
+
+## Examples
 
-## DIFF
+### DIFF
 
-### Print trees
+#### Print trees
 
 ```py
-from osm_easy_api import Node, Diff, Frequency
+from osm_easy_api.diff import Diff, Frequency
+from osm_easy_api.data_classes import Node
 
 # Download diff from last hour.
 d = Diff(Frequency.HOUR)
@@ -61,10 +63,11 @@ for action, element in gen:
         print(action, element.id)
 ```
 
-### Print incorrectly tagged single tress
+#### Print incorrectly tagged single tress
 
 ```py
-from osm_easy_api import Diff, Frequency, Action, Node
+from osm_easy_api.diff import Diff, Frequency
+from osm_easy_api.data_classes import Action, Node
 
 d = Diff(Frequency.DAY)
 
@@ -81,14 +84,15 @@ Example output:
 Node(id = 10208486717, visible = None, version = 1, changeset_id = 129216075, timestamp = 2022-11-22T00:16:44Z, user_id = 17471721, tags = {'leaf_type': 'broadleaved', 'natural': 'wood'}, latitude = 48.6522286, longitude = 12.583809, )
 ```
 
-## API
+### API
 
-### Add missing wikidata tag
+#### Add missing wikidata tag
 
 ```py
-from osm_easy_api import Api, Node, Tags
+from osm_easy_api.api import Api
+from osm_easy_api.data_classes import Node, Tags
 
-api = Api("https://master.apis.dev.openstreetmap.org", LOGIN, PASSWORD)
+api = Api("https://master.apis.dev.openstreetmap.org", ACCESS_TOKEN)
 
 node = api.elements.get(Node, 4296460336) # We are getting Node with id 4296460336 where we want to add a new tag to
 node.tags.add("wikidata", "Qexample") # Add a new tag to node.
@@ -98,11 +102,11 @@ api.elements.update(node, my_changeset) # Send new version of a node to osm
 api.changeset.close(my_changeset) # Close changeset.
 ```
 
-# Notes
+## Notes
 
 Note that the following codes do the same thing
 ```py
-from osm_easy_api import Diff, Frequency
+from osm_easy_api.diff import Diff, Frequency
 
 d = Diff(Frequency.DAY)
 
@@ -113,7 +117,8 @@ for action, element in gen:
         print(element)
 ```
 ```py
-from osm_easy_api import Diff, Frequency, Tags
+from osm_easy_api.diff import Diff, Frequency
+from osm_easy_api.data_classes import Tags
 
 d = Diff(Frequency.DAY)
 
@@ -126,7 +131,8 @@ but the second seems to be faster.
 
 Also you can use OsmChange object if you don't want to use generator
 ```py
-from osm_easy_api import Diff, Frequency, Action, Node
+from osm_easy_api.diff import Diff, Frequency
+from osm_easy_api.data_classes import Action, Node
 
 d = Diff(Frequency.MINUTE)
 
@@ -138,7 +144,7 @@ for node in deleted_nodes:
 ```
 but it can consume large amounts of ram and use of this method is not recommended for large diff's.
 
-# Tests
+## Tests
 
 You will need to install `test-requirements.txt`. You can use tox.
 To run tests manually use `python -m unittest discover`.

README.md

@@ -1,6 +1,6 @@
-VERSION = "2.2.0"
+"""Python package for parsing osm diffs and communicating with the OpenStreetMap api."""
+VERSION = "3.0.0"
 
-from .data_classes import *
-from .diff import Diff, Frequency
-
-from .api import Api
+from . import data_classes
+from . import diff
+from . import api

coverage-badge.svg

@@ -47,7 +47,13 @@ def __init__(self, base_url: str):
         }
 
         self.gpx: Dict[str, str] = {
-            "get": six_url + "/trackpoints?bbox={left},{bottom},{right},{top}&page={page_number}"
+            "get_gps_points": six_url + "/trackpoints?bbox={left},{bottom},{right},{top}&page={page_number}",
+            "create": six_url + "/gpx/create",
+            "update": six_url + "/gpx/{id}",
+            "delete": six_url + "/gpx/{id}",
+            "details": six_url + "/gpx/{id}/details",
+            "get_file": six_url + "/gpx/{id}/data",
+            "list": six_url + "/user/gpx_files"
         }
 
         self.user: Dict[str, str] = {