Merge pull request #160 from metaodi/develop

Release 4.1.0

.gitignore

@@ -7,3 +7,4 @@ MANIFEST
 .pycache/*
 .pytest_cache/*
 .env
+pyenv

CHANGELOG.md

@@ -4,6 +4,16 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ## [Unreleased]
 
+## [4.1.0] - 2024-03-19
+### Added
+- OAuth 2.0 example in README and in the `examples` directory
+
+### Changed
+- Check if a passed `session` is authenticated and use this instead of Username/Password, this enables OAuth 2.0 authentication
+
+### Removed
+- remove Python2 crumbs (see PR #159, thanks [Alexandre Detiste](https://github.com/a-detiste))
+
 ## [4.0.0] - 2023-07-15
 ### Added
 - Add Python 3.11 to build
@@ -339,7 +349,8 @@ Miroslav Šedivý
 - `Fixed` for any bug fixes.
 - `Security` to invite users to upgrade in case of vulnerabilities.
 
-[Unreleased]: https://github.com/metaodi/osmapi/compare/v4.0.0...HEAD
+[Unreleased]: https://github.com/metaodi/osmapi/compare/v4.1.0...HEAD
+[4.1.0]: https://github.com/metaodi/osmapi/compare/v4.0.0...v4.1.0
 [4.0.0]: https://github.com/metaodi/osmapi/compare/v3.1.0...v4.0.0
 [3.1.0]: https://github.com/metaodi/osmapi/compare/v3.0.0...v3.1.0
 [3.0.0]: https://github.com/metaodi/osmapi/compare/v2.0.2...v3.0.0

Makefile

@@ -10,6 +10,7 @@ deps:  ## Install dependencies
 	python -m pip install --upgrade pip
 	python -m pip install -r requirements.txt
 	python -m pip install -r test-requirements.txt
+	pre-commit install
 
 docs:  ## Generate documentation
 	python -m pdoc -o docs osmapi
@@ -21,8 +22,8 @@ lint:  ## Linting of source code
 	python -m black --check --diff osmapi examples tests *.py
 	python -m flake8 --statistics --show-source .
 
-test:  ## Run tests
-	python -m pytest --cov=osmapi tests/
+test:  ## Run tests (run in UTF-8 mode in Windows)
+	python -Xutf8 -m pytest --cov=osmapi tests/
 
 help: SHELL := /bin/bash
 help: ## Show help message

README.md

@@ -2,10 +2,12 @@ osmapi
 ======
 
 [![Build osmapi](https://github.com/metaodi/osmapi/actions/workflows/build.yml/badge.svg)](https://github.com/metaodi/osmapi/actions/workflows/build.yml)
-[![Coverage](https://img.shields.io/coveralls/metaodi/osmapi/develop.svg)](https://coveralls.io/r/metaodi/osmapi?branch=develop)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Version](https://img.shields.io/pypi/v/osmapi.svg)](https://pypi.python.org/pypi/osmapi/)
 [![License](https://img.shields.io/pypi/l/osmapi.svg)](https://github.com/metaodi/osmapi/blob/master/LICENSE.txt)
+[![Coverage](https://img.shields.io/coveralls/metaodi/osmapi/develop.svg)](https://coveralls.io/r/metaodi/osmapi?branch=develop)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+
 
 Python wrapper for the OSM API (requires Python >= 3.8)
 
@@ -30,6 +32,8 @@ To update the online documentation, you need to re-generate the documentation wi
 
 To test this library, please create an account on the [development server of OpenStreetMap (https://api06.dev.openstreetmap.org)](https://api06.dev.openstreetmap.org).
 
+Check the [examples directory](https://github.com/metaodi/osmapi/tree/develop/examples) to find more example code.
+
 ### Read from OpenStreetMap
 
 ```python
@@ -65,22 +69,81 @@ Note: Each line in the password file should have the format _user:password_
 >>> api.ChangesetClose()
 ```
 
-## Note
+### OAuth authentication
+
+Username/Password authentication will be deprecated in 2024 (see [official OWG announcemnt](https://www.openstreetmap.org/user/pnorman/diary/401157) for details).
+In order to use this library in the future, you'll need to use OAuth 2.0.
+
+To use OAuth 2.0, you must register an application with an OpenStreetMap account, either on the [development server](https://master.apis.dev.openstreetmap.org/oauth2/applications) or on the [production server](https://www.openstreetmap.org/oauth2/applications).
+Once this registration is done, you'll get a `client_id` and a `client_secret` that you can use to authenticate users.
+
+Example code using [`requests-oauth2client`](https://pypi.org/project/requests-oauth2client/):
+
+```python
+from requests_oauth2client import OAuth2Client, OAuth2AuthorizationCodeAuth
+import requests
+import webbrowser
+import osmapi
+import os
+
+client_id = "<client_id>"
+client_secret = "<client_secret>"
+
+# special value for redirect_uri for non-web applications
+redirect_uri = "urn:ietf:wg:oauth:2.0:oob"
+
+authorization_base_url = "https://master.apis.dev.openstreetmap.org/oauth2/authorize"
+token_url = "https://master.apis.dev.openstreetmap.org/oauth2/token"
+
+oauth2client = OAuth2Client(
+    token_endpoint=token_url,
+    authorization_endpoint=authorization_base_url,
+    redirect_uri=redirect_uri,
+    client_id=client_id,
+    client_secret=client_secret,
+    code_challenge_method=None,
+)
+
+# open OSM website to authrorize user using the write_api and write_notes scope
+scope = ["write_api", "write_notes"]
+az_request = oauth2client.authorization_request(scope=scope)
+print(f"Authorize user using this URL: {az_request.uri}")
+webbrowser.open(az_request.uri)
+
+# create a new requests session using the OAuth authorization
+auth_code = input("Paste the authorization code here: ")
+auth = OAuth2AuthorizationCodeAuth(
+    oauth2client,
+    auth_code,
+    redirect_uri=redirect_uri,
+)
+oauth_session = requests.Session()
+oauth_session.auth = auth
+
+# use the custom session
+api = osmapi.OsmApi(
+    api="https://api06.dev.openstreetmap.org",
+    session=oauth_session
+)
+with api.Changeset({"comment": "My first test"}) as changeset_id:
+    print(f"Part of Changeset {changeset_id}")
+    node1 = api.NodeCreate({"lon": 1, "lat": 1, "tag": {}})
+    print(node1)
+```
+
+## Note about imports / automated edits
 
 Scripted imports and automated edits should only be carried out by those with experience and understanding of the way the OpenStreetMap community creates maps, and only with careful **planning** and **consultation** with the local community.
 
 See the [Import/Guidelines](http://wiki.openstreetmap.org/wiki/Import/Guidelines) and [Automated Edits/Code of Conduct](http://wiki.openstreetmap.org/wiki/Automated_Edits/Code_of_Conduct) for more information.
 
-### Development
+## Development
 
 If you want to help with the development of `osmapi`, you should clone this repository and install the requirements:
 
-    pip install -r requirements.txt
-    pip install -r test-requirements.txt
+    make deps
 
-After that, it is recommended to install the pre-commit-hooks (flake8, black):
-
-    pre-commit install
+Better yet use the provided [`setup.sh`](https://github.com/metaodi/osmapi/blob/develop/setup.sh) script to create a virtual env and install this package in it. 
 
 You can lint the source code using this command:
 
@@ -90,8 +153,6 @@ And if you want to reformat the files (using the black code style) simply run:
 
     make format
 
-### Tests
-
 To run the tests use the following command:
 
     make test

docs/osmapi.html

@@ -56,7 +56,7 @@ <h1 class="modulename">
 
                         <details>
             <summary>View Source</summary>
-            <div class="codehilite"><pre><span></span><span class="n">__version__</span> <span class="o">=</span> <span class="s2">&quot;4.0.0&quot;</span>
+            <div class="codehilite"><pre><span></span><span class="n">__version__</span> <span class="o">=</span> <span class="s2">&quot;4.1.0&quot;</span>
 
 <span class="kn">from</span> <span class="nn">.OsmApi</span> <span class="kn">import</span> <span class="o">*</span>  <span class="c1"># noqa</span>
 <span class="kn">from</span> <span class="nn">.errors</span> <span class="kn">import</span> <span class="o">*</span>  <span class="c1"># noqa</span>